@docusaurus/utils 3.9.2 → 3.10.1-canary-6591

package/lib/vcs/vcsDefaultV1.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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 { VcsConfig } from '@docusaurus/types';
+/**
+ * This VCS implements the historical Git automatic strategy.
+ * It is only enabled in production mode, using ad-hoc git log commands.
+ */
+export declare const VcsDefaultV1: VcsConfig;
+//# sourceMappingURL=vcsDefaultV1.d.ts.map

package/lib/vcs/vcsDefaultV1.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vcsDefaultV1.d.ts","sourceRoot":"","sources":["../../src/vcs/vcsDefaultV1.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,mBAAmB,CAAC;AASjD;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,SAU1B,CAAC"}

package/lib/vcs/vcsDefaultV1.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VcsDefaultV1 = void 0;
+const vcsHardcoded_1 = require("./vcsHardcoded");
+const vcsGitAdHoc_1 = require("./vcsGitAdHoc");
+function getDynamicStrategy() {
+    return process.env.NODE_ENV === 'development' ||
+        process.env.NODE_ENV === 'test'
+        ? vcsHardcoded_1.VcsHardcoded
+        : vcsGitAdHoc_1.VcsGitAdHoc;
+}
+/**
+ * This VCS implements the historical Git automatic strategy.
+ * It is only enabled in production mode, using ad-hoc git log commands.
+ */
+exports.VcsDefaultV1 = {
+    initialize: (...params) => {
+        return getDynamicStrategy().initialize(...params);
+    },
+    getFileCreationInfo: (...params) => {
+        return getDynamicStrategy().getFileCreationInfo(...params);
+    },
+    getFileLastUpdateInfo: (...params) => {
+        return getDynamicStrategy().getFileLastUpdateInfo(...params);
+    },
+};
+//# sourceMappingURL=vcsDefaultV1.js.map

package/lib/vcs/vcsDefaultV1.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vcsDefaultV1.js","sourceRoot":"","sources":["../../src/vcs/vcsDefaultV1.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEH,iDAA4C;AAC5C,+CAA0C;AAG1C,SAAS,kBAAkB;IACzB,OAAO,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,aAAa;QAC3C,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,MAAM;QAC/B,CAAC,CAAC,2BAAY;QACd,CAAC,CAAC,yBAAW,CAAC;AAClB,CAAC;AAED;;;GAGG;AACU,QAAA,YAAY,GAAc;IACrC,UAAU,EAAE,CAAC,GAAG,MAAM,EAAE,EAAE;QACxB,OAAO,kBAAkB,EAAE,CAAC,UAAU,CAAC,GAAG,MAAM,CAAC,CAAC;IACpD,CAAC;IACD,mBAAmB,EAAE,CAAC,GAAG,MAAM,EAAE,EAAE;QACjC,OAAO,kBAAkB,EAAE,CAAC,mBAAmB,CAAC,GAAG,MAAM,CAAC,CAAC;IAC7D,CAAC;IACD,qBAAqB,EAAE,CAAC,GAAG,MAAM,EAAE,EAAE;QACnC,OAAO,kBAAkB,EAAE,CAAC,qBAAqB,CAAC,GAAG,MAAM,CAAC,CAAC;IAC/D,CAAC;CACF,CAAC"}

package/lib/vcs/vcsDefaultV2.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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 { VcsConfig } from '@docusaurus/types';
+/**
+ * This VCS implements the new eager Git automatic strategy.
+ * It is only enabled in production mode, reading the git repository eagerly.
+ */
+export declare const VcsDefaultV2: VcsConfig;
+//# sourceMappingURL=vcsDefaultV2.d.ts.map

package/lib/vcs/vcsDefaultV2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vcsDefaultV2.d.ts","sourceRoot":"","sources":["../../src/vcs/vcsDefaultV2.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,mBAAmB,CAAC;AASjD;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,SAU1B,CAAC"}

