@docusaurus/utils 2.0.0-beta.fc64c12e4 → 2.0.0

package/src/emitUtils.ts

@@ -0,0 +1,99 @@
+/**
+ * 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 path from 'path';
+import fs from 'fs-extra';
+import {createHash} from 'crypto';
+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`. 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 async function generate(
+  generatedFilesDir: string,
+  file: string,
+  content: string,
+  skipCache: boolean = process.env.NODE_ENV === 'production',
+): Promise<void> {
+  const filepath = path.resolve(generatedFilesDir, file);
+
+  if (skipCache) {
+    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 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');
+    fileHash.set(filepath, lastHash);
+  }
+
+  const currentHash = createHash('md5').update(content).digest('hex');
+
+  if (lastHash !== currentHash) {
+    await fs.outputFile(filepath, content);
+    fileHash.set(filepath, currentHash);
+  }
+}
+
+/**
+ * @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 async function readOutputHTMLFile(
+  permalink: string,
+  outDir: string,
+  trailingSlash: boolean | undefined,
+): Promise<Buffer> {
+  const withTrailingSlashPath = path.join(outDir, permalink, 'index.html');
+  const withoutTrailingSlashPath = path.join(
+    outDir,
+    `${permalink.replace(/\/$/, '')}.html`,
+  );
+  const HTMLPath = await findAsyncSequential(
+    [
+      trailingSlash !== false && withTrailingSlashPath,
+      trailingSlash !== true && withoutTrailingSlashPath,
+    ].filter((p): p is string => Boolean(p)),
+    fs.pathExists,
+  );
+  if (!HTMLPath) {
+    throw new Error(
+      `Expected output HTML file to be found at ${withTrailingSlashPath}.`,
+    );
+  }
+  return fs.readFile(HTMLPath);
+}

package/src/gitUtils.ts

@@ -0,0 +1,146 @@
+/**
+ * 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 path from 'path';
+import shell from 'shelljs';
+
+/** Custom error thrown when git is not found in `PATH`. */
+export class GitNotFoundError extends Error {}
+
+/** 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 {@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 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 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',
+    includeAuthor = false,
+  }: {
+    age?: 'oldest' | 'newest';
+    includeAuthor?: boolean;
+  },
+): {
+  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.`,
+    );
+  }
+
+  if (!shell.test('-f', file)) {
+    throw new Error(
+      `Failed to retrieve git history for "${file}" because the file does not exist.`,
+    );
+  }
+
+  const args = [
+    `--format=%ct${includeAuthor ? ',%an' : ''}`,
+    '--max-count=1',
+    age === 'oldest' ? '--follow --diff-filter=A' : undefined,
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+  const result = shell.exec(`git log ${args} -- "${path.basename(file)}"`, {
+    // Setting cwd is important, see: https://github.com/facebook/docusaurus/pull/5048
+    cwd: path.dirname(file),
+    silent: true,
+  });
+  if (result.code !== 0) {
+    throw new Error(
+      `Failed to retrieve the git history for file "${file}" with exit code ${result.code}: ${result.stderr}`,
+    );
+  }
+  let regex = /^(?<timestamp>\d+)$/;
+  if (includeAuthor) {
+    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) {
+    throw new Error(
+      `Failed to retrieve the git history for file "${file}" with unexpected output: ${output}`,
+    );
+  }
+
+  const timestamp = Number(match.groups!.timestamp);
+  const date = new Date(timestamp * 1000);
+
+  if (includeAuthor) {
+    return {date, timestamp, author: match.groups!.author!};
+  }
+  return {date, timestamp};
+}

package/src/globUtils.ts

@@ -7,37 +7,59 @@
 
 // Globby/Micromatch are the 2 libs we use in Docusaurus consistently
 
-export {default as Globby} from 'globby';
-import Micromatch from 'micromatch'; // Note: Micromatch is used by Globby
 import path from 'path';
+import Micromatch from 'micromatch'; // Note: Micromatch is used by Globby
+
+/** 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. If the list is empty, it defaults to
+ * matching none.
+ * @returns A matcher handle that tells if a file path is matched by any of the
+ * patterns.
+ */
 export function createMatcher(patterns: string[]): Matcher {
+  if (patterns.length === 0) {
+    // `/(?:)/.test("foo")` is `true`
+    return () => false;
+  }
   const regexp = new RegExp(
     patterns.map((pattern) => Micromatch.makeRe(pattern).source).join('|'),
   );
   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[],
@@ -50,8 +72,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

@@ -6,32 +6,33 @@
  */
 
 import {createHash} from 'crypto';
-import {kebabCase} from 'lodash';
+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 === '/') {
     return 'index';
   }
   const shortHash = simpleHash(str, 3);
