Merge pull request #530 from easyops-cn/copilot/fix-529

fix: Fix non-deterministic search-index.json generation

Author: weareoutman

docusaurus-search-local/src/server/utils/postBuildFactory.ts

@@ -82,7 +82,7 @@ export function postBuildFactory(
         docsByDirMap.set("", allDocuments);
       }
 
-      for (const [k, allDocs] of docsByDirMap) {
+      for (const [k, allDocs] of Array.from(docsByDirMap.entries()).sort(([a], [b]) => a.localeCompare(b))) {
         const searchIndex = buildIndex(allDocs, config);
 
         debugInfo(`writing index (/${k}) to disk`);

docusaurus-search-local/src/server/utils/processDocInfos.spec.ts

@@ -49,16 +49,16 @@ describe("processDocInfos", () => {
           {
             outDir: "/build",
             paths: [
-              {
-                filePath: expect.toMatchPath("/build/docs/a/index.html"),
-                type: "docs",
-                url: "/base/docs/a",
-              },
               {
                 filePath: expect.toMatchPath("/build/blog/b/index.html"),
                 type: "blog",
                 url: "/base/blog/b",
               },
+              {
+                filePath: expect.toMatchPath("/build/docs/a/index.html"),
+                type: "docs",
+                url: "/base/docs/a",
+              },
               {
                 filePath: expect.toMatchPath("/build/page/index.html"),
                 type: "page",
@@ -119,16 +119,16 @@ describe("processDocInfos", () => {
           {
             outDir: "/build",
             paths: [
-              {
-                filePath: expect.toMatchPath("/build/docs/a.html"),
-                type: "docs",
-                url: "/base/docs/a",
-              },
               {
                 filePath: expect.toMatchPath("/build/blog/b.html"),
                 type: "blog",
                 url: "/base/blog/b",
               },
+              {
+                filePath: expect.toMatchPath("/build/docs/a.html"),
+                type: "docs",
+                url: "/base/docs/a",
+              },
               {
                 filePath: expect.toMatchPath("/build/page.html"),
                 type: "page",
@@ -189,16 +189,16 @@ describe("processDocInfos", () => {
           {
             outDir: "/build",
             paths: [
-              {
-                filePath: expect.toMatchPath("/build/docs/a/index.html"),
-                type: "docs",
-                url: "/base/docs/a/",
-              },
               {
                 filePath: expect.toMatchPath("/build/blog/b/index.html"),
                 type: "blog",
                 url: "/base/blog/b/",
               },
+              {
+                filePath: expect.toMatchPath("/build/docs/a/index.html"),
+                type: "docs",
+                url: "/base/docs/a/",
+              },
               {
                 filePath: expect.toMatchPath("/build/page/index.html"),
                 type: "page",

docusaurus-search-local/src/server/utils/processDocInfos.ts

@@ -59,8 +59,11 @@ export function processDocInfos(
 
   // Create a list of files to index per document version. This will always include all pages and blogs.
   const result = [];
-  for (const [versionOutDir, docs] of versionData.entries()) {
-    const versionPaths = routesPaths
+  for (const [versionOutDir, docs] of Array.from(versionData.entries()).sort(([a], [b]) => a.localeCompare(b))) {
+    // Sort routesPaths to ensure deterministic processing order
+    const sortedRoutesPaths = routesPaths.slice().sort();
+    
+    const versionPaths = sortedRoutesPaths
       .map<DocInfoWithRoute | undefined>((url: string) => {
         // istanbul ignore next
         if (!url.startsWith(baseUrl)) {

docusaurus-search-local/src/server/utils/scanDocuments.ts

@@ -33,8 +33,9 @@ export async function scanDocuments(
     contentDocuments,
   ];
 
-  await Promise.all(
-    DocInfoWithFilePathList.map(async ({ filePath, url, type }) => {
+  // Process documents in parallel but assign IDs deterministically based on input order
+  const processedDocs = await Promise.all(
+    DocInfoWithFilePathList.map(async ({ filePath, url, type }, index) => {
       debugVerbose(
         `parsing %s file %o of %o`,
         type,
@@ -47,73 +48,82 @@ export async function scanDocuments(
       const parsed = parse(html, type, url, config);
       if (!parsed) {
         // Unlisted content
-        return;
+        return null;
       }
-      const { pageTitle, description, keywords, sections, breadcrumb } = parsed;
+      return { parsed, url, index };
+    })
+  );
 
-      const titleId = getNextDocId();
+  // Process results in input order to ensure deterministic ID assignment
+  for (let i = 0; i < processedDocs.length; i++) {
+    const result = processedDocs[i];
+    if (!result) continue;
+    
+    const { parsed, url } = result;
+    const { pageTitle, description, keywords, sections, breadcrumb } = parsed;
+
+    const titleId = getNextDocId();
+
+    titleDocuments.push({
+      i: titleId,
+      t: pageTitle,
+      u: url,
+      b: breadcrumb,
+    });
+
+    if (description) {
+      descriptionDocuments.push({
+        i: titleId,
+        t: description,
+        s: pageTitle,
+        u: url,
+        p: titleId,
+      });
+    }
 
-      titleDocuments.push({
+    if (keywords) {
+      keywordsDocuments.push({
         i: titleId,
-        t: pageTitle,
+        t: keywords,
+        s: pageTitle,
         u: url,
-        b: breadcrumb,
+        p: titleId,
       });
+    }
 
-      if (description) {
-        descriptionDocuments.push({
-          i: titleId,
-          t: description,
-          s: pageTitle,
-          u: url,
-          p: titleId,
-        });
-      }
+    for (const section of sections) {
+      const trimmedHash = getTrimmedHash(section.hash, url);
 
-      if (keywords) {
-        keywordsDocuments.push({
-          i: titleId,
-          t: keywords,
-          s: pageTitle,
+      if (section.title !== pageTitle) {
+        if (trimmedHash === false) {
+          continue;
+        }
+
+        headingDocuments.push({
+          i: getNextDocId(),
+          t: section.title,
           u: url,
+          h: trimmedHash,
           p: titleId,
         });
       }
 
-      for (const section of sections) {
-        const trimmedHash = getTrimmedHash(section.hash, url);
-
-        if (section.title !== pageTitle) {
-          if (trimmedHash === false) {
-            continue;
-          }
-
-          headingDocuments.push({
-            i: getNextDocId(),
-            t: section.title,
-            u: url,
-            h: trimmedHash,
-            p: titleId,
-          });
+      if (section.content) {
+        if (trimmedHash === false) {
+          continue;
         }
 
-        if (section.content) {
-          if (trimmedHash === false) {
-            continue;
-          }
-
-          contentDocuments.push({
-            i: getNextDocId(),
-            t: section.content,
-            s: section.title || pageTitle,
-            u: url,
-            h: trimmedHash,
-            p: titleId,
-          });
-        }
+        contentDocuments.push({
+          i: getNextDocId(),
+          t: section.content,
+          s: section.title || pageTitle,
+          u: url,
+          h: trimmedHash,
+          p: titleId,
+        });
       }
-    })
-  );
+    }
+  }
   return allDocuments;
 }