Merge pull request #84 from bmish/include-exclude-headers

bmish · Oct 9, 2022 · b7884d6 · b7884d6
2 parents 55a843b + 43e3a5d
commit b7884d6
Show file tree

Hide file tree

Showing 5 changed files with 151 additions and 8 deletions.
diff --git a/README.md b/README.md
@@ -120,6 +120,8 @@ If you have any custom configs (besides `all`, `recommended`), you'll need to de
 
 | Name | Description |
 | --- | --- |
+| `--rule-doc-section-include` | (optional) Required section in each rule doc (option can be repeated). |
+| `--rule-doc-section-exclude` | (optional) Disallowed section in each rule doc (option can be repeated). |
 | `--rule-doc-title-format` | (optional) The format to use for rule doc titles. Choices: `desc-parens-prefix-name` (default), `desc-parens-name`, `prefix-name`, `name`. |
 | `--url-configs` | (optional) Link to documentation about the ESLint configurations exported by the plugin. |
 

diff --git a/lib/cli.ts b/lib/cli.ts
@@ -22,6 +22,11 @@ function getCurrentPackageVersion(): string {
   return packageJson.version;
 }
 
+// Used for collecting repeated CLI options into an array.
+function collect(value: string, previous: string[]) {
+  return [...previous, value];
+}
+
 export function run() {
   const program = new Command();
 
@@ -30,6 +35,18 @@ export function run() {
     .addArgument(
       new Argument('[path]', 'path to ESLint plugin root').default('.')
     )
+    .option(
+      '--rule-doc-section-include <section>',
+      '(optional) Required section in each rule doc (option can be repeated).',
+      collect,
+      []
+    )
+    .option(
+      '--rule-doc-section-exclude <section>',
+      '(optional) Disallowed section in each rule doc (option can be repeated).',
+      collect,
+      []
+    )
     .addOption(
       new Option(
         '--rule-doc-title-format <format>',
@@ -44,9 +61,16 @@ export function run() {
     )
     .action(async function (
       path,
-      options: { ruleDocTitleFormat: RuleDocTitleFormat; urlConfigs?: string }
+      options: {
+        ruleDocSectionInclude: string[];
+        ruleDocSectionExclude: string[];
+        ruleDocTitleFormat: RuleDocTitleFormat;
+        urlConfigs?: string;
+      }
     ) {
       await generate(path, {
+        ruleDocSectionInclude: options.ruleDocSectionInclude,
+        ruleDocSectionExclude: options.ruleDocSectionExclude,
         ruleDocTitleFormat: options.ruleDocTitleFormat,
         urlConfigs: options.urlConfigs,
       });

diff --git a/lib/generator.ts b/lib/generator.ts
@@ -45,18 +45,34 @@ function expectSectionHeader(
     findSectionHeader(contents, header)
   );
   if (found !== expected) {
-    console.error(
-      `\`${ruleName}\` rule doc should ${expected ? '' : 'not '}have included ${
-        expected ? 'one' : 'any'
-      } of these headers: ${possibleHeaders.join(', ')}`
-    );
+    if (possibleHeaders.length > 1) {
+      console.error(
+        `\`${ruleName}\` rule doc should ${
+          expected ? '' : 'not '
+        }have included ${
+          expected ? 'one' : 'any'
+        } of these headers: ${possibleHeaders.join(', ')}`
+      );
+    } else {
+      console.error(
+        `\`${ruleName}\` rule doc should ${
+          expected ? '' : 'not '
+        }have included the header: ${possibleHeaders.join(', ')}`
+      );
+    }
+
     process.exitCode = 1;
   }
 }
 
 export async function generate(
   path: string,
-  options?: { ruleDocTitleFormat?: RuleDocTitleFormat; urlConfigs?: string }
+  options?: {
+    ruleDocSectionInclude?: string[];
+    ruleDocSectionExclude?: string[];
+    ruleDocTitleFormat?: RuleDocTitleFormat;
+    urlConfigs?: string;
+  }
 ) {
   const plugin = await loadPlugin(path);
   const pluginPrefix = getPluginPrefix(path);
@@ -138,6 +154,16 @@ export async function generate(
 
     // Check for potential issues with the rule doc.
 
+    // Check for required sections.
+    for (const section of options?.ruleDocSectionInclude || []) {
+      expectSectionHeader(name, contents, [section], true);
+    }
+
+    // Check for disallowed sections.
+    for (const section of options?.ruleDocSectionExclude || []) {
+      expectSectionHeader(name, contents, [section], false);
+    }
+
     // Options section.
     expectSectionHeader(
       name,

diff --git a/package.json b/package.json
@@ -40,7 +40,7 @@
     "lint:types": "tsc",
     "prepublishOnly": "tsc",
     "release": "release-it",
-    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage"
+    "test": "node --max-old-space-size=4096 --experimental-vm-modules node_modules/jest/bin/jest.js --coverage"
   },
   "dependencies": {
     "@typescript-eslint/utils": "^5.38.1",

diff --git a/test/lib/generator-test.ts b/test/lib/generator-test.ts
@@ -2071,5 +2071,96 @@ describe('generator', function () {
         expect(readFileSync('docs/rules/no-foo.md', 'utf8')).toMatchSnapshot();
       });
     });
+
+    describe('with `--rule-doc-section-include` and `--rule-doc-section-exclude` and no problems', function () {
+      beforeEach(function () {
+        mockFs({
+          'package.json': JSON.stringify({
+            name: 'eslint-plugin-test',
+            main: 'index.js',
+            type: 'module',
+          }),
+
+          'index.js': `
+            export default {
+              rules: {
+                'no-foo': { meta: { docs: { description: 'Description for no-foo.'} }, create(context) {} },
+              },
+            };`,
+
+          'README.md': '## Rules\n',
+
+          'docs/rules/no-foo.md': '## Examples\n',
+
+          // Needed for some of the test infrastructure to work.
+          node_modules: mockFs.load(
+            resolve(__dirname, '..', '..', 'node_modules')
+          ),
+        });
+      });
+
+      afterEach(function () {
+        mockFs.restore();
+        jest.resetModules();
+      });
+
+      it('has no issues', async function () {
+        await expect(
+          generate('.', {
+            ruleDocSectionInclude: ['Examples'],
+            ruleDocSectionExclude: ['Unwanted Section'],
+          })
+        ).resolves.toBeUndefined();
+      });
+    });
+
+    describe('with `--rule-doc-section-include` and `--rule-doc-section-exclude` and problems', function () {
+      beforeEach(function () {
+        mockFs({
+          'package.json': JSON.stringify({
+            name: 'eslint-plugin-test',
+            main: 'index.js',
+            type: 'module',
+          }),
+
+          'index.js': `
+            export default {
+              rules: {
+                'no-foo': { meta: { docs: { description: 'Description for no-foo.'} }, create(context) {} },
+              },
+            };`,
+
+          'README.md': '## Rules\n',
+
+          'docs/rules/no-foo.md': '## Unwanted Section\n',
+
+          // Needed for some of the test infrastructure to work.
+          node_modules: mockFs.load(
+            resolve(__dirname, '..', '..', 'node_modules')
+          ),
+        });
+      });
+
+      afterEach(function () {
+        mockFs.restore();
+        jest.resetModules();
+      });
+
+      it('prints errors', async function () {
+        const consoleErrorStub = sinon.stub(console, 'error');
+        await generate('.', {
+          ruleDocSectionInclude: ['Examples'],
+          ruleDocSectionExclude: ['Unwanted Section'],
+        });
+        expect(consoleErrorStub.callCount).toBe(2);
+        expect(consoleErrorStub.firstCall.args).toStrictEqual([
+          '`no-foo` rule doc should have included the header: Examples',
+        ]);
+        expect(consoleErrorStub.secondCall.args).toStrictEqual([
+          '`no-foo` rule doc should not have included the header: Unwanted Section',
+        ]);
+        consoleErrorStub.restore();
+      });
+    });
   });
 });