@docusaurus/utils-validation 2.0.0-beta.ff31de0ff → 2.0.0-rc.1

package/src/validationSchemas.ts

@@ -4,51 +4,118 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+
+import {isValidPathname, DEFAULT_PLUGIN_ID, type Tag} from '@docusaurus/utils';
 import Joi from './Joi';
-import {isValidPathname} from '@docusaurus/utils';
+import {JoiFrontMatter} from './JoiFrontMatter';
 
 export const PluginIdSchema = Joi.string()
-  .regex(/^[a-zA-Z_-]+$/)
-  // duplicate core constant, otherwise cyclic dependency is created :(
-  .default('default');
+  .regex(/^[\w-]+$/)
+  .message(
+    'Illegal plugin ID value "{#value}": it should only contain alphanumerics, underscores, and dashes.',
+  )
+  .default(DEFAULT_PLUGIN_ID);
 
 const MarkdownPluginsSchema = Joi.array()
   .items(
-    Joi.array().ordered(Joi.function().required(), Joi.object().required()),
+    Joi.array().ordered(Joi.function().required(), Joi.any().required()),
     Joi.function(),
     Joi.object(),
   )
+  .messages({
+    'array.includes': `{#label} does not look like a valid MDX plugin config. A plugin config entry should be one of:
+- A tuple, like \`[require("rehype-katex"), \\{ strict: false \\}]\`, or
+- A simple module, like \`require("remark-math")\``,
+  })
   .default([]);
 
 export const RemarkPluginsSchema = MarkdownPluginsSchema;
 export const RehypePluginsSchema = MarkdownPluginsSchema;
 
-export const AdmonitionsSchema = Joi.object().default({});
+const LegacyAdmonitionConfigSchema = Joi.forbidden().messages({
+  'any.unknown': `The Docusaurus admonitions system has changed, and the option {#label} does not exist anymore.
+You now need to swizzle the admonitions component to provide UI customizations such as icons.
+Please refer to https://github.com/facebook/docusaurus/pull/7152 for detailed upgrade instructions.`,
+});
 
