docs: default to sourceType: "module" in rule examples

[fasttime]

Prerequisites checklist

• I have read the contributing guidelines.

What is the purpose of this pull request? (put an "X" next to an item)

[X] Documentation update
[ ] Bug fix (template)
[ ] New rule (template)
[ ] Changes an existing rule (template)
[ ] Add autofix to a rule
[ ] Add a CLI option
[ ] Add something to the core
[ ] Other, please explain:

What changes did you make? (Give an overview)

This PR changes playground links in rule example links such that the sourceType parser option defaults to "module". Currently, the Playground default "script" is used when sourceType is not explicitly specified.

I had to add "sourceType": "script" (and in a few cases other parser options) to a number of rule examples to make sure that their behavior doesn't change. This is necessary for different reasons:

• Some rules explicitly state that they only apply in strict mode, e.g. no-invalid-this.
• Some examples contain syntax that is not allowed in strict mode, such as delete x, duplicate parameter names, octal escape sequences, with statements, etc.
• In some code examples, top-level "use strict" directives are necessary to show how the rule works. In ES modules, these directives are of no use and could be confusing (lines-around-directive).
• The global require() API is associated to script/CommonJS code (global-require).

Some code examples contain syntax that is allowed in scripts but forbidden in ES modules, i.e. top-level function declarations with non-unique names.

var a;
function a() {} // valid in scripts, syntax error in ES modules

Rather than keeping these examples as scripts, it was decided to rename the clashing identifiers in order to avoid a syntax error when parsing as ES modules.

---

This change is a first step towards implementating #17602. It will leave us with 126 syntax errors left in rule examples.

File docs/src/rules/arrow-body-style.md:
  - code block #2 on line 42 cannot be parsed: Identifier 'foo' has already been declared
  - code block #3 on line 60 cannot be parsed: Identifier 'foo' has already been declared
  - code block #4 on line 83 cannot be parsed: Identifier 'foo' has already been declared
  - code block #5 on line 117 cannot be parsed: Identifier 'foo' has already been declared
  - code block #6 on line 130 cannot be parsed: Identifier 'foo' has already been declared
  - code block #7 on line 146 cannot be parsed: Identifier 'foo' has already been declared
  - code block #8 on line 165 cannot be parsed: Identifier 'foo' has already been declared

File docs/src/rules/camelcase.md:
  - code block #1 on line 31 cannot be parsed: Identifier 'foo' has already been declared
  - code block #2 on line 75 cannot be parsed: Identifier 'foo' has already been declared

File docs/src/rules/class-methods-use-this.md:
  - code block #2 on line 78 cannot be parsed: Identifier 'A' has already been declared

File docs/src/rules/constructor-super.md:
  - code block #1 on line 19 cannot be parsed: super() call outside constructor of a subclass
  - code block #2 on line 51 cannot be parsed: Identifier 'A' has already been declared

File docs/src/rules/eol-last.md:
  - code block #2 on line 38 cannot be parsed: Expecting Unicode escape sequence \uXXXX

File docs/src/rules/generator-star.md:
  - no correct code blocks
  - no incorrect code blocks

File docs/src/rules/global-strict.md:
  - no correct code blocks
  - no incorrect code blocks

File docs/src/rules/id-blacklist.md:
  - no correct code blocks
  - no incorrect code blocks

File docs/src/rules/id-denylist.md:
  - code block #1 on line 44 cannot be parsed: Unexpected token }
  - code block #2 on line 84 cannot be parsed: Unexpected token }

File docs/src/rules/id-length.md:
  - code block #1 on line 28 cannot be parsed: Identifier 'x' has already been declared
  - code block #2 on line 63 cannot be parsed: Identifier 'foo' has already been declared
  - code block #3 on line 116 cannot be parsed: Identifier 'foo' has already been declared
  - code block #8 on line 247 cannot be parsed: Identifier 'x' has already been declared

File docs/src/rules/id-match.md:
  - code block #1 on line 32 cannot be parsed: Identifier 'myClass' has already been declared
  - code block #2 on line 64 cannot be parsed: Identifier 'myClass' has already been declared
  - code block #4 on line 121 cannot be parsed: Identifier 'myClass' has already been declared

File docs/src/rules/indent-legacy.md:
  - code block #7 on line 198 cannot be parsed: Identifier 'a' has already been declared
  - code block #8 on line 219 cannot be parsed: Identifier 'a' has already been declared
  - code block #9 on line 240 cannot be parsed: Identifier 'a' has already been declared
  - code block #10 on line 261 cannot be parsed: Identifier 'a' has already been declared

