@mintlify/cli 4.0.1812 → 4.1.1

package/src/validate/rules/content/foreignSyntax.ts

@@ -1,144 +0,0 @@
-import { maskCode, maskFrontmatter, maskNonMarkup, toPosition } from '../../mdx.js';
-import type { FileRule, FileFinding } from '../../types.js';
-
-type Pattern = {
-  regex: RegExp;
-  scope?: 'prose' | 'links' | 'prose-and-esm' | 'everything';
-  message: (match: RegExpMatchArray) => string;
-};
-
-const CALLOUTS: Record<string, string> = {
-  note: '<Note>',
-  info: '<Info>',
-  tip: '<Tip>',
-  hint: '<Tip>',
-  success: '<Check>',
-  important: '<Note>',
-  warning: '<Warning>',
-  caution: '<Warning>',
-  danger: '<Warning>',
-  error: '<Warning>',
-  details: '<Accordion>',
-};
-
-const callout = (name: string | undefined) =>
-  CALLOUTS[name?.toLowerCase() ?? ''] ?? 'a callout (<Note>, <Info>, <Tip> or <Warning>)';
-
-const LIQUID_TAGS: Record<string, string> = {
-  hint: 'a callout (<Note>, <Info>, <Tip> or <Warning>)',
-  tabs: '<Tabs>',
-  tab: '<Tab title="…">',
-  stepper: '<Steps>',
-  step: '<Step title="…">',
-  embed: 'a link or <Frame>',
-  'content-ref': '<Card>',
-  include: 'a snippet import',
-  code: 'a fenced code block',
-  file: 'a link to the file',
-  swagger: 'an OpenAPI page',
-  openapi: 'an OpenAPI page',
-};
-
-const PATTERNS: Pattern[] = [
-  {
-    regex: /\{%-?\s*(?!end)([\w-]+)[^%\n]*?-?%\}/g,
-    message: ([tag, name]) => {
-      const style = name === 'hint' ? /style=["']?(\w+)/.exec(tag)?.[1] : undefined;
-      const target = style
-        ? callout(style)
-        : (LIQUID_TAGS[name ?? ''] ?? 'Markdown or a Mintlify component');
-      return `${tag} is a GitBook or Liquid tag, which Mintlify does not support; use ${target}`;
-    },
-  },
-  {
-    regex: /\{\{[<%]\s*([\w/-]+)[^}\n]*[>%]\}\}/g,
-    message: ([tag]) =>
-      `${tag} is a Hugo shortcode, which Mintlify does not support; use Markdown or a Mintlify component`,
-  },
-  {
-    regex:
-      /\{\{-?\s*(?:(?:site|page|layout|include|jekyll|paginator)\.[^}\n]*|[^\s|{}]+\s*\|\s*\w+[^}\n]*)-?\}\}/g,
-    message: ([tag]) =>
-      `${tag} is a Liquid variable, which Mintlify does not support; write the value, or use a snippet or a variable`,
-  },
-  {
-    regex: /^ {0,3}:{3,}\s*([A-Za-z][\w-]*)/gm,
-    message: ([, name]) =>
-      `:::${name} is a Docusaurus or VitePress admonition, which Mintlify does not support; use ${callout(name)}`,
-  },
-  {
-    regex: /^ {0,3}::(?!:)([A-Za-z][\w-]*)/gm,
-    message: ([, name]) =>
-      `::${name} is an MDC (Nuxt Content, Docus) block, which Mintlify does not support; use the matching Mintlify component`,
-  },
-  {
-    regex: /^ {0,3}(!!!|\?\?\?\+?)[ \t]+([A-Za-z][\w-]*)/gm,
-    message: ([, marker, name]) =>
-      `${marker} ${name} is an MkDocs admonition, which Mintlify does not support; use ${
-        marker === '!!!' ? callout(name) : '<Accordion>'
-      }`,
-  },
-  {
-    regex: /^ {0,3}===\+?[ \t]+["']/gm,
-    message: () =>
-      `=== "…" is an MkDocs content tab, which Mintlify does not support; use <Tabs> with <Tab title="…">`,
-  },
-  {
-    regex: /^[ \t]*;?[ \t]*--8<--/gm,
-    scope: 'everything',
-    message: () =>
-      '--8<-- is an MkDocs snippet include, which Mintlify does not support; use a snippet import or paste the content',
-  },
-  {
-    regex: /\{:\s*[.#\w][^}\n]*\}/g,
-    message: ([list]) =>
-      `${list} is a Kramdown attribute list, which Mintlify does not support; remove it, use a component, or use {#id} for a heading anchor`,
-  },
-  {
-    regex: /(?<![[{\w])\[\[([^[\]\n]+)\]\](?![(:[])/g,
-    message: ([link]) =>
-      `${link} is a wiki link, which Mintlify does not support; use a Markdown link such as [text](/path)`,
-  },
-  {
-    regex: /(?:\]\(|href=["'])((?:doc|ref|blog|changelog|page):[^)\s"']+)/g,
-    scope: 'links',
-    message: ([, link]) =>
-      `${link} is a ReadMe link, which Mintlify does not support; link to the page path instead, such as /${
-        link?.split(':')[1] ?? ''
-      }`,
-  },
-  {
-    regex: /["'(]@site\/[^"')\s]*/g,
-    scope: 'prose-and-esm',
-    message: ([path]) =>
-      `${path.slice(1)} uses the Docusaurus @site alias, which Mintlify does not resolve; use a root-relative path such as /images/… or /snippets/…`,
-  },
-];
-
-export const foreignSyntax: FileRule = {
-  id: 'foreign-syntax',
-  group: 'content',
-  severity: 'warning',
-  scope: 'file',
-  description: "syntax from another docs framework that Mintlify doesn't render",
-  raw: true,
-  check: ({ content }) => {
-    const prose = maskCode(content);
-    const literal = maskNonMarkup(content);
-    const views = {
-      prose,
-      links: prose,
-      'prose-and-esm': maskCode(content, { keepEsm: true }),
-      everything: maskFrontmatter(content),
-    };
-    const issues: FileFinding[] = [];
-    for (const { regex, scope = 'prose', message } of PATTERNS) {
-      for (const match of views[scope].matchAll(regex)) {
-        const start = match.index + (match[0].length - match[0].trimStart().length);
-        if (scope === 'prose' && literal[start] !== prose[start]) continue;
-        issues.push({ ...toPosition(content, start), message: message(match) });
-      }
-    }
-    return issues;
-  },
-};

package/src/validate/rules/content/katex.ts

@@ -1,33 +0,0 @@
-import { isCurrencyMath } from '@mintlify/common';
-import katex from 'katex';
-import { visit } from 'unist-util-visit';
-
-import type { FileRule, FileFinding } from '../../types.js';
-
-export const katexRule: FileRule = {
-  id: 'katex',
-  group: 'content',
-  severity: 'warning',
-  scope: 'file',
-  description: "math that KaTeX can't render",
-  check: ({ tree, content }) => {
-    const issues: FileFinding[] = [];
-    visit(tree, (node) => {
-      if (node.type !== 'math' && node.type !== 'inlineMath') return;
-      if (node.type === 'inlineMath' && isCurrencyMath(node, content)) return;
-      try {
-        katex.renderToString(node.value, {
-          throwOnError: true,
-          displayMode: node.type === 'math',
-        });
-      } catch (error) {
-        issues.push({
-          line: node.position?.start.line,
-          column: node.position?.start.column,
-          message: error instanceof Error ? error.message : 'invalid math',
-        });
-      }
-    });
-    return issues;
-  },
-};

package/src/validate/rules/content/missingSnippet.ts

@@ -1,36 +0,0 @@
-import { replaceVariables } from '@mintlify/common';
-import { visit } from 'unist-util-visit';
-
-import type { FileFinding, FileRule } from '../../types.js';
-
-const exists = (file: string, readFile: (file: string) => string | undefined) =>
-  !file.startsWith('/') &&
-  (readFile(`_snippets/${file}`) !== undefined ||
-    (file.startsWith('snippets/') && readFile(file) !== undefined));
-
-export const missingSnippet: FileRule = {
-  id: 'missing-snippet',
-  group: 'content',
-  severity: 'error',
-  scope: 'file',
-  description: '<Snippet file> tags whose file the build cannot find',
-  check: ({ tree, readFile, variables }) => {
-    if (!readFile) return [];
-    const issues: FileFinding[] = [];
-    visit(tree, 'mdxJsxFlowElement', (node) => {
-      if (node.name !== 'Snippet') return;
-      const value = node.attributes.find(
-        (attribute) => attribute.type === 'mdxJsxAttribute' && attribute.name === 'file'
-      )?.value;
-      if (typeof value !== 'string') return;
-      const file = replaceVariables(value, variables);
-      if (exists(file, readFile)) return;
-      issues.push({
-        line: node.position?.start.line,
-        column: node.position?.start.column,
-        message: `<Snippet file="${value}"> renders nothing: no snippet matches "${file}"`,
-      });
-    });
-    return issues;
-  },
-};

package/src/validate/rules/content/undefinedVariable.ts

@@ -1,20 +0,0 @@
-import { maskCode, toPosition } from '../../mdx.js';
-import type { FileRule } from '../../types.js';
-
-const VARIABLE = /(?<!=\s*)\{\{\s*([\w.\-]+)\s*\}\}/g;
-
-export const undefinedVariable: FileRule = {
-  id: 'undefined-variable',
-  group: 'content',
-  severity: 'error',
-  scope: 'file',
-  description: '{{variables}} that docs.json does not define',
-  raw: true,
-  check: ({ content, variables = {} }) =>
-    [...maskCode(content).matchAll(VARIABLE)]
-      .filter(([, name]) => name !== undefined && variables[name] === undefined)
-      .map((match) => ({
-        ...toPosition(content, match.index),
-        message: `{{${match[1]}}} is not defined in the variables of docs.json`,
-      })),
-};

package/src/validate/rules/content/unknownComponent.ts

@@ -1,130 +0,0 @@
-import {
-  collectPatternNames,
-  collectExportedNames,
-  getAST,
-  isBuiltInComponent,
-  JSX_EXTENSIONS,
-  visitReferences,
-} from '@mintlify/common';
-import { visit } from 'unist-util-visit';
-
-import type { FileContext, FileRule, FileFinding } from '../../types.js';
-
-const getDeclared = (context: FileContext): Set<string> => {
-  const declared = new Set<string>();
-  visit(context.tree, 'mdxjsEsm', (node) => {
-    for (const statement of node.data?.estree?.body ?? []) {
-      if (statement.type === 'ImportDeclaration') {
-        for (const specifier of statement.specifiers) {
-          collectPatternNames(specifier.local, declared);
-        }
-      } else if (statement.type === 'ExportNamedDeclaration') {
-        const declaration = statement.declaration;
-        if (declaration?.type === 'VariableDeclaration') {
-          for (const declarator of declaration.declarations) {
-            collectPatternNames(declarator.id, declared);
-          }
-        } else if (declaration) {
-          collectPatternNames(declaration.id, declared);
-        }
-        for (const specifier of statement.specifiers) {
-          collectPatternNames(specifier.local, declared);
-          collectPatternNames(specifier.exported, declared);
-        }
-      } else if (statement.type === 'ExportDefaultDeclaration') {
-        const declaration = statement.declaration;
-        if (declaration.type === 'FunctionDeclaration' || declaration.type === 'ClassDeclaration') {
-          collectPatternNames(declaration.id, declared);
-        }
-      }
-    }
-  });
-  return declared;
-};
-
-const getImportPosition = (context: FileContext): number => {
-  const frontmatter = context.tree.children.find((child) => ['yaml', 'toml'].includes(child.type));
-  return frontmatter?.position?.end.offset ?? 0;
-};
-
-const getSpecifier = (snippet: string, file: string, name: string): string | undefined => {
-  let exported: Set<string>;
-  try {
-    exported = collectExportedNames(getAST(snippet, file));
-  } catch {
-    return undefined;
-  }
-  if (exported.has(name)) return `{ ${name} }`;
-  return exported.has('default') ? name : undefined;
-};
-
-export const unknownComponent: FileRule = {
-  id: 'unknown-component',
-  group: 'content',
-  severity: 'error',
-  scope: 'file',
-  description: 'JSX components that are not built in, imported or exported',
-  pagesOnly: true,
-  check: (context) => {
-    const declared = getDeclared(context);
-    const reported = new Set<string>();
-    const issues: FileFinding[] = [];
-    const insertAt = getImportPosition(context);
-    const prefix = insertAt === 0 ? '' : '\n\n';
-    const following = /^\n*/.exec(context.content.slice(insertAt))?.[0].length ?? 0;
-    const suffix = '\n'.repeat(Math.max(0, 2 - following));
-
-    const check = (
-      tag: string | null | undefined,
-      position: { line?: number; column?: number } | undefined
-    ) => {
-      const name = tag?.split('.')[0];
-      if (!tag || !name || !/^[A-Z]/.test(name)) return;
-      if (declared.has(name) || reported.has(tag) || isBuiltInComponent(tag)) return;
-      reported.add(tag);
-
-      const file = JSX_EXTENSIONS.map((extension) => `snippets/${name}${extension}`).find(
-        (candidate) => context.readFile?.(candidate) !== undefined
-      );
-      const source = file && context.readFile?.(file);
-      const specifier =
-        file && source !== undefined && tag === name ? getSpecifier(source, file, name) : undefined;
-      issues.push({
-        line: position?.line,
-        column: position?.column,
-        message: `<${tag}> is not built in, imported or exported on this page`,
-        edit: specifier
-          ? {
-              start: insertAt,
-              end: insertAt,
-              text: `${prefix}import ${specifier} from "/${file}";${suffix}`,
-            }
-          : undefined,
-      });
-    };
-
-    const checkJsxInExpression = (estree: unknown, fallback?: { line?: number; column?: number }) =>
-      visitReferences(estree, new Set(), {
-        reference: (identifier) => {
-          if (identifier.type !== 'JSXIdentifier') return;
-          const loc = identifier.loc as { start?: { line: number; column: number } } | undefined;
-          check(String(identifier.name), loc?.start ?? fallback);
-        },
-      });
-
-    visit(context.tree, (node) => {
-      if (node.type === 'mdxJsxFlowElement' || node.type === 'mdxJsxTextElement') {
-        check(node.name, node.position?.start);
-        for (const attribute of node.attributes) {
-          const value = attribute.type === 'mdxJsxAttribute' ? attribute.value : attribute;
-          if (value && typeof value === 'object') {
-            checkJsxInExpression(value.data?.estree, node.position?.start);
-          }
-        }
-      } else if (node.type === 'mdxFlowExpression' || node.type === 'mdxTextExpression') {
-        checkJsxInExpression(node.data?.estree, node.position?.start);
-      }
-    });
-    return issues;
-  },
-};

package/src/validate/rules/content/voidTags.ts

@@ -1,43 +0,0 @@
-import { htmlVoidElements } from 'html-void-elements';
-
-import { maskNonMarkup } from '../../mdx.js';
-import type { FileRule, FileFinding } from '../../types.js';
-
-const VOID_TAG_NAMES = htmlVoidElements.filter((tag) => tag !== 'image');
-const ATTRIBUTE = String.raw`"[^"]*"|'[^']*'|\{[^{}]*\}|[^<>"'{}]`;
-const VOID_TAG = new RegExp(
-  String.raw`<(${VOID_TAG_NAMES.join('|')})(?=[\s/>])(?:${ATTRIBUTE})*?(\/?)>`,
-  'g'
-);
-
-export const voidTags: FileRule = {
-  id: 'void-tags',
-  group: 'content',
-  severity: 'error',
-  scope: 'file',
-  description:
-    "self-close void HTML tags (<br>, <img>, <source>, …); MDX can't parse them unclosed",
-  raw: true,
-  check: ({ content }) => {
-    const masked = maskNonMarkup(content);
-    const issues: FileFinding[] = [];
-    for (const match of masked.matchAll(VOID_TAG)) {
-      if (match[2]) continue;
-      const start = match.index;
-      const end = start + match[0].length;
-      if (new RegExp(`^\\s*</${match[1]}\\s*>`).test(masked.slice(end))) continue;
-      const before = content.slice(0, start).split('\n');
-      issues.push({
-        line: before.length,
-        column: (before.pop()?.length ?? 0) + 1,
-        message: `<${match[1]}> must be self-closed`,
-        edit: {
-          start,
-          end,
-          text: `${content.slice(start, end - 1).trimEnd()} />`,
-        },
-      });
-    }
-    return issues;
-  },
-};

package/src/validate/rules/index.ts

@@ -1,23 +0,0 @@
-import type { Rule } from '../types.js';
-import { BUILD_RULES } from './build.js';
-import { duplicateH1 } from './content/duplicateH1.js';
-import { foreignSyntax } from './content/foreignSyntax.js';
-import { katexRule } from './content/katex.js';
-import { missingSnippet } from './content/missingSnippet.js';
-import { undefinedVariable } from './content/undefinedVariable.js';
-import { unknownComponent } from './content/unknownComponent.js';
-import { voidTags } from './content/voidTags.js';
-import { openApiSpec } from './openapi.js';
-
-/** Every check mint validate runs, in report order. */
-export const RULES: Rule[] = [
-  voidTags,
-  duplicateH1,
-  unknownComponent,
-  undefinedVariable,
-  missingSnippet,
-  katexRule,
-  foreignSyntax,
-  openApiSpec,
-  ...BUILD_RULES,
-];

package/src/validate/rules/openapi.ts

@@ -1,59 +0,0 @@
-import fs from 'node:fs/promises';
-import path from 'node:path';
-
-import { errorMessage } from '../../helpers.js';
-import {
-  buildOverlayRegistryForCheck,
-  checkOpenApiFile,
-  getOpenApiFilenamesFromDocsConfig,
-  type OpenApiCheckMessage,
-} from '../../openApiCheck.js';
-import type { Finding, SiteRule } from '../types.js';
-
-export const openApiSpec: SiteRule = {
-  id: 'openapi-spec',
-  group: 'openapi',
-  severity: 'error',
-  scope: 'site',
-  description:
-    "OpenAPI specs in docs.json or mint.json that don't parse or validate, with overlays applied",
-  check: async (site) => {
-    let filenames: string[] = [];
-    try {
-      const config = JSON.parse(
-        await fs.readFile(path.join(site.baseDir, site.configFile), 'utf-8')
-      );
-      // mint.json lists its specs under a top-level openapi key
-      filenames = getOpenApiFilenamesFromDocsConfig(
-        site.configFile === 'mint.json' ? { api: { openapi: config.openapi } } : config
-      );
-    } catch {
-      // A missing or invalid config file is the build's to report
-    }
-    if (filenames.length === 0) return [];
-
-    let overlayRegistry;
-    try {
-      overlayRegistry = await buildOverlayRegistryForCheck(site.localSchema);
-    } catch (error) {
-      return [{ file: site.configFile, message: `OpenAPI overlays: ${errorMessage(error)}` }];
-    }
-
-    const perFile = await Promise.all(
-      filenames.map(async (file) => {
-        const messages: OpenApiCheckMessage[] = [];
-        await checkOpenApiFile(file, site.localSchema, overlayRegistry, (message) =>
-          messages.push(message)
-        );
-        return messages.flatMap(({ level, message }): Finding[] =>
-          level === 'error'
-            ? [{ file, message }]
-            : level === 'warning'
-              ? [{ file, message, severity: 'warning' }]
-              : []
-        );
-      })
-    );
-    return perFile.flat();
-  },
-};

package/src/validate/rules/parseError.ts

@@ -1,9 +0,0 @@
-import type { DiagnosticSource } from '../types.js';
-
-/** The engine's built-in diagnostic for files neither parser can parse; not a selectable rule. */
-export const PARSE_ERROR: DiagnosticSource = {
-  id: 'parse-error',
-  group: 'content',
-  severity: 'error',
-  description: "files MDX can't parse; other checks skip them",
-};

package/src/validate/site.ts

@@ -1,53 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-
-import { readSiteFiles } from './files.js';
-import { toPosition } from './mdx.js';
-import type { Site } from './types.js';
-
-const readVariables = (config: string): Record<string, string> | undefined => {
-  try {
-    const { variables } = JSON.parse(config) as { variables?: unknown };
-    return variables && typeof variables === 'object'
-      ? (variables as Record<string, string>)
-      : undefined;
-  } catch {
-    return undefined;
-  }
-};
-
-/** Lists the site's pages and snippets; locate reads files from disk on demand. */
-export const loadSite = async (
-  baseDir: string,
-  { selected, localSchema }: { selected?: ReadonlySet<string>; localSchema: boolean }
-): Promise<Site> => {
-  const files = await readSiteFiles(baseDir);
-  const byPath = new Map<string, string | undefined>();
-  const configFile = fs.existsSync(path.join(baseDir, 'docs.json')) ? 'docs.json' : 'mint.json';
-
-  const read = (file: string) => {
-    if (!byPath.has(file)) {
-      try {
-        byPath.set(file, fs.readFileSync(path.join(baseDir, file), 'utf-8'));
-      } catch {
-        byPath.set(file, undefined);
-      }
-    }
-    return byPath.get(file);
-  };
-
-  return {
-    baseDir,
-    files,
-    selected,
-    configFile,
-    variables: readVariables(read(configFile) ?? ''),
-    localSchema,
-    read,
-    locate: (file, text) => {
-      const content = read(file) ?? '';
-      const offset = text ? content.indexOf(text) : -1;
-      return offset === -1 ? {} : toPosition(content, offset);
-    },
-  };
-};

package/src/validate/types.ts

@@ -1,102 +0,0 @@
-import type { BuildValidationResult } from '@mintlify/previewing';
-import type { Root } from 'mdast';
-
-export type Group = 'content' | 'nav' | 'config' | 'openapi';
-
-export const GROUPS: Group[] = ['content', 'nav', 'config', 'openapi'];
-
-export type Severity = 'error' | 'warning';
-
-export type Edit = { start: number; end: number; text: string };
-
-export type FileEdit = Edit & { file: string };
-
-/** A fix --fix applied: where it was and the text it replaced. */
-export type Change = {
-  rule: string;
-  file: string;
-  line?: number;
-  column?: number;
-  before: string;
-  after: string;
-};
-
-export type Diagnostic = {
-  rule: string;
-  group: Group;
-  severity: Severity;
-  file: string;
-  line?: number;
-  column?: number;
-  message: string;
-  fix?: FileEdit;
-};
-
-/** What a rule reports; the engine adds its id and group, and its severity unless overridden. */
-export type Finding = Omit<Diagnostic, 'rule' | 'group' | 'severity'> & { severity?: Severity };
-
-type RuleMeta = {
-  id: string;
-  group: Group;
-  severity: Severity;
-  needsBuild?: boolean;
-  description: string;
-};
-
-export type DiagnosticSource = Pick<RuleMeta, 'id' | 'group' | 'severity' | 'description'>;
-
-export type FileKind = 'page' | 'snippet';
-
-export type FileContext = {
-  file: string;
-  content: string;
-  baseDir: string;
-  frontmatter: Record<string, unknown>;
-  tree: Root;
-  readFile?: (file: string) => string | undefined;
-  anchorLinks?: ReadonlySet<string>;
-  variables?: Record<string, string>;
-};
-
-/** A finding in one file, with an optional edit against the content the rule saw. */
-export type FileFinding = {
-  line?: number;
-  column?: number;
-  message: string;
-  edit?: Edit;
-};
-
-/** Checks one page or snippet at a time. Raw rules read text; the rest also get the MDX tree. */
-export type FileRule = RuleMeta & {
-  scope: 'file';
-  raw?: boolean;
-  pagesOnly?: boolean;
-  needsAnchorLinks?: boolean;
-  check: (context: FileContext) => FileFinding[];
-};
-
-export type SiteFile = { file: string; kind: FileKind };
-
-export type BuildResult = BuildValidationResult;
-
-export type Site = {
-  baseDir: string;
-  files: SiteFile[];
-  /** Set with --files: rules report on these files only. */
-  selected?: ReadonlySet<string>;
-  configFile: string;
-  variables?: Record<string, string>;
-  build?: BuildResult;
-  /** The line and column of the first occurrence of text in a file. */
-  locate: (file: string, text: string) => { line?: number; column?: number };
-  read: (file: string) => string | undefined;
-  localSchema: boolean;
-};
-
-/** Checks the site as a whole. */
-export type SiteRule = RuleMeta & {
-  scope: 'site';
-  check: (site: Site) => Finding[] | Promise<Finding[]>;
-};
-
-export type Rule = FileRule | SiteRule;

package/src/vendor/converter.ts

@@ -1 +0,0 @@
-export * from '@mintlify/editor/converter';