check rule examples for syntax errors

eslint · mdjermanovic · Nov 20, 2023 · Nov 6, 2023 · Nov 6, 2023 · Nov 7, 2023
commit 538e7e8126abb53e7b8744baff38d10f914c90d3
@@ -33,6 +33,8 @@ jobs:
       run: npm run lint:scss
     - name: Lint Docs JS Files
       run: node Makefile lintDocsJS
+    - name: Check Rule Examples
+      run: node Makefile checkRuleExamples
     - name: Build Docs Website
       working-directory: docs
       run: npm run build

@@ -867,6 +867,10 @@ target.checkRuleFiles = function() {
 
 };
 
+target.checkRuleExamples = function() {
+    exec(`${NODE}tools/check-rule-examples.js docs/src/rules/*.md`);
 // determine which files to check 
 let filenames = process.argv.slice(2); 
 if (filenames.length === 0) { 
     filenames = glob.sync("docs/src/rules/*.md", { cwd: BASE_DIR }); 
 } 
 // determine which files to check 
 let filenames = process.argv.slice(2); 
  
 if (filenames.length === 0) { 
     filenames = glob.sync("docs/src/rules/*.md", { cwd: BASE_DIR }); 
 } 
+};
+
 target.checkLicenses = function() {
 
     /**

@@ -14,6 +14,8 @@ const { highlighter, lineNumberPlugin } = require("./src/_plugins/md-syntax-high
 const {
     DateTime
 } = require("luxon");
+const markdownIt = require("markdown-it");
+const markdownItRuleExample = require("./tools/markdown-it-rule-example");
 
 module.exports = function(eleventyConfig) {
 
@@ -113,7 +115,7 @@ module.exports = function(eleventyConfig) {
      * Source: https://github.com/11ty/eleventy/issues/658
      */
     eleventyConfig.addFilter("markdown", value => {
-        const markdown = require("markdown-it")({
+        const markdown = markdownIt({
             html: true
         });
 
@@ -191,57 +193,39 @@ module.exports = function(eleventyConfig) {
         return btoa(unescape(encodeURIComponent(text)));
     }
 
-    /**
-     * Creates markdownItContainer settings for a playground-linked codeblock.
-     * @param {string} name Plugin name and class name to add to the code block.
-     * @returns {[string, object]} Plugin name and options for markdown-it.
-     */
-    function withPlaygroundRender(name) {
-        return [
-            name,
-            {
-                render(tokens, index) {
-                    if (tokens[index].nesting !== 1) {
-                        return "</div>";
-                    }
-
-                    // See https://github.com/eslint/eslint.org/blob/ac38ab41f99b89a8798d374f74e2cce01171be8b/src/playground/App.js#L44
-                    const parserOptionsJSON = tokens[index].info?.split("correct ")[1]?.trim();
-                    const parserOptions = { sourceType: "module", ...(parserOptionsJSON && JSON.parse(parserOptionsJSON)) };
-
-                    // Remove trailing newline and presentational `⏎` characters (https://github.com/eslint/eslint/issues/17627):
-                    const content = tokens[index + 1].content
-                        .replace(/\n$/u, "")
-                        .replace(/⏎(?=\n)/gu, "");
-                    const state = encodeToBase64(
-                        JSON.stringify({
-                            options: { parserOptions },
-                            text: content
-                        })
-                    );
-                    const prefix = process.env.CONTEXT && process.env.CONTEXT !== "deploy-preview"
-                        ? ""
-                        : "https://eslint.org";
-
-                    return `
-                        <div class="${name}">
+    // markdown-it plugin options for playground-linked code blocks in rule examples.
+    const ruleExampleOptions = markdownItRuleExample({
+        open(type, code, parserOptions) {
+
+            // See https://github.com/eslint/eslint.org/blob/ac38ab41f99b89a8798d374f74e2cce01171be8b/src/playground/App.js#L44
+            const state = encodeToBase64(
+                JSON.stringify({
+                    options: { parserOptions },
+                    text: code
+                })
+            );
+            const prefix = process.env.CONTEXT && process.env.CONTEXT !== "deploy-preview"
+                ? ""
+                : "https://eslint.org";
+
+            return `
+                        <div class="${type}">
                             <a class="c-btn c-btn--secondary c-btn--playground" href="${prefix}/play#${state}" target="_blank">
                                 Open in Playground
                             </a>
-                    `.trim();
-                }
-            }
-        ];
-    }
+            `.trim();
+        },
+        close() {
+            return "</div>";
+        }
+    });
 
-    const markdownIt = require("markdown-it");
     const md = markdownIt({ html: true, linkify: true, typographer: true, highlight: (str, lang) => highlighter(md, str, lang) })
         .use(markdownItAnchor, {
             slugify: s => slug(s)
         })
         .use(markdownItContainer, "img-container", {})
-        .use(markdownItContainer, ...withPlaygroundRender("correct"))
-        .use(markdownItContainer, ...withPlaygroundRender("incorrect"))
+        .use(markdownItContainer, "rule-example", ruleExampleOptions)
         .use(markdownItContainer, "warning", {
             render(tokens, idx) {
                 return generateAlertMarkup("warning", tokens, idx);

@@ -0,0 +1,28 @@
+"use strict";
+
+module.exports =
+function markdownItRuleExample({ open, close }) {
+    return {
+        validate(info) {
+            return /^\s*(?:in)?correct(?!\S)/u.test(info);
+        },
+        render(tokens, index) {
+            const tagToken = tokens[index];
+
+            if (tagToken.nesting < 0) {
+                return close ? close() : void 0;
            }
+
+            const { type, parserOptionsJSON } = /^\s*(?<type>\S+)(\s+(?<parserOptionsJSON>.+?))?\s*$/u.exec(tagToken.info).groups;
-            const { type, parserOptionsJSON } = /^\s*(?<type>\S+)(\s+(?<parserOptionsJSON>.+?))?\s*$/u.exec(tagToken.info).groups;
+            const { type, parserOptionsJSON } = /^\s*(?<type>\S+)(\s+(?<parserOptionsJSON>\S.*?))?\s*$/u.exec(tagToken.info).groups;
-            const { type, parserOptionsJSON } = /^\s*(?<type>\S+)(\s+(?<parserOptionsJSON>.+?))?\s*$/u.exec(tagToken.info).groups;
+            const { type, parserOptionsJSON } = /^\s*(?<type>\S+)(\s+(?<parserOptionsJSON>\S.*?))?\s*$/u.exec(tagToken.info).groups;
+            const parserOptions = { sourceType: "module", ...(parserOptionsJSON && JSON.parse(parserOptionsJSON)) };
+            const codeBlockToken = tokens[index + 1];
+
+            // Remove trailing newline and presentational `⏎` characters (https://github.com/eslint/eslint/issues/17627):
+            const code = codeBlockToken.content
+                .replace(/\n$/u, "")
+                .replace(/⏎(?=\n)/gu, "");
+
+            return open(type, code, parserOptions, codeBlockToken);
+        }
+    };
+};
@@ -13,6 +13,7 @@
     "./use-at-your-own-risk": "./lib/unsupported-api.js"
   },
   "scripts": {
+    "build:docs:check-rule-examples": "node Makefile.js checkRuleExamples",
     "build:docs:update-links": "node tools/fetch-docs-links.js",
     "build:site": "node Makefile.js gensite",
     "build:webpack": "node Makefile.js webpack",
@@ -42,6 +43,7 @@
       "git add packages/js/src/configs/eslint-all.js"
     ],
     "docs/src/rules/*.md": [
+      "node tools/check-rule-examples.js",
       "node tools/fetch-docs-links.js",
       "git add docs/src/_data/further_reading_links.json"
     ],
@@ -132,6 +134,8 @@
     "gray-matter": "^4.0.3",
     "lint-staged": "^11.0.0",
     "load-perf": "^0.2.0",
+    "markdown-it": "^12.2.0",
+    "markdown-it-container": "^3.0.0",
     "markdownlint": "^0.31.1",
     "markdownlint-cli": "^0.37.0",
     "marked": "^4.0.8",

@@ -0,0 +1,26 @@
+---
+title: Lorem Ipsum
+---
+
+This file contains rule example code with syntax errors.
+
+<!-- markdownlint-capture -->
+<!-- markdownlint-disable MD040 -->
+::: incorrect { "sourceType": "script" }
+
+```
+export default "foo";
+```
+
+:::
+<!-- markdownlint-restore -->
+
+:::correct
+
+```ts
+const foo = "bar";
+
+const foo = "baz";
+```
+
+:::
@@ -0,0 +1,24 @@
+This file contains rule example code without syntax errors.
+
+::: incorrect
+
 ```js
+export default⏎
+"foo";
+```
+
+:::
+
+::: correct { "ecmaFeatures": { "jsx": true } }
+
+```jsx
+const foo = <bar></bar>;
+```
+
+:::
+
+The following code block is not a rule example, so it won't be checked:
+
+```js
+!@#$%^&*()
+```
@@ -0,0 +1,88 @@
+"use strict";
+
+//------------------------------------------------------------------------------
+// Requirements
+//------------------------------------------------------------------------------
+
+const assert = require("assert");
+const { execFile } = require("child_process");
+const { promisify } = require("util");
+
+//------------------------------------------------------------------------------
+// Helpers
+//------------------------------------------------------------------------------
+
+/**
+ * Runs check-rule-examples on the specified files.
+ * @param {...string} filenames Files to be passed to check-rule-examples.
+ * @returns {Promise<ChildProcess>} An object with properties `stdout` and `stderr` on success.
+ * @throws An object with properties `code`, `stdout` and `stderr` on success.
+ */
+async function runCheckRuleExamples(...filenames) {
+    return await promisify(execFile)(
+        process.execPath,
+        ["--no-deprecation", "tools/check-rule-examples.js", ...filenames]
+    );
+}
+
+//------------------------------------------------------------------------------
+// Tests
+//------------------------------------------------------------------------------
+
+describe("check-rule-examples", () => {
+
+    it("succeeds when not passed any files", async () => {
+        const childProcess = await runCheckRuleExamples();
+
+        assert.strictEqual(childProcess.stdout, "");
+        assert.strictEqual(childProcess.stderr, "");
+    });
+
+    it("succeeds when passed a syntax error free file", async () => {
+        const childProcess = await runCheckRuleExamples("tests/fixtures/good-examples.md");
+
+        assert.strictEqual(childProcess.stdout, "");
+        assert.strictEqual(childProcess.stderr, "");
+    });
+
+    it("fails when passed a file with a syntax error", async () => {
+        const promise = runCheckRuleExamples("tests/fixtures/good-examples.md", "tests/fixtures/bad-examples.md");
+
+        await assert.rejects(
+            promise,
+            {
+                code: 1,
+                stdout: "",
+                stderr:
+                "\n" +
+                "tests/fixtures/bad-examples.md\n" +
+                "  11:4  error  Missing language tag: use one of 'javascript', 'js' or 'jsx'\n" +
+                "  12:1  error  Syntax error: 'import' and 'export' may appear only with 'sourceType: module'\n" +
+                "  20:4  error  Nonstandard language tag 'ts': use one of 'javascript', 'js' or 'jsx'\n" +
+                "  23:7  error  Syntax error: Identifier 'foo' has already been declared\n" +
+                "\n" +
+                "✖ 4 problems (4 errors, 0 warnings)\n" +
+                "\n"
+            }
+        );
+    });
+
+    it("fails when a file cannot be processed", async () => {
+        const promise = runCheckRuleExamples("tests/fixtures/non-existing-examples.md");
+
+        await assert.rejects(
+            promise,
+            {
+                code: 1,
+                stdout: "",
+                stderr:
+                "\n" +
+                "tests/fixtures/non-existing-examples.md\n" +
+                "  0:0  error  Error checking file: ENOENT: no such file or directory, open 'tests/fixtures/non-existing-examples.md'\n" +
+                "\n" +
+                "✖ 1 problem (1 error, 0 warnings)\n" +
+                "\n"
+            }
+        );
+    });
+});