File docs/src/rules/indent.md:
  - code block #9 on line 242 cannot be parsed: Identifier 'a' has already been declared
  - code block #10 on line 263 cannot be parsed: Identifier 'a' has already been declared
  - code block #11 on line 284 cannot be parsed: Identifier 'a' has already been declared
  - code block #12 on line 305 cannot be parsed: Identifier 'a' has already been declared
  - code block #13 on line 326 cannot be parsed: Identifier 'a' has already been declared
  - code block #14 on line 347 cannot be parsed: Identifier 'a' has already been declared
  - code block #44 on line 852 cannot be parsed: Identifier 'foo' has already been declared

File docs/src/rules/jsx-quotes.md:
  - code block #2 on line 52 cannot be parsed: Adjacent JSX elements must be wrapped in an enclosing tag
  - code block #4 on line 79 cannot be parsed: Adjacent JSX elements must be wrapped in an enclosing tag

File docs/src/rules/keyword-spacing.md:
  - code block #2 on line 61 cannot be parsed: Identifier 'a' has already been declared
  - code block #6 on line 176 cannot be parsed: Identifier 'a' has already been declared

File docs/src/rules/lines-around-comment.md:
  - code block #29 on line 660 cannot be parsed: Unexpected token ,

File docs/src/rules/lines-between-class-members.md:
  - code block #4 on line 91 cannot be parsed: Identifier 'Foo' has already been declared
  - code block #5 on line 115 cannot be parsed: Identifier 'Foo' has already been declared

File docs/src/rules/max-len.md:
  - code block #3 on line 72 cannot be parsed: Expecting Unicode escape sequence \uXXXX
  - code block #4 on line 84 cannot be parsed: Expecting Unicode escape sequence \uXXXX

File docs/src/rules/max-params.md:
  - code block #1 on line 39 cannot be parsed: Identifier 'foo' has already been declared
  - code block #2 on line 58 cannot be parsed: Identifier 'foo' has already been declared

File docs/src/rules/max-statements.md:
  - code block #1 on line 45 cannot be parsed: Identifier 'foo' has already been declared
  - code block #2 on line 86 cannot be parsed: Identifier 'foo' has already been declared

File docs/src/rules/newline-after-var.md:
  - code block #1 on line 45 cannot be parsed: Identifier 'greet' has already been declared
  - code block #2 on line 73 cannot be parsed: Identifier 'greet' has already been declared
  - code block #3 on line 107 cannot be parsed: Identifier 'greet' has already been declared
  - code block #4 on line 139 cannot be parsed: Identifier 'greet' has already been declared

File docs/src/rules/no-arrow-condition.md:
  - no correct code blocks

File docs/src/rules/no-delete-var.md:
  - no correct code blocks

File docs/src/rules/no-dupe-class-members.md:
  - code block #1 on line 32 cannot be parsed: Identifier 'Foo' has already been declared
  - code block #2 on line 67 cannot be parsed: Identifier 'Foo' has already been declared

File docs/src/rules/no-empty-static-block.md:
  - code block #2 on line 34 cannot be parsed: Identifier 'Foo' has already been declared

File docs/src/rules/no-extra-parens.md:
  - code block #7 on line 217 cannot be parsed: Identifier 'Component' has already been declared
  - code block #8 on line 233 cannot be parsed: Identifier 'Component' has already been declared
  - code block #9 on line 245 cannot be parsed: Identifier 'Component' has already been declared
  - code block #10 on line 265 cannot be parsed: Identifier 'Component' has already been declared
  - code block #11 on line 285 cannot be parsed: Identifier 'Component' has already been declared

File docs/src/rules/no-invalid-this.md:
  - code block #2 on line 100 cannot be parsed: Identifier 'Foo' has already been declared

File docs/src/rules/no-irregular-whitespace.md:
  - code block #1 on line 72 cannot be parsed: Unexpected character '᠎'
  - code block #6 on line 200 cannot be parsed: Unexpected token `}`. Did you mean `}` or `{"}"}`?

File docs/src/rules/no-loss-of-precision.md:
  - code block #1 on line 16 cannot be parsed: Identifier 'x' has already been declared
  - code block #2 on line 33 cannot be parsed: Identifier 'x' has already been declared

File docs/src/rules/no-misleading-character-class.md:
  - code block #1 on line 58 cannot be parsed: Unexpected token ^
  - code block #2 on line 75 cannot be parsed: Unexpected token ^

