@azerion/bunosaurus-mdx-loader 0.0.0-stage → 4.0.0

package/src/remark/unusedDirectives/index.ts

@@ -0,0 +1,171 @@
+/**
+ * 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 'node:path';
+import process from 'node:process';
+import {visit} from 'unist-util-visit';
+import logger from '@docusaurus/logger';
+import {toMessageRelativeFilePath, posixPath} from '@docusaurus/utils';
+import {formatNodePositionExtraMessage, transformNode} from '../utils';
+import type {Root} from 'mdast';
+import type {Parent} from 'unist';
+import type {Transformer, Processor, Plugin} from 'unified';
+import type {Directives, TextDirective} from 'mdast-util-directive';
+import type {
+  MarkdownConfig,
+  OnUnusedMarkdownDirectivesFunction,
+} from '@docusaurus/types';
+
+type DirectiveType = Directives['type'];
+
+const directiveTypes: DirectiveType[] = [
+  'containerDirective',
+  'leafDirective',
+  'textDirective',
+];
+
+const directivePrefixMap: {[key in DirectiveType]: string} = {
+  textDirective: ':',
+  leafDirective: '::',
+  containerDirective: ':::',
+};
+
+function formatDirectiveName(directive: Directives) {
+  const prefix = directivePrefixMap[directive.type];
+  if (!prefix) {
+    throw new Error(
+      `unexpected, no prefix found for directive of type ${directive.type}`,
+    );
+  }
+  // To simplify we don't display the eventual label/props of directives
+  return `${prefix}${directive.name}`;
+}
+
+function formatUnusedDirectiveMessage(directive: Directives) {
+  const name = formatDirectiveName(directive);
+  return `- ${name}${formatNodePositionExtraMessage(directive)}`;
+}
+
+function formatUnusedDirectivesMessage({
+  directives,
+  filePath,
+}: {
+  directives: Directives[];
+  filePath: string;
+}): string {
+  const supportUrl = 'https://github.com/facebook/docusaurus/pull/9394';
+  const customPath = posixPath(path.relative(process.cwd(), filePath));
+  const warningTitle = logger.interpolate`Docusaurus found ${directives.length} unused Markdown directives in file path=${customPath}`;
+  const customSupportUrl = logger.interpolate`url=${supportUrl}`;
+  const warningMessages = directives
+    .map(formatUnusedDirectiveMessage)
+    .join('\n');
+
+  return `${warningTitle}
+${warningMessages}
+Your content might render in an unexpected way. Visit ${customSupportUrl} to find out why and how to fix it.`;
+}
+
+export type PluginOptions = {
+  onUnusedMarkdownDirectives: MarkdownConfig['hooks']['onUnusedMarkdownDirectives'];
+};
+
+function asFunction(
+  onUnusedMarkdownDirectives: PluginOptions['onUnusedMarkdownDirectives'],
+): OnUnusedMarkdownDirectivesFunction {
+  if (typeof onUnusedMarkdownDirectives === 'string') {
+    const extraHelp =
+      onUnusedMarkdownDirectives === 'throw'
+        ? logger.interpolate`\nTo ignore this error, use the code=${'siteConfig.markdown.hooks.onUnusedMarkdownDirectives'} option.`
+        : '';
+    return ({sourceFilePath, directives}) => {
+      const relativePath = toMessageRelativeFilePath(sourceFilePath);
+      logger.report(onUnusedMarkdownDirectives)`${formatUnusedDirectivesMessage(
+        {
+          directives,
+          filePath: relativePath,
+        },
+      )}${extraHelp}`;
+    };
+  } else {
+    return (params) =>
+      onUnusedMarkdownDirectives({
+        ...params,
+        sourceFilePath: toMessageRelativeFilePath(params.sourceFilePath),
+      });
+  }
+}
+
+function isTextDirective(directive: Directives): directive is TextDirective {
+  return directive.type === 'textDirective';
+}
+
+// A simple text directive is one without any label/props
+function isSimpleTextDirective(
+  directive: Directives,
+): directive is TextDirective {
+  if (isTextDirective(directive)) {
+    // Attributes in MDAST = Directive props
+    const hasAttributes =
+      directive.attributes && Object.keys(directive.attributes).length > 0;
+    // Children in MDAST = Directive label
+    const hasChildren = directive.children.length > 0;
+    return !hasAttributes && !hasChildren;
+  }
+  return false;
+}
+
+function transformSimpleTextDirectiveToString(textDirective: Directives) {
+  transformNode(textDirective, {
+    type: 'text',
+    value: `:${textDirective.name}`, // We ignore label/props on purpose here
+  });
+}
+
+function isUnusedDirective(directive: Directives) {
+  // If directive data is set (notably hName/hProperties set by admonitions)
+  // this usually means the directive has been handled by another plugin
+  return !directive.data;
+}
+
+const plugin: Plugin<PluginOptions[], Root> = function plugin(
+  this: Processor,
+  options,
+): Transformer<Root> {
+  const onUnusedMarkdownDirectives = asFunction(
+    options.onUnusedMarkdownDirectives,
+  );
+
+  return (tree, file) => {
+    const unusedDirectives: Directives[] = [];
+
+    // @ts-expect-error: TODO fix type
+    visit<Parent, Directives>(tree, directiveTypes, (directive: Directives) => {
+      // If directive data is set (hName/hProperties set by admonitions)
+      // this usually means the directive has been handled by another plugin
+      if (isUnusedDirective(directive)) {
+        if (isSimpleTextDirective(directive)) {
+          transformSimpleTextDirectiveToString(directive);
+        } else {
+          unusedDirectives.push(directive);
+        }
+      }
+    });
+
+    // We only process unused directives for the client compiler
+    // This avoids emitting duplicate errors/warnings in prod mode
+    // Note: the client compiler is used in both dev/prod modes
+    // Also: the client compiler is what gets used when using crossCompilerCache
+    if (file.data.compilerName === 'client' && unusedDirectives.length > 0) {
+      onUnusedMarkdownDirectives({
+        sourceFilePath: file.path!,
+        directives: unusedDirectives,
+      });
+    }
+  };
+};
+
+export default plugin;

package/src/remark/utils/index.ts

@@ -0,0 +1,99 @@
+/**
+ * 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 logger from '@docusaurus/logger';
+import type {Node} from 'unist';
+import type {MdxJsxAttributeValueExpression} from 'mdast-util-mdx';
+
+/**
+ * Util to transform one node type to another node type
+ * The input node is mutated in place
+ * @param node the node to mutate
+ * @param newNode what the original node should become become
+ */
+export function transformNode<NewNode extends Node>(
+  node: Node,
+  newNode: NewNode,
+): NewNode {
+  Object.keys(node).forEach((key) => {
+    // @ts-expect-error: unsafe but ok
+    delete node[key];
+  });
+  Object.keys(newNode).forEach((key) => {
+    // @ts-expect-error: unsafe but ok
+    node[key] = newNode[key];
+  });
+  return node as NewNode;
+}
+
+export function assetRequireAttributeValue(
+  requireString: string,
+  hash: string,
+): MdxJsxAttributeValueExpression {
+  return {
+    type: 'mdxJsxAttributeValueExpression',
+    value: `require("${requireString}").default${hash && ` + '${hash}'`}`,
+    data: {
+      estree: {
+        type: 'Program',
+        body: [
+          {
+            type: 'ExpressionStatement',
+            expression: {
+              type: 'BinaryExpression',
+              left: {
+                type: 'MemberExpression',
+                object: {
+                  type: 'CallExpression',
+                  callee: {
+                    type: 'Identifier',
+                    name: 'require',
+                  },
+                  arguments: [
+                    {
+                      type: 'Literal',
+                      value: requireString,
+                      raw: `"${requireString}"`,
+                    },
+                  ],
+                  optional: false,
+                },
+                property: {
+                  type: 'Identifier',
+                  name: 'default',
+                },
+                computed: false,
+                optional: false,
+              },
+              operator: '+',
+              right: {
+                type: 'Literal',
+                value: hash,
+                raw: `"${hash}"`,
+              },
+            },
+          },
+        ],
+        sourceType: 'module',
+        comments: [],
+      },
+    },
+  };
+}
+
+function formatNodePosition(node: Node): string | undefined {
+  return node.position?.start
+    ? logger.interpolate`number=${node.position.start.line}:number=${node.position.start.column}`
+    : undefined;
+}
+
+// Returns " (line:column)" when position info is available
+// The initial space is useful to append easily to any existing message
+export function formatNodePositionExtraMessage(node: Node): string {
+  const position = formatNodePosition(node);
+  return `${position ? ` (${position})` : ''}`;
+}

