@docusaurus/utils 2.0.0-beta.16 → 2.0.0-beta.19

package/lib/constants.d.ts

@@ -4,17 +4,67 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+/** Node major version, directly read from env. */
 export declare const NODE_MAJOR_VERSION: number;
+/** Node minor version, directly read from env. */
 export declare const NODE_MINOR_VERSION: number;
+/** Docusaurus core version. */
+export declare const DOCUSAURUS_VERSION: any;
+/**
+ * Can be overridden with cli option `--out-dir`. Code should generally use
+ * `context.outDir` instead (which is always absolute and localized).
+ */
 export declare const DEFAULT_BUILD_DIR_NAME = "build";
+/**
+ * Can be overridden with cli option `--config`. Code should generally use
+ * `context.siteConfigPath` instead (which is always absolute).
+ */
 export declare const DEFAULT_CONFIG_FILE_NAME = "docusaurus.config.js";
+/** Can be absolute or relative to site directory. */
 export declare const BABEL_CONFIG_FILE_NAME: string;
+/**
+ * Can be absolute or relative to site directory. Code should generally use
+ * `context.generatedFilesDir` instead (which is always absolute).
+ */
 export declare const GENERATED_FILES_DIR_NAME: string;
+/**
+ * We would assume all of the site's JS code lives in here and not outside.
+ * Relative to the site directory.
+ */
 export declare const SRC_DIR_NAME = "src";
-export declare const STATIC_DIR_NAME = "static";
+/**
+ * Can be overridden with `config.staticDirectories`. Code should use
+ * `context.siteConfig.staticDirectories` instead (which is always absolute).
+ */
+export declare const DEFAULT_STATIC_DIR_NAME = "static";
+/**
+ * Files here are handled by webpack, hashed (can be cached aggressively).
+ * Relative to the build output folder.
+ */
 export declare const OUTPUT_STATIC_ASSETS_DIR_NAME = "assets";
+/**
+ * Components in this directory will receive the `@theme` alias and be able to
+ * shadow default theme components.
+ */
 export declare const THEME_PATH: string;
+/**
+ * All translation-related data live here, relative to site directory. Content
+ * will be namespaced by locale.
+ */
+export declare const I18N_DIR_NAME = "i18n";
+/**
+ * Translations for React code.
+ */
+export declare const CODE_TRANSLATIONS_FILE_NAME = "code.json";
+/** Dev server opens on this port by default. */
 export declare const DEFAULT_PORT = 3000;
+/** Default plugin ID. */
 export declare const DEFAULT_PLUGIN_ID = "default";
+/**
+ * Allow overriding the limit after which the url loader will no longer inline
+ * assets.
+ *
+ * @see https://github.com/facebook/docusaurus/issues/5493
+ */
 export declare const WEBPACK_URL_LOADER_LIMIT: string | number;
 //# sourceMappingURL=constants.d.ts.map

package/lib/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,kBAAkB,QAG9B,CAAC;AACF,eAAO,MAAM,kBAAkB,QAG9B,CAAC;AAGF,eAAO,MAAM,sBAAsB,UAAU,CAAC;AAG9C,eAAO,MAAM,wBAAwB,yBAAyB,CAAC;AAE/D,eAAO,MAAM,sBAAsB,QACiC,CAAC;AAErE,eAAO,MAAM,wBAAwB,QAC6B,CAAC;AAEnE,eAAO,MAAM,YAAY,QAAQ,CAAC;AAClC,eAAO,MAAM,eAAe,WAAW,CAAC;AACxC,eAAO,MAAM,6BAA6B,WAAW,CAAC;AACtD,eAAO,MAAM,UAAU,QAA0B,CAAC;AAClD,eAAO,MAAM,YAAY,OAAO,CAAC;AACjC,eAAO,MAAM,iBAAiB,YAAY,CAAC;AAG3C,eAAO,MAAM,wBAAwB,iBACU,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,kDAAkD;AAClD,eAAO,MAAM,kBAAkB,QAG9B,CAAC;AACF,kDAAkD;AAClD,eAAO,MAAM,kBAAkB,QAG9B,CAAC;AAEF,+BAA+B;AAE/B,eAAO,MAAM,kBAAkB,KAAqC,CAAC;AAErE;;;GAGG;AACH,eAAO,MAAM,sBAAsB,UAAU,CAAC;AAE9C;;;GAGG;AACH,eAAO,MAAM,wBAAwB,yBAAyB,CAAC;AAE/D,qDAAqD;AACrD,eAAO,MAAM,sBAAsB,QACiC,CAAC;AAErE;;;GAGG;AACH,eAAO,MAAM,wBAAwB,QAC6B,CAAC;AAEnE;;;GAGG;AACH,eAAO,MAAM,YAAY,QAAQ,CAAC;AAElC;;;GAGG;AACH,eAAO,MAAM,uBAAuB,WAAW,CAAC;AAEhD;;;GAGG;AACH,eAAO,MAAM,6BAA6B,WAAW,CAAC;AAEtD;;;GAGG;AACH,eAAO,MAAM,UAAU,QAA0B,CAAC;AAElD;;;GAGG;AACH,eAAO,MAAM,aAAa,SAAS,CAAC;AAEpC;;GAEG;AACH,eAAO,MAAM,2BAA2B,cAAc,CAAC;AAEvD,gDAAgD;AAChD,eAAO,MAAM,YAAY,OAAO,CAAC;AAEjC,yBAAyB;AACzB,eAAO,MAAM,iBAAiB,YAAY,CAAC;AAE3C;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,iBACU,CAAC"}

package/lib/constants.js

@@ -5,23 +5,70 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-var _a;
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WEBPACK_URL_LOADER_LIMIT = exports.DEFAULT_PLUGIN_ID = exports.DEFAULT_PORT = exports.THEME_PATH = exports.OUTPUT_STATIC_ASSETS_DIR_NAME = exports.STATIC_DIR_NAME = exports.SRC_DIR_NAME = exports.GENERATED_FILES_DIR_NAME = exports.BABEL_CONFIG_FILE_NAME = exports.DEFAULT_CONFIG_FILE_NAME = exports.DEFAULT_BUILD_DIR_NAME = exports.NODE_MINOR_VERSION = exports.NODE_MAJOR_VERSION = void 0;
+exports.WEBPACK_URL_LOADER_LIMIT = exports.DEFAULT_PLUGIN_ID = exports.DEFAULT_PORT = exports.CODE_TRANSLATIONS_FILE_NAME = exports.I18N_DIR_NAME = exports.THEME_PATH = exports.OUTPUT_STATIC_ASSETS_DIR_NAME = exports.DEFAULT_STATIC_DIR_NAME = exports.SRC_DIR_NAME = exports.GENERATED_FILES_DIR_NAME = exports.BABEL_CONFIG_FILE_NAME = exports.DEFAULT_CONFIG_FILE_NAME = exports.DEFAULT_BUILD_DIR_NAME = exports.DOCUSAURUS_VERSION = exports.NODE_MINOR_VERSION = exports.NODE_MAJOR_VERSION = void 0;
+/** Node major version, directly read from env. */
 exports.NODE_MAJOR_VERSION = parseInt(process.versions.node.split('.')[0], 10);