File docs/src/rules/no-multi-assign.md:
  - code block #1 on line 25 cannot be parsed: Identifier 'a' has already been declared
  - code block #2 on line 49 cannot be parsed: Identifier 'a' has already been declared

File docs/src/rules/no-multiple-empty-lines.md:
  - code block #5 on line 93 cannot be parsed: Unexpected character '⏎'
  - code block #6 on line 110 cannot be parsed: Unexpected character '⏎'

File docs/src/rules/no-restricted-exports.md:
  - code block #6 on line 141 cannot be parsed: Duplicate export 'default'
  - code block #8 on line 173 cannot be parsed: Duplicate export 'default'

File docs/src/rules/no-restricted-imports.md:
  - code block #7 on line 197 cannot be parsed: Identifier 'AllowedObject' has already been declared

File docs/src/rules/no-script-url.md:
  - no correct code blocks

File docs/src/rules/no-self-compare.md:
  - no correct code blocks

File docs/src/rules/no-sequences.md:
  - code block #3 on line 84 cannot be parsed: Identifier 'foo' has already been declared
  - code block #4 on line 99 cannot be parsed: Identifier 'foo' has already been declared

File docs/src/rules/no-tabs.md:
  - code block #1 on line 15 cannot be parsed: Expecting Unicode escape sequence \uXXXX
  - code block #3 on line 57 cannot be parsed: Expecting Unicode escape sequence \uXXXX

File docs/src/rules/no-this-before-super.md:
  - code block #1 on line 21 cannot be parsed: Identifier 'A' has already been declared
  - code block #2 on line 59 cannot be parsed: Identifier 'A' has already been declared

File docs/src/rules/no-underscore-dangle.md:
  - code block #2 on line 38 cannot be parsed: Identifier 'foo' has already been declared
  - code block #5 on line 102 cannot be parsed: 'super' keyword outside a method
  - code block #7 on line 132 cannot be parsed: Identifier 'Foo' has already been declared
  - code block #8 on line 160 cannot be parsed: Identifier 'Foo' has already been declared
  - code block #9 on line 192 cannot be parsed: Identifier '_bar' has already been declared
  - code block #10 on line 208 cannot be parsed: Identifier 'foo' has already been declared
  - code block #11 on line 221 cannot be parsed: Identifier 'foo' has already been declared
  - code block #12 on line 236 cannot be parsed: Identifier 'foo' has already been declared

File docs/src/rules/no-unexpected-multiline.md:
  - code block #1 on line 29 cannot be parsed: Identifier 'x' has already been declared

File docs/src/rules/no-unused-private-class-members.md:
  - code block #1 on line 18 cannot be parsed: Identifier 'Foo' has already been declared
  - code block #2 on line 55 cannot be parsed: Identifier 'Foo' has already been declared

File docs/src/rules/no-useless-constructor.md:
  - code block #2 on line 52 cannot be parsed: Identifier 'A' has already been declared

File docs/src/rules/no-useless-rename.md:
  - code block #1 on line 58 cannot be parsed: Identifier 'foo' has already been declared
  - code block #2 on line 79 cannot be parsed: Identifier 'foo' has already been declared
  - code block #4 on line 122 cannot be parsed: Duplicate export 'foo'
  - code block #5 on line 135 cannot be parsed: Identifier 'foo' has already been declared

File docs/src/rules/object-curly-newline.md:
  - code block #13 on line 550 cannot be parsed: Identifier 'bar' has already been declared
  - code block #14 on line 575 cannot be parsed: Identifier 'foo' has already been declared

File docs/src/rules/one-var-declaration-per-line.md:
  - code block #1 on line 41 cannot be parsed: Identifier 'a' has already been declared
  - code block #2 on line 57 cannot be parsed: Identifier 'a' has already been declared
  - code block #3 on line 78 cannot be parsed: Identifier 'a' has already been declared
  - code block #4 on line 95 cannot be parsed: Identifier 'a' has already been declared

File docs/src/rules/one-var.md:
  - code block #3 on line 190 cannot be parsed: Identifier 'bar' has already been declared
  - code block #10 on line 412 cannot be parsed: Identifier 'bar' has already been declared

File docs/src/rules/prefer-const.md:
  - code block #1 on line 21 cannot be parsed: Identifier 'a' has already been declared
  - code block #2 on line 57 cannot be parsed: Identifier 'a' has already been declared
  - code block #4 on line 162 cannot be parsed: Identifier 'a' has already been declared

