Docs: update README.md

mysticatea · mysticatea · commit 98bfc40919dc · 2017-10-28T23:12:53.000+09:00
diff --git a/README.md b/README.md
@@ -8,7 +8,7 @@
 
 Additional ESLint rules for ESLint's directive-comments (e.g. `//eslint-disable-line`).
 
-## :cd: Installation
+## 💿 Installation
 
 ```
 npm install --save-dev eslint eslint-plugin-eslint-comments
@@ -17,67 +17,75 @@ npm install --save-dev eslint eslint-plugin-eslint-comments
 ### Requirements
 
 - Node.js `^4.0.0`, `^6.0.0`, or newer.
-- ESLint `^3.1.0`, or newer.
+- ESLint `^4.7.0`, or newer.
 
-## :book: Usage
+## 📖 Usage
 
 Write in your ESLint configurations: http://eslint.org/docs/user-guide/configuring#using-the-configuration-from-a-plugin
 
 ### Example
 
 **.eslintrc.json**
 
+```json
+{
+    "extends": [
+        "eslint:recommended",
+        "plugin:eslint-comments/recommended"
+    ],
+}
+```
+
+Or you can specify for each rule:
+
 ```json
 {
     "plugins": [
         "eslint-comments"
     ],
     "rules": {
-        "eslint-comments/disable-enable-pair": "error",
-        "eslint-comments/no-duplicate-disable": "error",
-        "eslint-comments/no-unlimited-disable": "error",
         "eslint-comments/no-unused-disable": "error",
         "eslint-comments/no-unused-enable": "error",
-        "eslint-comments/no-use": "error",
+        // ...
     }
 }
 ```
 
-### Rules
+## Rules
+
+- 🌟 mark: the rule is enabled by `eslint-comments/recommended` preset.
+- ✒️ mark: the rule is fixable by `eslint --fix` command.
+
+<!--RULES_TABLE_START-->
+### Best Practices
+
+|    | Rule ID | Description |
+|:---|:--------|:------------|
+| 🌟 | [eslint-comments/disable-enable-pair](./docs/rules/eslint-comments/disable-enable-pair.md) | requires a `eslint-enable` comment for every `eslint-disable` comment |
+| 🌟 | [eslint-comments/no-aggregating-enable](./docs/rules/eslint-comments/no-aggregating-enable.md) | disallows `eslint-enable` comments for multiple `eslint-disable` comments |
+| 🌟 | [eslint-comments/no-duplicate-disable](./docs/rules/eslint-comments/no-duplicate-disable.md) | disallows duplicate `eslint-disable` comments |
+| 🌟 | [eslint-comments/no-unlimited-disable](./docs/rules/eslint-comments/no-unlimited-disable.md) | disallows `eslint-disable` comments without rule names |
+| 🌟 | [eslint-comments/no-unused-disable](./docs/rules/eslint-comments/no-unused-disable.md) | disallows unused `eslint-disable` comments |
+| 🌟 | [eslint-comments/no-unused-enable](./docs/rules/eslint-comments/no-unused-enable.md) | disallows unused `eslint-enable` comments |
+
+### Stylistic Issues
+
+|    | Rule ID | Description |
+|:---|:--------|:------------|
+|  | [eslint-comments/no-restricted-disable](./docs/rules/eslint-comments/no-restricted-disable.md) | disallows `eslint-disable` comments about specific rules |
+|  | [eslint-comments/no-use](./docs/rules/eslint-comments/no-use.md) | disallows ESLint directive-comments |
 
-- [eslint-comments/disable-enable-pair](docs/rules/disable-enable-pair.md) requires a `eslint-enable` comment for every `eslint-disable` comment.
-- [eslint-comments/no-duplicate-disable](docs/rules/no-duplicate-disable.md) disallows duplicate `eslint-disable` comments.
-- [eslint-comments/no-unlimited-disable](docs/rules/no-unlimited-disable.md) disallows `eslint-disable` comments without rule names.
-- [eslint-comments/no-unused-disable](docs/rules/no-unused-disable.md) disallows unused `eslint-disable` comments.
-- [eslint-comments/no-unused-enable](docs/rules/no-unused-enable.md) disallows unused `eslint-enable` comments.
-- [eslint-comments/no-use](docs/rules/no-use.md) disallows ESLint directive-comments.
+<!--RULES_TABLE_END-->
 
-## :anchor: Semantic Versioning Policy
+## 🚥 Semantic Versioning Policy
 
 `eslint-plugin-eslint-comments` follows [semantic versioning](http://semver.org/) and [ESLint's Semantic Versioning Policy](https://github.com/eslint/eslint#semantic-versioning-policy).
 
-- Patch release (intended to not break your lint build)
-    - A bug fix in a rule that results in `eslint-plugin-eslint-comments` reporting fewer errors.
-    - Improvements to documentation.
-    - Non-user-facing changes such as refactoring code, adding, deleting, or modifying tests, and increasing test coverage.
-    - Re-releasing after a failed release (i.e., publishing a release that doesn't work for anyone).
-- Minor release (might break your lint build)
-    - A bug fix in a rule that results in `eslint-plugin-eslint-comments` reporting more errors.
-    - A new rule is created.
-    - A new option to an existing rule is created.
-    - An existing rule is deprecated.
-- Major release (likely to break your lint build)
-    - A support for old Node version is dropped.
-    - A support for old ESLint version is dropped.
-    - An existing rule is removed.
-    - An existing option of a rule is removed.
-    - An existing config is updated.
-
-## :newspaper: Changelog
+## 📰 Changelog
 
 - [GitHub Releases](https://github.com/mysticatea/eslint-plugin-eslint-comments/releases)
 
-## :muscle: Contributing
+## 🍻 Contributing
 
 Welcome contributing!
 
diff --git a/docs/rules/disable-enable-pair.md b/docs/rules/disable-enable-pair.md
@@ -1,5 +1,7 @@
 # requires a `eslint-enable` comment for every `eslint-disable` comment (eslint-comments/disable-enable-pair)
 
+- 🌟 The `"extends": "plugin:eslint-comments/recommended"` property in a configuration file enables this rule.
+
 `eslint-disable` directive-comments disable ESLint rules in all lines preceded by the comment.
 If you forget `eslint-enable` directive-comment, you may overlook ESLint warnings unintentionally.
 
diff --git a/docs/rules/no-aggregating-enable.md b/docs/rules/no-aggregating-enable.md
@@ -1,4 +1,6 @@
-# disallows `eslint-enable` comments for multiple `eslint-disable` comments (no-aggregating-enable)
+# disallows `eslint-enable` comments for multiple `eslint-disable` comments (eslint-comments/no-aggregating-enable)
+
+- 🌟 The `"extends": "plugin:eslint-comments/recommended"` property in a configuration file enables this rule.
 
 `eslint-enable` directive-comments can enable rules which are disabled by different `eslint-disable` directive-comments.
 It can enable a rule unintentionally.
diff --git a/docs/rules/no-duplicate-disable.md b/docs/rules/no-duplicate-disable.md
@@ -1,5 +1,7 @@
 # disallows duplicate `eslint-disable` comments (eslint-comments/no-duplicate-disable)
 
+- 🌟 The `"extends": "plugin:eslint-comments/recommended"` property in a configuration file enables this rule.
+
 Duplicate of `eslint-disable` directive-comments implies that there is a mix of wide-range directive-comments and narrow-range directive-comments.
 The mix may cause to overlook ESLint warnings in future.
 
diff --git a/docs/rules/no-restricted-disable.md b/docs/rules/no-restricted-disable.md
@@ -1,4 +1,4 @@
-# disallows `eslint-disable` comments about specific rules (no-restricted-disable)
+# disallows `eslint-disable` comments about specific rules (eslint-comments/no-restricted-disable)
 
 This rule warns `eslint-disable` directive-comments if the comment disable specific rules.
 
diff --git a/docs/rules/no-unlimited-disable.md b/docs/rules/no-unlimited-disable.md
@@ -1,5 +1,7 @@
 # disallows `eslint-disable` comments without rule names (eslint-comments/no-unlimited-disable)
 
+- 🌟 The `"extends": "plugin:eslint-comments/recommended"` property in a configuration file enables this rule.
+
 `eslint-disable` directive-comments disable all rules by default. This may cause to overlook some ESLint warnings unintentionally.
 So you should specify the rules to disable accurately.
 
diff --git a/docs/rules/no-unused-disable.md b/docs/rules/no-unused-disable.md
@@ -1,5 +1,7 @@
 # disallows unused `eslint-disable` comments (eslint-comments/no-unused-disable)
 
+- 🌟 The `"extends": "plugin:eslint-comments/recommended"` property in a configuration file enables this rule.
+
 Since refactoring or a bug fix of upstream, an `eslint-disable` directive-comment may become unnecessary.
 In that case, you should remove the garbage as soon as possible since the garbage may cause to overlook ESLint warnings in future.
 
diff --git a/docs/rules/no-unused-enable.md b/docs/rules/no-unused-enable.md
@@ -1,5 +1,7 @@
 # disallows unused `eslint-enable` comments (eslint-comments/no-unused-enable)
 
+- 🌟 The `"extends": "plugin:eslint-comments/recommended"` property in a configuration file enables this rule.
+
 This rule warns `eslint-enable` directive-comments which have no effect.
 
 ## Rule Details
diff --git a/lib/rules/disable-enable-pair.js b/lib/rules/disable-enable-pair.js
@@ -56,7 +56,7 @@ module.exports = {
         docs: {
             description: "requires a `eslint-enable` comment for every `eslint-disable` comment",
             category: "Best Practices",
-            recommended: false,
+            recommended: true,
         },
         fixable: false,
         schema: [{
diff --git a/lib/rules/no-aggregating-enable.js b/lib/rules/no-aggregating-enable.js
@@ -50,7 +50,7 @@ module.exports = {
         docs: {
             description: "disallows `eslint-enable` comments for multiple `eslint-disable` comments",
             category: "Best Practices",
-            recommended: false,
+            recommended: true,
         },
         fixable: false,
         schema: [],
diff --git a/lib/rules/no-duplicate-disable.js b/lib/rules/no-duplicate-disable.js
@@ -21,7 +21,7 @@ module.exports = {
         docs: {
             description: "disallows duplicate `eslint-disable` comments",
             category: "Best Practices",
-            recommended: false,
+            recommended: true,
         },
         fixable: false,
         schema: [],
diff --git a/lib/rules/no-unlimited-disable.js b/lib/rules/no-unlimited-disable.js
@@ -29,6 +29,7 @@ module.exports = {
         docs: {
             description: "disallows `eslint-disable` comments without rule names",
             category: "Best Practices",
+            recommended: true,
         },
         fixable: false,
         schema: [],
diff --git a/lib/rules/no-unused-disable.js b/lib/rules/no-unused-disable.js
@@ -21,7 +21,7 @@ module.exports = {
         docs: {
             description: "disallows unused `eslint-disable` comments",
             category: "Best Practices",
-            recommended: false,
+            recommended: true,
         },
         fixable: false,
         schema: [],
diff --git a/lib/rules/no-unused-enable.js b/lib/rules/no-unused-enable.js
@@ -21,7 +21,7 @@ module.exports = {
         docs: {
             description: "disallows unused `eslint-enable` comments",
             category: "Best Practices",
-            recommended: false,
+            recommended: true,
         },
         fixable: false,
         schema: [],
diff --git a/lib/rules/no-use.js b/lib/rules/no-use.js
@@ -28,7 +28,7 @@ module.exports = {
     meta: {
         docs: {
             description: "disallows ESLint directive-comments",
-            category: "Best Practices",
+            category: "Stylistic Issues",
             recommended: false,
         },
         fixable: false,
diff --git a/scripts/build.js b/scripts/build.js
@@ -12,6 +12,8 @@
 const fs = require("fs")
 const path = require("path")
 const generateIndex = require("./generate-index")
+const updateDocHeaders = require("./update-doc-headers")
+const updateReadme = require("./update-readme")
 
 //------------------------------------------------------------------------------
 // Main
@@ -35,3 +37,5 @@ const rules =
         })
 
 generateIndex(rules)
+updateDocHeaders(rules)
+updateReadme(rules)
diff --git a/scripts/update-doc-headers.js b/scripts/update-doc-headers.js
@@ -0,0 +1,56 @@
+/**
+ * @author Toru Nagashima
+ * @copyright 2017 Toru Nagashima. All rights reserved.
+ * See LICENSE file in root directory for full license.
+ */
+"use strict"
+
+//------------------------------------------------------------------------------
+// Requirements
+//------------------------------------------------------------------------------
+
+const fs = require("fs")
+const path = require("path")
+
+//------------------------------------------------------------------------------
+// Helpers
+//------------------------------------------------------------------------------
+
+const PLACE_HOLDER = /^#[^\n]*\n+(?:- .+\n)*\n*/
+
+//------------------------------------------------------------------------------
+// Exports
+//------------------------------------------------------------------------------
+
+/**
+ * Update the header of `docs/rules/*.md` files.
+ * @param {{id:string,name:string,category:string,description:string,recommended:boolean,fixable:boolean,deprecated:boolean,replacedBy:string[]}[]} rules The rules to update headers.
+ * @returns {void}
+ */
+module.exports = (rules) => {
+    for (const rule of rules) {
+        const filePath = path.join(__dirname, `../docs/rules/${rule.name}.md`)
+        const headerLines = [
+            `# ${rule.description} (${rule.id})`,
+        ]
+
+        if (rule.recommended || rule.deprecated || rule.fixable) {
+            headerLines.push("")
+        }
+        if (rule.deprecated) {
+            headerLines.push(`- ⚠️ This rule was **deprecated** and replaced by ${rule.replacedBy.map(id => `[${id}](${id}.md) rule`).join(", ")}.`)
+        }
+        else if (rule.recommended) {
+            headerLines.push("- 🌟 The `\"extends\": \"plugin:eslint-comments/recommended\"` property in a configuration file enables this rule.")
+        }
+        if (rule.fixable) {
+            headerLines.push("- ✒️ The `--fix` option on the [command line](http://eslint.org/docs/user-guide/command-line-interface#fix) can automatically fix some of the problems reported by this rule.")
+        }
+        headerLines.push("", "")
+
+        fs.writeFileSync(
+            filePath,
+            fs.readFileSync(filePath, "utf8").replace(PLACE_HOLDER, headerLines.join("\n"))
+        )
+    }
+}
diff --git a/scripts/update-readme.js b/scripts/update-readme.js
@@ -0,0 +1,76 @@
+/**
+ * @author Toru Nagashima
+ * @copyright 2017 Toru Nagashima. All rights reserved.
+ * See LICENSE file in root directory for full license.
+ */
+"use strict"
+
+//------------------------------------------------------------------------------
+// Requirements
+//------------------------------------------------------------------------------
+
+const fs = require("fs")
+const path = require("path")
+
+//------------------------------------------------------------------------------
+// Helpers
+//------------------------------------------------------------------------------
+
+const README_FILE_PATH = path.resolve(__dirname, "../README.md")
+const CATEGORIES = ["Best Practices", "Stylistic Issues"]
+const PLACE_HOLDER = /<!--RULES_TABLE_START-->[\s\S]*<!--RULES_TABLE_END-->/
+
+/**
+ * Convert a given rule to a table row.
+ * @param {{id:string,name:string,category:string,description:string,recommended:boolean,fixable:boolean,deprecated:boolean,replacedBy:string[]}} rule The rule object.
+ * @returns {string} The table row of the rule.
+ */
+function toTableRow(rule) {
+    const mark = `${rule.recommended ? "🌟" : ""}${rule.fixable ? "✒️" : ""}`
+    const link = `[${rule.id}](./docs/rules/${rule.id}.md)`
+    const description = rule.description || "(no description)"
+    return `| ${mark} | ${link} | ${description} |\n`
+}
+
+/**
+ * Convert a given category to the section of the category.
+ * @param {string} category The category to convert.
+ * @param {{id:string,name:string,category:string,description:string,recommended:boolean,fixable:boolean,deprecated:boolean,replacedBy:string[]}[]} rules The rules to convert.
+ * @returns {string} The section of the category.
+ */
+function toCategorySection(category, rules) {
+    return `### ${category}
+
+|    | Rule ID | Description |
+|:---|:--------|:------------|
+${
+    rules
+        .filter(rule => rule.category === category && !rule.deprecated)
+        .map(toTableRow)
+        .join("")
+}
+`
+}
+
+//------------------------------------------------------------------------------
+// Exports
+//------------------------------------------------------------------------------
+
+/**
+ * Update `README.md` files.
+ * @param {{id:string,name:string,category:string,description:string,recommended:boolean,fixable:boolean,deprecated:boolean,replacedBy:string[]}[]} rules The rules to update `README.md`.
+ * @returns {void}
+ */
+module.exports = (rules) => {
+    fs.writeFileSync(
+        README_FILE_PATH,
+        fs.readFileSync(README_FILE_PATH, "utf8").replace(
+            PLACE_HOLDER,
+            `<!--RULES_TABLE_START-->\n${
+                CATEGORIES
+                    .map(category => toCategorySection(category, rules))
+                    .join("")
+            }<!--RULES_TABLE_END-->`
+        )
+    )
+}

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		-# disallows `eslint-disable` comments about specific rules (no-restricted-disable)
	`1`	+# disallows `eslint-disable` comments about specific rules (eslint-comments/no-restricted-disable)
`2`	`2`
`3`	`3`	This rule warns `eslint-disable` directive-comments if the comment disable specific rules.
`4`	`4`