package/src/serializeJS.ts

@@ -0,0 +1,22 @@
+/**
+ * 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 {generate} from 'astring';
+import {valueToEstree} from 'estree-util-value-to-estree';
+
+/**
+ * Serializes a value to a JS expression string, that can be inlined in the
+ * code of a generated JS module, such as the front matter of an MDX file:
+ *
+ * `export const frontMatter = ${serializeJS(frontMatter)};`
+ *
+ * Contrary to JSON, the output preserves values such as `undefined`, `NaN`,
+ * `Infinity` or `Date` instances.
+ */
+export function serializeJS(value: unknown): string {
+  return generate(valueToEstree(value, {instanceAsObject: true}));
+}

package/src/types.d.mts

@@ -0,0 +1,40 @@
+/**
+ * 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 type {WebpackCompilerName} from '@docusaurus/utils';
+
+declare module 'vfile' {
+  /*
+  This map registers the type of the data key of a VFile (TypeScript type).
+  This type can be augmented to register custom data types.
+  See https://github.com/vfile/vfile#datamap
+   */
+  interface DataMap {
+    frontMatter: {[key: string]: unknown};
+    compilerName: WebpackCompilerName;
+    contentTitle?: string;
+  }
+}
+
+declare module 'unist' {
+  interface Data {
+    hName?: string;
+    hProperties?: Record<string, unknown>;
+  }
+}
+
+declare module 'mdast' {
+  interface Data {
+    id?: string;
+    hName?: string;
+    hProperties?: Record<string, unknown>;
+  }
+
+  interface HeadingData {
+    hProperties?: {id?: string};
+  }
+}

