Recognize mdx jsx comments (#5)

* Recognize jsx-style comments in .mdx files

* Build lib

* 0.4.2

README.md

@@ -27,8 +27,7 @@ You can install this package via npm:
 
 ## Tagging your Code as a Best Practice
 
-You can tag blocks of code as best practices with specially formatted
-comments:
+You can tag blocks of code as best practices with specially formatted comments:
 
 ```tsx
 // @BestPractice React Components
@@ -108,6 +107,11 @@ like to insert a best practice:
     <!-- @BestPractice.insert insertIntoStaticDocs -->
     <!-- @BestPractice.end -->
 
+If your file is a `.mdx` Markdown file, use `JSX` style comments instead:
+
+    {/* @BestPractice.insert insertIntoStaticDocs */}
+    {/* @BestPractice.end */}
+
 It's important to have both the start and end lines, as these will be used as
 boundaries of the program to know where to replace the code.
 

lib/cjs/utils/replace.js

@@ -69,14 +69,15 @@ exports.insertBestPracticesIntoDoc = insertBestPracticesIntoDoc;
  * Given lines from a file, return new lines with best practices inserted.
  */
 const replaceBestPractices = (filename, lines, index, getBestPracticeLines) => {
+    const [startRe, endRe] = getInsertREs(filename);
     let inBestPractice = false;
     let lineNumber = 0;
     const newLines = [];
     const insertedIds = [];
     for (const line of lines) {
         lineNumber += 1;
         if (inBestPractice) {
-            if (INSERT_END_RE.test(line)) {
+            if (endRe.test(line)) {
                 inBestPractice = false;
                 // Do not continue, we want to write out the end line
             }
@@ -85,9 +86,9 @@ const replaceBestPractices = (filename, lines, index, getBestPracticeLines) => {
             }
         }
         newLines.push(line);
-        if (INSERT_START_RE.test(line)) {
+        if (startRe.test(line)) {
             inBestPractice = true;
-            const [, bestPracticeId] = INSERT_START_RE.exec(line);
+            const [, bestPracticeId] = startRe.exec(line);
             if (!index.has(bestPracticeId)) {
                 throw new Error(`Missing best practice: file ${filename} at line ${lineNumber} expects best practice ID: ${bestPracticeId}. No best practice with this ID was found.`);
             }
@@ -98,5 +99,18 @@ const replaceBestPractices = (filename, lines, index, getBestPracticeLines) => {
     return [newLines, new Set(insertedIds)];
 };
 exports.replaceBestPractices = replaceBestPractices;
-const INSERT_START_RE = /^\s*<!-- @BestPractice.insert (\S+) -->$/;
-const INSERT_END_RE = /^\s*<!-- @BestPractice.end -->$/;
+/**
+ * Get the regexp to match insertion comments in a documentation file.
+ *
+ * .mdx files use jsx comments rather than html comments.
+ */
+const getInsertREs = (filename) => {
+    if (/\.mdx$/.test(filename)) {
+        return [MDX_INSERT_START_RE, MDX_INSERT_END_RE];
+    }
+    return [MD_INSERT_START_RE, MD_INSERT_END_RE];
+};
+const MD_INSERT_START_RE = /^\s*<!-- @BestPractice.insert (\S+) -->$/;
+const MD_INSERT_END_RE = /^\s*<!-- @BestPractice.end -->$/;
+const MDX_INSERT_START_RE = /^\s*{\/\* @BestPractice.insert (\S+) \*\/}$/;
+const MDX_INSERT_END_RE = /^\s*{\/\* @BestPractice.end \*\/}$/;

lib/esm/utils/replace.js

@@ -40,14 +40,15 @@ exports.insertBestPracticesIntoDoc = insertBestPracticesIntoDoc;
  * Given lines from a file, return new lines with best practices inserted.
  */
 const replaceBestPractices = (filename, lines, index, getBestPracticeLines) => {
+    const [startRe, endRe] = getInsertREs(filename);
     let inBestPractice = false;
     let lineNumber = 0;
     const newLines = [];
     const insertedIds = [];
     for (const line of lines) {
         lineNumber += 1;
         if (inBestPractice) {
-            if (INSERT_END_RE.test(line)) {
+            if (endRe.test(line)) {
                 inBestPractice = false;
                 // Do not continue, we want to write out the end line
             }
@@ -56,9 +57,9 @@ const replaceBestPractices = (filename, lines, index, getBestPracticeLines) => {
             }
         }
         newLines.push(line);
-        if (INSERT_START_RE.test(line)) {
+        if (startRe.test(line)) {
             inBestPractice = true;
-            const [, bestPracticeId] = INSERT_START_RE.exec(line);
+            const [, bestPracticeId] = startRe.exec(line);
             if (!index.has(bestPracticeId)) {
                 throw new Error(`Missing best practice: file ${filename} at line ${lineNumber} expects best practice ID: ${bestPracticeId}. No best practice with this ID was found.`);
             }
@@ -69,5 +70,18 @@ const replaceBestPractices = (filename, lines, index, getBestPracticeLines) => {
     return [newLines, new Set(insertedIds)];
 };
 exports.replaceBestPractices = replaceBestPractices;
-const INSERT_START_RE = /^\s*<!-- @BestPractice.insert (\S+) -->$/;
-const INSERT_END_RE = /^\s*<!-- @BestPractice.end -->$/;
+/**
+ * Get the regexp to match insertion comments in a documentation file.
+ *
+ * .mdx files use jsx comments rather than html comments.
+ */
+const getInsertREs = (filename) => {
+    if (/\.mdx$/.test(filename)) {
+        return [MDX_INSERT_START_RE, MDX_INSERT_END_RE];
+    }
+    return [MD_INSERT_START_RE, MD_INSERT_END_RE];
+};
+const MD_INSERT_START_RE = /^\s*<!-- @BestPractice.insert (\S+) -->$/;
+const MD_INSERT_END_RE = /^\s*<!-- @BestPractice.end -->$/;
+const MDX_INSERT_START_RE = /^\s*{\/\* @BestPractice.insert (\S+) \*\/}$/;
+const MDX_INSERT_END_RE = /^\s*{\/\* @BestPractice.end \*\/}$/;

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@closeio/best-practices-documentation",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Tooling to document best practices in your code base.",
   "author": "Trey Cucco",
   "main": "index.js",

src/utils/replace.test.ts

@@ -4,24 +4,24 @@ import BestPractice from '../BestPractice';
 import { replaceBestPractices } from './replace';
 
 describe(replaceBestPractices, () => {
-  test('replaces best practices correctly', () => {
-    const getBestPracticeLines = (bestPractice: BestPractice) => {
-      return [
-        `\`\`\`${bestPractice.getFileType()}`,
-        ...bestPractice.codeLines,
-        '```',
-      ];
-    };
-
-    const bestPractices = [
-      mockBestPractice({ meta: { id: ['sample_id_1'] } }),
-      mockBestPractice({
-        codeLines: ['const c = a + b'],
-        meta: { id: ['sample_id_2'] },
-      }),
+  const getBestPracticeLines = (bestPractice: BestPractice) => {
+    return [
+      `\`\`\`${bestPractice.getFileType()}`,
+      ...bestPractice.codeLines,
+      '```',
     ];
-    const index = new Map(bestPractices.map((bp) => [bp.getMeta('id'), bp]));
+  };
+
+  const bestPractices = [
+    mockBestPractice({ meta: { id: ['sample_id_1'] } }),
+    mockBestPractice({
+      codeLines: ['const c = a + b'],
+      meta: { id: ['sample_id_2'] },
+    }),
+  ];
+  const index = new Map(bestPractices.map((bp) => [bp.getMeta('id'), bp]));
 
+  test('replaces .md best practices correctly', () => {
     const oldLines = [
       '## A Title',
       '',
@@ -62,4 +62,46 @@ describe(replaceBestPractices, () => {
 
     expect(insertedIds).toEqual(new Set(['sample_id_1']));
   });
+
+  test('replaces .mdx best practices correctly', () => {
+    const oldLines = [
+      '## A Title',
+      '',
+      "Hello and here's the thing.",
+      '',
+      '{/* @BestPractice.insert sample_id_1 */}',
+      'this is',
+      'lines that were',
+      'inserted before',
+      '{/* @BestPractice.end */}',
+      '',
+      "And here's some stuff after",
+    ];
+
+    const [newLines, insertedIds] = replaceBestPractices(
+      'someDocumentation.mdx',
+      oldLines,
+      index,
+      getBestPracticeLines,
+    );
+
+    expect(newLines).toEqual([
+      '## A Title',
+      '',
+      "Hello and here's the thing.",
+      '',
+      '{/* @BestPractice.insert sample_id_1 */}',
+      '```ts',
+      '  const add = (a: number) => (b: number) => {',
+      '    return a + b;',
+      '  };',
+      '  return add(5);',
+      '```',
+      '{/* @BestPractice.end */}',
+      '',
+      "And here's some stuff after",
+    ]);
+
+    expect(insertedIds).toEqual(new Set(['sample_id_1']));
+  });
 });

src/utils/replace.ts

@@ -63,6 +63,7 @@ export const replaceBestPractices = (
   index: Map<string, BestPractice>,
   getBestPracticeLines: (bestPractices: BestPractice) => string[],
 ): [newLines: string[], insertedIds: Set<string>] => {
+  const [startRe, endRe] = getInsertREs(filename);
   let inBestPractice = false;
   let lineNumber = 0;
 
@@ -73,7 +74,7 @@ export const replaceBestPractices = (
     lineNumber += 1;
 
     if (inBestPractice) {
-      if (INSERT_END_RE.test(line)) {
+      if (endRe.test(line)) {
         inBestPractice = false;
         // Do not continue, we want to write out the end line
       } else {
@@ -83,10 +84,10 @@ export const replaceBestPractices = (
 
     newLines.push(line);
 
-    if (INSERT_START_RE.test(line)) {
+    if (startRe.test(line)) {
       inBestPractice = true;
 
-      const [, bestPracticeId] = INSERT_START_RE.exec(line)!;
+      const [, bestPracticeId] = startRe.exec(line)!;
 
       if (!index.has(bestPracticeId)) {
         throw new Error(
@@ -102,5 +103,19 @@ export const replaceBestPractices = (
   return [newLines, new Set(insertedIds)];
 };
 
-const INSERT_START_RE = /^\s*<!-- @BestPractice.insert (\S+) -->$/;
-const INSERT_END_RE = /^\s*<!-- @BestPractice.end -->$/;
+/**
+ * Get the regexp to match insertion comments in a documentation file.
+ *
+ * .mdx files use jsx comments rather than html comments.
+ */
+const getInsertREs = (filename: string): [start: RegExp, end: RegExp] => {
+  if (/\.mdx$/.test(filename)) {
+    return [MDX_INSERT_START_RE, MDX_INSERT_END_RE];
+  }
+  return [MD_INSERT_START_RE, MD_INSERT_END_RE];
+};
+
+const MD_INSERT_START_RE = /^\s*<!-- @BestPractice.insert (\S+) -->$/;
+const MD_INSERT_END_RE = /^\s*<!-- @BestPractice.end -->$/;
+const MDX_INSERT_START_RE = /^\s*{\/\* @BestPractice.insert (\S+) \*\/}$/;
+const MDX_INSERT_END_RE = /^\s*{\/\* @BestPractice.end \*\/}$/;