package/lib/vcs/vcsDefaultV2.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VcsDefaultV2 = void 0;
+const vcsHardcoded_1 = require("./vcsHardcoded");
+const vcsGitEager_1 = require("./vcsGitEager");
+function getStrategy() {
+    return process.env.NODE_ENV === 'development' ||
+        process.env.NODE_ENV === 'test'
+        ? vcsHardcoded_1.VcsHardcoded
+        : vcsGitEager_1.VscGitEager;
+}
+/**
+ * This VCS implements the new eager Git automatic strategy.
+ * It is only enabled in production mode, reading the git repository eagerly.
+ */
+exports.VcsDefaultV2 = {
+    initialize: (...params) => {
+        return getStrategy().initialize(...params);
+    },
+    getFileCreationInfo: (...params) => {
+        return getStrategy().getFileCreationInfo(...params);
+    },
+    getFileLastUpdateInfo: (...params) => {
+        return getStrategy().getFileLastUpdateInfo(...params);
+    },
+};
+//# sourceMappingURL=vcsDefaultV2.js.map

package/lib/vcs/vcsDefaultV2.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vcsDefaultV2.js","sourceRoot":"","sources":["../../src/vcs/vcsDefaultV2.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEH,iDAA4C;AAC5C,+CAA0C;AAG1C,SAAS,WAAW;IAClB,OAAO,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,aAAa;QAC3C,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,MAAM;QAC/B,CAAC,CAAC,2BAAY;QACd,CAAC,CAAC,yBAAW,CAAC;AAClB,CAAC;AAED;;;GAGG;AACU,QAAA,YAAY,GAAc;IACrC,UAAU,EAAE,CAAC,GAAG,MAAM,EAAE,EAAE;QACxB,OAAO,WAAW,EAAE,CAAC,UAAU,CAAC,GAAG,MAAM,CAAC,CAAC;IAC7C,CAAC;IACD,mBAAmB,EAAE,CAAC,GAAG,MAAM,EAAE,EAAE;QACjC,OAAO,WAAW,EAAE,CAAC,mBAAmB,CAAC,GAAG,MAAM,CAAC,CAAC;IACtD,CAAC;IACD,qBAAqB,EAAE,CAAC,GAAG,MAAM,EAAE,EAAE;QACnC,OAAO,WAAW,EAAE,CAAC,qBAAqB,CAAC,GAAG,MAAM,CAAC,CAAC;IACxD,CAAC;CACF,CAAC"}

package/lib/vcs/vcsDisabled.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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 { VcsConfig } from '@docusaurus/types';
+/**
+ * This VCS implementation always returns null values
+ */
+export declare const VcsDisabled: VcsConfig;
+//# sourceMappingURL=vcsDisabled.d.ts.map

package/lib/vcs/vcsDisabled.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vcsDisabled.d.ts","sourceRoot":"","sources":["../../src/vcs/vcsDisabled.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,mBAAmB,CAAC;AAEjD;;GAEG;AACH,eAAO,MAAM,WAAW,EAAE,SAYzB,CAAC"}

package/lib/vcs/vcsDisabled.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VcsDisabled = void 0;
+/**
+ * This VCS implementation always returns null values
+ */
+exports.VcsDisabled = {
+    initialize: () => {
+        // Noop
+    },
+    getFileCreationInfo: async (_filePath) => {
+        return null;
+    },
+    getFileLastUpdateInfo: async (_ilePath) => {
+        return null;
+    },
+};
+//# sourceMappingURL=vcsDisabled.js.map

package/lib/vcs/vcsDisabled.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vcsDisabled.js","sourceRoot":"","sources":["../../src/vcs/vcsDisabled.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAIH;;GAEG;AACU,QAAA,WAAW,GAAc;IACpC,UAAU,EAAE,GAAG,EAAE;QACf,OAAO;IACT,CAAC;IAED,mBAAmB,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE;QACvC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,qBAAqB,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE;QACxC,OAAO,IAAI,CAAC;IACd,CAAC;CACF,CAAC"}

package/lib/vcs/vcsGitAdHoc.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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 { VcsConfig } from '@docusaurus/types';
+/**
+ * A VCS strategy to query Git information in an ad-hoc way.
+ * This is the default/historical Docusaurus Git VCS implementation.
+ * Unfortunately, it is a major bottleneck for large sites/repositories.
+ *
+ * See also https://github.com/facebook/docusaurus/issues/11208
+ */
+export declare const VcsGitAdHoc: VcsConfig;
+//# sourceMappingURL=vcsGitAdHoc.d.ts.map