File docs/src/rules/prefer-destructuring.md:
  - code block #2 on line 52 cannot be parsed: Identifier 'foo' has already been declared

File docs/src/rules/require-unicode-regexp.md:
  - code block #2 on line 78 cannot be parsed: Identifier 'f' has already been declared

File docs/src/rules/rest-spread-spacing.md:
  - code block #1 on line 83 cannot be parsed: Unexpected token ...
  - code block #2 on line 100 cannot be parsed: Unexpected token ...
  - code block #3 on line 125 cannot be parsed: Unexpected token ...
  - code block #4 on line 142 cannot be parsed: Unexpected token ...

File docs/src/rules/sort-imports.md:
  - code block #1 on line 74 cannot be parsed: Identifier 'a' has already been declared
  - code block #2 on line 106 cannot be parsed: Identifier 'a' has already been declared

File docs/src/rules/sort-keys.md:
  - code block #1 on line 18 cannot be parsed: Identifier 'obj' has already been declared
  - code block #2 on line 44 cannot be parsed: Identifier 'obj' has already been declared
  - code block #3 on line 115 cannot be parsed: Identifier 'obj' has already been declared
  - code block #4 on line 135 cannot be parsed: Identifier 'obj' has already been declared
  - code block #5 on line 157 cannot be parsed: Identifier 'obj' has already been declared
  - code block #6 on line 171 cannot be parsed: Identifier 'obj' has already been declared
  - code block #9 on line 215 cannot be parsed: Identifier 'obj' has already been declared
  - code block #10 on line 243 cannot be parsed: Identifier 'obj' has already been declared
  - code block #12 on line 315 cannot be parsed: Identifier 'obj' has already been declared

File docs/src/rules/space-before-keywords.md:
  - code block #1 on line 46 cannot be parsed: Identifier 'foo' has already been declared
  - code block #2 on line 69 cannot be parsed: Unexpected token onClick

File docs/src/rules/space-infix-ops.md:
  - code block #1 on line 44 cannot be parsed: Identifier 'a' has already been declared
  - code block #2 on line 69 cannot be parsed: Identifier 'a' has already been declared

File docs/src/rules/yield-star-spacing.md:
  - no incorrect code blocks

The code to generate the above report is the same I've used in #17602 except for adding sourceType: "module" to the default parser options.

check-rule-examples.js

// Put this file into the eslint project folder and run it with `node`.

"use strict";

const { parse } = require("espree");
const { promises: { readFile } } = require("fs");
const glob = require("glob");
const { promisify } = require("util");

/**
 * Tries to parse a specified JavaScript code.
 * @param {string} code The JavaScript code to parse.
 * @param {ParserOptions} parserOptions Explicitly specified parser options.
 * @returns {string|undefined} An error message if the code cannot be parsed, or undefined.
 */
function tryParse(code, parserOptions) {
    try {
        parse(code, { ecmaVersion: "latest", sourceType: "module", ...parserOptions });
    } catch ({ message }) {
        return message;
    }
    return void 0;
}

/**
 * Checks a rule docs file for possible problems.
 * @param {string} file The path of a rule docs file to be checked.
 * @returns {Promise<string[]>} A list of warnings found for the file.
 */
async function checkFile(file) {
    const text = await readFile(file, "utf-8");
    const warnings = [];
    const blockMatches = text.matchAll(/^:::(?<heading>.*?)$\s*^(?<codeBlock>.*?)$\s*^:::$/gmsu);
    let anyCorrectMatches = false;
    let anyIncorrectMatches = false;
    let count = 0;

    for (const blockMatch of blockMatches) {
        const blockNumber = ++count;
        let currentBlock = {
            toString() {
                const lineNumber = text.slice(0, blockMatch.index).match(/\n/gu).length + 1;

                return (currentBlock = `code block #${blockNumber} on line ${lineNumber}`);
            }
        };
        const { heading, codeBlock } = blockMatch.groups;
        const { typeTag, parserOptionsJSON } =
        /^\s*(?<typeTag>\S*)(?:\s+(?<parserOptionsJSON>.*?)\s*)?$/u.exec(heading).groups;

        switch (typeTag) {
            case "correct":
                anyCorrectMatches = true;
                break;
            case "incorrect":
                anyIncorrectMatches = true;
                break;
            default:
                warnings.push(`${currentBlock} has wrong type tag '${typeTag}'`);
                break;
        }
        const codeBlockMatch = /^```(?<langTag>.*?)\n(?<code>.*)\n```$/su.exec(codeBlock);

        if (codeBlockMatch) {
            const { code, langTag } = codeBlockMatch.groups;

            if (!["javascript", "js", "jsx"].includes(langTag)) {
                warnings.push(`${currentBlock} has unexpected language tag '${langTag}'`);
            }
            const parserOptions = parserOptionsJSON ? JSON.parse(parserOptionsJSON) : { };
            const message = tryParse(code, parserOptions);

            if (message) {
                warnings.push(`${currentBlock} cannot be parsed: ${message}`);
            }
        } else {
            warnings.push(`${currentBlock} has no fenced code block`);
        }
    }
    if (!anyCorrectMatches) {
        warnings.push("no correct code blocks");
    }
    if (!anyIncorrectMatches) {
        warnings.push("no incorrect code blocks");
    }
    return warnings;
}

