feat(options): support CodeBlock's comment (#69)

azu · web-flow · commit ee6692164c70 · 2019-12-18T10:40:13.000+09:00
## Features - Add `checkCodeComment` options Example ```json { "rules": { "prh": { "checkCodeComment": ["js", "javascript"], "rulePaths" :["./prh.yml"] } } } ``` Support `CodeBlock`'s comment `//` and `/*`. ```js // $ is jquery ``` Limitation: It just support JavaScript Code, because I don't found any lang comment parser correctly. fix #38
diff --git a/README.md b/README.md
@@ -52,13 +52,35 @@ You can use `~` as Home directory abbreviation.
 - `checkBlockQuote`(optional) : Check `BlockQuote` node type (default: `false`)
 - `checkEmphasis`(optional) : Check `Emphasis` node type (default: `false`)
 - `checkHeader`(optional) : Check `Header` node type (default: `true`)
+- `checkCodeComment`(optional) : Check `CodeBlock` node's comment for `lang` (default: `[]`)
+    - Set `lang` array like `["<codeblock-lang>"]` for checking CodeBlock
+    - Example: If you want to check JavaScript CodeBlock, set `{ "checkCodeComment": ["js", "javascript"] }` Options
+    - **Note:** Currently only support JavaScript CodeBlock
+        - It use [@babel/parser](https://babeljs.io/docs/en/babel-parser) 
+
+**Examples**:
 
 ```json
 {
     "rules": {
         "prh": {
             "checkEmphasis": true,
-            "checkHeader": false
+            "checkHeader": false,
+            "rulePaths" :["./prh.yml"]
+        }
+    }
+}
+```
+
+Check CodeBlock's comment in JavaScript Code.
+
+
+```json
+{
+    "rules": {
+        "prh": {
+            "checkCodeComment": ["js", "javascript"],
+            "rulePaths" :["./prh.yml"]
         }
     }
 }
@@ -157,7 +179,7 @@ rules:
 
 #### imports
 
-prh.yml can import other yaml file
+`prh.yml` can import other yaml file
 
 ```yaml
 version: 1
diff --git a/package.json b/package.json
@@ -33,6 +33,7 @@
     "prh"
   ],
   "dependencies": {
+    "@babel/parser": "^7.7.5",
     "prh": "^5.4.4",
     "textlint-rule-helper": "^2.1.1",
     "untildify": "^3.0.3"
diff --git a/src/textlint-rule-prh.js b/src/textlint-rule-prh.js
@@ -1,6 +1,8 @@
 // LICENSE : MIT
 "use strict";
 import { RuleHelper } from "textlint-rule-helper";
+
+import { parse } from "@babel/parser";
 /**
  * RegExp#flags polyfill
  */
@@ -21,7 +23,16 @@ const defaultOptions = {
     checkLink: false,
     checkBlockQuote: false,
     checkEmphasis: false,
-    checkHeader: true
+    checkHeader: true,
+    /**
+     * Check CodeBlock text
+     * Default: []
+     */
+    checkCodeComment: [],
+    /**
+     * Report parsing error for debug
+     */
+    debug: false
 };
 
 function createPrhEngine(rulePaths, baseDir) {
@@ -144,6 +155,38 @@ const getConfigBaseDir = context => {
     return textlintRcFilePath ? path.dirname(textlintRcFilePath) : process.cwd();
 };
 
+/**
+ * [Markdown] get actual code value from CodeBlock node
+ * @param {Object} node
+ * @param {string} raw raw value include CodeBlock syntax
+ * @returns {string}
+ */
+function getUntrimmedCode(node, raw) {
+    if (node.type !== "CodeBlock") {
+        return node.value;
+    }
+    // Space indented CodeBlock that has not lang
+    if (!node.lang) {
+        return node.value;
+    }
+
+    // If it is not markdown codeBlock, just use node.value
+    if (!(raw.startsWith("```") && raw.endsWith("```"))) {
+        if (node.value.endsWith("\n")) {
+            return node.value;
+        }
+        return node.value + "\n";
+    }
+    // Markdown(remark) specific hack
+    // https://github.com/wooorm/remark/issues/207#issuecomment-244620590
+    const lines = raw.split("\n");
+    // code lines without the first line and the last line
+    const codeLines = lines.slice(1, lines.length - 1);
+    // add last new line
+    // \n```
+    return codeLines.join("\n") + "\n";
+}
+
 function reporter(context, userOptions = {}) {
     assertOptions(userOptions);
     const options = Object.assign({}, defaultOptions, userOptions);
@@ -159,6 +202,8 @@ function reporter(context, userOptions = {}) {
     const helper = new RuleHelper(context);
     const { Syntax, getSource, report, fixer, RuleError } = context;
     const ignoreNodeTypes = createIgnoreNodeTypes(options, Syntax);
+    const codeCommentTypes = options.checkCodeComment ? options.checkCodeComment : defaultOptions.checkCodeComment;
+    const isDebug = options.debug ? options.debug : defaultOptions.debug;
     return {
         [Syntax.Str](node) {
             if (helper.isChildNode(node, ignoreNodeTypes)) {
@@ -185,6 +230,71 @@ function reporter(context, userOptions = {}) {
                     })
                 );
             });
+        },
+        [Syntax.CodeBlock](node) {
+            const lang = node.lang;
+            if (!lang) {
+                return;
+            }
+            const checkLang = codeCommentTypes.some(type => {
+                return type === node.lang;
+            });
+            if (!checkLang) {
+                return;
+            }
+            const rawText = getSource(node);
+            const codeText = getUntrimmedCode(node, rawText);
+            const sourceBlockDiffIndex = rawText !== node.value ? rawText.indexOf(codeText) : 0;
+            const reportComment = comment => {
+                // to get position from index
+                // https://github.com/prh/prh/issues/29
+                const dummyFilePath = "";
+                // TODO: trim option for value?
+                const text = comment.value;
+                const makeChangeSet = prhEngine.makeChangeSet(dummyFilePath, text);
+                forEachChange(makeChangeSet, text, ({ matchStartIndex, matchEndIndex, actual, expected, prh }) => {
+                    // If result is not changed, should not report
+                    if (actual === expected) {
+                        return;
+                    }
+
+                    const suffix = prh !== null ? "\n" + prh : "";
+                    const messages = actual + " => " + expected + suffix;
+                    const commentIdentifier = comment.type === "CommentBlock" ? "/*" : "//";
+                    const commentStart = sourceBlockDiffIndex + comment.start + commentIdentifier.length;
+                    report(
+                        node,
+                        new RuleError(messages, {
+                            index: commentStart + matchStartIndex,
+                            fix: fixer.replaceTextRange(
+                                [commentStart + matchStartIndex, commentStart + matchEndIndex],
+                                expected
+                            )
+                        })
+                    );
+                });
+            };
+            try {
+                const AST = parse(codeText, {
+                    ranges: true,
+                    allowReturnOutsideFunction: true,
+                    allowAwaitOutsideFunction: true,
+                    allowUndeclaredExports: true,
+                    allowSuperOutsideMethod: true
+                });
+                const comments = AST.comments;
+                if (!comments) {
+                    return;
+                }
+                comments.forEach(comment => {
+                    reportComment(comment);
+                });
+            } catch (error) {
+                if (isDebug) {
+                    console.error(error);
+                    report(node, new RuleError(error.message));
+                }
+            }
         }
     };
 }