package/lib/vcs/vcsGitAdHoc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vcsGitAdHoc.d.ts","sourceRoot":"","sources":["../../src/vcs/vcsGitAdHoc.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,mBAAmB,CAAC;AAEjD;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,EAAE,SAYzB,CAAC"}

package/lib/vcs/vcsGitAdHoc.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VcsGitAdHoc = void 0;
+const gitUtils_1 = require("./gitUtils");
+/**
+ * A VCS strategy to query Git information in an ad-hoc way.
+ * This is the default/historical Docusaurus Git VCS implementation.
+ * Unfortunately, it is a major bottleneck for large sites/repositories.
+ *
+ * See also https://github.com/facebook/docusaurus/issues/11208
+ */
+exports.VcsGitAdHoc = {
+    initialize: () => {
+        // Nothing to do here for the default/historical Git implementation
+    },
+    getFileCreationInfo: async (filePath) => {
+        return (0, gitUtils_1.getGitCreation)(filePath);
+    },
+    getFileLastUpdateInfo: async (filePath) => {
+        return (0, gitUtils_1.getGitLastUpdate)(filePath);
+    },
+};
+//# sourceMappingURL=vcsGitAdHoc.js.map

package/lib/vcs/vcsGitAdHoc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vcsGitAdHoc.js","sourceRoot":"","sources":["../../src/vcs/vcsGitAdHoc.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEH,yCAA4D;AAG5D;;;;;;GAMG;AACU,QAAA,WAAW,GAAc;IACpC,UAAU,EAAE,GAAG,EAAE;QACf,mEAAmE;IACrE,CAAC;IAED,mBAAmB,EAAE,KAAK,EAAE,QAAgB,EAAE,EAAE;QAC9C,OAAO,IAAA,yBAAc,EAAC,QAAQ,CAAC,CAAC;IAClC,CAAC;IAED,qBAAqB,EAAE,KAAK,EAAE,QAAgB,EAAE,EAAE;QAChD,OAAO,IAAA,2BAAgB,EAAC,QAAQ,CAAC,CAAC;IACpC,CAAC;CACF,CAAC"}

package/lib/vcs/vcsGitEager.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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 { VcsConfig } from '@docusaurus/types';
+export declare function createVcsGitEagerConfig(): VcsConfig;
+export declare const VscGitEager: VcsConfig;
+//# sourceMappingURL=vcsGitEager.d.ts.map

package/lib/vcs/vcsGitEager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vcsGitEager.d.ts","sourceRoot":"","sources":["../../src/vcs/vcsGitEager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAUH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,mBAAmB,CAAC;AAmEjD,wBAAgB,uBAAuB,IAAI,SAAS,CAiDnD;AAGD,eAAO,MAAM,WAAW,EAAE,SAAqC,CAAC"}