+export const AdmonitionsSchema = JoiFrontMatter.alternatives()
+  .try(
+    JoiFrontMatter.boolean().required(),
+    JoiFrontMatter.object({
+      tag: JoiFrontMatter.string(),
+      keywords: JoiFrontMatter.array().items(
+        JoiFrontMatter.string().required(),
+      ),
+      // TODO Remove before 2023
+      customTypes: LegacyAdmonitionConfigSchema,
+      icons: LegacyAdmonitionConfigSchema,
+      infima: LegacyAdmonitionConfigSchema,
+    }).required(),
+  )
+  .default(true)
+  .messages({
+    'alternatives.types':
+      '{{#label}} does not look like a valid admonitions config',
+  });
+
+// TODO how can we make this emit a custom error message :'(
+//  Joi is such a pain, good luck to annoying trying to improve this
 export const URISchema = Joi.alternatives(
   Joi.string().uri({allowRelative: true}),
-  Joi.custom((val, helpers) => {
+  // This custom validation logic is required notably because Joi does not
+  // accept paths like /a/b/c ...
+  Joi.custom((val: unknown, helpers) => {
     try {
-      const url = new URL(val);
-      if (url) {
-        return val;
-      } else {
-        return helpers.error('any.invalid');
-      }
+      // eslint-disable-next-line no-new
+      new URL(String(val));
+      return val;
     } catch {
       return helpers.error('any.invalid');
     }
   }),
-);
+).messages({
+  'alternatives.match':
+    "{{#label}} does not look like a valid url (value='{{.value}}')",
+});
 
 export const PathnameSchema = Joi.string()
-  .custom((val) => {
+  .custom((val: string) => {
     if (!isValidPathname(val)) {
       throw new Error();
-    } else {
-      return val;
     }
+    return val;
   })
   .message(
-    '{{#label}} is not a valid pathname. Pathname should start with / and not contain any domain or query string',
+    '{{#label}} is not a valid pathname. Pathname should start with slash and not contain any domain or query string.',
   );
+
+const FrontMatterTagSchema = JoiFrontMatter.alternatives()
+  .try(
+    JoiFrontMatter.string().required(),
+    JoiFrontMatter.object<Tag>({
+      label: JoiFrontMatter.string().required(),
+      permalink: JoiFrontMatter.string().required(),
+    }).required(),
+  )
+  .messages({
+    'alternatives.match': '{{#label}} does not look like a valid tag',
+    'alternatives.types': '{{#label}} does not look like a valid tag',
+  });
+
+export const FrontMatterTagsSchema = JoiFrontMatter.array()
+  .items(FrontMatterTagSchema)
+  .messages({
+    'array.base':
+      '{{#label}} does not look like a valid front matter Yaml array.',
+  });
+
+export const FrontMatterTOCHeadingLevels = {
+  toc_min_heading_level: JoiFrontMatter.number().when('toc_max_heading_level', {
+    is: JoiFrontMatter.exist(),
+    then: JoiFrontMatter.number()
+      .min(2)
+      .max(JoiFrontMatter.ref('toc_max_heading_level')),
+    otherwise: JoiFrontMatter.number().min(2).max(6),
+  }),
+  toc_max_heading_level: JoiFrontMatter.number().min(2).max(6),
+};

package/src/validationUtils.ts

@@ -4,106 +4,80 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import Joi from './Joi';
-import chalk from 'chalk';
-import {PluginIdSchema} from './validationSchemas';
 
-// TODO temporary escape hatch for alpha-60: to be removed soon
-// Our validation schemas might be buggy at first
-// will permit users to bypass validation until we fix all validation errors
-// see for example: https://github.com/facebook/docusaurus/pull/3120
-// Undocumented on purpose, as we don't want users to keep using it over time
-// Maybe we'll make this escape hatch official some day, with a better api?
-export const isValidationDisabledEscapeHatch =
-  process.env.DISABLE_DOCUSAURUS_VALIDATION === 'true';
+import logger from '@docusaurus/logger';
+import Yaml from 'js-yaml';
+import {PluginIdSchema} from './validationSchemas';
+import type Joi from './Joi';
 
-if (isValidationDisabledEscapeHatch) {
-  console.error(
-    chalk.red(
-      'You should avoid using DISABLE_DOCUSAURUS_VALIDATION escape hatch, this will be removed',
-    ),
-  );
+/** Print warnings returned from Joi validation. */
+export function printWarning(warning?: Joi.ValidationError): void {
+  if (warning) {
+    const warningMessages = warning.details
+      .map(({message}) => message)
+      .join('\n');
+    logger.warn(warningMessages);
+  }
 }
 
-export const logValidationBugReportHint = (): void => {
-  console.log(
-    `\n${chalk.red('A validation error occured.')}${chalk.cyanBright(
-      '\nThe validation system was added recently to Docusaurus as an attempt to avoid user configuration errors.' +
-        '\nWe may have made some mistakes.' +
-        '\nIf you think your configuration is valid and should keep working, please open a bug report.',
-    )}\n`,
-  );
-};
-
+/**
+ * The callback that should be used to validate plugin options. Handles plugin
+ * IDs on a generic level: no matter what the schema declares, this callback
+ * would require a string ID or default to "default".
+ */
 export function normalizePluginOptions<T extends {id?: string}>(
   schema: Joi.ObjectSchema<T>,
-  options: Partial<T>,
+  // This allows us to automatically normalize undefined to { id: "default" }
+  options: Partial<T> = {},
 ): T {
   // All plugins can be provided an "id" option (multi-instance support)
   // we add schema validation automatically
   const finalSchema = schema.append({
     id: PluginIdSchema,
   });
-  const {error, value} = finalSchema.validate(options, {
+  const {error, warning, value} = finalSchema.validate(options, {
     convert: false,
   });
+
+  printWarning(warning);
+
   if (error) {
-    logValidationBugReportHint();
-    if (isValidationDisabledEscapeHatch) {
-      console.error(error);
-      return options as T;
-    } else {
-      throw error;
-    }
+    throw error;
   }
+
   return value;
 }
 
+/**
+ * The callback that should be used to validate theme config. No matter what the
+ * schema declares, this callback would allow unknown attributes.
+ */
 export function normalizeThemeConfig<T>(
   schema: Joi.ObjectSchema<T>,
   themeConfig: Partial<T>,
 ): T {
-  // A theme should only validate his "slice" of the full themeConfig,
+  // A theme should only validate its "slice" of the full themeConfig,
   // not the whole object, so we allow unknown attributes
   // otherwise one theme would fail validating the data of another theme
   const finalSchema = schema.unknown();
 
-  const {error, value} = finalSchema.validate(themeConfig, {
+  const {error, warning, value} = finalSchema.validate(themeConfig, {
     convert: false,
   });
 
+  printWarning(warning);
+
   if (error) {
-    logValidationBugReportHint();
-    if (isValidationDisabledEscapeHatch) {
-      console.error(error);
-      return themeConfig as T;
-    } else {
-      throw error;
-    }
+    throw error;
   }
   return value;
 }
 
-// Enhance the default Joi.string() type so that it can convert number to strings
-// If user use frontmatter "tag: 2021", we shouldn't need to ask the user to write "tag: '2021'"
-// Also yaml tries to convert patterns like "2019-01-01" to dates automatically
-// see https://github.com/facebook/docusaurus/issues/4642
-// see https://github.com/sideway/joi/issues/1442#issuecomment-823997884
-const JoiFrontMatterString: Joi.Extension = {
-  type: 'string',
-  base: Joi.string(),
-  // Fix Yaml that tries to auto-convert many things to string out of the box
-  prepare: (value) => {
-    if (typeof value === 'number' || value instanceof Date) {
-      return {value: value.toString()};
-    }
-    return {value};
-  },
-};
-export const JoiFrontMatter: typeof Joi = Joi.extend(JoiFrontMatterString);
-
+/**
+ * Validate front matter with better error message
+ */
 export function validateFrontMatter<T>(
-  frontMatter: Record<string, unknown>,
+  frontMatter: {[key: string]: unknown},
   schema: Joi.ObjectSchema<T>,
 ): T {
   const {value, error, warning} = schema.validate(frontMatter, {
@@ -112,32 +86,20 @@ export function validateFrontMatter<T>(
     abortEarly: false,
   });
 
+  printWarning(warning);
+
   if (error) {
-    const frontMatterString = JSON.stringify(frontMatter, null, 2);
     const errorDetails = error.details;
     const invalidFields = errorDetails.map(({path}) => path).join(', ');
-    const errorMessages = errorDetails
-      .map(({message}) => ` - ${message}`)
-      .join('\n');
 
-    logValidationBugReportHint();
-
-    console.error(
-      chalk.red(
-        `The following FrontMatter:\n${chalk.yellow(
-          frontMatterString,
-        )}\ncontains invalid values for field(s): ${invalidFields}.\n${errorMessages}\n`,
-      ),
-    );
+    logger.error`The following front matter:
+---
+${Yaml.dump(frontMatter)}---
+contains invalid values for field(s): code=${invalidFields}.
+${errorDetails.map(({message}) => message)}
+`;
     throw error;
   }
 
-  if (warning) {
-    const warningMessages = warning.details
-      .map(({message}) => message)
-      .join('\n');
-    console.log(chalk.yellow(warningMessages));
-  }
-
   return value;
 }