Revamped configs into 'core', 'latest', and (legacy) 'recommended'

.gitignore

@@ -1,24 +1,14 @@
+.npm_cache
 node_modules
 npm-debug.log
 
-# TypeScrit temporary/cache files
-**/.baseDir.ts
-**/.tscache/
-tscommand-*.tmp.txt
-
-**/dist/
-
 # IDEA
 .idea
 tslint-microsoft-contrib.iml
 
 # vim swap files
 *.sw*
 
-**/tags
-
-# local npm cache
-.npm_cache
-
-out.html
+# Generated for builds
+**/dist/
 rule-metadata.json

.prettierignore

@@ -1,15 +1,11 @@
 # Build directory
 dist/
 
+# Configuration and npm settings
+*.json
+
 # Definition files
 *.d.ts
 
-# NPM files
-package.json
-package-lock.json
-
 # Test files
 test-data/NoUnnecessarySemicolonsTestInput.ts
-
-# Generated files
-recommended_ruleset.js

README.md

@@ -40,23 +40,59 @@ Add `"node_modules/tslint-microsoft-contrib"` under your `"rulesDirectory"` conf
 ### Which Rules Should I Turn On?
 
 There certainly are a lot of options!
-To start, you can enable our recommended defaults ([recommended_ruleset.js](recommended_ruleset.js)) by adding `"tslint-microsoft-contrib"` under `"extends"` in your `tslint.json`:
+
+If you extend from one of the following configurations, `rulesDirectory` will have `node_modules/tslint-microsoft-contrib` included for you.
+
+> Please note, some of the default ruleset rules require the `--project` TSLint option.
+
+#### Recommended
+
+To start, you can enable our stable "recommended" defaults that come with tslint-microsoft-contrib ([recommended.json](./recommended.json)) by adding `"tslint-microsoft-contrib/recommended"` under `"extends"` in your `tslint.json`:
 
 ```json
 {
-    "extends": ["tslint-microsoft-contrib"],
-    "rulesDirectory": ["node_modules/tslint-microsoft-contrib"],
-    "rules": {
-        // ...
-    }
+    "extends": ["tslint-microsoft-contrib/recommended"]
+    // ...
 }
 ```
 
-You can then disable rules you don't find useful.
+These rules will not be added to in minor or patch releases, but will be in major releases.
+
+#### Latest
+
+To run with the latest and greatest rules ([latest.json](./latest.json)), extend from `tslint-microsoft-contrib/latest`:
+
+```json
+{
+    "extends": ["tslint-microsoft-contrib/latest"]
+    // ...
+}
+```
+
+These rules will not be added to in patch releases, but will be in minor releases.
+
+#### Legacy
+
+The old "recommended" ruleset that ships by extending `tslint-microsoft-contrib` itself contains a list of rules that includes core TSLint rules.
+
+To start, you can enable our recommended defaults ([recommended.json](./recommended.json)) by adding just `"tslint-microsoft-contrib"` under `"extends"` in your `tslint.json`:
+
+```json
+{
+    "extends": ["tslint-microsoft-contrib"]
+    // ...
+}
+```
+
+**This ruleset is considered legacy**; it is generally preferable to extend from the 'recommended' or 'latest' rulesets.
+We recommend you instead explicitly include `tslint:recommended`, `tslint:latest`, or `tslint:all` in your `tslint.json` rather than enable core rules through this configuration.
+
+In the next major version of TSLint, this will instead be an alis for `"tslint-microsoft-contrib/recommended"`.
+
+### Overriding Configurations
 