package/lib/vcs/vcsGitEager.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VscGitEager = void 0;
+exports.createVcsGitEagerConfig = createVcsGitEagerConfig;
+const tslib_1 = require("tslib");
+const node_path_1 = require("node:path");
+const logger_1 = tslib_1.__importStar(require("@docusaurus/logger"));
+const gitUtils_1 = require("./gitUtils");
+// The Map keys should be absolute file paths, not relative Git paths
+function resolveFileInfoMapPaths(repoRoot, filesInfo) {
+    function transformMapEntry(entry) {
+        // We just resolve the Git paths that are relative to the repo root
+        return [(0, node_path_1.resolve)(repoRoot, entry[0]), entry[1]];
+    }
+    return new Map(Array.from(filesInfo.entries()).map(transformMapEntry));
+}
+function mergeFileMaps(fileMaps) {
+    return new Map(fileMaps.flatMap((m) => [...m]));
+}
+async function loadAllGitFilesInfoMap(cwd) {
+    const roots = await logger_1.PerfLogger.async('Reading Git root dirs', () => (0, gitUtils_1.getGitAllRepoRoots)(cwd));
+    const allMaps = await Promise.all(roots.map(async (root) => {
+        const map = await logger_1.PerfLogger.async(`Reading Git history for repo ${logger_1.default.path((0, node_path_1.basename)(root))}`, () => (0, gitUtils_1.getGitRepositoryFilesInfo)(root));
+        return resolveFileInfoMapPaths(root, map);
+    }));
+    return mergeFileMaps(allMaps);
+}
+async function initialize({ siteDir, }) {
+    try {
+        const isInWorktree = await (0, gitUtils_1.isGitInsideWorktree)(siteDir);
+        if (!isInWorktree) {
+            return { type: 'error', reason: 'not-in-worktree' };
+        }
+        const filesMap = await loadAllGitFilesInfoMap(siteDir);
+        return { type: 'success', filesMap };
+    }
+    catch (error) {
+        return { type: 'error', reason: 'unknown', cause: error };
+    }
+}
+function createVcsGitEagerConfig() {
+    let initPromise = null;
+    async function getGitFileInfo(filePath) {
+        const init = (await initPromise);
+        if (init.type === 'success') {
+            return init.filesMap.get(filePath) ?? null;
+        }
+        else if (init.reason === 'not-in-worktree') {
+            throw new Error(`This Docusaurus site is outside any Git worktree.
+Unable to read Git info for file ${logger_1.default.path(filePath)} `);
+        }
+        else {
+            throw init.cause;
+        }
+    }
+    return {
+        initialize: ({ siteDir }) => {
+            if (initPromise) {
+                // We only initialize this VCS once!
+                // For i18n sites, this permits reading ahead of time for all locales
+                // so that it only slows down the first locale
+                // I assume this logic is fine, but we'll see if it causes trouble
+                // Note: we could also only call "initialize()" once from the outside,
+                // But maybe it could be useful for custom VCS implementations to be
+                // able to initialize once per locale?
+                logger_1.PerfLogger.log('Git Eager VCS strategy already initialized, skipping re-initialization');
+                return;
+            }
+            initPromise = logger_1.PerfLogger.async('Git Eager VCS init', () => initialize({ siteDir }));
+        },
+        getFileCreationInfo: async (filePath) => {
+            const fileInfo = await getGitFileInfo(filePath);
+            return fileInfo?.creation ?? null;
+        },
+        getFileLastUpdateInfo: async (filePath) => {
+            const fileInfo = await getGitFileInfo(filePath);
+            return fileInfo?.lastUpdate ?? null;
+        },
+    };
+}
+// TODO it probably shouldn't be a singleton, but good enough for now
+exports.VscGitEager = createVcsGitEagerConfig();
+//# sourceMappingURL=vcsGitEager.js.map