+/** Node minor version, directly read from env. */
 exports.NODE_MINOR_VERSION = parseInt(process.versions.node.split('.')[1], 10);
-// Can be overridden with cli option --out-dir
+/** Docusaurus core version. */
+// eslint-disable-next-line global-require, @typescript-eslint/no-var-requires
+exports.DOCUSAURUS_VERSION = require('../package.json').version;
+/**
+ * Can be overridden with cli option `--out-dir`. Code should generally use
+ * `context.outDir` instead (which is always absolute and localized).
+ */
 exports.DEFAULT_BUILD_DIR_NAME = 'build';
-// Can be overridden with cli option --config
+/**
+ * Can be overridden with cli option `--config`. Code should generally use
+ * `context.siteConfigPath` instead (which is always absolute).
+ */
 exports.DEFAULT_CONFIG_FILE_NAME = 'docusaurus.config.js';
-exports.BABEL_CONFIG_FILE_NAME = process.env.DOCUSAURUS_BABEL_CONFIG_FILE_NAME || 'babel.config.js';
-exports.GENERATED_FILES_DIR_NAME = process.env.DOCUSAURUS_GENERATED_FILES_DIR_NAME || '.docusaurus';
+/** Can be absolute or relative to site directory. */
+exports.BABEL_CONFIG_FILE_NAME = process.env.DOCUSAURUS_BABEL_CONFIG_FILE_NAME ?? 'babel.config.js';
+/**
+ * Can be absolute or relative to site directory. Code should generally use
+ * `context.generatedFilesDir` instead (which is always absolute).
+ */
+exports.GENERATED_FILES_DIR_NAME = process.env.DOCUSAURUS_GENERATED_FILES_DIR_NAME ?? '.docusaurus';
+/**
+ * We would assume all of the site's JS code lives in here and not outside.
+ * Relative to the site directory.
+ */
 exports.SRC_DIR_NAME = 'src';
-exports.STATIC_DIR_NAME = 'static';
-exports.OUTPUT_STATIC_ASSETS_DIR_NAME = 'assets'; // files handled by webpack, hashed (can be cached aggressively)
+/**
+ * Can be overridden with `config.staticDirectories`. Code should use
+ * `context.siteConfig.staticDirectories` instead (which is always absolute).
+ */
+exports.DEFAULT_STATIC_DIR_NAME = 'static';
+/**
+ * Files here are handled by webpack, hashed (can be cached aggressively).
+ * Relative to the build output folder.
+ */
+exports.OUTPUT_STATIC_ASSETS_DIR_NAME = 'assets';
+/**
+ * Components in this directory will receive the `@theme` alias and be able to
+ * shadow default theme components.
+ */
 exports.THEME_PATH = `${exports.SRC_DIR_NAME}/theme`;
+/**
+ * All translation-related data live here, relative to site directory. Content
+ * will be namespaced by locale.
+ */
+exports.I18N_DIR_NAME = 'i18n';
+/**
+ * Translations for React code.
+ */
+exports.CODE_TRANSLATIONS_FILE_NAME = 'code.json';
+/** Dev server opens on this port by default. */
 exports.DEFAULT_PORT = 3000;
+/** Default plugin ID. */
 exports.DEFAULT_PLUGIN_ID = 'default';
-// Temporary fix for https://github.com/facebook/docusaurus/issues/5493
-exports.WEBPACK_URL_LOADER_LIMIT = (_a = process.env.WEBPACK_URL_LOADER_LIMIT) !== null && _a !== void 0 ? _a : 10000;
+/**
+ * Allow overriding the limit after which the url loader will no longer inline
+ * assets.
+ *
+ * @see https://github.com/facebook/docusaurus/issues/5493
+ */
+exports.WEBPACK_URL_LOADER_LIMIT = process.env.WEBPACK_URL_LOADER_LIMIT ?? 10000;
 //# sourceMappingURL=constants.js.map

package/lib/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;;AAEU,QAAA,kBAAkB,GAAG,QAAQ,CACxC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EACnC,EAAE,CACH,CAAC;AACW,QAAA,kBAAkB,GAAG,QAAQ,CACxC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EACnC,EAAE,CACH,CAAC;AAEF,8CAA8C;AACjC,QAAA,sBAAsB,GAAG,OAAO,CAAC;AAE9C,6CAA6C;AAChC,QAAA,wBAAwB,GAAG,sBAAsB,CAAC;AAElD,QAAA,sBAAsB,GACjC,OAAO,CAAC,GAAG,CAAC,iCAAiC,IAAI,iBAAiB,CAAC;AAExD,QAAA,wBAAwB,GACnC,OAAO,CAAC,GAAG,CAAC,mCAAmC,IAAI,aAAa,CAAC;AAEtD,QAAA,YAAY,GAAG,KAAK,CAAC;AACrB,QAAA,eAAe,GAAG,QAAQ,CAAC;AAC3B,QAAA,6BAA6B,GAAG,QAAQ,CAAC,CAAC,gEAAgE;AAC1G,QAAA,UAAU,GAAG,GAAG,oBAAY,QAAQ,CAAC;AACrC,QAAA,YAAY,GAAG,IAAI,CAAC;AACpB,QAAA,iBAAiB,GAAG,SAAS,CAAC;AAE3C,uEAAuE;AAC1D,QAAA,wBAAwB,GACnC,MAAA,OAAO,CAAC,GAAG,CAAC,wBAAwB,mCAAI,KAAK,CAAC"}
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEH,kDAAkD;AACrC,QAAA,kBAAkB,GAAG,QAAQ,CACxC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAE,EACpC,EAAE,CACH,CAAC;AACF,kDAAkD;AACrC,QAAA,kBAAkB,GAAG,QAAQ,CACxC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAE,EACpC,EAAE,CACH,CAAC;AAEF,+BAA+B;AAC/B,8EAA8E;AACjE,QAAA,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC,OAAO,CAAC;AAErE;;;GAGG;AACU,QAAA,sBAAsB,GAAG,OAAO,CAAC;AAE9C;;;GAGG;AACU,QAAA,wBAAwB,GAAG,sBAAsB,CAAC;AAE/D,qDAAqD;AACxC,QAAA,sBAAsB,GACjC,OAAO,CAAC,GAAG,CAAC,iCAAiC,IAAI,iBAAiB,CAAC;AAErE;;;GAGG;AACU,QAAA,wBAAwB,GACnC,OAAO,CAAC,GAAG,CAAC,mCAAmC,IAAI,aAAa,CAAC;AAEnE;;;GAGG;AACU,QAAA,YAAY,GAAG,KAAK,CAAC;AAElC;;;GAGG;AACU,QAAA,uBAAuB,GAAG,QAAQ,CAAC;AAEhD;;;GAGG;AACU,QAAA,6BAA6B,GAAG,QAAQ,CAAC;AAEtD;;;GAGG;AACU,QAAA,UAAU,GAAG,GAAG,oBAAY,QAAQ,CAAC;AAElD;;;GAGG;AACU,QAAA,aAAa,GAAG,MAAM,CAAC;AAEpC;;GAEG;AACU,QAAA,2BAA2B,GAAG,WAAW,CAAC;AAEvD,gDAAgD;AACnC,QAAA,YAAY,GAAG,IAAI,CAAC;AAEjC,yBAAyB;AACZ,QAAA,iBAAiB,GAAG,SAAS,CAAC;AAE3C;;;;;GAKG;AACU,QAAA,wBAAwB,GACnC,OAAO,CAAC,GAAG,CAAC,wBAAwB,IAAI,KAAK,CAAC"}