diff --git a/test/prh-rule-tester-test.js b/test/prh-rule-tester-test.js
@@ -5,6 +5,8 @@ var tester = new TextLintTester();
 // rule
 import rule from "../src/textlint-rule-prh";
 // ruleName, rule, { valid, invalid }
+const CODE_START_JS = "```js";
+const CODE_END = "```";
 tester.run("prh", rule, {
     valid: [
         {
@@ -25,6 +27,39 @@ tester.run("prh", rule, {
                 rulePaths: [__dirname + "/fixtures/rule.yaml"],
                 checkHeader: false
             }
+        },
+        {
+            text: `${CODE_START_JS}\n" + "\n" + "\n" + "// JavaScript\n" + "var a = 1;\n${CODE_END}`,
+            options: {
+                checkCodeComment: ["js"],
+                rulePaths: [__dirname + "/fixtures/rule.yaml"]
+            }
+        },
+        {
+            text: `${CODE_START_JS}// jquery is wrong, but this check is not by default\n${CODE_END}`,
+            options: {
+                checkCodeComment: [],
+                rulePaths: [__dirname + "/fixtures/rule.yaml"]
+            }
+        },
+        // empty code block
+        {
+            text: `${CODE_START_JS}${CODE_END}`,
+            options: {
+                checkCodeComment: ["js"],
+                rulePaths: [__dirname + "/fixtures/rule.yaml"]
+            }
+        },
+        // The CodeBlock includes invalid syntax, it is just ignored
+        {
+            text: `${CODE_START_JS}
++++++++
+// jquery
+${CODE_START_JS}`,
+            options: {
+                checkCodeComment: ["js"],
+                rulePaths: [__dirname + "/fixtures/rule.yaml"]
+            }
         }
     ],
     invalid: [
@@ -212,6 +247,87 @@ tester.run("prh", rule, {
                 }
             ]
         },
+        // comment
+        {
+            text: `${CODE_START_JS}
+// $ is jquery
+const $ = jquery;
+${CODE_END}`,
+            output: `${CODE_START_JS}
+// $ is jQuery
+const $ = jquery;
+${CODE_END}`,
+            errors: [
+                {
+                    index: 14,
+                    message: "jquery => jQuery"
+                }
+            ],
+            options: {
+                checkCodeComment: ["js"],
+                rulePaths: [__dirname + "/fixtures/rule.yaml"]
+            }
+        },
+        // BlockComment
+        {
+            text: `${CODE_START_JS}
+/**
+ * $ is jquery
+ **/
+const $ = jquery;
+${CODE_END}`,
+            output: `${CODE_START_JS}
+/**
+ * $ is jQuery
+ **/
+const $ = jquery;
+${CODE_END}`,
+            errors: [
+                {
+                    index: 18,
+                    message: "jquery => jQuery"
+                }
+            ],
+            options: {
+                checkCodeComment: ["js"],
+                rulePaths: [__dirname + "/fixtures/rule.yaml"]
+            }
+        },
+        // BlockComment multiple
+        {
+            text:
+                "```javascript\n" +
+                "/**\n" +
+                " * $ is jquery\n" +
+                " **/" +
+                "/**\n" +
+                " * cookie is Cookie\n" +
+                " **/\n" +
+                "```",
+            output:
+                "```javascript\n" +
+                "/**\n" +
+                " * $ is jQuery\n" +
+                " **/" +
+                "/**\n" +
+                " * Cookie is Cookie\n" +
+                " **/\n" +
+                "```",
+            errors: [
+                {
+                    index: 26,
+                    message: "jquery => jQuery"
+                },
+                {
+                    index: 44,
+                    message: "cookie => Cookie"
+                }
+            ],
+            options: {
+                checkCodeComment: ["javascript"],
+                rulePaths: [__dirname + "/fixtures/rule.yaml"]
+            }
+        },
         // example-prh.yml
         {
             text: "jqueryではクッキー。ディフォルトとハードウエアー。(そのとおり)\nサーバはサーバーサイドをjsする。",
diff --git a/yarn.lock b/yarn.lock