package/lib/vcs/vcsGitEager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vcsGitEager.js","sourceRoot":"","sources":["../../src/vcs/vcsGitEager.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AA6EH,0DAiDC;;AA5HD,yCAA4C;AAC5C,qEAAsD;AACtD,yCAIoB;AAIpB,qEAAqE;AACrE,SAAS,uBAAuB,CAC9B,QAAgB,EAChB,SAAyB;IAEzB,SAAS,iBAAiB,CACxB,KAA4B;QAE5B,mEAAmE;QACnE,OAAO,CAAC,IAAA,mBAAO,EAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACjD,CAAC;IAED,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC;AACzE,CAAC;AAED,SAAS,aAAa,CAAC,QAA0B;IAC/C,OAAO,IAAI,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AAClD,CAAC;AAED,KAAK,UAAU,sBAAsB,CAAC,GAAW;IAC/C,MAAM,KAAK,GAAG,MAAM,mBAAU,CAAC,KAAK,CAAC,uBAAuB,EAAE,GAAG,EAAE,CACjE,IAAA,6BAAkB,EAAC,GAAG,CAAC,CACxB,CAAC;IAEF,MAAM,OAAO,GAAqB,MAAM,OAAO,CAAC,GAAG,CACjD,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE;QACvB,MAAM,GAAG,GAAG,MAAM,mBAAU,CAAC,KAAK,CAChC,gCAAgC,gBAAM,CAAC,IAAI,CAAC,IAAA,oBAAQ,EAAC,IAAI,CAAC,CAAC,EAAE,EAC7D,GAAG,EAAE,CAAC,IAAA,oCAAyB,EAAC,IAAI,CAAC,CACtC,CAAC;QACF,OAAO,uBAAuB,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC5C,CAAC,CAAC,CACH,CAAC;IAEF,OAAO,aAAa,CAAC,OAAO,CAAC,CAAC;AAChC,CAAC;AAaD,KAAK,UAAU,UAAU,CAAC,EACxB,OAAO,GAGR;IACC,IAAI,CAAC;QACH,MAAM,YAAY,GAAG,MAAM,IAAA,8BAAmB,EAAC,OAAO,CAAC,CAAC;QACxD,IAAI,CAAC,YAAY,EAAE,CAAC;YAClB,OAAO,EAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAC,CAAC;QACpD,CAAC;QACD,MAAM,QAAQ,GAAG,MAAM,sBAAsB,CAAC,OAAO,CAAC,CAAC;QACvD,OAAO,EAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAC,CAAC;IACrC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,EAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,KAAc,EAAC,CAAC;IACnE,CAAC;AACH,CAAC;AAED,SAAgB,uBAAuB;IACrC,IAAI,WAAW,GAAqC,IAAI,CAAC;IAEzD,KAAK,UAAU,cAAc,CAAC,QAAgB;QAC5C,MAAM,IAAI,GAAG,CAAC,MAAM,WAAW,CAAE,CAAC;QAClC,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC5B,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC;QAC7C,CAAC;aAAM,IAAI,IAAI,CAAC,MAAM,KAAK,iBAAiB,EAAE,CAAC;YAC7C,MAAM,IAAI,KAAK,CACb;mCAC2B,gBAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CACpD,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,CAAC,KAAK,CAAC;QACnB,CAAC;IACH,CAAC;IAED,OAAO;QACL,UAAU,EAAE,CAAC,EAAC,OAAO,EAAC,EAAE,EAAE;YACxB,IAAI,WAAW,EAAE,CAAC;gBAChB,oCAAoC;gBACpC,qEAAqE;gBACrE,8CAA8C;gBAC9C,kEAAkE;gBAElE,sEAAsE;gBACtE,oEAAoE;gBACpE,sCAAsC;gBACtC,mBAAU,CAAC,GAAG,CACZ,wEAAwE,CACzE,CAAC;gBACF,OAAO;YACT,CAAC;YAED,WAAW,GAAG,mBAAU,CAAC,KAAK,CAAC,oBAAoB,EAAE,GAAG,EAAE,CACxD,UAAU,CAAC,EAAC,OAAO,EAAC,CAAC,CACtB,CAAC;QACJ,CAAC;QAED,mBAAmB,EAAE,KAAK,EAAE,QAAgB,EAAE,EAAE;YAC9C,MAAM,QAAQ,GAAG,MAAM,cAAc,CAAC,QAAQ,CAAC,CAAC;YAChD,OAAO,QAAQ,EAAE,QAAQ,IAAI,IAAI,CAAC;QACpC,CAAC;QAED,qBAAqB,EAAE,KAAK,EAAE,QAAgB,EAAE,EAAE;YAChD,MAAM,QAAQ,GAAG,MAAM,cAAc,CAAC,QAAQ,CAAC,CAAC;YAChD,OAAO,QAAQ,EAAE,UAAU,IAAI,IAAI,CAAC;QACtC,CAAC;KACF,CAAC;AACJ,CAAC;AAED,qEAAqE;AACxD,QAAA,WAAW,GAAc,uBAAuB,EAAE,CAAC"}

package/lib/vcs/vcsHardcoded.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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 { VcsConfig, VcsChangeInfo } from '@docusaurus/types';
+export declare const VCS_HARDCODED_CREATION_INFO: VcsChangeInfo;
+export declare const VCS_HARDCODED_LAST_UPDATE_INFO: VcsChangeInfo;
+export declare const VCS_HARDCODED_UNTRACKED_FILE_PATH: string;
+/**
+ * This VCS implementation always returns hardcoded values for testing purposes.
+ * It is also useful in dev environments where VCS info is not important.
+ * Reading information from the VCS can be slow and is not always necessary.
+ */
+export declare const VcsHardcoded: VcsConfig;
+//# sourceMappingURL=vcsHardcoded.d.ts.map

