wip: unused directives plugin

packages/docusaurus-mdx-loader/src/processor.ts

@@ -14,6 +14,7 @@ import details from './remark/details';
 import head from './remark/head';
 import mermaid from './remark/mermaid';
 import transformAdmonitions from './remark/admonitions';
+import unusedDirectivesWarning from './remark/unusedDirectives';
 import codeCompatPlugin from './remark/mdx1Compat/codeCompatPlugin';
 import {getFormat} from './format';
 import type {MDXFrontMatter} from './frontMatter';
@@ -114,6 +115,7 @@ async function createProcessorFactory() {
       gfm,
       options.markdownConfig.mdx1Compat.comments ? comment : null,
       ...(options.remarkPlugins ?? []),
+      unusedDirectivesWarning,
     ].filter((plugin): plugin is MDXPlugin => Boolean(plugin));
 
     // codeCompatPlugin needs to be applied last after user-provided plugins

packages/docusaurus-mdx-loader/src/remark/unusedDirectives/__tests__/__snapshots__/index.test.ts.snap

@@ -0,0 +1,13 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`directives remark plugin default behavior for custom keyword 1`] = `
+"<p>Test directives</p>
+<p><div></div></p>
+<p>Text<div></div></p>
+<p>Text: base</p>
+<div></div>
+<div><p>::::info <strong>Weather</strong>
+On nice days, you can enjoy skiing in the mountains.</p><p>:::danger <em>Storms</em>
+Take care of snowstorms...</p></div>
+<p>::::</p>"
+`;

packages/docusaurus-mdx-loader/src/remark/unusedDirectives/__tests__/index.test.ts

@@ -0,0 +1,49 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import path from 'path';
+import remark2rehype from 'remark-rehype';
+import stringify from 'rehype-stringify';
+import vfile from 'to-vfile';
+import preprocessor from '../../../preprocessor';
+import plugin from '../index';
+
+const processFixture = async (name: string) => {
+  const {remark} = await import('remark');
+  const {default: directives} = await import('remark-directive');
+
+  const filePath = path.join(__dirname, '__fixtures__', `${name}.md`);
+  const file = await vfile.read(filePath);
+  const fileContentPreprocessed = preprocessor({
+    fileContent: file.toString(),
+    filePath,
+    markdownConfig: {
+      mermaid: false,
+      mdx1Compat: {
+        admonitions: false,
+        comments: false,
+        headingIds: false,
+      },
+    },
+  });
+
+  const result = await remark()
+    .use(directives)
+    .use(plugin)
+    .use(remark2rehype)
+    .use(stringify)
+    .process(fileContentPreprocessed);
+
+  return result.value;
+};
+
+describe('directives remark plugin', () => {
+  it('default behavior for custom keyword', async () => {
+    const result = await processFixture('directives');
+    expect(result).toMatchSnapshot();
+  });
+});

packages/docusaurus-mdx-loader/src/remark/unusedDirectives/index.ts

@@ -0,0 +1,74 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import visit from 'unist-util-visit';
+// @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
+import type {Transformer, Processor, Parent} from 'unified';
+
+import type {
+  ContainerDirective,
+  LeafDirective,
+  TextDirective,
+  // @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
+} from 'mdast-util-directive';
+
+// TODO as of April 2023, no way to import/re-export this ESM type easily :/
+// This might change soon, likely after TS 5.2
+// See https://github.com/microsoft/TypeScript/issues/49721#issuecomment-1517839391
+// import type {Plugin} from 'unified';
+type Plugin = any; // TODO fix this asap
+
+const plugin: Plugin = function plugin(this: Processor): Transformer {
+  return (root) => {
+    const unusedDirectives: Array<{
+      name: string;
+      type: string;
+    }> = [];
+    const directiveTypes = [
+      'containerDirective',
+      'leafDirective',
+      'textDirective',
+    ];
+
+    const directiveVisitor = (
+      node: ContainerDirective | LeafDirective | TextDirective,
+    ) => {
+      if (directiveTypes.includes(node.type)) {
+        unusedDirectives.push({
+          name: node.name,
+          type: node.type,
+          // start: node.position.start.line,
+          // path: ` ${filePath}:${node.position.start.line}:${node.position.start.column}`,
+        });
+      }
+    };
+
+    // const directiveVisitor = (
+    //   node: ContainerDirective | LeafDirective | TextDirective,
+    // ) => {
+    //   // Convert the directive to plain text and add it to the
+    //   // unusedDirectives array
+
+    //   unusedDirectives.push(directiveText);
+
+    //   // Remove the directive from the tree
+    //   if (parent) {
+    //     const index = parent.children.indexOf(node);
+    //     if (index !== -1) {
+    //       parent.children.splice(index, 1);
+    //     }
+    //   }
+    // };
+
+    visit<Parent>(root, 'containerDirective', directiveVisitor);
+    visit<Parent>(root, 'leafDirective', directiveVisitor);
+    visit<Parent>(root, 'textDirective', directiveVisitor);
+
+    console.log('Unused Directives:', unusedDirectives);
+  };
+};
+
+export default plugin;