package/lib/dataFileUtils.d.ts

@@ -6,19 +6,55 @@
  */
 import type { ContentPaths } from './markdownLinks';
 declare type DataFileParams = {
+    /** Path to the potential data file, relative to `contentPaths` */
     filePath: string;
+    /**
+     * Includes the base path and localized path, both of which are eligible for
+     * sourcing data files. Both paths should be absolute.
+     */
     contentPaths: ContentPaths;
 };
+/**
+ * Looks for a data file in the potential content paths; loads a localized data
+ * file in priority.
+ *
+ * @returns An absolute path to the data file, or `undefined` if there isn't one.
+ */
 export declare function getDataFilePath({ filePath, contentPaths, }: DataFileParams): Promise<string | undefined>;
 /**
- * Looks up for a data file in the content paths, returns the normalized object.
- * Throws when validation fails; returns undefined when file not found
+ * Looks up for a data file in the content paths, returns the object validated
+ * and normalized according to the `validate` callback.
+ *
+ * @returns `undefined` when file not found
+ * @throws Throws when validation fails, displaying a helpful context message.
  */
 export declare function getDataFileData<T>(params: DataFileParams & {
+    /** Used for the "The X file looks invalid" message. */
     fileType: string;
 }, validate: (content: unknown) => T): Promise<T | undefined>;
+/**
+ * Takes the `contentPaths` data structure and returns an ordered path list
+ * indicating their priorities. For all data, we look in the localized folder
+ * in priority.
+ */
 export declare function getContentPathList(contentPaths: ContentPaths): string[];
+/**
+ * @param folderPaths a list of absolute paths.
+ * @param relativeFilePath file path relative to each `folderPaths`.
+ * @returns the first folder path in which the file exists, or `undefined` if
+ * none is found.
+ */
 export declare function findFolderContainingFile(folderPaths: string[], relativeFilePath: string): Promise<string | undefined>;
+/**
+ * Fail-fast alternative to `findFolderContainingFile`.
+ *
+ * @param folderPaths a list of absolute paths.
+ * @param relativeFilePath file path relative to each `folderPaths`.
+ * @returns the first folder path in which the file exists.
+ * @throws Throws if no file can be found. You should use this method only when
+ * you actually know the file exists (e.g. when the `relativeFilePath` is read
+ * with a glob and you are just trying to localize it)
+ */
 export declare function getFolderContainingFile(folderPaths: string[], relativeFilePath: string): Promise<string>;
 export {};
 //# sourceMappingURL=dataFileUtils.d.ts.map