package/lib/vcs/vcsHardcoded.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vcsHardcoded.d.ts","sourceRoot":"","sources":["../../src/vcs/vcsHardcoded.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAE,aAAa,EAAC,MAAM,mBAAmB,CAAC;AAEhE,eAAO,MAAM,2BAA2B,EAAE,aAGzC,CAAC;AAEF,eAAO,MAAM,8BAA8B,EAAE,aAG5C,CAAC;AAEF,eAAO,MAAM,iCAAiC,QAAmC,CAAC;AAElF;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,SAkB1B,CAAC"}

package/lib/vcs/vcsHardcoded.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VcsHardcoded = exports.VCS_HARDCODED_UNTRACKED_FILE_PATH = exports.VCS_HARDCODED_LAST_UPDATE_INFO = exports.VCS_HARDCODED_CREATION_INFO = void 0;
+exports.VCS_HARDCODED_CREATION_INFO = {
+    timestamp: 1490997600000, // 1st Apr 2017
+    author: 'Creator',
+};
+exports.VCS_HARDCODED_LAST_UPDATE_INFO = {
+    timestamp: 1539502055000, // 14th Oct 2018
+    author: 'Author',
+};
+exports.VCS_HARDCODED_UNTRACKED_FILE_PATH = `file/path/${Math.random()}.mdx`;
+/**
+ * This VCS implementation always returns hardcoded values for testing purposes.
+ * It is also useful in dev environments where VCS info is not important.
+ * Reading information from the VCS can be slow and is not always necessary.
+ */
+exports.VcsHardcoded = {
+    initialize: () => {
+        // Noop
+    },
+    getFileCreationInfo: async (filePath) => {
+        if (filePath === exports.VCS_HARDCODED_UNTRACKED_FILE_PATH) {
+            return null;
+        }
+        return exports.VCS_HARDCODED_CREATION_INFO;
+    },
+    getFileLastUpdateInfo: async (filePath) => {
+        if (filePath === exports.VCS_HARDCODED_UNTRACKED_FILE_PATH) {
+            return null;
+        }
+        return exports.VCS_HARDCODED_LAST_UPDATE_INFO;
+    },
+};
+//# sourceMappingURL=vcsHardcoded.js.map

package/lib/vcs/vcsHardcoded.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vcsHardcoded.js","sourceRoot":"","sources":["../../src/vcs/vcsHardcoded.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAIU,QAAA,2BAA2B,GAAkB;IACxD,SAAS,EAAE,aAAa,EAAE,eAAe;IACzC,MAAM,EAAE,SAAS;CAClB,CAAC;AAEW,QAAA,8BAA8B,GAAkB;IAC3D,SAAS,EAAE,aAAa,EAAE,gBAAgB;IAC1C,MAAM,EAAE,QAAQ;CACjB,CAAC;AAEW,QAAA,iCAAiC,GAAG,aAAa,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC;AAElF;;;;GAIG;AACU,QAAA,YAAY,GAAc;IACrC,UAAU,EAAE,GAAG,EAAE;QACf,OAAO;IACT,CAAC;IAED,mBAAmB,EAAE,KAAK,EAAE,QAAgB,EAAE,EAAE;QAC9C,IAAI,QAAQ,KAAK,yCAAiC,EAAE,CAAC;YACnD,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,mCAA2B,CAAC;IACrC,CAAC;IAED,qBAAqB,EAAE,KAAK,EAAE,QAAgB,EAAE,EAAE;QAChD,IAAI,QAAQ,KAAK,yCAAiC,EAAE,CAAC;YACnD,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,sCAA8B,CAAC;IACxC,CAAC;CACF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/utils",
-  "version": "3.9.2",
+  "version": "3.10.1-canary-6591",
   "description": "Node utility functions for Docusaurus packages.",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -18,13 +18,13 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/logger": "3.9.2",
-    "@docusaurus/types": "3.9.2",
-    "@docusaurus/utils-common": "3.9.2",
+    "@docusaurus/logger": "3.10.1-canary-6591",
+    "@docusaurus/types": "3.10.1-canary-6591",
+    "@docusaurus/utils-common": "3.10.1-canary-6591",
     "escape-string-regexp": "^4.0.0",
