@docusaurus/utils 2.0.0-beta.17 → 2.0.0-beta.18

package/src/dataFileUtils.ts

@@ -13,15 +13,25 @@ import type {ContentPaths} from './markdownLinks';
 import logger from '@docusaurus/logger';
 
 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 async function getDataFilePath({
   filePath,
   contentPaths,
 }: DataFileParams): Promise<string | undefined> {
-  // Loads a localized data file in priority
   const contentPath = await findFolderContainingFile(
     getContentPathList(contentPaths),
     filePath,
@@ -33,11 +43,17 @@ export async function 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.
  */
 export async function getDataFileData<T>(
-  params: DataFileParams & {fileType: string},
+  params: DataFileParams & {
+    /** Used for the "The X file looks invalid" message. */
+    fileType: string;
+  },
   validate: (content: unknown) => T,
 ): Promise<T | undefined> {
   const filePath = await getDataFilePath(params);
@@ -49,18 +65,26 @@ export async function getDataFileData<T>(
     const unsafeContent = Yaml.load(contentString);
     return validate(unsafeContent);
   } catch (err) {
-    // TODO replace later by error cause, see https://v8.dev/features/error-cause
     logger.error`The ${params.fileType} file at path=${filePath} looks invalid.`;
     throw err;
   }
 }
 
-// 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.
+ */
 export function getContentPathList(contentPaths: ContentPaths): string[] {
   return [contentPaths.contentPathLocalized, contentPaths.contentPath];
 }
 
-// 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.
+ */
 export async function findFolderContainingFile(
   folderPaths: string[],
   relativeFilePath: string,
@@ -70,6 +94,16 @@ export async function 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)
+ */
 export async function getFolderContainingFile(
   folderPaths: string[],
   relativeFilePath: string,
@@ -78,12 +112,10 @@ export async function getFolderContainingFile(
     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- ',
-      )}]`,
+      `File "${relativeFilePath}" does not exist in any of these folders:
+- ${folderPaths.join('\n- ')}`,
     );
   }
   return maybeFolderPath;

package/src/emitUtils.ts

@@ -13,6 +13,16 @@ import {findAsyncSequential} from './jsUtils';
 
 const fileHash = new Map<string, string>();
 
+/**
+ * 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`.
+ * @param content String content to write.
+ * @param skipCache If `true` (defaults as `true` for production), file is
+ * force-rewritten, skipping cache.
+ */
 export async function generate(
   generatedFilesDir: string,
   file: string,
@@ -22,16 +32,22 @@ export async function generate(
   const filepath = path.join(generatedFilesDir, file);
 
   if (skipCache) {
-    await fs.ensureDir(path.dirname(filepath));
-    await fs.writeFile(filepath, content);
+    await fs.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, createHash('md5').update(content).digest('hex'));
+    }
     return;
   }
 
   let lastHash = fileHash.get(filepath);
 
-  // If file already exists but its 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 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.pathExists(filepath))) {
     const lastContent = await fs.readFile(filepath, 'utf8');
     lastHash = createHash('md5').update(lastContent).digest('hex');
@@ -41,13 +57,12 @@ export async function generate(
   const currentHash = createHash('md5').update(content).digest('hex');
 
   if (lastHash !== currentHash) {
-    await fs.ensureDir(path.dirname(filepath));
-    await fs.writeFile(filepath, content);
+    await fs.outputFile(filepath, content);
     fileHash.set(filepath, currentHash);
   }
 }
 
-const chunkNameCache = new Map();
+const chunkNameCache = new Map<string, string>();
 
 /**
  * Generate unique chunk name given a module path.
@@ -58,7 +73,7 @@ export function genChunkName(
   preferredName?: string,
   shortId: boolean = process.env.NODE_ENV === 'production',
 ): string {
-  let chunkName: string | undefined = chunkNameCache.get(modulePath);
+  let chunkName = chunkNameCache.get(modulePath);
   if (!chunkName) {
     if (shortId) {
       chunkName = simpleHash(modulePath, 8);
@@ -84,6 +99,8 @@ export function genChunkName(
  * @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 async function readOutputHTMLFile(
   permalink: string,

package/src/gitUtils.ts

@@ -8,9 +8,70 @@
 import path from 'path';
 import shell from 'shelljs';
 
+/** Custom error thrown when git is not found in `PATH`. */
 export class GitNotFoundError extends Error {}
 
-export const getFileCommitDate = (
+/** Custom error thrown when the current file is not tracked by git. */
+export 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 {GitNotFoundError} If git is not found in `PATH`.
+ * @throws {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 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 {GitNotFoundError} If git is not found in `PATH`.
+ * @throws {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 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;
+  /** The author's name, as returned from git. */
+  author: string;
+};
+export function getFileCommitDate(
   file: string,
   {
     age = 'oldest',
@@ -23,7 +84,7 @@ export const getFileCommitDate = (
   date: Date;
   timestamp: number;
   author?: string;
-} => {
+} {
   if (!shell.which('git')) {
     throw new GitNotFoundError(
       `Failed to retrieve git history for "${file}" because git is not installed.`,
@@ -36,9 +97,6 @@ export const getFileCommitDate = (
     );
   }
 
-  const fileBasename = path.basename(file);
-  const fileDirname = path.dirname(file);
-
   let formatArg = '--format=%ct';
   if (includeAuthor) {
     formatArg += ',%an';
@@ -52,10 +110,10 @@ export const getFileCommitDate = (
   }
 
   const result = shell.exec(
-    `git log ${extraArgs} ${formatArg} -- "${fileBasename}"`,
+    `git log ${extraArgs} ${formatArg} -- "${path.basename(file)}"`,
     {
       // cwd is important, see: https://github.com/facebook/docusaurus/pull/5048
-      cwd: fileDirname,
+      cwd: path.dirname(file),
       silent: true,
     },
   );
@@ -70,24 +128,26 @@ export const getFileCommitDate = (
   }
 
   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);
+  const timestamp = Number(match.groups!.timestamp);
   const date = new Date(timestamp * 1000);
 
   if (includeAuthor) {
-    return {date, timestamp, author: match.groups.author};
+    return {date, timestamp, author: match.groups!.author!};
   }
   return {date, timestamp};
-};
+}

package/src/globUtils.ts

@@ -10,24 +10,31 @@
 import Micromatch from 'micromatch'; // Note: Micromatch is used by Globby
 import path from 'path';
 
+/** A re-export of the globby instance. */
 export {default as Globby} from 'globby';
 
-// The default patterns we ignore when globbing
-// using _ prefix for exclusion by convention
+/**
+ * The default glob patterns we ignore when sourcing content.
+ * - Ignore files and folders starting with `_` recursively
+ * - Ignore tests
+ */
 export const GlobExcludeDefault = [
-  // Ignore files starting with _
   '**/_*.{js,jsx,ts,tsx,md,mdx}',
-
-  // Ignore folders starting with _ (including folder content)
   '**/_*/**',
-
-  // Ignore tests
   '**/*.test.{js,jsx,ts,tsx}',
   '**/__tests__/**',
 ];
 
 type Matcher = (str: string) => boolean;
 
+/**
+ * A very thin wrapper around `Micromatch.makeRe`.
+ *
+ * @see {@link createAbsoluteFilePathMatcher}
+ * @param patterns A list of glob patterns.
+ * @returns A matcher handle that tells if a file path is matched by any of the
+ * patterns.
+ */
 export function createMatcher(patterns: string[]): Matcher {
   const regexp = new RegExp(
     patterns.map((pattern) => Micromatch.makeRe(pattern).source).join('|'),
@@ -35,10 +42,19 @@ export function createMatcher(patterns: string[]): Matcher {
   return (str) => regexp.test(str);
 }
 
-// We use match patterns like '**/_*/**',
-// This function permits to help to:
-// Match /user/sebastien/website/docs/_partials/xyz.md
-// Ignore /user/_sebastien/website/docs/partials/xyz.md
+/**
+ * We use match patterns like `"** /_* /**"` (ignore the spaces), where `"_*"`
+ * should only be matched within a subfolder. This function would:
+ * - Match `/user/sebastien/website/docs/_partials/xyz.md`
+ * - Ignore `/user/_sebastien/website/docs/partials/xyz.md`
+ *
+ * @param patterns A list of glob patterns.
+ * @param rootFolders A list of root folders to resolve the glob from.
+ * @returns A matcher handle that tells if a file path is matched by any of the
+ * patterns, resolved from the first root folder that contains the path.
+ * @throws Throws when the returned matcher receives a path that doesn't belong
+ * to any of the `rootFolders`.
+ */
 export function createAbsoluteFilePathMatcher(
   patterns: string[],
   rootFolders: string[],
@@ -51,8 +67,8 @@ export function createAbsoluteFilePathMatcher(
     );
     if (!rootFolder) {
       throw new Error(
-        `createAbsoluteFilePathMatcher unexpected error, absoluteFilePath=${absoluteFilePath} was not contained in any of the root folders ${JSON.stringify(
-          rootFolders,
+        `createAbsoluteFilePathMatcher unexpected error, absoluteFilePath=${absoluteFilePath} was not contained in any of the root folders: ${rootFolders.join(
+          ', ',
         )}`,
       );
     }

package/src/hashUtils.ts

@@ -9,20 +9,21 @@ import {createHash} from 'crypto';
 import _ from 'lodash';
 import {shortName, isNameTooLong} from './pathUtils';
 
+/** Thin wrapper around `crypto.createHash("md5")`. */
 export function md5Hash(str: string): string {
   return createHash('md5').update(str).digest('hex');
 }
 
+/** Creates an MD5 hash and truncates it to the given length. */
 export function simpleHash(str: string, length: number): string {
-  return md5Hash(str).substr(0, length);
+  return md5Hash(str).substring(0, length);
 }
 
 // Based on https://github.com/gatsbyjs/gatsby/pull/21518/files
 /**
- * Given an input string, convert to kebab-case and append a hash.
- * Avoid str collision.
- * Also removes part of the string if its larger than the allowed
- * filename per OS. Avoids ERRNAMETOOLONG error.
+ * Given an input string, convert to kebab-case and append a hash, avoiding name
+ * collision. Also removes part of the string if its larger than the allowed
+ * filename per OS, avoiding `ERRNAMETOOLONG` error.
  */
 export function docuHash(str: string): string {
   if (str === '/') {

package/src/i18nUtils.ts

@@ -8,16 +8,21 @@
 import path from 'path';
 import _ from 'lodash';
 import type {TranslationFileContent, TranslationFile} from '@docusaurus/types';
-import {DEFAULT_PLUGIN_ID} from './constants';
+import {DEFAULT_PLUGIN_ID, I18N_DIR_NAME} from './constants';
 
+/**
+ * Takes a list of translation file contents, and shallow-merges them into one.
+ */
 export function mergeTranslations(
   contents: TranslationFileContent[],
 ): TranslationFileContent {
   return contents.reduce((acc, content) => ({...acc, ...content}), {});
 }
 
-// Useful to update all the messages of a translation file
-// Used in tests to simulate translations
+/**
+ * Useful to update all the messages of a translation file. Used in tests to
+ * simulate translations.
+ */
 export function updateTranslationFileMessages(
   translationFile: TranslationFile,
   updateMessage: (message: string) => string,
@@ -31,6 +36,10 @@ export function updateTranslationFileMessages(
   };
 }
 
+/**
+ * Takes everything needed and constructs a plugin i18n path. Plugins should
+ * expect everything it needs for translations to be found under this path.
+ */
 export function getPluginI18nPath({
   siteDir,
   locale,
@@ -46,7 +55,7 @@ export function getPluginI18nPath({
 }): string {
   return path.join(
     siteDir,
-    'i18n',
+    I18N_DIR_NAME,
     // namespace first by locale: convenient to work in a single folder for a
     // translator
     locale,

package/src/index.ts

@@ -13,15 +13,21 @@ export {
   BABEL_CONFIG_FILE_NAME,
   GENERATED_FILES_DIR_NAME,
   SRC_DIR_NAME,
-  STATIC_DIR_NAME,
+  DEFAULT_STATIC_DIR_NAME,
   OUTPUT_STATIC_ASSETS_DIR_NAME,
   THEME_PATH,
+  I18N_DIR_NAME,
+  CODE_TRANSLATIONS_FILE_NAME,
   DEFAULT_PORT,
   DEFAULT_PLUGIN_ID,
   WEBPACK_URL_LOADER_LIMIT,
 } from './constants';
 export {generate, genChunkName, readOutputHTMLFile} from './emitUtils';
-export {getFileCommitDate, GitNotFoundError} from './gitUtils';
+export {
+  getFileCommitDate,
+  FileNotTrackedError,
+  GitNotFoundError,
+} from './gitUtils';
 export {
   mergeTranslations,
   updateTranslationFileMessages,
@@ -30,7 +36,6 @@ export {
 export {
   removeSuffix,
   removePrefix,
-  getElementsAround,
   mapAsyncSequential,
   findAsyncSequential,
   reportMessage,
@@ -45,12 +50,13 @@ export {
   addLeadingSlash,
   addTrailingSlash,
   removeTrailingSlash,
+  hasSSHProtocol,
+  buildHttpsUrl,
+  buildSshUrl,
 } from './urlUtils';
 export {
   type Tag,
   type FrontMatterTag,
-  type TaggedItemGroup,
-  normalizeFrontMatterTag,
   normalizeFrontMatterTags,
   groupTaggedItems,
 } from './tags';
@@ -60,12 +66,12 @@ export {
   parseFrontMatter,
   parseMarkdownContentTitle,
   parseMarkdownString,
-} from './markdownParser';
+  writeMarkdownHeadingId,
+  type WriteHeadingIDOptions,
+} from './markdownUtils';
 export {
   type ContentPaths,
   type BrokenMarkdownLink,
-  type ReplaceMarkdownLinksParams,
-  type ReplaceMarkdownLinksReturn,
   replaceMarkdownLinks,
 } from './markdownLinks';
 export {type SluggerOptions, type Slugger, createSlugger} from './slugger';

package/src/jsUtils.ts

@@ -8,36 +8,27 @@
 import type {ReportingSeverity} from '@docusaurus/types';
 import logger from '@docusaurus/logger';
 
+/** Removes a given string suffix from `str`. */
 export function removeSuffix(str: string, suffix: string): string {
   if (suffix === '') {
-    return str; // always returns "" otherwise!
+    // str.slice(0, 0) is ""
+    return str;
   }
   return str.endsWith(suffix) ? str.slice(0, -suffix.length) : str;
 }
 
+/** Removes a given string prefix from `str`. */
 export function removePrefix(str: string, prefix: string): string {
   return str.startsWith(prefix) ? str.slice(prefix.length) : str;
 }
 
-export function getElementsAround<T>(
-  array: T[],
-  aroundIndex: number,
-): {
-  next: T | undefined;
-  previous: T | undefined;
-} {
-  const min = 0;
-  const max = array.length - 1;
-  if (aroundIndex < min || aroundIndex > max) {
-    throw new Error(
-      `Valid "aroundIndex" for array (of size ${array.length}) are between ${min} and ${max}, but you provided ${aroundIndex}.`,
-    );
-  }
-  const previous = aroundIndex === min ? undefined : array[aroundIndex - 1];
-  const next = aroundIndex === max ? undefined : array[aroundIndex + 1];
-  return {previous, next};
-}
-
+/**
+ * `Array#map` for async operations where order matters.
+ * @param array The array to traverse.
+ * @param action An async action to be performed on every array item. Will be
+ * awaited before working on the next.
+ * @returns The list of results returned from every `action(item)`
+ */
 export async function mapAsyncSequential<T, R>(
   array: T[],
   action: (t: T) => Promise<R>,
@@ -50,6 +41,14 @@ export async function mapAsyncSequential<T, R>(
   return results;
 }
 
+/**
+ * `Array#find` for async operations where order matters.
+ * @param array The array to traverse.
+ * @param predicate An async predicate to be called on every array item. Should
+ * return a boolean indicating whether the currently element should be returned.
+ * @returns The function immediately returns the first item on which `predicate`
+ * returns `true`, or `undefined` if none matches the predicate.
+ */
 export async function findAsyncSequential<T>(
   array: T[],
   predicate: (t: T) => Promise<boolean>,
@@ -62,6 +61,21 @@ export async function findAsyncSequential<T>(
   return undefined;
 }
 
+/**
+ * Takes a message and reports it according to the severity that the user wants.
+ *
+ * - `ignore`: completely no-op
+ * - `log`: uses the `INFO` log level
+ * - `warn`: uses the `WARN` log level
+ * - `error`: uses the `ERROR` log level
+ * - `throw`: aborts the process, throws the error.
+ *
+ * Since the logger doesn't have logging level filters yet, these severities
+ * mostly just differ by their colors.
+ *
+ * @throws In addition to throwing when `reportingSeverity === "throw"`, this
+ * function also throws if `reportingSeverity` is not one of the above.
+ */
 export function reportMessage(
   message: string,
   reportingSeverity: ReportingSeverity,