@docusaurus/plugin-content-docs 0.0.0-4848 → 0.0.0-4851

package/src/versions/validation.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 _ from 'lodash';
+import type {VersionsOptions} from '@docusaurus/plugin-content-docs';
+
+export function validateVersionName(name: unknown): asserts name is string {
+  if (typeof name !== 'string') {
+    throw new Error(
+      `Versions should be strings. Found type "${typeof name}" for version "${name}".`,
+    );
+  }
+  if (!name.trim()) {
+    throw new Error(
+      `Invalid version name "${name}": version name must contain at least one non-whitespace character.`,
+    );
+  }
+  const errors: [RegExp, string][] = [
+    [/[/\\]/, 'should not include slash (/) or backslash (\\)'],
+    [/.{33,}/, 'cannot be longer than 32 characters'],
+    // eslint-disable-next-line no-control-regex
+    [/[<>:"|?*\x00-\x1F]/, 'should be a valid file path'],
+    [/^\.\.?$/, 'should not be "." or ".."'],
+  ];
+
+  errors.forEach(([pattern, message]) => {
+    if (pattern.test(name)) {
+      throw new Error(
+        `Invalid version name "${name}": version name ${message}.`,
+      );
+    }
+  });
+}
+
+export function validateVersionNames(
+  names: unknown,
+): asserts names is string[] {
+  if (!Array.isArray(names)) {
+    throw new Error(
+      `The versions file should contain an array of version names! Found content: ${JSON.stringify(
+        names,
+      )}`,
+    );
+  }
+
+  names.forEach(validateVersionName);
+}
+
+/**
+ * @throws Throws for one of the following invalid options:
+ * - `lastVersion` is non-existent
+ * - `versions` includes unknown keys
+ * - `onlyIncludeVersions` is empty, contains unknown names, or doesn't include
+ * `latestVersion` (if provided)
+ */
+export function validateVersionsOptions(
+  availableVersionNames: string[],
+  options: VersionsOptions,
+): void {
+  const availableVersionNamesMsg = `Available version names are: ${availableVersionNames.join(
+    ', ',
+  )}`;
+  if (
+    options.lastVersion &&
+    !availableVersionNames.includes(options.lastVersion)
+  ) {
+    throw new Error(
+      `Docs option lastVersion: ${options.lastVersion} is invalid. ${availableVersionNamesMsg}`,
+    );
+  }
+  const unknownVersionConfigNames = _.difference(
+    Object.keys(options.versions),
+    availableVersionNames,
+  );
+  if (unknownVersionConfigNames.length > 0) {
+    throw new Error(
+      `Invalid docs option "versions": unknown versions (${unknownVersionConfigNames.join(
+        ',',
+      )}) found. ${availableVersionNamesMsg}`,
+    );
+  }
+
+  if (options.onlyIncludeVersions) {
+    if (options.onlyIncludeVersions.length === 0) {
+      throw new Error(
+        `Invalid docs option "onlyIncludeVersions": an empty array is not allowed, at least one version is needed.`,
+      );
+    }
+    const unknownOnlyIncludeVersionNames = _.difference(
+      options.onlyIncludeVersions,
+      availableVersionNames,
+    );
+    if (unknownOnlyIncludeVersionNames.length > 0) {
+      throw new Error(
+        `Invalid docs option "onlyIncludeVersions": unknown versions (${unknownOnlyIncludeVersionNames.join(
+          ',',
+        )}) found. ${availableVersionNamesMsg}`,
+      );
+    }
+    if (
+      options.lastVersion &&
+      !options.onlyIncludeVersions.includes(options.lastVersion)
+    ) {
+      throw new Error(
+        `Invalid docs option "lastVersion": if you use both the "onlyIncludeVersions" and "lastVersion" options, then "lastVersion" must be present in the provided "onlyIncludeVersions" array.`,
+      );
+    }
+  }
+}

package/lib/versions.d.ts

@@ -1,45 +0,0 @@
-/**
- * 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 { PluginOptions, VersionBanner, VersionMetadata } from '@docusaurus/plugin-content-docs';
-import type { LoadContext } from '@docusaurus/types';
-export declare function getVersionedDocsDirPath(siteDir: string, pluginId: string): string;
-export declare function getVersionedSidebarsDirPath(siteDir: string, pluginId: string): string;
-export declare function getVersionsFilePath(siteDir: string, pluginId: string): string;
-export declare function readVersionsFile(siteDir: string, pluginId: string): Promise<string[] | null>;
-export declare function readVersionNames(siteDir: string, options: Pick<PluginOptions, 'id' | 'disableVersioning' | 'includeCurrentVersion'>): Promise<string[]>;
-export declare function getDocsDirPathLocalized({ siteDir, locale, pluginId, versionName, }: {
-    siteDir: string;
-    locale: string;
-    pluginId: string;
-    versionName: string;
-}): string;
-export declare function getDefaultVersionBanner({ versionName, versionNames, lastVersionName, }: {
-    versionName: string;
-    versionNames: string[];
-    lastVersionName: string;
-}): VersionBanner | null;
-export declare function getVersionBanner({ versionName, versionNames, lastVersionName, options, }: {
-    versionName: string;
-    versionNames: string[];
-    lastVersionName: string;
-    options: Pick<PluginOptions, 'versions'>;
-}): VersionBanner | null;
-export declare function getVersionBadge({ versionName, versionNames, options, }: {
-    versionName: string;
-    versionNames: string[];
-    options: Pick<PluginOptions, 'versions'>;
-}): boolean;
-/**
- * Filter versions according to provided options.
- * Note: we preserve the order in which versions are provided;
- * the order of the onlyIncludeVersions array does not matter
- */
-export declare function filterVersions(versionNamesUnfiltered: string[], options: Pick<PluginOptions, 'onlyIncludeVersions'>): string[];
-export declare function readVersionsMetadata({ context, options, }: {
-    context: Pick<LoadContext, 'siteDir' | 'baseUrl' | 'i18n'>;
-    options: Pick<PluginOptions, 'id' | 'path' | 'sidebarPath' | 'routeBasePath' | 'tagsBasePath' | 'includeCurrentVersion' | 'disableVersioning' | 'lastVersion' | 'versions' | 'onlyIncludeVersions' | 'editUrl' | 'editCurrentVersion'>;
-}): Promise<VersionMetadata[]>;

package/lib/versions.js

@@ -1,314 +0,0 @@
-"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.readVersionsMetadata = exports.filterVersions = exports.getVersionBadge = exports.getVersionBanner = exports.getDefaultVersionBanner = exports.getDocsDirPathLocalized = exports.readVersionNames = exports.readVersionsFile = exports.getVersionsFilePath = exports.getVersionedSidebarsDirPath = exports.getVersionedDocsDirPath = 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 constants_1 = require("./constants");
-const utils_1 = require("@docusaurus/utils");
-const lodash_1 = tslib_1.__importDefault(require("lodash"));
-const sidebars_1 = require("./sidebars");
-// retro-compatibility: no prefix for the default plugin id
-function addPluginIdPrefix(fileOrDir, pluginId) {
-    return pluginId === utils_1.DEFAULT_PLUGIN_ID
-        ? fileOrDir
-        : `${pluginId}_${fileOrDir}`;
-}
-function getVersionedDocsDirPath(siteDir, pluginId) {
-    return path_1.default.join(siteDir, addPluginIdPrefix(constants_1.VERSIONED_DOCS_DIR, pluginId));
-}
-exports.getVersionedDocsDirPath = getVersionedDocsDirPath;
-function getVersionedSidebarsDirPath(siteDir, pluginId) {
-    return path_1.default.join(siteDir, addPluginIdPrefix(constants_1.VERSIONED_SIDEBARS_DIR, pluginId));
-}
-exports.getVersionedSidebarsDirPath = getVersionedSidebarsDirPath;
-function getVersionsFilePath(siteDir, pluginId) {
-    return path_1.default.join(siteDir, addPluginIdPrefix(constants_1.VERSIONS_JSON_FILE, pluginId));
-}
-exports.getVersionsFilePath = getVersionsFilePath;
-function ensureValidVersionString(version) {
-    if (typeof version !== 'string') {
-        throw new Error(`Versions should be strings. Found type "${typeof version}" for version "${version}".`);
-    }
-    // Should we forbid versions with special chars like / ?
-    if (version.trim().length === 0) {
-        throw new Error(`Invalid version "${version}".`);
-    }
-}
-function ensureValidVersionArray(versionArray) {
-    if (!Array.isArray(versionArray)) {
-        throw new Error(`The versions file should contain an array of version names! Found content: ${JSON.stringify(versionArray)}`);
-    }
-    versionArray.forEach(ensureValidVersionString);
-}
-async function readVersionsFile(siteDir, pluginId) {
-    const versionsFilePath = getVersionsFilePath(siteDir, pluginId);
-    if (await fs_extra_1.default.pathExists(versionsFilePath)) {
-        const content = JSON.parse(await fs_extra_1.default.readFile(versionsFilePath, 'utf8'));
-        ensureValidVersionArray(content);
-        return content;
-    }
-    return null;
-}
-exports.readVersionsFile = readVersionsFile;
-async function readVersionNames(siteDir, options) {
-    const versionFileContent = await readVersionsFile(siteDir, options.id);
-    if (!versionFileContent && options.disableVersioning) {
-        throw new Error(`Docs: using "disableVersioning: ${options.disableVersioning}" option on a non-versioned site does not make sense.`);
-    }
-    const versions = options.disableVersioning ? [] : versionFileContent ?? [];
-    // We add the current version at the beginning, unless:
-    // - user don't want to; or
-    // - it's already been explicitly added to versions.json
-    if (options.includeCurrentVersion &&
-        !versions.includes(constants_1.CURRENT_VERSION_NAME)) {
-        versions.unshift(constants_1.CURRENT_VERSION_NAME);
-    }
-    if (versions.length === 0) {
-        throw new Error(`It is not possible to use docs without any version. Please check the configuration of these options: "includeCurrentVersion: ${options.includeCurrentVersion}", "disableVersioning: ${options.disableVersioning}".`);
-    }
-    return versions;
-}
-exports.readVersionNames = readVersionNames;
-function getDocsDirPathLocalized({ siteDir, locale, pluginId, versionName, }) {
-    return (0, utils_1.getPluginI18nPath)({
-        siteDir,
-        locale,
-        pluginName: 'docusaurus-plugin-content-docs',
-        pluginId,
-        subPaths: [
-            versionName === constants_1.CURRENT_VERSION_NAME
-                ? constants_1.CURRENT_VERSION_NAME
-                : `version-${versionName}`,
-        ],
-    });
-}
-exports.getDocsDirPathLocalized = getDocsDirPathLocalized;
-function getVersionMetadataPaths({ versionName, context, options, }) {
-    const isCurrentVersion = versionName === constants_1.CURRENT_VERSION_NAME;
-    const contentPathLocalized = getDocsDirPathLocalized({
-        siteDir: context.siteDir,
-        locale: context.i18n.currentLocale,
-        pluginId: options.id,
-        versionName,
-    });
-    if (isCurrentVersion) {
-        return {
-            contentPath: path_1.default.resolve(context.siteDir, options.path),
-            contentPathLocalized,
-            sidebarFilePath: (0, sidebars_1.resolveSidebarPathOption)(context.siteDir, options.sidebarPath),
-        };
-    }
-    return {
-        contentPath: path_1.default.join(getVersionedDocsDirPath(context.siteDir, options.id), `version-${versionName}`),
-        contentPathLocalized,
-        sidebarFilePath: path_1.default.join(getVersionedSidebarsDirPath(context.siteDir, options.id), `version-${versionName}-sidebars.json`),
-    };
-}
-function getVersionEditUrls({ contentPath, contentPathLocalized, context: { siteDir, i18n }, options: { id, path: currentVersionPath, editUrl: editUrlOption, editCurrentVersion, }, }) {
-    // If the user is using the functional form of editUrl,
-    // she has total freedom and we can't compute a "version edit url"
-    if (!editUrlOption || typeof editUrlOption === 'function') {
-        return { editUrl: undefined, editUrlLocalized: undefined };
-    }
-    const editDirPath = editCurrentVersion ? currentVersionPath : contentPath;
-    const editDirPathLocalized = editCurrentVersion
-        ? getDocsDirPathLocalized({
-            siteDir,
-            locale: i18n.currentLocale,
-            versionName: constants_1.CURRENT_VERSION_NAME,
-            pluginId: id,
-        })
-        : contentPathLocalized;
-    const versionPathSegment = (0, utils_1.posixPath)(path_1.default.relative(siteDir, path_1.default.resolve(siteDir, editDirPath)));
-    const versionPathSegmentLocalized = (0, utils_1.posixPath)(path_1.default.relative(siteDir, path_1.default.resolve(siteDir, editDirPathLocalized)));
-    const editUrl = (0, utils_1.normalizeUrl)([editUrlOption, versionPathSegment]);
-    const editUrlLocalized = (0, utils_1.normalizeUrl)([
-        editUrlOption,
-        versionPathSegmentLocalized,
-    ]);
-    return {
-        editUrl,
-        editUrlLocalized,
-    };
-}
-function getDefaultVersionBanner({ versionName, versionNames, lastVersionName, }) {
-    // Current version: good, no banner
-    if (versionName === lastVersionName) {
-        return null;
-    }
-    // Upcoming versions: unreleased banner
-    if (versionNames.indexOf(versionName) < versionNames.indexOf(lastVersionName)) {
-        return 'unreleased';
-    }
-    // Older versions: display unmaintained banner
-    return 'unmaintained';
-}
-exports.getDefaultVersionBanner = getDefaultVersionBanner;
-function getVersionBanner({ versionName, versionNames, lastVersionName, options, }) {
-    const versionBannerOption = options.versions[versionName]?.banner;
-    if (versionBannerOption) {
-        return versionBannerOption === 'none' ? null : versionBannerOption;
-    }
-    return getDefaultVersionBanner({
-        versionName,
-        versionNames,
-        lastVersionName,
-    });
-}
-exports.getVersionBanner = getVersionBanner;
-function getVersionBadge({ versionName, versionNames, options, }) {
-    const versionBadgeOption = options.versions[versionName]?.badge;
-    // If site is not versioned or only one version is included
-    // we don't show the version badge by default
-    // See https://github.com/facebook/docusaurus/issues/3362
-    const versionBadgeDefault = versionNames.length !== 1;
-    return versionBadgeOption ?? versionBadgeDefault;
-}
-exports.getVersionBadge = getVersionBadge;
-function getVersionClassName({ versionName, options, }) {
-    const versionClassNameOption = options.versions[versionName]?.className;
-    const versionClassNameDefault = `docs-version-${versionName}`;
-    return versionClassNameOption ?? versionClassNameDefault;
-}
-function createVersionMetadata({ versionName, versionNames, lastVersionName, context, options, }) {
-    const { sidebarFilePath, contentPath, contentPathLocalized } = getVersionMetadataPaths({ versionName, context, options });
-    const isLast = versionName === lastVersionName;
-    // retro-compatible values
-    const defaultVersionLabel = versionName === constants_1.CURRENT_VERSION_NAME ? 'Next' : versionName;
-    function getDefaultVersionPathPart() {
-        if (isLast) {
-            return '';
-        }
-        return versionName === constants_1.CURRENT_VERSION_NAME ? 'next' : versionName;
-    }
-    const defaultVersionPathPart = getDefaultVersionPathPart();
-    const versionOptions = options.versions[versionName] ?? {};
-    const label = versionOptions.label ?? defaultVersionLabel;
-    const versionPathPart = versionOptions.path ?? defaultVersionPathPart;
-    const routePath = (0, utils_1.normalizeUrl)([
-        context.baseUrl,
-        options.routeBasePath,
-        versionPathPart,
-    ]);
-    const versionEditUrls = getVersionEditUrls({
-        contentPath,
-        contentPathLocalized,
-        context,
-        options,
-    });
-    const routePriority = versionPathPart === '' ? -1 : undefined;
-    // the path that will be used to refer the docs tags
-    // example below will be using /docs/tags
-    const tagsPath = (0, utils_1.normalizeUrl)([routePath, options.tagsBasePath]);
-    return {
-        versionName,
-        label,
-        path: routePath,
-        tagsPath,
-        editUrl: versionEditUrls.editUrl,
-        editUrlLocalized: versionEditUrls.editUrlLocalized,
-        banner: getVersionBanner({
-            versionName,
-            versionNames,
-            lastVersionName,
-            options,
-        }),
-        badge: getVersionBadge({ versionName, versionNames, options }),
-        className: getVersionClassName({ versionName, options }),
-        isLast,
-        routePriority,
-        sidebarFilePath,
-        contentPath,
-        contentPathLocalized,
-    };
-}
-async function checkVersionMetadataPaths({ versionMetadata, context, }) {
-    const { versionName, contentPath, sidebarFilePath } = versionMetadata;
-    const { siteDir } = context;
-    const isCurrentVersion = versionName === constants_1.CURRENT_VERSION_NAME;
-    if (!(await fs_extra_1.default.pathExists(contentPath))) {
-        throw new Error(`The docs folder does not exist for version "${versionName}". A docs folder is expected to be found at ${path_1.default.relative(siteDir, contentPath)}.`);
-    }
-    // If the current version defines a path to a sidebar file that does not
-    // exist, we throw! Note: for versioned sidebars, the file may not exist (as
-    // we prefer to not create it rather than to create an empty file)
-    // See https://github.com/facebook/docusaurus/issues/3366
-    // See https://github.com/facebook/docusaurus/pull/4775
-    if (isCurrentVersion &&
-        typeof sidebarFilePath === 'string' &&
-        !(await fs_extra_1.default.pathExists(sidebarFilePath))) {
-        throw new Error(`The path to the sidebar file does not exist at "${path_1.default.relative(siteDir, sidebarFilePath)}".
-Please set the docs "sidebarPath" field in your config file to:
-- a sidebars path that exists
-- false: to disable the sidebar
-- undefined: for Docusaurus to generate it automatically`);
-    }
-}
-// TODO for retrocompatibility with existing behavior
-// We should make this configurable
-// "last version" is not a very good concept nor api surface
-function getDefaultLastVersionName(versionNames) {
-    if (versionNames.length === 1) {
-        return versionNames[0];
-    }
-    return versionNames.filter((versionName) => versionName !== constants_1.CURRENT_VERSION_NAME)[0];
-}
-function checkVersionsOptions(availableVersionNames, options) {
-    const availableVersionNamesMsg = `Available version names are: ${availableVersionNames.join(', ')}`;
-    if (options.lastVersion &&
-        !availableVersionNames.includes(options.lastVersion)) {
-        throw new Error(`Docs option lastVersion: ${options.lastVersion} is invalid. ${availableVersionNamesMsg}`);
-    }
-    const unknownVersionConfigNames = lodash_1.default.difference(Object.keys(options.versions), availableVersionNames);
-    if (unknownVersionConfigNames.length > 0) {
-        throw new Error(`Invalid docs option "versions": unknown versions (${unknownVersionConfigNames.join(',')}) found. ${availableVersionNamesMsg}`);
-    }
-    if (options.onlyIncludeVersions) {
-        if (options.onlyIncludeVersions.length === 0) {
-            throw new Error(`Invalid docs option "onlyIncludeVersions": an empty array is not allowed, at least one version is needed.`);
-        }
-        const unknownOnlyIncludeVersionNames = lodash_1.default.difference(options.onlyIncludeVersions, availableVersionNames);
-        if (unknownOnlyIncludeVersionNames.length > 0) {
-            throw new Error(`Invalid docs option "onlyIncludeVersions": unknown versions (${unknownOnlyIncludeVersionNames.join(',')}) found. ${availableVersionNamesMsg}`);
-        }
-        if (options.lastVersion &&
-            !options.onlyIncludeVersions.includes(options.lastVersion)) {
-            throw new Error(`Invalid docs option "lastVersion": if you use both the "onlyIncludeVersions" and "lastVersion" options, then "lastVersion" must be present in the provided "onlyIncludeVersions" array.`);
-        }
-    }
-}
-/**
- * Filter versions according to provided options.
- * Note: we preserve the order in which versions are provided;
- * the order of the onlyIncludeVersions array does not matter
- */
-function filterVersions(versionNamesUnfiltered, options) {
-    if (options.onlyIncludeVersions) {
-        return versionNamesUnfiltered.filter((name) => options.onlyIncludeVersions.includes(name));
-    }
-    return versionNamesUnfiltered;
-}
-exports.filterVersions = filterVersions;
-async function readVersionsMetadata({ context, options, }) {
-    const versionNamesUnfiltered = await readVersionNames(context.siteDir, options);
-    checkVersionsOptions(versionNamesUnfiltered, options);
-    const versionNames = filterVersions(versionNamesUnfiltered, options);
-    const lastVersionName = options.lastVersion ?? getDefaultLastVersionName(versionNames);
-    const versionsMetadata = versionNames.map((versionName) => createVersionMetadata({
-        versionName,
-        versionNames,
-        lastVersionName,
-        context,
-        options,
-    }));
-    await Promise.all(versionsMetadata.map((versionMetadata) => checkVersionMetadataPaths({ versionMetadata, context })));
-    return versionsMetadata;
-}
-exports.readVersionsMetadata = readVersionsMetadata;