(async function main() {
    const files = await promisify(glob)("docs/src/rules/*.md");
    const warningsList = await Promise.all(files.map(checkFile));

    warningsList.forEach((warnings, index) => {
        if (warnings.length) {
            console.log( // eslint-disable-line no-console -- not for release
                `File ${files[index]}:\n${warnings.map(warning => `  - ${warning}\n`).join("")}`
            );
        }
    });
}());

Is there anything you'd like reviewers to focus on?

[netlify]

✅ Deploy Preview for docs-eslint ready!

Name	Link
🔨 Latest commit	19d48bd
🔍 Latest deploy log	https://app.netlify.com/sites/docs-eslint/deploys/651e9306b24c6a000859797e
😎 Deploy Preview	https://deploy-preview-17615--docs-eslint.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[mdjermanovic]

I think a better fix here would be to change the name of the second function so that it's not a duplicate but also matches the ^UNSAFE_ pattern. It seems very unlikely that the intent was really to redeclare the function. It's much more likely that the intent was to show that the regex can allow multiple different names.

[mdjermanovic]

• Some code examples contain syntax that is allowed in scripts but forbidden in ES modules, i.e. top-level function declarations with non-unique names.

  var a;
  function a() {} // valid in scripts, syntax error in ES modules

  This is such a common pattern that I updated the examples where it occurs in the separate commit 67d3b57. In fact, I'm not even sure that setting the sourceType to script as I did is the best solution to keep things working. Another option would be renaming the identifiers to make them unique. That would work also to fix name clashes that do not involve function declarations, which are not targeted by this PR.

  var a;
  const a = 1; // Syntax error in scripts and ES modules

I think it would be better to rename variables, except in cases where it seems that it was important to specifically show how the rule works with redeclared variables (which should rarely be the case), and use sourceType: "script" only in examples where we definitely need it for specific cases that are important to the logic of the rule, such as certain syntax that isn't allowed in strict mode or declarations that create global variables.

[fasttime]

I think it would be better to rename variables, except in cases where it seems that it was important to specifically show how the rule works with redeclared variables (which should rarely be the case), and use sourceType: "script" only in examples where we definitely need it for specific cases that are important to the logic of the rule, such as certain syntax that isn't allowed in strict mode or declarations that create global variables.

Thanks for the feedback @mdjermanovic. I have removed sourceType: "script" and solved the name conflicts inside the code blocks where I thought it would be appropriate in b248d24. I haven't bothered renaming variables in code blocks that need to stay as scripts for some reason, like those that show syntax which is forbidden in strict mode.
Let me know if this is what you had in mind, or if we should go further and switch more examples to ES modules or apply other changes to the code.

[nzakas]

LGTM. Would like @mdjermanovic to verify his changes before merging.

[mdjermanovic]

Just a few small suggestions/questions, then LGTM.

Some fixed examples still produce parsing errors (e.g., duplicate class or const declarations), but I get that such renaming wasn't part of this task.

[mdjermanovic]

This rule was removed so the change seems unnecessary if we are going to remove the "Open in Playground" button from examples of removed rules?

[mdjermanovic]

This looks like an unusual requirement for this rule. Perhaps it would be better to just replace return; with something else?

[mdjermanovic]

Suggested change

	b(a);
	d(a);

I think this was supposed to refer to the function just above it, which is now d.

[fasttime]

I have done the changes suggested by @mdjermanovic. I'm planning to submit another PR to fix the syntax errors left after this one is merge, including duplicate names in classes or let/const declarations.

[mdjermanovic]

LGTM, thanks!