package/src/utils.ts

@@ -0,0 +1,134 @@
+/**
+ * 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 logger from '@docusaurus/logger';
+import {escapePath, type WebpackCompilerName} from '@docusaurus/utils';
+import {getProcessor, type SimpleProcessorResult} from './processor';
+import {validateMDXFrontMatter} from './frontMatter';
+import preprocessor from './preprocessor';
+import type {Options} from './options';
+
+/**
+ * Converts assets an object with Webpack require calls code.
+ * This is useful for mdx files to reference co-located assets using relative
+ * paths. Those assets should enter the Webpack assets pipeline and be hashed.
+ * For now, we only handle that for images and paths starting with `./`:
+ *
+ * `{image: "./myImage.png"}` => `{image: require("./myImage.png")}`
+ */
+export function createAssetsExportCode({
+  assets,
+  inlineMarkdownAssetImageFileLoader,
+}: {
+  assets: unknown;
+  inlineMarkdownAssetImageFileLoader: string;
+}): string {
+  if (
+    typeof assets !== 'object' ||
+    !assets ||
+    Object.keys(assets).length === 0
+  ) {
+    return 'undefined';
+  }
+
+  // TODO implementation can be completed/enhanced
+  function createAssetValueCode(assetValue: unknown): string | undefined {
+    if (Array.isArray(assetValue)) {
+      const arrayItemCodes = assetValue.map(
+        (item: unknown) => createAssetValueCode(item) ?? 'undefined',
+      );
+      return `[${arrayItemCodes.join(', ')}]`;
+    }
+    // Only process string values starting with ./
+    // We could enhance this logic and check if file exists on disc?
+    if (typeof assetValue === 'string' && assetValue.startsWith('./')) {
+      // TODO do we have other use-cases than image assets?
+      // Probably not worth adding more support, as we want to move to Webpack 5 new asset system (https://github.com/facebook/docusaurus/pull/4708)
+      return `require("${inlineMarkdownAssetImageFileLoader}${escapePath(
+        assetValue,
+      )}").default`;
+    }
+    return undefined;
+  }
+
+  const assetEntries = Object.entries(assets);
+
+  const codeLines = assetEntries
+    .map(([key, value]: [string, unknown]) => {
+      const assetRequireCode = createAssetValueCode(value);
+      return assetRequireCode ? `"${key}": ${assetRequireCode},` : undefined;
+    })
+    .filter(Boolean);
+
+  return `{\n${codeLines.join('\n')}\n}`;
+}
+
+/**
+ * data.contentTitle is set by the remark contentTitle plugin
+ */
+export function extractContentTitleData(data: {
+  [key: string]: unknown;
+}): string | undefined {
+  return data.contentTitle as string | undefined;
+}
+
+export async function compileToJSX({
+  filePath,
+  fileContent,
+  frontMatter,
+  options,
+  compilerName,
+}: {
+  filePath: string;
+  fileContent: string;
+  frontMatter: Record<string, unknown>;
+  options: Options;
+  compilerName: WebpackCompilerName;
+}): Promise<SimpleProcessorResult> {
+  const preprocessedFileContent = preprocessor({
+    fileContent,
+    filePath,
+    admonitions: options.admonitions,
+    markdownConfig: options.markdownConfig,
+  });
+
+  const mdxFrontMatter = validateMDXFrontMatter(frontMatter.mdx);
+
+  const processor = getProcessor({
+    filePath,
+    options,
+    mdxFrontMatter,
+  });
+
+  try {
+    return await processor.process({
+      content: preprocessedFileContent,
+      filePath,
+      frontMatter,
+      compilerName,
+    });
+  } catch (errorUnknown) {
+    const error = errorUnknown as Error;
+
+    // MDX can emit errors that have useful extra attributes
+    const errorJSON = JSON.stringify(error, null, 2);
+    const errorDetails =
+      errorJSON === '{}'
+        ? // regular JS error case: print stacktrace
+          (error.stack ?? 'N/A')
+        : // MDX error: print extra attributes + stacktrace
+          `${errorJSON}\n${error.stack}`;
+
+    throw new Error(
+      `MDX compilation failed for file ${logger.path(filePath)}\nCause: ${
+        error.message
+      }\nDetails:\n${errorDetails}`,
+      // TODO error cause doesn't seem to be used by Webpack stats.errors :s
+      {cause: errorUnknown},
+    );
+  }
+}