-    "execa": "5.1.1",
+    "execa": "^5.1.1",
     "file-loader": "^6.2.0",
-    "fs-extra": "^11.1.1",
+    "fs-extra": "^11.2.0",
     "github-slugger": "^1.5.0",
     "globby": "^11.1.0",
     "gray-matter": "^4.0.3",
@@ -38,18 +38,18 @@
     "tslib": "^2.6.0",
     "url-loader": "^4.1.1",
     "utility-types": "^3.10.0",
-    "webpack": "^5.88.1"
+    "webpack": "^5.106.2"
   },
   "engines": {
-    "node": ">=20.0"
+    "node": ">=24.14"
   },
   "devDependencies": {
     "@types/dedent": "^0.7.0",
     "@types/github-slugger": "^1.3.0",
-    "@types/micromatch": "^4.0.2",
-    "@types/react-dom": "^18.2.7",
+    "@types/micromatch": "^4.0.10",
+    "@types/react-dom": "^19.2.3",
     "dedent": "^0.7.0",
     "tmp-promise": "^3.0.3"
   },
-  "gitHead": "abfbe5621b08407bc3dcbe6111ff118d4c22f7a1"
+  "gitHead": "0a37b4e95aa595949734a1cb72d13305bbacb822"
 }

package/src/index.ts

