Metadata for each rule (palantir#1311)

* Adds metadata for each rule
* Adds a gulp docs command that runs a script which reads the metadata from each rule and outputs file into the Jekyll docs site
* Removes docs/sample.tslint.json because it's redundant documentation and also to make room for the docs build script.

.gitignore

@@ -1,6 +1,7 @@
 .DS_Store
 .tscache/
 /build/
+/scripts/*.js
 /lib/
 node_modules/
 tscommand*.txt

Gruntfile.js

@@ -20,6 +20,7 @@ module.exports = function (grunt) {
 
         clean: {
             core: ["lib/**/*.js", "lib/**/*.d.ts"],
+            scripts: ["scripts/*.js"],
             test: ["build/", "test/config/node_modules/"],
         },
 
@@ -40,6 +41,11 @@ module.exports = function (grunt) {
             testRules: {
                 args: ["./build/test/ruleTestRunner.js"],
             },
+            docs: {
+                cmd: "node",
+                args: ["buildDocs.js"],
+                options: {cwd: "./scripts/"},
+            },
         },
 
         tslint: {
@@ -51,6 +57,9 @@ module.exports = function (grunt) {
                 "src/rules/**/*.ts",
                 "src/test/**/*.ts",
             ],
+            scripts: [
+                "scripts/**/*.ts",
+            ],
             test: [
                 "test/**/*.ts",
                 "!test/**/*.test.ts",
@@ -62,6 +71,9 @@ module.exports = function (grunt) {
             core: {
                 tsconfig: "src/tsconfig.json",
             },
+            scripts: {
+                tsconfig: "scripts/tsconfig.json",
+            },
             test: {
                 tsconfig: "test/tsconfig.json",
             },
@@ -91,6 +103,11 @@ module.exports = function (grunt) {
         "ts:core",
         "tslint:src",
     ]);
+    grunt.registerTask("scripts", [
+        "clean:scripts",
+        "ts:scripts",
+        "tslint:scripts",
+    ]);
     grunt.registerTask("test", [
         "clean:test",
         "npm-command:test",
@@ -99,7 +116,12 @@ module.exports = function (grunt) {
         "mochaTest",
         "run:testRules",
     ].concat(checkBinTest));
+    // generates new docs metadata files
+    grunt.registerTask("docs", [
+        "default",
+        "run:docs",
+    ]);
 
     // create default task
-    grunt.registerTask("default", ["eslint", "core", "test"]);
+    grunt.registerTask("default", ["eslint", "core", "scripts", "test"]);
 };

package.json

@@ -39,6 +39,7 @@
     "grunt-run": "~0.6.0",
     "grunt-ts": "^5.1.0",
     "grunt-tslint": "latest",
+    "js-yaml": "^3.4.6",
     "mocha": "^2.2.5",
     "tslint": "latest",
     "tslint-test-config-non-relative": "file:test/external/tslint-test-config-non-relative",

scripts/buildDocs.ts

@@ -0,0 +1,83 @@
+/*
+ * Copyright 2016 Palantir Technologies, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/*
+ * This TS script reads the metadata from each TSLint built-in rule
+ * and serializes it in a format appropriate for the docs website.
+ *
+ * This script expects there to be a tslint-gh-pages directory
+ * parallel to the main tslint directory. The tslint-gh-pages should
+ * have the gh-pages branch of the TSLint repo checked out.
+ * One easy way to do this is with the following Git command:
+ *
+ * ```
+ * git worktree add -b gh-pages ../tslint-gh-pages origin/gh-pages
+ * ```
+ *
+ * See http://palantir.github.io/tslint/develop/docs/ for more info
+ *
+ */
+
+import * as fs from "fs";
+import * as glob from "glob";
+import * as path from "path";
+import * as yaml from "js-yaml";
+import {IRuleMetadata} from "../lib/language/rule/rule";
+import {AbstractRule} from "../lib/language/rule/abstractRule";
+
+const DOCS_DIR = "../../tslint-gh-pages";
+const DOCS_RULE_DIR = path.join(DOCS_DIR, "rules");
+
+const rulePaths = glob.sync("../lib/rules/*Rule.js");
+const rulesJson: IRuleMetadata[] = [];
+for (const rulePath of rulePaths) {
+    // tslint:disable-next-line:no-var-requires
+    const ruleModule = require(rulePath);
+    const Rule = ruleModule.Rule as typeof AbstractRule;
+    if (Rule != null && Rule.metadata != null) {
+        const { metadata } = Rule;
+        const fileData = generateRuleFile(metadata);
+        const fileDirectory = path.join(DOCS_RULE_DIR, metadata.ruleName);
+
+        // write file for each specific rule
+        if (!fs.existsSync(fileDirectory)) {
+            fs.mkdirSync(fileDirectory);
+        }
+        fs.writeFileSync(path.join(fileDirectory, "index.html"), fileData);
+
+        rulesJson.push(metadata);
+    }
+}
+
+// write overall data file, this is used to generate the index page for the rules
+const fileData = JSON.stringify(rulesJson, undefined, 2);
+fs.writeFileSync(path.join(DOCS_DIR, "_data", "rules.json"), fileData);
+
+/**
+ * Based off a rule's metadata, generates a string Jekyll "HTML" file
+ * that only consists of a YAML front matter block.
+ */
+function generateRuleFile(metadata: IRuleMetadata) {
+    const yamlData: any = {};
+    // TODO: Use Object.assign when Node 0.12 support is dropped (#1181)
+    for (const key of Object.keys(metadata)) {
+        yamlData[key] = (<any> metadata)[key];
+    }
+    yamlData.optionsJSON = JSON.stringify(metadata.options, undefined, 2);
+    yamlData.layout = "rule";
+    yamlData.title = `Rule: ${metadata.ruleName}`;
+    return `---\n${yaml.safeDump(yamlData, <any> {lineWidth: 140})}---`;
+}

scripts/tsconfig.json

@@ -0,0 +1,31 @@
+{
+    "version": "1.8.0",
+    "compilerOptions": {
+        "module": "commonjs",
+        "noImplicitAny": true,
+        "declaration": false,
+        "sourceMap": false,
+        "target": "es5",
+        "outDir": "."
+    },
+    "atom": {
+        "rewriteTsconfig": false
+    },
+    "filesGlob": [
+        "../typings/**/*.d.ts",
+        "./*.ts"
+    ],
+    "files": [
+        "../typings/colors/colors.d.ts",
+        "../typings/diff/diff.d.ts",
+        "../typings/findup-sync/findup-sync.d.ts",
+        "../typings/glob/glob.d.ts",
+        "../typings/js-yaml/js-yaml.d.ts",
+        "../typings/minimatch/minimatch.d.ts",
+        "../typings/node/node.d.ts",
+        "../typings/optimist/optimist.d.ts",
+        "../typings/underscore.string/underscore.string.d.ts",
+        "../typings/underscore/underscore.d.ts",
+        "buildDocs.ts"
+    ]
+}

src/language/rule/abstractRule.ts

@@ -18,9 +18,10 @@
 import * as ts from "typescript";
 import {IOptions} from "../../lint";
 import {RuleWalker} from "../walker/ruleWalker";
-import {IRule, IDisabledInterval, RuleFailure} from "./rule";
+import {IRule, IRuleMetadata, IDisabledInterval, RuleFailure} from "./rule";
 
 export abstract class AbstractRule implements IRule {
+    public static metadata: IRuleMetadata;
     private value: any;
     private options: IOptions;