docs: standardized rule docs heading and option-less Options

[JoshuaKGoldberg]

PR Checklist

• Addresses an existing issue: starts on Rework template for individual Rules pages #4365
• That issue was marked as accepting prs
• Steps in CONTRIBUTING.md were taken

Overview

Applies two changes to all rules .md docs files:

• Changes the top-level heading to be just the rule name, with the description as the following paragraph
• Enforces an ## Options section with a jsonc snippet for just the recommended, non-extension rules without options

Fun little script I used to rewrite all rule docs file headings:

const fs = require('fs');

const dir = fs
  .readdirSync(__dirname)
  .filter(fileName => !fileName.includes('README'));

for (const fileName of dir) {
  const ruleName = fileName.split('.')[0];
  const contents = fs.readFileSync(fileName).toString();
  const firstHeader = contents.match(/^\# (.*)/g)?.[0];
  if (!firstHeader) {
    continue;
  }

  const description = `${firstHeader
    .slice(2)
    .replace(` (\`${ruleName}\`)`, '')}.`;

  const replaced = [
    `# \`${ruleName}\``,
    '',
    description,
    '',
    contents.slice(firstHeader.length + 2),
  ].join('\n');

  fs.writeFileSync(fileName, replaced);
}

[nx-cloud]

☁️ Nx Cloud Report

CI ran the following commands for commit fc3404b. Click to see the status, the terminal output, and the build insights.

📂 See all runs for this branch

---

✅ Successfully ran 48 targets

• Node 12.x - nx run-many --target=typecheck --all --parallel
• Node 16.x - nx test @typescript-eslint/eslint-plugin-tslint
• Node 16.x - nx test @typescript-eslint/eslint-plugin
• Node 12.x - nx test @typescript-eslint/eslint-plugin-internal
• Node 16.x - nx test @typescript-eslint/parser
• Node 12.x - nx test @typescript-eslint/eslint-plugin-tslint
• Node 12.x - nx test @typescript-eslint/eslint-plugin
• Node 16.x - nx test @typescript-eslint/type-utils
• Node 12.x - nx test @typescript-eslint/parser
• Node 16.x - nx test @typescript-eslint/utils
• Node 12.x - nx test @typescript-eslint/type-utils
• Node 16.x - nx test @typescript-eslint/scope-manager
• Node 12.x - nx test @typescript-eslint/utils
• Node 16.x - nx test @typescript-eslint/visitor-keys
• Node 12.x - nx test @typescript-eslint/scope-manager
• Node 12.x - nx test @typescript-eslint/visitor-keys
• Node 16.x - nx test @typescript-eslint/typescript-estree
• Node 12.x - nx test @typescript-eslint/typescript-estree
• Node 16.x - nx run-many --target=build --all --parallel --exclude website --exclude website
• Node 12.x - nx run-many --target=build --all --parallel --exclude website --exclude website
• Node 16.x - nx prebuild @typescript-eslint/types
• Node 12.x - nx run-many --target=build --all --parallel --exclude website --exclude website
• Node 12.x - nx prebuild @typescript-eslint/types
• Node 12.x - nx run-many --target=build --all --parallel --exclude website --exclude website
• Node 12.x - nx prebuild @typescript-eslint/types
• Node 12.x - nx test @typescript-eslint/eslint-plugin-tslint
• Node 12.x - nx test @typescript-eslint/eslint-plugin
• Node 12.x - nx test @typescript-eslint/parser
• Node 12.x - nx prebuild @typescript-eslint/types
• Node 14.x - nx test @typescript-eslint/eslint-plugin-tslint
• Node 12.x - nx test @typescript-eslint/type-utils
• Node 14.x - nx test @typescript-eslint/eslint-plugin
• Node 12.x - nx test @typescript-eslint/utils
• Node 14.x - nx test @typescript-eslint/parser
• Node 12.x - nx test @typescript-eslint/scope-manager
• Node 14.x - nx test @typescript-eslint/type-utils
• Node 12.x - nx test @typescript-eslint/visitor-keys
• Node 14.x - nx test @typescript-eslint/utils
• Node 14.x - nx test @typescript-eslint/scope-manager
• Node 12.x - nx test @typescript-eslint/typescript-estree
• Node 14.x - nx test @typescript-eslint/visitor-keys
• Node 12.x - nx run-many --target=build --all --parallel --exclude website --exclude website
• Node 14.x - nx test @typescript-eslint/typescript-estree
• Node 12.x - nx run-many --target=build --all --parallel --exclude website --exclude website
• Node 14.x - nx run-many --target=build --all --parallel --exclude website --exclude website
• Node 12.x - nx prebuild @typescript-eslint/types
• Node 12.x - nx prebuild @typescript-eslint/types
• Node 14.x - nx prebuild @typescript-eslint/types

---

Sent with 💌 from NxCloud.

[typescript-eslint]

Thanks for the PR, @JoshuaKGoldberg!

typescript-eslint is a 100% community driven project, and we are incredibly grateful that you are contributing to that community.

The core maintainers work on this in their personal time, so please understand that it may not be possible for them to review your work immediately.

Thanks again!

---

🙏 Please, if you or your company is finding typescript-eslint valuable, help us sustain the project by sponsoring it transparently on https://opencollective.com/typescript-eslint. As a thank you, your profile/company logo will be added to our main README which receives thousands of unique visitors per day.

[netlify]

✔️ Deploy Preview for typescript-eslint ready!

🔨 Explore the source changes: fc3404b

🔍 Inspect the deploy log: https://app.netlify.com/sites/typescript-eslint/deploys/61f570220b32b00008f89750

😎 Browse the preview: https://deploy-preview-4367--typescript-eslint.netlify.app

[JoshuaKGoldberg]

Drafting pending resolution in #4365.

[bradzacher]

it'd be good to create a blank .md file that people can use as a template when creating a new rule doc. That would make it super easy for people to adhere to the style/layout without going through a test to check.

otherwise people end up copy-pasting an old rule and then sometimes we have bad text in docs.

[codecov]

Codecov Report

Merging #4367 (fed1694) into main (d4768c0) will increase coverage by 7.40%.
The diff coverage is n/a.

❗ Current head fed1694 differs from pull request most recent head fc3404b. Consider uploading reports for the commit fc3404b to get more accurate results

@@            Coverage Diff             @@
##             main    #4367      +/-   ##
==========================================
+ Coverage   86.97%   94.38%   +7.40%     
==========================================
  Files           5      164     +159     
  Lines         215     9235    +9020     
  Branches       60     2889    +2829     
==========================================
+ Hits          187     8716    +8529     
- Misses         22      300     +278     
- Partials        6      219     +213     

Flag	Coverage Δ
unittest	94.38% <ø> (+7.40%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files	Coverage Δ
...internal/src/rules/no-typescript-default-import.ts
...plugin-internal/src/rules/prefer-ast-types-enum.ts
...gin-internal/src/rules/no-poorly-typed-ts-props.ts
...-internal/src/rules/no-typescript-estree-import.ts
...lugin-internal/src/rules/plugin-test-formatting.ts
packages/eslint-plugin/src/rules/no-redeclare.ts	91.89% <0.00%> (ø)
packages/eslint-plugin/src/rules/return-await.ts	99.00% <0.00%> (ø)
...s/eslint-plugin/src/rules/no-implicit-any-catch.ts	84.61% <0.00%> (ø)
...lugin/src/rules/padding-line-between-statements.ts	93.83% <0.00%> (ø)
...slint-plugin/src/rules/prefer-namespace-keyword.ts	100.00% <0.00%> (ø)
... and 159 more

[bradzacher]