package/lib/dataFileUtils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dataFileUtils.d.ts","sourceRoot":"","sources":["../src/dataFileUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,iBAAiB,CAAC;AAGlD,aAAK,cAAc,GAAG;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,YAAY,CAAC;CAC5B,CAAC;AAEF,wBAAsB,eAAe,CAAC,EACpC,QAAQ,EACR,YAAY,GACb,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAU9C;AAED;;;GAGG;AACH,wBAAsB,eAAe,CAAC,CAAC,EACrC,MAAM,EAAE,cAAc,GAAG;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAC,EAC3C,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,CAAC,GAChC,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAcxB;AAGD,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,YAAY,GAAG,MAAM,EAAE,CAEvE;AAGD,wBAAsB,wBAAwB,CAC5C,WAAW,EAAE,MAAM,EAAE,EACrB,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAI7B;AAED,wBAAsB,uBAAuB,CAC3C,WAAW,EAAE,MAAM,EAAE,EACrB,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAAC,MAAM,CAAC,CAcjB"}
+{"version":3,"file":"dataFileUtils.d.ts","sourceRoot":"","sources":["../src/dataFileUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,iBAAiB,CAAC;AAGlD,aAAK,cAAc,GAAG;IACpB,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,YAAY,EAAE,YAAY,CAAC;CAC5B,CAAC;AAEF;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,EACpC,QAAQ,EACR,YAAY,GACb,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAS9C;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,CAAC,EACrC,MAAM,EAAE,cAAc,GAAG;IACvB,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;CAClB,EACD,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,CAAC,GAChC,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAaxB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,YAAY,GAAG,MAAM,EAAE,CAEvE;AAED;;;;;GAKG;AACH,wBAAsB,wBAAwB,CAC5C,WAAW,EAAE,MAAM,EAAE,EACrB,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAI7B;AAED;;;;;;;;;GASG;AACH,wBAAsB,uBAAuB,CAC3C,WAAW,EAAE,MAAM,EAAE,EACrB,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAAC,MAAM,CAAC,CAYjB"}

package/lib/dataFileUtils.js

@@ -8,23 +8,31 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getFolderContainingFile = exports.findFolderContainingFile = exports.getContentPathList = exports.getDataFileData = exports.getDataFilePath = void 0;
 const tslib_1 = require("tslib");
-const fs_extra_1 = (0, tslib_1.__importDefault)(require("fs-extra"));
-const js_yaml_1 = (0, tslib_1.__importDefault)(require("js-yaml"));
-const path_1 = (0, tslib_1.__importDefault)(require("path"));
+const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
+const js_yaml_1 = tslib_1.__importDefault(require("js-yaml"));
+const path_1 = tslib_1.__importDefault(require("path"));
 const index_1 = require("./index");
-const logger_1 = (0, tslib_1.__importDefault)(require("@docusaurus/logger"));
+const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
+/**
+ * Looks for a data file in the potential content paths; loads a localized data
+ * file in priority.
+ *
+ * @returns An absolute path to the data file, or `undefined` if there isn't one.
+ */
 async function getDataFilePath({ filePath, contentPaths, }) {
-    // Loads a localized data file in priority
     const contentPath = await findFolderContainingFile(getContentPathList(contentPaths), filePath);
     if (contentPath) {
-        return path_1.default.join(contentPath, filePath);
+        return path_1.default.resolve(contentPath, filePath);
     }
     return undefined;
 }
 exports.getDataFilePath = getDataFilePath;
 /**
- * Looks up for a data file in the content paths, returns the normalized object.
- * Throws when validation fails; returns undefined when file not found
+ * Looks up for a data file in the content paths, returns the object validated
+ * and normalized according to the `validate` callback.
+ *
+ * @returns `undefined` when file not found
+ * @throws Throws when validation fails, displaying a helpful context message.
  */
 async function getDataFileData(params, validate) {
     const filePath = await getDataFilePath(params);
@@ -37,27 +45,45 @@ async function getDataFileData(params, validate) {
         return validate(unsafeContent);
     }
     catch (err) {
-        // TODO replace later by error cause, see https://v8.dev/features/error-cause
         logger_1.default.error `The ${params.fileType} file at path=${filePath} looks invalid.`;
         throw err;
     }
 }
 exports.getDataFileData = getDataFileData;
-// Order matters: we look in priority in localized folder
+/**
+ * Takes the `contentPaths` data structure and returns an ordered path list
+ * indicating their priorities. For all data, we look in the localized folder
+ * in priority.
+ */
 function getContentPathList(contentPaths) {
     return [contentPaths.contentPathLocalized, contentPaths.contentPath];
 }
 exports.getContentPathList = getContentPathList;
-// return the first folder path in which the file exists in
+/**
+ * @param folderPaths a list of absolute paths.
+ * @param relativeFilePath file path relative to each `folderPaths`.
+ * @returns the first folder path in which the file exists, or `undefined` if
+ * none is found.
+ */
 async function findFolderContainingFile(folderPaths, relativeFilePath) {
     return (0, index_1.findAsyncSequential)(folderPaths, (folderPath) => fs_extra_1.default.pathExists(path_1.default.join(folderPath, relativeFilePath)));
 }
 exports.findFolderContainingFile = findFolderContainingFile;
+/**
+ * Fail-fast alternative to `findFolderContainingFile`.
+ *
+ * @param folderPaths a list of absolute paths.
+ * @param relativeFilePath file path relative to each `folderPaths`.
+ * @returns the first folder path in which the file exists.
+ * @throws Throws if no file can be found. You should use this method only when
+ * you actually know the file exists (e.g. when the `relativeFilePath` is read
+ * with a glob and you are just trying to localize it)
+ */
 async function getFolderContainingFile(folderPaths, relativeFilePath) {
     const maybeFolderPath = await findFolderContainingFile(folderPaths, relativeFilePath);
-    // should never happen, as the source was read from the FS anyway...
     if (!maybeFolderPath) {
-        throw new Error(`File "${relativeFilePath}" does not exist in any of these folders:\n- ${folderPaths.join('\n- ')}]`);
+        throw new Error(`File "${relativeFilePath}" does not exist in any of these folders:
+- ${folderPaths.join('\n- ')}`);
     }
     return maybeFolderPath;
 }

package/lib/dataFileUtils.js.map

@@ -1 +1 @@
-{"version":3,"file":"dataFileUtils.js","sourceRoot":"","sources":["../src/dataFileUtils.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;;AAEH,qEAA0B;AAC1B,mEAA2B;AAC3B,6DAAwB;AACxB,mCAA4C;AAE5C,6EAAwC;AAOjC,KAAK,UAAU,eAAe,CAAC,EACpC,QAAQ,EACR,YAAY,GACG;IACf,0CAA0C;IAC1C,MAAM,WAAW,GAAG,MAAM,wBAAwB,CAChD,kBAAkB,CAAC,YAAY,CAAC,EAChC,QAAQ,CACT,CAAC;IACF,IAAI,WAAW,EAAE;QACf,OAAO,cAAI,CAAC,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;KACzC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAbD,0CAaC;AAED;;;GAGG;AACI,KAAK,UAAU,eAAe,CACnC,MAA2C,EAC3C,QAAiC;IAEjC,MAAM,QAAQ,GAAG,MAAM,eAAe,CAAC,MAAM,CAAC,CAAC;IAC/C,IAAI,CAAC,QAAQ,EAAE;QACb,OAAO,SAAS,CAAC;KAClB;IACD,IAAI;QACF,MAAM,aAAa,GAAG,MAAM,kBAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,EAAC,QAAQ,EAAE,MAAM,EAAC,CAAC,CAAC;QACtE,MAAM,aAAa,GAAG,iBAAI,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAC/C,OAAO,QAAQ,CAAC,aAAa,CAAC,CAAC;KAChC;IAAC,OAAO,GAAG,EAAE;QACZ,6EAA6E;QAC7E,gBAAM,CAAC,KAAK,CAAA,OAAO,MAAM,CAAC,QAAQ,iBAAiB,QAAQ,iBAAiB,CAAC;QAC7E,MAAM,GAAG,CAAC;KACX;AACH,CAAC;AAjBD,0CAiBC;AAED,yDAAyD;AACzD,SAAgB,kBAAkB,CAAC,YAA0B;IAC3D,OAAO,CAAC,YAAY,CAAC,oBAAoB,EAAE,YAAY,CAAC,WAAW,CAAC,CAAC;AACvE,CAAC;AAFD,gDAEC;AAED,2DAA2D;AACpD,KAAK,UAAU,wBAAwB,CAC5C,WAAqB,EACrB,gBAAwB;IAExB,OAAO,IAAA,2BAAmB,EAAC,WAAW,EAAE,CAAC,UAAU,EAAE,EAAE,CACrD,kBAAE,CAAC,UAAU,CAAC,cAAI,CAAC,IAAI,CAAC,UAAU,EAAE,gBAAgB,CAAC,CAAC,CACvD,CAAC;AACJ,CAAC;AAPD,4DAOC;AAEM,KAAK,UAAU,uBAAuB,CAC3C,WAAqB,EACrB,gBAAwB;IAExB,MAAM,eAAe,GAAG,MAAM,wBAAwB,CACpD,WAAW,EACX,gBAAgB,CACjB,CAAC;IACF,oEAAoE;IACpE,IAAI,CAAC,eAAe,EAAE;QACpB,MAAM,IAAI,KAAK,CACb,SAAS,gBAAgB,gDAAgD,WAAW,CAAC,IAAI,CACvF,MAAM,CACP,GAAG,CACL,CAAC;KACH;IACD,OAAO,eAAe,CAAC;AACzB,CAAC;AAjBD,0DAiBC"}
+{"version":3,"file":"dataFileUtils.js","sourceRoot":"","sources":["../src/dataFileUtils.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;;AAEH,gEAA0B;AAC1B,8DAA2B;AAC3B,wDAAwB;AACxB,mCAA4C;AAE5C,wEAAwC;AAYxC;;;;;GAKG;AACI,KAAK,UAAU,eAAe,CAAC,EACpC,QAAQ,EACR,YAAY,GACG;IACf,MAAM,WAAW,GAAG,MAAM,wBAAwB,CAChD,kBAAkB,CAAC,YAAY,CAAC,EAChC,QAAQ,CACT,CAAC;IACF,IAAI,WAAW,EAAE;QACf,OAAO,cAAI,CAAC,OAAO,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;KAC5C;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAZD,0CAYC;AAED;;;;;;GAMG;AACI,KAAK,UAAU,eAAe,CACnC,MAGC,EACD,QAAiC;IAEjC,MAAM,QAAQ,GAAG,MAAM,eAAe,CAAC,MAAM,CAAC,CAAC;IAC/C,IAAI,CAAC,QAAQ,EAAE;QACb,OAAO,SAAS,CAAC;KAClB;IACD,IAAI;QACF,MAAM,aAAa,GAAG,MAAM,kBAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,EAAC,QAAQ,EAAE,MAAM,EAAC,CAAC,CAAC;QACtE,MAAM,aAAa,GAAG,iBAAI,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAC/C,OAAO,QAAQ,CAAC,aAAa,CAAC,CAAC;KAChC;IAAC,OAAO,GAAG,EAAE;QACZ,gBAAM,CAAC,KAAK,CAAA,OAAO,MAAM,CAAC,QAAQ,iBAAiB,QAAQ,iBAAiB,CAAC;QAC7E,MAAM,GAAG,CAAC;KACX;AACH,CAAC;AAnBD,0CAmBC;AAED;;;;GAIG;AACH,SAAgB,kBAAkB,CAAC,YAA0B;IAC3D,OAAO,CAAC,YAAY,CAAC,oBAAoB,EAAE,YAAY,CAAC,WAAW,CAAC,CAAC;AACvE,CAAC;AAFD,gDAEC;AAED;;;;;GAKG;AACI,KAAK,UAAU,wBAAwB,CAC5C,WAAqB,EACrB,gBAAwB;IAExB,OAAO,IAAA,2BAAmB,EAAC,WAAW,EAAE,CAAC,UAAU,EAAE,EAAE,CACrD,kBAAE,CAAC,UAAU,CAAC,cAAI,CAAC,IAAI,CAAC,UAAU,EAAE,gBAAgB,CAAC,CAAC,CACvD,CAAC;AACJ,CAAC;AAPD,4DAOC;AAED;;;;;;;;;GASG;AACI,KAAK,UAAU,uBAAuB,CAC3C,WAAqB,EACrB,gBAAwB;IAExB,MAAM,eAAe,GAAG,MAAM,wBAAwB,CACpD,WAAW,EACX,gBAAgB,CACjB,CAAC;IACF,IAAI,CAAC,eAAe,EAAE;QACpB,MAAM,IAAI,KAAK,CACb,SAAS,gBAAgB;IAC3B,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CACzB,CAAC;KACH;IACD,OAAO,eAAe,CAAC;AACzB,CAAC;AAfD,0DAeC"}

package/lib/emitUtils.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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.
+ */
+/// <reference types="node" />
+/**
+ * Outputs a file to the generated files directory. Only writes files if content
+ * differs from cache (for hot reload performance).
+ *
+ * @param generatedFilesDir Absolute path.
+ * @param file Path relative to `generatedFilesDir`. File will always be
+ * outputted; no need to ensure directory exists.
+ * @param content String content to write.
+ * @param skipCache If `true` (defaults as `true` for production), file is
+ * force-rewritten, skipping cache.
+ */
+export declare function generate(generatedFilesDir: string, file: string, content: string, skipCache?: boolean): Promise<void>;
+/**
+ * @param permalink The URL that the HTML file corresponds to, without base URL
+ * @param outDir Full path to the output directory
+ * @param trailingSlash The site config option. If provided, only one path will
+ * be read.
+ * @returns This returns a buffer, which you have to decode string yourself if
+ * needed. (Not always necessary since the output isn't for human consumption
+ * anyways, and most HTML manipulation libs accept buffers)
+ * @throws Throws when the HTML file is not found at any of the potential paths.
+ * This should never happen as it would lead to a 404.
+ */
+export declare function readOutputHTMLFile(permalink: string, outDir: string, trailingSlash: boolean | undefined): Promise<Buffer>;
+//# sourceMappingURL=emitUtils.d.ts.map

package/lib/emitUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitUtils.d.ts","sourceRoot":"","sources":["../src/emitUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;;AASH;;;;;;;;;;GAUG;AACH,wBAAsB,QAAQ,CAC5B,iBAAiB,EAAE,MAAM,EACzB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,SAAS,GAAE,OAA+C,GACzD,OAAO,CAAC,IAAI,CAAC,CAgCf;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,OAAO,GAAG,SAAS,GACjC,OAAO,CAAC,MAAM,CAAC,CAmBjB"}

package/lib/emitUtils.js

@@ -0,0 +1,80 @@
+"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.readOutputHTMLFile = exports.generate = void 0;
+const tslib_1 = require("tslib");
+const path_1 = tslib_1.__importDefault(require("path"));
+const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
+const crypto_1 = require("crypto");
+const jsUtils_1 = require("./jsUtils");
+const fileHash = new Map();
+/**
+ * Outputs a file to the generated files directory. Only writes files if content
+ * differs from cache (for hot reload performance).
+ *
+ * @param generatedFilesDir Absolute path.
+ * @param file Path relative to `generatedFilesDir`. File will always be
+ * outputted; no need to ensure directory exists.
+ * @param content String content to write.
+ * @param skipCache If `true` (defaults as `true` for production), file is
+ * force-rewritten, skipping cache.
+ */
+async function generate(generatedFilesDir, file, content, skipCache = process.env.NODE_ENV === 'production') {
+    const filepath = path_1.default.resolve(generatedFilesDir, file);
+    if (skipCache) {
+        await fs_extra_1.default.outputFile(filepath, content);
+        // Cache still needs to be reset, otherwise, writing "A", "B", and "A" where
+        // "B" skips cache will cause the last "A" not be able to overwrite as the
+        // first "A" remains in cache. But if the file never existed in cache, no
+        // need to register it.
+        if (fileHash.get(filepath)) {
+            fileHash.set(filepath, (0, crypto_1.createHash)('md5').update(content).digest('hex'));
+        }
+        return;
+    }
+    let lastHash = fileHash.get(filepath);
+    // If file already exists but it's not in runtime cache yet, we try to
+    // calculate the content hash and then compare. This is to avoid unnecessary
+    // overwriting and we can reuse old file.
+    if (!lastHash && (await fs_extra_1.default.pathExists(filepath))) {
+        const lastContent = await fs_extra_1.default.readFile(filepath, 'utf8');
+        lastHash = (0, crypto_1.createHash)('md5').update(lastContent).digest('hex');
+        fileHash.set(filepath, lastHash);
+    }
+    const currentHash = (0, crypto_1.createHash)('md5').update(content).digest('hex');
+    if (lastHash !== currentHash) {
+        await fs_extra_1.default.outputFile(filepath, content);
+        fileHash.set(filepath, currentHash);
+    }
+}
+exports.generate = generate;
+/**
+ * @param permalink The URL that the HTML file corresponds to, without base URL
+ * @param outDir Full path to the output directory
+ * @param trailingSlash The site config option. If provided, only one path will
+ * be read.
+ * @returns This returns a buffer, which you have to decode string yourself if
+ * needed. (Not always necessary since the output isn't for human consumption
+ * anyways, and most HTML manipulation libs accept buffers)
+ * @throws Throws when the HTML file is not found at any of the potential paths.
+ * This should never happen as it would lead to a 404.
+ */
+async function readOutputHTMLFile(permalink, outDir, trailingSlash) {
+    const withTrailingSlashPath = path_1.default.join(outDir, permalink, 'index.html');
+    const withoutTrailingSlashPath = path_1.default.join(outDir, `${permalink.replace(/\/$/, '')}.html`);
+    const HTMLPath = await (0, jsUtils_1.findAsyncSequential)([
+        trailingSlash !== false && withTrailingSlashPath,
+        trailingSlash !== true && withoutTrailingSlashPath,
+    ].filter((p) => Boolean(p)), fs_extra_1.default.pathExists);
+    if (!HTMLPath) {
+        throw new Error(`Expected output HTML file to be found at ${withTrailingSlashPath}.`);
+    }
+    return fs_extra_1.default.readFile(HTMLPath);
+}
+exports.readOutputHTMLFile = readOutputHTMLFile;
+//# sourceMappingURL=emitUtils.js.map

package/lib/emitUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitUtils.js","sourceRoot":"","sources":["../src/emitUtils.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;;AAEH,wDAAwB;AACxB,gEAA0B;AAC1B,mCAAkC;AAClC,uCAA8C;AAE9C,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;AAE3C;;;;;;;;;;GAUG;AACI,KAAK,UAAU,QAAQ,CAC5B,iBAAyB,EACzB,IAAY,EACZ,OAAe,EACf,YAAqB,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY;IAE1D,MAAM,QAAQ,GAAG,cAAI,CAAC,OAAO,CAAC,iBAAiB,EAAE,IAAI,CAAC,CAAC;IAEvD,IAAI,SAAS,EAAE;QACb,MAAM,kBAAE,CAAC,UAAU,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QACvC,4EAA4E;QAC5E,0EAA0E;QAC1E,yEAAyE;QACzE,uBAAuB;QACvB,IAAI,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE;YAC1B,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAA,mBAAU,EAAC,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;SACzE;QACD,OAAO;KACR;IAED,IAAI,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAEtC,sEAAsE;IACtE,4EAA4E;IAC5E,yCAAyC;IACzC,IAAI,CAAC,QAAQ,IAAI,CAAC,MAAM,kBAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,EAAE;QAChD,MAAM,WAAW,GAAG,MAAM,kBAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QACxD,QAAQ,GAAG,IAAA,mBAAU,EAAC,KAAK,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC/D,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;KAClC;IAED,MAAM,WAAW,GAAG,IAAA,mBAAU,EAAC,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAEpE,IAAI,QAAQ,KAAK,WAAW,EAAE;QAC5B,MAAM,kBAAE,CAAC,UAAU,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QACvC,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;KACrC;AACH,CAAC;AArCD,4BAqCC;AAED;;;;;;;;;;GAUG;AACI,KAAK,UAAU,kBAAkB,CACtC,SAAiB,EACjB,MAAc,EACd,aAAkC;IAElC,MAAM,qBAAqB,GAAG,cAAI,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,YAAY,CAAC,CAAC;IACzE,MAAM,wBAAwB,GAAG,cAAI,CAAC,IAAI,CACxC,MAAM,EACN,GAAG,SAAS,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CACvC,CAAC;IACF,MAAM,QAAQ,GAAG,MAAM,IAAA,6BAAmB,EACxC;QACE,aAAa,KAAK,KAAK,IAAI,qBAAqB;QAChD,aAAa,KAAK,IAAI,IAAI,wBAAwB;KACnD,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EACxC,kBAAE,CAAC,UAAU,CACd,CAAC;IACF,IAAI,CAAC,QAAQ,EAAE;QACb,MAAM,IAAI,KAAK,CACb,4CAA4C,qBAAqB,GAAG,CACrE,CAAC;KACH;IACD,OAAO,kBAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AAC/B,CAAC;AAvBD,gDAuBC"}

package/lib/gitUtils.d.ts

@@ -4,14 +4,63 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+/** Custom error thrown when git is not found in `PATH`. */
 export declare class GitNotFoundError extends Error {
 }
-export declare const getFileCommitDate: (file: string, { age, includeAuthor, }: {
-    age?: "oldest" | "newest" | undefined;
-    includeAuthor?: boolean | undefined;
-}) => {
+/** Custom error thrown when the current file is not tracked by git. */
+export declare class FileNotTrackedError extends Error {
+}
+/**
+ * Fetches the git history of a file and returns a relevant commit date.
+ * It gets the commit date instead of author date so that amended commits
+ * can have their dates updated.
+ *
+ * @throws {@link GitNotFoundError} If git is not found in `PATH`.
+ * @throws {@link FileNotTrackedError} If the current file is not tracked by git.
+ * @throws Also throws when `git log` exited with non-zero, or when it outputs
+ * unexpected text.
+ */
+export declare function getFileCommitDate(
+/** Absolute path to the file. */
+file: string, args: {
+    /**
+     * `"oldest"` is the commit that added the file, following renames;
+     * `"newest"` is the last commit that edited the file.
+     */
+    age?: 'oldest' | 'newest';
+    /** Use `includeAuthor: true` to get the author information as well. */
+    includeAuthor?: false;
+}): {
+    /** Relevant commit date. */
+    date: Date;
+    /** Timestamp in **seconds**, as returned from git. */
+    timestamp: number;
+};
+/**
+ * Fetches the git history of a file and returns a relevant commit date.
+ * It gets the commit date instead of author date so that amended commits
+ * can have their dates updated.
+ *
+ * @throws {@link GitNotFoundError} If git is not found in `PATH`.
+ * @throws {@link FileNotTrackedError} If the current file is not tracked by git.
+ * @throws Also throws when `git log` exited with non-zero, or when it outputs
+ * unexpected text.
+ */
+export declare function getFileCommitDate(
+/** Absolute path to the file. */
+file: string, args: {
+    /**
+     * `"oldest"` is the commit that added the file, following renames;
+     * `"newest"` is the last commit that edited the file.
+     */
+    age?: 'oldest' | 'newest';
+    includeAuthor: true;
+}): {
+    /** Relevant commit date. */
     date: Date;
+    /** Timestamp in **seconds**, as returned from git. */
     timestamp: number;
-    author?: string | undefined;
+    /** The author's name, as returned from git. */
+    author: string;
 };
 //# sourceMappingURL=gitUtils.d.ts.map

package/lib/gitUtils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gitUtils.d.ts","sourceRoot":"","sources":["../src/gitUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,qBAAa,gBAAiB,SAAQ,KAAK;CAAG;AAE9C,eAAO,MAAM,iBAAiB,SACtB,MAAM;;;;UASN,IAAI;eACC,MAAM;;CAqElB,CAAC"}
+{"version":3,"file":"gitUtils.d.ts","sourceRoot":"","sources":["../src/gitUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,2DAA2D;AAC3D,qBAAa,gBAAiB,SAAQ,KAAK;CAAG;AAE9C,uEAAuE;AACvE,qBAAa,mBAAoB,SAAQ,KAAK;CAAG;AAEjD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB;AAC/B,iCAAiC;AACjC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE;IACJ;;;OAGG;IACH,GAAG,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC1B,uEAAuE;IACvE,aAAa,CAAC,EAAE,KAAK,CAAC;CACvB,GACA;IACD,4BAA4B;IAC5B,IAAI,EAAE,IAAI,CAAC;IACX,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AACF;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB;AAC/B,iCAAiC;AACjC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE;IACJ;;;OAGG;IACH,GAAG,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC1B,aAAa,EAAE,IAAI,CAAC;CACrB,GACA;IACD,4BAA4B;IAC5B,IAAI,EAAE,IAAI,CAAC;IACX,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC"}

package/lib/gitUtils.js

@@ -6,22 +6,25 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getFileCommitDate = exports.GitNotFoundError = void 0;
+exports.getFileCommitDate = exports.FileNotTrackedError = exports.GitNotFoundError = void 0;
 const tslib_1 = require("tslib");
-const path_1 = (0, tslib_1.__importDefault)(require("path"));
-const shelljs_1 = (0, tslib_1.__importDefault)(require("shelljs"));
+const path_1 = tslib_1.__importDefault(require("path"));
+const shelljs_1 = tslib_1.__importDefault(require("shelljs"));
+/** Custom error thrown when git is not found in `PATH`. */
 class GitNotFoundError extends Error {
 }
 exports.GitNotFoundError = GitNotFoundError;
-const getFileCommitDate = (file, { age = 'oldest', includeAuthor = false, }) => {
+/** Custom error thrown when the current file is not tracked by git. */
+class FileNotTrackedError extends Error {
+}
+exports.FileNotTrackedError = FileNotTrackedError;
+function getFileCommitDate(file, { age = 'oldest', includeAuthor = false, }) {
     if (!shelljs_1.default.which('git')) {
         throw new GitNotFoundError(`Failed to retrieve git history for "${file}" because git is not installed.`);
     }
     if (!shelljs_1.default.test('-f', file)) {
         throw new Error(`Failed to retrieve git history for "${file}" because the file does not exist.`);
     }
-    const fileBasename = path_1.default.basename(file);
-    const fileDirname = path_1.default.dirname(file);
     let formatArg = '--format=%ct';
     if (includeAuthor) {
         formatArg += ',%an';
@@ -32,9 +35,9 @@ const getFileCommitDate = (file, { age = 'oldest', includeAuthor = false, }) =>
         // --diff-filter=A ensures we only get the commit which (A)dded the file
         extraArgs += ' --follow --diff-filter=A';
     }
-    const result = shelljs_1.default.exec(`git log ${extraArgs} ${formatArg} -- "${fileBasename}"`, {
-        // cwd is important, see: https://github.com/facebook/docusaurus/pull/5048
-        cwd: fileDirname,
+    const result = shelljs_1.default.exec(`git log ${extraArgs} ${formatArg} -- "${path_1.default.basename(file)}"`, {
+        // Setting cwd is important, see: https://github.com/facebook/docusaurus/pull/5048
+        cwd: path_1.default.dirname(file),
         silent: true,
     });
     if (result.code !== 0) {
@@ -45,11 +48,11 @@ const getFileCommitDate = (file, { age = 'oldest', includeAuthor = false, }) =>
         regex = /^(?<timestamp>\d+),(?<author>.+)$/;
     }
     const output = result.stdout.trim();
+    if (!output) {
+        throw new FileNotTrackedError(`Failed to retrieve the git history for file "${file}" because the file is not tracked by git.`);
+    }
     const match = output.match(regex);
-    if (!match ||
-        !match.groups ||
-        !match.groups.timestamp ||
-        (includeAuthor && !match.groups.author)) {
+    if (!match) {
         throw new Error(`Failed to retrieve the git history for file "${file}" with unexpected output: ${output}`);
     }
     const timestamp = Number(match.groups.timestamp);
@@ -58,6 +61,6 @@ const getFileCommitDate = (file, { age = 'oldest', includeAuthor = false, }) =>
         return { date, timestamp, author: match.groups.author };
     }
     return { date, timestamp };
-};
+}
 exports.getFileCommitDate = getFileCommitDate;
 //# sourceMappingURL=gitUtils.js.map

package/lib/gitUtils.js.map

@@ -1 +1 @@
-{"version":3,"file":"gitUtils.js","sourceRoot":"","sources":["../src/gitUtils.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;;AAEH,6DAAwB;AACxB,mEAA4B;AAE5B,MAAa,gBAAiB,SAAQ,KAAK;CAAG;AAA9C,4CAA8C;AAEvC,MAAM,iBAAiB,GAAG,CAC/B,IAAY,EACZ,EACE,GAAG,GAAG,QAAQ,EACd,aAAa,GAAG,KAAK,GAItB,EAKD,EAAE;IACF,IAAI,CAAC,iBAAK,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE;QACvB,MAAM,IAAI,gBAAgB,CACxB,uCAAuC,IAAI,iCAAiC,CAC7E,CAAC;KACH;IAED,IAAI,CAAC,iBAAK,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE;QAC3B,MAAM,IAAI,KAAK,CACb,uCAAuC,IAAI,oCAAoC,CAChF,CAAC;KACH;IAED,MAAM,YAAY,GAAG,cAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IACzC,MAAM,WAAW,GAAG,cAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvC,IAAI,SAAS,GAAG,cAAc,CAAC;IAC/B,IAAI,aAAa,EAAE;QACjB,SAAS,IAAI,MAAM,CAAC;KACrB;IAED,IAAI,SAAS,GAAG,eAAe,CAAC;IAChC,IAAI,GAAG,KAAK,QAAQ,EAAE;QACpB,+CAA+C;QAC/C,wEAAwE;QACxE,SAAS,IAAI,2BAA2B,CAAC;KAC1C;IAED,MAAM,MAAM,GAAG,iBAAK,CAAC,IAAI,CACvB,WAAW,SAAS,IAAI,SAAS,QAAQ,YAAY,GAAG,EACxD;QACE,0EAA0E;QAC1E,GAAG,EAAE,WAAW;QAChB,MAAM,EAAE,IAAI;KACb,CACF,CAAC;IACF,IAAI,MAAM,CAAC,IAAI,KAAK,CAAC,EAAE;QACrB,MAAM,IAAI,KAAK,CACb,gDAAgD,IAAI,oBAAoB,MAAM,CAAC,IAAI,KAAK,MAAM,CAAC,MAAM,EAAE,CACxG,CAAC;KACH;IACD,IAAI,KAAK,GAAG,qBAAqB,CAAC;IAClC,IAAI,aAAa,EAAE;QACjB,KAAK,GAAG,mCAAmC,CAAC;KAC7C;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IACpC,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAElC,IACE,CAAC,KAAK;QACN,CAAC,KAAK,CAAC,MAAM;QACb,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS;QACvB,CAAC,aAAa,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,EACvC;QACA,MAAM,IAAI,KAAK,CACb,gDAAgD,IAAI,6BAA6B,MAAM,EAAE,CAC1F,CAAC;KACH;IAED,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACjD,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAExC,IAAI,aAAa,EAAE;QACjB,OAAO,EAAC,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAC,CAAC;KACvD;IACD,OAAO,EAAC,IAAI,EAAE,SAAS,EAAC,CAAC;AAC3B,CAAC,CAAC;AAhFW,QAAA,iBAAiB,qBAgF5B"}
+{"version":3,"file":"gitUtils.js","sourceRoot":"","sources":["../src/gitUtils.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;;AAEH,wDAAwB;AACxB,8DAA4B;AAE5B,2DAA2D;AAC3D,MAAa,gBAAiB,SAAQ,KAAK;CAAG;AAA9C,4CAA8C;AAE9C,uEAAuE;AACvE,MAAa,mBAAoB,SAAQ,KAAK;CAAG;AAAjD,kDAAiD;AA2DjD,SAAgB,iBAAiB,CAC/B,IAAY,EACZ,EACE,GAAG,GAAG,QAAQ,EACd,aAAa,GAAG,KAAK,GAItB;IAMD,IAAI,CAAC,iBAAK,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE;QACvB,MAAM,IAAI,gBAAgB,CACxB,uCAAuC,IAAI,iCAAiC,CAC7E,CAAC;KACH;IAED,IAAI,CAAC,iBAAK,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE;QAC3B,MAAM,IAAI,KAAK,CACb,uCAAuC,IAAI,oCAAoC,CAChF,CAAC;KACH;IAED,IAAI,SAAS,GAAG,cAAc,CAAC;IAC/B,IAAI,aAAa,EAAE;QACjB,SAAS,IAAI,MAAM,CAAC;KACrB;IAED,IAAI,SAAS,GAAG,eAAe,CAAC;IAChC,IAAI,GAAG,KAAK,QAAQ,EAAE;QACpB,+CAA+C;QAC/C,wEAAwE;QACxE,SAAS,IAAI,2BAA2B,CAAC;KAC1C;IAED,MAAM,MAAM,GAAG,iBAAK,CAAC,IAAI,CACvB,WAAW,SAAS,IAAI,SAAS,QAAQ,cAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,EAC/D;QACE,kFAAkF;QAClF,GAAG,EAAE,cAAI,CAAC,OAAO,CAAC,IAAI,CAAC;QACvB,MAAM,EAAE,IAAI;KACb,CACF,CAAC;IACF,IAAI,MAAM,CAAC,IAAI,KAAK,CAAC,EAAE;QACrB,MAAM,IAAI,KAAK,CACb,gDAAgD,IAAI,oBAAoB,MAAM,CAAC,IAAI,KAAK,MAAM,CAAC,MAAM,EAAE,CACxG,CAAC;KACH;IACD,IAAI,KAAK,GAAG,qBAAqB,CAAC;IAClC,IAAI,aAAa,EAAE;QACjB,KAAK,GAAG,mCAAmC,CAAC;KAC7C;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IAEpC,IAAI,CAAC,MAAM,EAAE;QACX,MAAM,IAAI,mBAAmB,CAC3B,gDAAgD,IAAI,2CAA2C,CAChG,CAAC;KACH;IAED,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAElC,IAAI,CAAC,KAAK,EAAE;QACV,MAAM,IAAI,KAAK,CACb,gDAAgD,IAAI,6BAA6B,MAAM,EAAE,CAC1F,CAAC;KACH;IAED,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,MAAO,CAAC,SAAS,CAAC,CAAC;IAClD,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAExC,IAAI,aAAa,EAAE;QACjB,OAAO,EAAC,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,MAAO,CAAC,MAAO,EAAC,CAAC;KACzD;IACD,OAAO,EAAC,IAAI,EAAE,SAAS,EAAC,CAAC;AAC3B,CAAC;AA/ED,8CA+EC"}