@@ -25,10 +25,12 @@ export {
 } from './constants';
 export {generate, readOutputHTMLFile} from './emitUtils';
 export {
+  // TODO Docusaurus v4: remove these legacy exports,
+  //  they are only kept for retro-compatibility
   getFileCommitDate,
   FileNotTrackedError,
   GitNotFoundError,
-} from './gitUtils';
+} from './vcs/gitUtils';
 export {
   mergeTranslations,
   updateTranslationFileMessages,
@@ -66,17 +68,20 @@ export {
   getTagVisibility,
 } from './tags';
 export {
-  parseMarkdownHeadingId,
-  escapeMarkdownHeadingIds,
   unwrapMdxCodeBlocks,
   admonitionTitleToDirectiveLabel,
   createExcerpt,
   DEFAULT_PARSE_FRONT_MATTER,
   parseMarkdownContentTitle,
   parseMarkdownFile,
+} from './markdownUtils';
+export {
+  parseMarkdownHeadingId,
+  escapeMarkdownHeadingIds,
   writeMarkdownHeadingId,
+  type HeadingIdSyntax,
   type WriteHeadingIDOptions,
-} from './markdownUtils';
+} from './markdownHeadingIdUtils';
 export {
   type ContentPaths,
   type SourceToPermalink,
@@ -117,16 +122,14 @@ export {
 } from './dataFileUtils';
 export {isDraft, isUnlisted} from './contentVisibilityUtils';
 export {escapeRegexp} from './regExpUtils';
-export {askPreferredLanguage} from './cliUtils';
 export {flattenRoutes} from './routeUtils';
 
 export {
-  getGitLastUpdate,
-  getLastUpdate,
   readLastUpdateData,
-  LAST_UPDATE_FALLBACK,
   type LastUpdateData,
   type FrontMatterLastUpdate,
 } from './lastUpdateUtils';
 
+export {VcsPresetNames, getVcsPreset, TEST_VCS} from './vcs/vcs';
+
 export {normalizeTags, reportInlineTags} from './tags';

package/src/lastUpdateUtils.ts

@@ -6,13 +6,9 @@
  */
 
 import _ from 'lodash';
-import logger from '@docusaurus/logger';
-import {
-  FileNotTrackedError,
-  GitNotFoundError,
-  getFileCommitDate,
-} from './gitUtils';
-import type {PluginOptions} from '@docusaurus/types';
+import {getVcsPreset} from './vcs/vcs';
+
+import type {PluginOptions, VcsConfig} from '@docusaurus/types';
 
 export type LastUpdateData = {
   /**
@@ -29,72 +25,6 @@ export type LastUpdateData = {
   lastUpdatedBy: string | undefined | null;
 };
 
-let showedGitRequirementError = false;
-let showedFileNotTrackedError = false;
-
-export async function getGitLastUpdate(
-  filePath: string,
-): Promise<LastUpdateData | null> {
-  if (!filePath) {
-    return null;
-  }
-
-  // Wrap in try/catch in case the shell commands fail
-  // (e.g. project doesn't use Git, etc).
-  try {
-    const result = await getFileCommitDate(filePath, {
-      age: 'newest',
-      includeAuthor: true,
-    });
-
-    return {lastUpdatedAt: result.timestamp, lastUpdatedBy: result.author};
-  } catch (err) {
-    if (err instanceof GitNotFoundError) {
-      if (!showedGitRequirementError) {
-        logger.warn('Sorry, the last update options require Git.');
-        showedGitRequirementError = true;
-      }
-    } else if (err instanceof FileNotTrackedError) {
-      if (!showedFileNotTrackedError) {
-        logger.warn(
-          'Cannot infer the update date for some files, as they are not tracked by git.',
-        );
-        showedFileNotTrackedError = true;
-      }
-    } else {
-      throw new Error(
-        `An error occurred when trying to get the last update date`,
-        {cause: err},
-      );
-    }
-    return null;
-  }
-}
-
-export const LAST_UPDATE_FALLBACK: LastUpdateData = {
-  lastUpdatedAt: 1539502055000,
-  lastUpdatedBy: 'Author',
-};
-
-// Not proud of this, but convenient for tests :/
-export const LAST_UPDATE_UNTRACKED_GIT_FILEPATH = `file/path/${Math.random()}.mdx`;
-
-export async function getLastUpdate(
-  filePath: string,
-): Promise<LastUpdateData | null> {
-  if (filePath === LAST_UPDATE_UNTRACKED_GIT_FILEPATH) {
-    return null;
-  }
-  if (
-    process.env.NODE_ENV !== 'production' ||
-    process.env.DOCUSAURUS_DISABLE_LAST_UPDATE === 'true'
-  ) {
-    // Use fake data in dev/test for faster development.
-    return LAST_UPDATE_FALLBACK;
-  }
-  return getGitLastUpdate(filePath);
-}
-
 type LastUpdateOptions = Pick<
   PluginOptions,
   'showLastUpdateAuthor' | 'showLastUpdateTime'
@@ -109,11 +39,21 @@ export type FrontMatterLastUpdate = {
   date?: Date | string;
 };
 
+// TODO Docusaurus v4: refactor/rename, make it clear this fn is only
+//  for Markdown files with front matter shared by content plugin
 export async function readLastUpdateData(
   filePath: string,
   options: LastUpdateOptions,
   lastUpdateFrontMatter: FrontMatterLastUpdate | undefined,
+  vcsParam: Pick<VcsConfig, 'getFileLastUpdateInfo'>,
 ): Promise<LastUpdateData> {
+  // We fallback to the default VSC config at runtime on purpose
+  // It preserves retro-compatibility if a third-party plugin imports it
+  // This also ensures unit tests keep working without extra setup
+  // We still want to ensure type safety by requiring the VCS param
+  // TODO Docusaurus v4: refactor all these Git read APIs
+  const vcs = vcsParam ?? getVcsPreset('default-v1');
+
   const {showLastUpdateAuthor, showLastUpdateTime} = options;
 
   if (!showLastUpdateAuthor && !showLastUpdateTime) {
@@ -128,14 +68,16 @@ export async function readLastUpdateData(
   // We try to minimize git last update calls
   // We call it at most once
   // If all the data is provided as front matter, we do not call it
-  const getLastUpdateMemoized = _.memoize(() => getLastUpdate(filePath));
+  const getLastUpdateMemoized = _.memoize(() =>
+    vcs.getFileLastUpdateInfo(filePath),
+  );
   const getLastUpdateBy = () =>
     getLastUpdateMemoized().then((update) => {
       // Important, see https://github.com/facebook/docusaurus/pull/11211
       if (update === null) {
         return null;
       }
-      return update?.lastUpdatedBy;
+      return update?.author;
     });
   const getLastUpdateAt = () =>
     getLastUpdateMemoized().then((update) => {
@@ -143,7 +85,7 @@ export async function readLastUpdateData(
       if (update === null) {
         return null;
       }
-      return update?.lastUpdatedAt;
+      return update?.timestamp;
     });
 
   const lastUpdatedBy = showLastUpdateAuthor