feat: allow content above rule doc title

bmish · Nov 23, 2022 · af208a2 · af208a2
1 parent 1a6850f
commit af208a2
Show file tree

Hide file tree

Showing 4 changed files with 160 additions and 20 deletions.
diff --git a/lib/generator.ts b/lib/generator.ts
@@ -162,9 +162,8 @@ export async function generate(path: string, options?: GenerateOptions) {
       (details) => !ignoreDeprecatedRules || !details.deprecated
     );
 
-  let initializedRuleDoc = false;
-
   // Update rule doc for each rule.
+  let initializedRuleDoc = false;
   for (const { name, description, schema } of details) {
     const pathToDoc = join(path, pathRuleDoc).replace(/{name}/g, name);
 
@@ -243,6 +242,12 @@ export async function generate(path: string, options?: GenerateOptions) {
     }
   }
 
+  if (initRuleDocs && !initializedRuleDoc) {
+    throw new Error(
+      '--init-rule-docs was enabled, but no rule doc file needed to be created.'
+    );
+  }
+
   // Find the README.
   const pathToReadme = getPathWithExactFileNameCasing(join(path, pathRuleList));
   if (!pathToReadme || !existsSync(pathToReadme)) {
@@ -282,10 +287,4 @@ export async function generate(path: string, options?: GenerateOptions) {
   } else {
     writeFileSync(pathToReadme, readmeContentsNew, 'utf8');
   }
-
-  if (initRuleDocs && !initializedRuleDoc) {
-    throw new Error(
-      '--init-rule-docs was enabled, but no rule doc file needed to be created.'
-    );
-  }
 }