-Please note, some of the default rules require the `--project` TSLint option.
+You can [disable rules](https://palantir.github.io/tslint/usage/rule-flags) you don't find useful.
 
-Also, please note that adding a rule to the recommended ruleset is considered backwards compatible.
 If you rely on version ranges in your dependencies then you may find that new rules being added to the product create violations and fail your build.
 We recommend you specify exact versions of lint libraries, including `tslint-microsoft-contrib`, in your `package.json`.
 

build-tasks/common/files.js

@@ -2,6 +2,15 @@ const { red } = require('chalk');
 const fs = require('fs');
 const stripJsonComments = require('strip-json-comments');
 
+function readDirectory(directoryName) {
+    try {
+        return fs.readdirSync(directoryName);
+    } catch (e) {
+        console.log(red(`Unable to read directory: ${directoryName}. Error code: ${e.code}`));
+        process.exit(1);
+    }
+}
+
 function readFile(fileName) {
     try {
         return fs.readFileSync(fileName, { encoding: 'utf8' });
@@ -39,6 +48,7 @@ function readJSONWithComments(fileName) {
 }
 
 module.exports = {
+    readDirectory,
     readFile,
     readJSON,
     readJSONWithComments,

build-tasks/common/meta.js

@@ -2,9 +2,9 @@ const path = require('path');
 const glob = require('glob');
 const { readJSON } = require('./files');
 
-function getAllRules() {
+function getAllRules({ ignoreTslintRules = false } = {}) {
     const contribRules = glob.sync('dist/build/*Rule.js');
-    const baseRules = glob.sync('node_modules/tslint/lib/rules/*Rule.js');
+    const baseRules = ignoreTslintRules ? [] : glob.sync('node_modules/tslint/lib/rules/*Rule.js');
 
     return contribRules.concat(baseRules);
 }

build-tasks/copy-config-json.js

@@ -0,0 +1,21 @@
+/**
+ * Converts configs/*.json to ./dist/build/*.json.
+ */
+
+const mkdirp = require('mkdirp');
+const path = require('path');
+
+const { readDirectory, readFile, writeFile } = require('./common/files');
+
+const copyConfigFile = (configFileName, destinationFileName) => {
+    const resolvedDestination = path.resolve(destinationFileName);
+    const data = readFile(path.resolve(configFileName));
+
+    writeFile(resolvedDestination, data.replace(/"rulesDirectory": \[(.*)\]/, `"rulesDirectory": ["./"]`));
+};
+
+mkdirp.sync('./dist/build');
+
+for (const configFileName of readDirectory('./configs')) {
+    copyConfigFile(`./configs/${configFileName}`, `./dist/build/${configFileName}`);
+}

build-tasks/generate-latest-config.js

@@ -0,0 +1,47 @@
+/**
+ * Generates config/latest.json.
+ * The `recommended` metadata for each rule is added there, except if...
+ *  - ...the rule's `metadata.group` is `'Ignored'`
+ *  - ...the rule is also mentioned in config/recommended.json
+ *  - ...the recommended setting starts with `false` (the rule is likely deprecated)
+ */
+
+const { writeFile } = require('./common/files');
+const { getAllRules, getMetadataFromFile, getMetadataValue } = require('./common/meta');
+
+const recommendations = [];
+
+const recommendedRules = new Set(Object.keys(require('../configs/recommended.json').rules));
+
+getAllRules({
+    ignoreTslintRules: true
+}).forEach(ruleFile => {
+    const metadata = getMetadataFromFile(ruleFile);
+    const ruleName = getMetadataValue(metadata, 'ruleName');
+
+    const groupName = getMetadataValue(metadata, 'group');
+    if (groupName === 'Ignored') {
+        return;
+    }
+
+    let recommendation = getMetadataValue(metadata, 'recommendation', true, true);
+    if (recommendation === '') {
+        recommendation = 'true';
+    }
+
+    // Don't mention rules recommended as disabled
+    if (recommendation.startsWith('false')) {
+        return;
+    }
+
+    // Don't redundantly mention rules added to the 'recommended' preset
+    if (recommendedRules.has(ruleName)) {
+        return;
+    }
+
+    recommendations.push(`        "${ruleName}": ${recommendation}`);
+});
+
+const latestTemplate = require('./templates/latest.json.template');
+
+writeFile('configs/latest.json', latestTemplate(recommendations));

build-tasks/templates/latest.json.template.js

@@ -0,0 +1,8 @@
+module.exports = recommendations => `{
+    "extends": ["./recommended.json"],
+    "rulesDirectory": ["../"],
+    "rules": {
+${[...recommendations].sort().join(',\n')}
+    }
+}
+`;