@docusaurus/utils 2.0.0-beta.15a2b59f9 → 2.0.0-beta.17

package/src/emitUtils.ts

@@ -0,0 +1,113 @@
+/**
+ * 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 {simpleHash, docuHash} from './hashUtils';
+import {findAsyncSequential} from './jsUtils';
+
+const fileHash = new Map<string, string>();
+
+export async function generate(
+  generatedFilesDir: string,
+  file: string,
+  content: string,
+  skipCache: boolean = process.env.NODE_ENV === 'production',
+): Promise<void> {
+  const filepath = path.join(generatedFilesDir, file);
+
+  if (skipCache) {
+    await fs.ensureDir(path.dirname(filepath));
+    await fs.writeFile(filepath, content);
+    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 (!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.ensureDir(path.dirname(filepath));
+    await fs.writeFile(filepath, content);
+    fileHash.set(filepath, currentHash);
+  }
+}
+
+const chunkNameCache = new Map();
+
+/**
+ * Generate unique chunk name given a module path.
+ */
+export function genChunkName(
+  modulePath: string,
+  prefix?: string,
+  preferredName?: string,
+  shortId: boolean = process.env.NODE_ENV === 'production',
+): string {
+  let chunkName: string | undefined = chunkNameCache.get(modulePath);
+  if (!chunkName) {
+    if (shortId) {
+      chunkName = simpleHash(modulePath, 8);
+    } else {
+      let str = modulePath;
+      if (preferredName) {
+        const shortHash = simpleHash(modulePath, 3);
+        str = `${preferredName}${shortHash}`;
+      }
+      const name = str === '/' ? 'index' : docuHash(str);
+      chunkName = prefix ? `${prefix}---${name}` : name;
+    }
+    chunkNameCache.set(modulePath, chunkName);
+  }
+  return chunkName;
+}
+
+/**
+ * @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)
+ */
+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`,
+  );
+  if (trailingSlash) {
+    return fs.readFile(withTrailingSlashPath);
+  } else if (trailingSlash === false) {
+    return fs.readFile(withoutTrailingSlashPath);
+  }
+  const HTMLPath = await findAsyncSequential(
+    [withTrailingSlashPath, withoutTrailingSlashPath],
+    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,93 @@
+/**
+ * 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';
+
+export class GitNotFoundError extends Error {}
+
+export const 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 fileBasename = path.basename(file);
+  const fileDirname = path.dirname(file);
+
+  let formatArg = '--format=%ct';
+  if (includeAuthor) {
+    formatArg += ',%an';
+  }
+
+  let extraArgs = '--max-count=1';
+  if (age === 'oldest') {
+    // --follow is necessary to follow file renames
+    // --diff-filter=A ensures we only get the commit which (A)dded the file
+    extraArgs += ' --follow --diff-filter=A';
+  }
+
+  const result = shell.exec(
+    `git log ${extraArgs} ${formatArg} -- "${fileBasename}"`,
+    {
+      // cwd is important, see: https://github.com/facebook/docusaurus/pull/5048
+      cwd: fileDirname,
+      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();
+  const match = output.match(regex);
+
+  if (
+    !match ||
+    !match.groups ||
+    !match.groups.timestamp ||
+    (includeAuthor && !match.groups.author)
+  ) {
+    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

@@ -0,0 +1,64 @@
+/**
+ * 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.
+ */
+
+// Globby/Micromatch are the 2 libs we use in Docusaurus consistently
+
+import Micromatch from 'micromatch'; // Note: Micromatch is used by Globby
+import path from 'path';
+
+export {default as Globby} from 'globby';
+
+// The default patterns we ignore when globbing
+// using _ prefix for exclusion by convention
+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;
+
+export function createMatcher(patterns: string[]): Matcher {
+  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
+export function createAbsoluteFilePathMatcher(
+  patterns: string[],
+  rootFolders: string[],
+): Matcher {
+  const matcher = createMatcher(patterns);
+
+  function getRelativeFilePath(absoluteFilePath: string) {
+    const rootFolder = rootFolders.find((folderPath) =>
+      absoluteFilePath.startsWith(folderPath),
+    );
+    if (!rootFolder) {
+      throw new Error(
+        `createAbsoluteFilePathMatcher unexpected error, absoluteFilePath=${absoluteFilePath} was not contained in any of the root folders ${JSON.stringify(
+          rootFolders,
+        )}`,
+      );
+    }
+    return path.relative(rootFolder, absoluteFilePath);
+  }
+
+  return (absoluteFilePath: string) =>
+    matcher(getRelativeFilePath(absoluteFilePath));
+}

package/src/hashUtils.ts

@@ -6,7 +6,7 @@
  */
 
 import {createHash} from 'crypto';
-import {kebabCase} from 'lodash';
+import _ from 'lodash';
 import {shortName, isNameTooLong} from './pathUtils';
 
 export function md5Hash(str: string): string {
@@ -29,9 +29,9 @@ export function docuHash(str: string): string {
     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,58 @@
+/**
+ * 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 type {TranslationFileContent, TranslationFile} from '@docusaurus/types';
+import {DEFAULT_PLUGIN_ID} from './constants';
+
+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),
+    })),
+  };
+}
+
+export function getPluginI18nPath({
+  siteDir,
+  locale,
+  pluginName,
+  pluginId = DEFAULT_PLUGIN_ID,
+  subPaths = [],
+}: {
+  siteDir: string;
+  locale: string;
+  pluginName: string;
+  pluginId?: string | undefined;
+  subPaths?: string[];
+}): string {
+  return path.join(
+    siteDir,
+    'i18n',
+    // namespace first by locale: convenient to work in a single folder for a
+    // translator
+    locale,
+    // Make it convenient to use for single-instance
+    // ie: return "docs", not "docs-default" nor "docs/default"
+    `${pluginName}${pluginId === DEFAULT_PLUGIN_ID ? '' : `-${pluginId}`}`,
+    ...subPaths,
+  );
+}