refactor(content-docs): read category metadata files before autogenerating (#6586)

* refactor(content-docs): read category metadata files before autogenerating

* fix tests

* fix Windows...

* warn user when behavior is undetermined

* oops

* fix typo

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

@@ -5,12 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {
-  DefaultSidebarItemsGenerator,
-  type CategoryMetadataFile,
-} from '../generator';
+import {DefaultSidebarItemsGenerator} from '../generator';
 import type {Sidebar, SidebarItemsGenerator} from '../types';
-import fs from 'fs-extra';
 import {DefaultNumberPrefixParser} from '../../numberPrefix';
 import {isCategoryIndex} from '../../docs';
 
@@ -34,26 +30,11 @@ describe('DefaultSidebarItemsGenerator', () => {
         sidebarCollapsed: true,
         sidebarCollapsible: true,
       },
+      categoriesMetadata: {},
       ...params,
     });
   }
 
-  function mockCategoryMetadataFiles(
-    categoryMetadataFiles: Record<string, Partial<CategoryMetadataFile>>,
-  ) {
-    jest
-      .spyOn(fs, 'pathExists')
-      .mockImplementation(
-        (metadataFilePath) =>
-          typeof categoryMetadataFiles[metadataFilePath] !== 'undefined',
-      );
-    jest.spyOn(fs, 'readFile').mockImplementation(
-      // @ts-expect-error: annoying TS error due to overrides
-      async (metadataFilePath: string) =>
-        JSON.stringify(categoryMetadataFiles[metadataFilePath]),
-    );
-  }
-
   test('generates empty sidebar slice when no docs and emit a warning', async () => {
     const consoleWarn = jest.spyOn(console, 'warn');
     const sidebarSlice = await testDefaultSidebarItemsGenerator({
@@ -133,19 +114,6 @@ describe('DefaultSidebarItemsGenerator', () => {
   });
 
   test('generates complex nested sidebar', async () => {
-    mockCategoryMetadataFiles({
-      '02-Guides/_category_.json': {collapsed: false} as CategoryMetadataFile,
-      '02-Guides/01-SubGuides/_category_.yml': {
-        label: 'SubGuides (metadata file label)',
-        link: {
-          type: 'generated-index',
-          slug: 'subguides-generated-index-slug',
-          title: 'subguides-title',
-          description: 'subguides-description',
-        },
-      },
-    });
-
     const sidebarSlice = await DefaultSidebarItemsGenerator({
       numberPrefixParser: DefaultNumberPrefixParser,
       isCategoryIndex,
@@ -157,6 +125,18 @@ describe('DefaultSidebarItemsGenerator', () => {
         versionName: 'current',
         contentPath: '',
       },
+      categoriesMetadata: {
+        '02-Guides': {collapsed: false},
+        '02-Guides/01-SubGuides': {
+          label: 'SubGuides (metadata file label)',
+          link: {
+            type: 'generated-index',
+            slug: 'subguides-generated-index-slug',
+            title: 'subguides-title',
+            description: 'subguides-description',
+          },
+        },
+      },
       docs: [
         {
           id: 'intro',
@@ -279,24 +259,6 @@ describe('DefaultSidebarItemsGenerator', () => {
   test('generates subfolder sidebar', async () => {
     // Ensure that category metadata file is correctly read
     // fix edge case found in https://github.com/facebook/docusaurus/issues/4638
-    mockCategoryMetadataFiles({
-      'subfolder/subsubfolder/subsubsubfolder2/_category_.yml': {
-        position: 2,
-        label: 'subsubsubfolder2 (_category_.yml label)',
-        className: 'bar',
-      },
-      'subfolder/subsubfolder/subsubsubfolder3/_category_.json': {
-        position: 1,
-        label: 'subsubsubfolder3 (_category_.json label)',
-        collapsible: false,
-        collapsed: false,
-        link: {
-          type: 'doc',
-          id: 'doc1', // This is a "fully-qualified" ID that can't be found locally
-        },
-      },
-    });
-
     const sidebarSlice = await DefaultSidebarItemsGenerator({
       numberPrefixParser: DefaultNumberPrefixParser,
       isCategoryIndex,
@@ -308,6 +270,23 @@ describe('DefaultSidebarItemsGenerator', () => {
         versionName: 'current',
         contentPath: '',
       },
+      categoriesMetadata: {
+        'subfolder/subsubfolder/subsubsubfolder2': {
+          position: 2,
+          label: 'subsubsubfolder2 (_category_.yml label)',
+          className: 'bar',
+        },
+        'subfolder/subsubfolder/subsubsubfolder3': {
+          position: 1,
+          label: 'subsubsubfolder3 (_category_.json label)',
+          collapsible: false,
+          collapsed: false,
+          link: {
+            type: 'doc',
+            id: 'doc1', // This is a "fully-qualified" ID that can't be found locally
+          },
+        },
+      },
       docs: [
         {
           id: 'doc1',
@@ -408,20 +387,6 @@ describe('DefaultSidebarItemsGenerator', () => {
   });
 
   test('uses explicit link over the index/readme.{md,mdx} naming convention', async () => {
-    mockCategoryMetadataFiles({
-      'Category/_category_.yml': {
-        label: 'Category label',
-        link: {
-          type: 'doc',
-          id: 'doc3', // Using a "local doc id" ("doc1" instead of "parent/doc1") on purpose
-        },
-      },
-      'Category2/_category_.yml': {
-        label: 'Category 2 label',
-        link: null,
-      },
-    });
-
     const sidebarSlice = await DefaultSidebarItemsGenerator({
       numberPrefixParser: DefaultNumberPrefixParser,
       item: {
@@ -432,6 +397,19 @@ describe('DefaultSidebarItemsGenerator', () => {
         versionName: 'current',
         contentPath: '',
       },
+      categoriesMetadata: {
+        Category: {
+          label: 'Category label',
+          link: {
+            type: 'doc',
+            id: 'doc3', // Using a "local doc id" ("doc1" instead of "parent/doc1") on purpose
+          },
+        },
+        Category2: {
+          label: 'Category 2 label',
+          link: null,
+        },
+      },
       docs: [
         {
           id: 'parent/doc1',
@@ -541,6 +519,7 @@ describe('DefaultSidebarItemsGenerator', () => {
         versionName: 'current',
         contentPath: '',
       },
+      categoriesMetadata: {},
       docs: [
         {
           id: 'intro',