fix(docs): resolve metadata paths with zero-width spaces

Author: danyalahmed1995

packages/docusaurus-plugin-content-docs/src/__tests__/contentHelpers.test.ts

@@ -0,0 +1,106 @@
+/**
+ * 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 {describe, expect, it} from 'vitest';
+import {docuHash} from '@docusaurus/utils';
+import {fromPartial} from '@total-typescript/shoehorn';
+
+import {createContentHelpers} from '../contentHelpers';
+import type {DocMetadata, LoadedContent} from '@docusaurus/plugin-content-docs';
+
+function createLoadedContent(sources: string[]): LoadedContent {
+  return fromPartial<LoadedContent>({
+    loadedVersions: [
+      {
+        docs: sources.map((source) =>
+          fromPartial<DocMetadata>({
+            source,
+          }),
+        ),
+      },
+    ],
+  });
+}
+
+describe('contentHelpers', () => {
+  it('resolves MDX loader metadata sources with zero-width spaces', () => {
+    const asciiHelpers = createContentHelpers();
+    asciiHelpers.updateContent(
+      createLoadedContent([
+        '@site/docs/contribute/vulnerability-report/index.mdx',
+      ]),
+    );
+
+    expect(
+      docuHash(
+        asciiHelpers.getMetadataSource(
+          '@site/docs/contribute/vulnerability-report/index.mdx',
+        ),
+      ),
+    ).toBe('site-docs-contribute-vulnerability-report-index-mdx-59e');
+
+    const trailingZeroWidthSpaceHelpers = createContentHelpers();
+    trailingZeroWidthSpaceHelpers.updateContent(
+      createLoadedContent([
+        '@site/docs/contribute/vulnerability-report\u200B\u200B/index.mdx',
+      ]),
+    );
+
+    expect(
+      docuHash(
+        trailingZeroWidthSpaceHelpers.getMetadataSource(
+          '@site/docs/contribute/vulnerability-report\u200B/index.mdx',
+        ),
+      ),
+    ).toBe('site-docs-contribute-vulnerability-report-index-mdx-b66');
+
+    const internalZeroWidthSpaceHelpers = createContentHelpers();
+    internalZeroWidthSpaceHelpers.updateContent(
+      createLoadedContent([
+        '@site/docs/contribute/vulnerability\u200B-report/index.mdx',
+      ]),
+    );
+
+    expect(
+      docuHash(
+        internalZeroWidthSpaceHelpers.getMetadataSource(
+          '@site/docs/contribute/vulnerability-report/index.mdx',
+        ),
+      ),
+    ).toBe('site-docs-contribute-vulnerability-report-index-mdx-ed8');
+
+    const unicodeHelpers = createContentHelpers();
+    unicodeHelpers.updateContent(
+      createLoadedContent(['@site/docs/contribute/보안-취약점-제보/index.mdx']),
+    );
+
+    expect(
+      docuHash(
+        unicodeHelpers.getMetadataSource(
+          '@site/docs/contribute/보안-취약점-제보/index.mdx',
+        ),
+      ),
+    ).toBe('site-docs-contribute-보안-취약점-제보-index-mdx-6b2');
+  });
+
+  it('reports ambiguous zero-width-space metadata sources clearly', () => {
+    const helpers = createContentHelpers();
+
+    helpers.updateContent(
+      createLoadedContent([
+        '@site/docs/contribute/vulnerability-report/index.mdx',
+        '@site/docs/contribute/vulnerability\u200B-report/index.mdx',
+      ]),
+    );
+
+    expect(() =>
+      helpers.getMetadataSource(
+        '@site/docs/contribute/vulnerability-report/index.mdx',
+      ),
+    ).toThrow(/U\+200B ZERO WIDTH SPACE/);
+  });
+});

packages/docusaurus-plugin-content-docs/src/contentHelpers.ts

@@ -7,28 +7,63 @@
 
 import type {DocMetadata, LoadedContent} from '@docusaurus/plugin-content-docs';
 
+const ZeroWidthSpace = '\u200B';
+
 function indexDocsBySource(content: LoadedContent): Map<string, DocMetadata> {
   const allDocs = content.loadedVersions.flatMap((v) => v.docs);
   return new Map(allDocs.map((doc) => [doc.source, doc]));
 }
 
+function getMetadataSourceKey(source: string): string {
+  return source.replaceAll(ZeroWidthSpace, '');
+}
+
+type ContentHelpers = {
+  updateContent: (content: LoadedContent) => void;
+  sourceToDoc: Map<string, DocMetadata>;
+  sourceToPermalink: Map<string, string>;
+  getMetadataSource: (source: string) => string;
+};
+
 // TODO this is bad, we should have a better way to do this (new lifecycle?)
 //  The source to doc/permalink is a mutable map passed to the mdx loader
 //  See https://github.com/facebook/docusaurus/pull/10457
 //  See https://github.com/facebook/docusaurus/pull/10185
-export function createContentHelpers() {
+export function createContentHelpers(): ContentHelpers {
   const sourceToDoc = new Map<string, DocMetadata>();
   const sourceToPermalink = new Map<string, string>();
+  const metadataSourceKeyToSource = new Map<string, string>();
+  const ambiguousMetadataSourceKeys = new Set<string>();
 
   // Mutable map update :/
   function updateContent(content: LoadedContent): void {
     sourceToDoc.clear();
     sourceToPermalink.clear();
+    metadataSourceKeyToSource.clear();
+    ambiguousMetadataSourceKeys.clear();
     indexDocsBySource(content).forEach((value, key) => {
       sourceToDoc.set(key, value);
       sourceToPermalink.set(key, value.permalink);
+
+      const metadataSourceKey = getMetadataSourceKey(key);
+      const existingSource = metadataSourceKeyToSource.get(metadataSourceKey);
+      if (existingSource && existingSource !== key) {
+        ambiguousMetadataSourceKeys.add(metadataSourceKey);
+        metadataSourceKeyToSource.delete(metadataSourceKey);
+      } else if (!ambiguousMetadataSourceKeys.has(metadataSourceKey)) {
+        metadataSourceKeyToSource.set(metadataSourceKey, key);
+      }
     });
   }
 
-  return {updateContent, sourceToDoc, sourceToPermalink};
+  function getMetadataSource(source: string): string {
+    const metadataSourceKey = getMetadataSourceKey(source);
+    if (ambiguousMetadataSourceKeys.has(metadataSourceKey)) {
+      throw new Error(`Docusaurus could not safely resolve the docs metadata path for "${source}" because multiple docs paths only differ by U+200B ZERO WIDTH SPACE characters.
+Please rename the affected docs files or folders to remove the invisible zero-width spaces.`);
+    }
+    return metadataSourceKeyToSource.get(metadataSourceKey) ?? source;
+  }
+
+  return {updateContent, sourceToDoc, sourceToPermalink, getMetadataSource};
 }

packages/docusaurus-plugin-content-docs/src/index.ts

@@ -150,7 +150,8 @@ export default async function pluginContentDocs(
           // Note that metadataPath must be the same/in-sync as
           // the path from createData for each MDX.
           const aliasedPath = aliasedSitePath(mdxPath, siteDir);
-          return path.join(dataDir, `${docuHash(aliasedPath)}.json`);
+          const metadataSource = contentHelpers.getMetadataSource(aliasedPath);
+          return path.join(dataDir, `${docuHash(metadataSource)}.json`);
         },
         // createAssets converts relative paths to require() calls
         createAssets: ({frontMatter}: {frontMatter: DocFrontMatter}) => ({