-  const parsedPath = `${kebabCase(str)}-${shortHash}`;
+  const parsedPath = `${_.kebabCase(str)}-${shortHash}`;
   if (isNameTooLong(parsedPath)) {
-    return `${shortName(kebabCase(str))}-${shortHash}`;
+    return `${shortName(_.kebabCase(str))}-${shortHash}`;
   }
   return parsedPath;
 }

package/src/i18nUtils.ts

@@ -0,0 +1,114 @@
+/**
+ * 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 path from 'path';
+import _ from 'lodash';
+import {DEFAULT_PLUGIN_ID} from './constants';
+import {normalizeUrl} from './urlUtils';
+import type {
+  TranslationFileContent,
+  TranslationFile,
+  I18n,
+} from '@docusaurus/types';
+
+/**
+ * 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.
+ */
+export function updateTranslationFileMessages(
+  translationFile: TranslationFile,
+  updateMessage: (message: string) => string,
+): TranslationFile {
+  return {
+    ...translationFile,
+    content: _.mapValues(translationFile.content, (translation) => ({
+      ...translation,
+      message: updateMessage(translation.message),
+    })),
+  };
+}
+
+/**
+ * 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({
+  localizationDir,
+  pluginName,
+  pluginId = DEFAULT_PLUGIN_ID,
+  subPaths = [],
+}: {
+  localizationDir: string;
+  pluginName: string;
+  pluginId?: string | undefined;
+  subPaths?: string[];
+}): string {
+  return path.join(
+    localizationDir,
+    // Make it convenient to use for single-instance
+    // ie: return "docs", not "docs-default" nor "docs/default"
+    `${pluginName}${pluginId === DEFAULT_PLUGIN_ID ? '' : `-${pluginId}`}`,
+    ...subPaths,
+  );
+}
+
+/**
+ * Takes a path and returns a localized a version (which is basically `path +
+ * i18n.currentLocale`).
+ *
+ * This is used to resolve the `outDir` and `baseUrl` of each locale; it is NOT
+ * used to determine plugin localization file locations.
+ */
+export function localizePath({
+  pathType,
+  path: originalPath,
+  i18n,
+  options = {},
+}: {
+  /**
+   * FS paths will treat Windows specially; URL paths will always have a
+   * trailing slash to make it a valid base URL.
+   */
+  pathType: 'fs' | 'url';
+  /** The path, URL or file path, to be localized. */
+  path: string;
+  /** The current i18n context. */
+  i18n: I18n;
+  options?: {
+    /**
+     * By default, we don't localize the path of defaultLocale. This option
+     * would override that behavior. Setting `false` is useful for `yarn build
+     * -l zh-Hans` to always emit into the root build directory.
+     */
+    localizePath?: boolean;
+  };
+}): string {
+  const shouldLocalizePath: boolean =
+    options.localizePath ?? i18n.currentLocale !== i18n.defaultLocale;
+
+  if (!shouldLocalizePath) {
+    return originalPath;
+  }
+  // FS paths need special care, for Windows support. Note: we don't use the
+  // locale config's `path` here, because this function is used for resolving
+  // outDir, which must be the same as baseUrl. When we have the baseUrl config,
+  // we need to sync the two.
+  if (pathType === 'fs') {
+    return path.join(originalPath, i18n.currentLocale);
+  }
+  // Url paths; add a trailing slash so it's a valid base URL
+  return normalizeUrl([originalPath, i18n.currentLocale, '/']);
+}