diff --git a/lib/markdown.ts b/lib/markdown.ts
@@ -14,14 +14,17 @@ export function replaceOrCreateHeader(
 ) {
   const lines = markdown.split('\n');
 
+  const titleLineIndex = lines.findIndex((line) => line.startsWith('# '));
   const markerLineIndex = lines.indexOf(marker);
+  const hasTitle = titleLineIndex !== -1;
+  const hasMarker = markerLineIndex !== -1;
 
-  if (markerLineIndex === -1 && lines.length > 0 && lines[0].startsWith('# ')) {
-    // No marker present so delete any existing title before we add the new one.
-    lines.splice(0, 1);
-  }
+  const preHeader = hasTitle ? lines.slice(0, titleLineIndex).join('\n') : '';
+  const postHeader = lines
+    .slice(hasMarker ? markerLineIndex + 1 : hasTitle ? titleLineIndex + 1 : 0)
+    .join('\n');
 
-  return `${newHeader}\n${lines.slice(markerLineIndex + 1).join('\n')}`;
+  return `${preHeader ? `${preHeader}\n` : ''}${newHeader}\n${postHeader}`;
 }
 
 /**

diff --git a/test/lib/generate/__snapshots__/comment-markers-test.ts.snap b/test/lib/generate/__snapshots__/comment-markers-test.ts.snap
@@ -46,6 +46,24 @@ exports[`generate (comment markers) no existing comment markers - minimal doc co
 "
 `;
 
+exports[`generate (comment markers) no existing comment markers - rule doc with content above title updates the documentation 1`] = `
+"---
+pageClass: "rule-details"
+sidebarDepth: 0
+title: "plugin/rule-name"
+description: "disallow foo"
+since: "v0.12.0"
+---
+# Description (\`test/no-foo\`)
+
+💼 This rule is enabled in the ✅ \`recommended\` config.
+
+<!-- end auto-generated rule header -->
+Pre-existing notice about the rule being recommended.
+## Rule details
+Details."
+`;
+
 exports[`generate (comment markers) no existing comment markers - with no blank lines in existing content generates the documentation 1`] = `
 "## Rules
 <!-- begin auto-generated rules list -->
@@ -94,6 +112,23 @@ exports[`generate (comment markers) no existing comment markers - with one blank
 Existing rule doc content."
 `;
 
+exports[`generate (comment markers) rule doc with content above title and comment marker updates the documentation 1`] = `
+"---
+pageClass: "rule-details"
+sidebarDepth: 0
+title: "plugin/rule-name"
+description: "disallow foo"
+since: "v0.12.0"
+---
+# Description (\`test/no-foo\`)
+
+💼 This rule is enabled in the ✅ \`recommended\` config.
+
+<!-- end auto-generated rule header -->
+## Rule details
+Details."
+`;
+
 exports[`generate (comment markers) rule doc without header marker but pre-existing header updates the documentation 1`] = `
 "# Description (\`test/no-foo\`)
 

diff --git a/test/lib/generate/comment-markers-test.ts b/test/lib/generate/comment-markers-test.ts
@@ -260,6 +260,60 @@ describe('generate (comment markers)', function () {
     });
   });
 
+  describe('no existing comment markers - rule doc with content above title', function () {
+    beforeEach(function () {
+      mockFs({
+        'package.json': JSON.stringify({
+          name: 'eslint-plugin-test',
+          exports: 'index.js',
+          type: 'module',
+        }),
+
+        'index.js': `
+          export default {
+            rules: {
+              'no-foo': {
+                meta: { docs: { description: 'Description.' }, },
+                create(context) {}
+              },
+            },
+            configs: { recommended: { rules: { 'test/no-foo': 'error', } } }
+          };`,
+
+        'README.md': '## Rules\n',
+
+        // Vuepress-style content above title.
+        'docs/rules/no-foo.md': outdent`
+          ---
+          pageClass: "rule-details"
+          sidebarDepth: 0
+          title: "plugin/rule-name"
+          description: "disallow foo"
+          since: "v0.12.0"
+          ---
+          # Some pre-existing title.
+          Pre-existing notice about the rule being recommended.
+          ## Rule details
+          Details.
+        `,
+
+        // Needed for some of the test infrastructure to work.
+        node_modules: mockFs.load(PATH_NODE_MODULES),
+      });
+    });
+
+    afterEach(function () {
+      mockFs.restore();
+      jest.resetModules();
+    });
+
+    it('updates the documentation', async function () {
+      await generate('.');
+
+      expect(readFileSync('docs/rules/no-foo.md', 'utf8')).toMatchSnapshot();
+    });
+  });
+
   describe('README missing rule list markers but with rules section', function () {
     beforeEach(function () {
       mockFs({
@@ -363,13 +417,7 @@ describe('generate (comment markers)', function () {
                 create(context) {}
               },
             },
-            configs: {
-              recommended: {
-                rules: {
-                  'test/no-foo': 'error',
-                }
-              }
-            }
+            configs: { recommended: { rules: { 'test/no-foo': 'error', } } }
           };`,
 
         'README.md':
@@ -398,4 +446,59 @@ describe('generate (comment markers)', function () {
       expect(readFileSync('docs/rules/no-foo.md', 'utf8')).toMatchSnapshot();
     });
   });
+
+  describe('rule doc with content above title and comment marker', function () {
+    beforeEach(function () {
+      mockFs({
+        'package.json': JSON.stringify({
+          name: 'eslint-plugin-test',
+          exports: 'index.js',
+          type: 'module',
+        }),
+
+        'index.js': `
+          export default {
+            rules: {
+              'no-foo': {
+                meta: { docs: { description: 'Description.' }, },
+                create(context) {}
+              },
+            },
+            configs: { recommended: { rules: { 'test/no-foo': 'error', } } }
+          };`,
+
+        'README.md': '## Rules\n',
+
+        // Vuepress-style content above title.
+        'docs/rules/no-foo.md': outdent`
+          ---
+          pageClass: "rule-details"
+          sidebarDepth: 0
+          title: "plugin/rule-name"
+          description: "disallow foo"
+          since: "v0.12.0"
+          ---
+          # Outdated title.
+          Outdated content.
+          <!-- end auto-generated rule header -->
+          ## Rule details
+          Details.
+        `,
+
+        // Needed for some of the test infrastructure to work.
+        node_modules: mockFs.load(PATH_NODE_MODULES),
+      });
+    });
+
+    afterEach(function () {
+      mockFs.restore();
+      jest.resetModules();
+    });
+
+    it('updates the documentation', async function () {
+      await generate('.');
+
+      expect(readFileSync('docs/rules/no-foo.md', 'utf8')).toMatchSnapshot();
+    });
+  });
 });