@mintlify/cli 4.0.1812 → 4.1.1

package/src/validate/command.tsx

@@ -1,135 +0,0 @@
-import { addLog, checkBuild, clearLogs, ErrorLog, SpinnerLog } from '@mintlify/previewing';
-import path from 'node:path';
-import { format } from 'node:util';
-
-import { CMD_EXEC_PATH, errorMessage, getVersions, terminate } from '../helpers.js';
-import { resolveExplicitFiles } from '../resolveFiles.js';
-import { sendPublishPrompt } from '../signup.js';
-import { checkSite, runBuildChecks, selectRules } from './engine.js';
-import { logReport } from './output.js';
-import { toReport, type BuildStatus } from './report.js';
-
-export type ValidateArgs = {
-  'local-schema': boolean;
-  'client-version'?: string;
-  groups?: (string | number)[];
-  files?: (string | number)[];
-  build: boolean;
-  enable?: string[];
-  disable?: string[];
-  fix: boolean;
-  format: 'text' | 'json';
-};
-
-export const EXIT = { passed: 0, failed: 1, crashed: 2 } as const;
-
-export const splitList = (values: string[]) =>
-  values.flatMap((value) =>
-    value
-      .split(',')
-      .map((item) => item.trim())
-      .filter(Boolean)
-  );
-
-const write = (text: string) =>
-  new Promise<void>((resolve) => {
-    process.stdout.write(text, () => resolve());
-  });
-
-/**
- * Writes console output straight to stderr, so --format json leaves stdout to the report. Ink
- * patches console and redraws on stdout, so redirecting to console.error isn't enough.
- */
-const consoleToStderr = () => {
-  const original = {
-    log: console.log,
-    info: console.info,
-    warn: console.warn,
-    error: console.error,
-  };
-  const toStderr = (...args: unknown[]) => {
-    process.stderr.write(`${format(...args)}\n`);
-  };
-  console.log = console.info = console.warn = console.error = toStderr;
-  return () => Object.assign(console, original);
-};
-
-const resolveSelection = async (baseDir: string, values: (string | number)[] | undefined) => {
-  const args = (values ?? []).map(String).filter(Boolean);
-  if (args.length === 0) return undefined;
-  const files = await resolveExplicitFiles(CMD_EXEC_PATH, args);
-  return new Set(
-    files.map((file) =>
-      path.relative(baseDir, path.resolve(CMD_EXEC_PATH, file)).split(path.sep).join('/')
-    )
-  );
-};
-
-/** mint validate: one pass over every selected rule, then the strict build when nothing failed. */
-export const validateHandler = async (
-  argv: ValidateArgs,
-  packageName: string,
-  baseDir = CMD_EXEC_PATH
-) => {
-  const json = argv.format === 'json';
-  const restoreConsole = json ? consoleToStderr() : undefined;
-  try {
-    const rules = selectRules({
-      enable: argv.enable,
-      disable: argv.disable ?? [],
-    });
-    const selected = await resolveSelection(baseDir, argv.files);
-    if (!json) addLog(<SpinnerLog message="validating..." />);
-
-    const { site, fixed, ...checked } = await checkSite(baseDir, rules, {
-      selected,
-      localSchema: argv['local-schema'],
-      fix: argv.fix,
-    });
-    let { diagnostics } = checked;
-
-    const buildRules = rules.some(({ needsBuild }) => needsBuild);
-    let build: BuildStatus;
-    if (!argv.build) {
-      build = { ran: false, reason: 'disabled' };
-    } else if (!buildRules) {
-      build = { ran: false, reason: 'no build rules' };
-    } else if (diagnostics.some(({ severity }) => severity === 'error')) {
-      build = { ran: false, reason: 'errors found' };
-    } else {
-      if (!json) addLog(<SpinnerLog message="building..." />);
-      const { cli: cliVersion } = getVersions(packageName);
-      site.build = await checkBuild({
-        ...argv,
-        _: [],
-        $0: packageName,
-        packageName,
-        cliVersion,
-        disableOpenapi: !rules.some(({ group }) => group === 'openapi'),
-      });
-      diagnostics = await runBuildChecks(site, rules, diagnostics);
-      build = { ran: true, passed: site.build.passed };
-    }
-
-    const report = toReport(diagnostics, build, argv.fix ? fixed : undefined);
-    if (json) {
-      restoreConsole?.();
-      await write(`${JSON.stringify(report)}\n`);
-    } else {
-      clearLogs();
-      logReport(report);
-      if (report.passed && build.ran && build.passed) await sendPublishPrompt();
-    }
-    await terminate(report.passed ? EXIT.passed : EXIT.failed);
-  } catch (error) {
-    // Bad arguments and crashes alike mean validate could not run
-    if (json) {
-      restoreConsole?.();
-      process.stderr.write(`Error: ${errorMessage(error)}\n`);
-    } else {
-      clearLogs();
-      addLog(<ErrorLog message={errorMessage(error)} />);
-    }
-    await terminate(EXIT.crashed);
-  }
-};

package/src/validate/engine.ts

@@ -1,210 +0,0 @@
-import { replaceVariables } from '@mintlify/common';
-import fs from 'node:fs/promises';
-import path from 'node:path';
-
-import { checkFiles, parseFile } from './files.js';
-import { applyEdits, selectEdits, toPosition } from './mdx.js';
-import { buildFindings } from './rules/build.js';
-import { RULES } from './rules/index.js';
-import { PARSE_ERROR } from './rules/parseError.js';
-import { loadSite } from './site.js';
-import {
-  GROUPS,
-  type Change,
-  type Diagnostic,
-  type DiagnosticSource,
-  type FileEdit,
-  type FileRule,
-  type Finding,
-  type Rule,
-  type Site,
-} from './types.js';
-
-export class UsageError extends Error {}
-
-const ruleList = () => RULES.map(({ id }) => id).join(', ');
-
-const matchToken = (token: string): Rule[] => {
-  if (token === 'all') return RULES;
-  const rule = RULES.find(({ id }) => id === token);
-  if (rule) return [rule];
-  if ((GROUPS as string[]).includes(token)) {
-    return RULES.filter(({ group }) => group === token);
-  }
-  throw new UsageError(
-    `unknown rule or group "${token}". Groups: all, ${GROUPS.join(', ')}. Rules: ${ruleList()}`
-  );
-};
-
-/** Every rule, minus --disable, plus --enable. parse-error is the engine's own, not selectable. */
-export const selectRules = ({
-  enable = [],
-  disable = [],
-}: {
-  enable?: string[];
-  disable?: string[];
-}): Rule[] => {
-  if ([...disable, ...enable].includes(PARSE_ERROR.id)) {
-    throw new UsageError(`${PARSE_ERROR.id} always runs and can't be disabled`);
-  }
-  const selected = new Set(RULES);
-  for (const token of disable) for (const rule of matchToken(token)) selected.delete(rule);
-  for (const token of enable) for (const rule of matchToken(token)) selected.add(rule);
-  return RULES.filter((rule) => selected.has(rule));
-};
-
-const toDiagnostic = (source: DiagnosticSource, finding: Finding): Diagnostic => ({
-  ...finding,
-  rule: source.id,
-  group: source.group,
-  severity: finding.severity ?? source.severity,
-});
-
-const RULE_ORDER = new Map(RULES.map(({ id }, index) => [id, index]));
-
-const sortDiagnostics = (diagnostics: Diagnostic[]) =>
-  diagnostics.sort(
-    (a, b) =>
-      (a.file < b.file ? -1 : a.file > b.file ? 1 : 0) ||
-      (a.line ?? 0) - (b.line ?? 0) ||
-      (a.column ?? 0) - (b.column ?? 0) ||
-      (RULE_ORDER.get(a.rule) ?? 0) - (RULE_ORDER.get(b.rule) ?? 0)
-  );
-
-/** Adds findings for a rule unless a diagnostic of that rule already has the same key. */
-const merge = (
-  diagnostics: Diagnostic[],
-  source: DiagnosticSource,
-  extra: Finding[],
-  key: (item: Pick<Diagnostic, 'file' | 'message'>) => string
-) => {
-  const reported = new Set(diagnostics.filter((item) => item.rule === source.id).map(key));
-  for (const finding of extra) {
-    if (reported.has(key(finding))) continue;
-    reported.add(key(finding));
-    diagnostics.push(toDiagnostic(source, finding));
-  }
-};
-
-const addParseErrors = (site: Site, diagnostics: Diagnostic[], extra: Finding[]) =>
-  merge(
-    diagnostics,
-    PARSE_ERROR,
-    extra.filter(({ file }) => !site.selected || site.selected.has(file)),
-    ({ file }) => file
-  );
-
-const fileRulesOf = (rules: Rule[]) =>
-  rules.filter((rule): rule is FileRule => rule.scope === 'file');
-
-const runSiteRules = async (
-  site: Site,
-  rules: Rule[],
-  needsBuild: boolean,
-  diagnostics: Diagnostic[]
-) => {
-  for (const rule of rules) {
-    if (rule.scope !== 'site' || Boolean(rule.needsBuild) !== needsBuild) continue;
-    for (const finding of await rule.check(site)) diagnostics.push(toDiagnostic(rule, finding));
-  }
-};
-
-/** Runs every selected rule that doesn't need the build. */
-export const runChecks = async (site: Site, rules: Rule[]) => {
-  const diagnostics = await checkFiles(site, fileRulesOf(rules));
-  await runSiteRules(site, rules, false, diagnostics);
-  return sortDiagnostics(diagnostics);
-};
-
-/** Adds the build's findings to a site whose build has run. */
-export const runBuildChecks = async (site: Site, rules: Rule[], diagnostics: Diagnostic[]) => {
-  await runSiteRules(site, rules, true, diagnostics);
-  // The file pass already reported files it couldn't parse; the build adds the rest
-  addParseErrors(site, diagnostics, buildFindings(site, 'parse-error'));
-  return sortDiagnostics(diagnostics);
-};
-
-const parseLevel = (file: string, content: string, baseDir: string) => {
-  const parsed = parseFile(file, content, baseDir);
-  return 'error' in parsed ? 0 : parsed.approximate ? 1 : 2;
-};
-
-/** Applies every fix that doesn't overlap an earlier fix in the same file, writing each Markdown file only when its fixed content parses at least as well as before. */
-export const applyFixes = async (site: Site, diagnostics: Diagnostic[]): Promise<Change[]> => {
-  const read = (file: string) => site.read(file) ?? '';
-  const chosen = new Map<string, { fix: FileEdit; change: Change }[]>();
-  const overlaps = ({ file, start, end }: FileEdit) =>
-    (chosen.get(file) ?? []).some(({ fix }) => start < fix.end && fix.start < end);
-
-  for (const { rule, fix } of diagnostics) {
-    if (!fix || overlaps(fix)) continue;
-    const content = read(fix.file);
-    const change = {
-      rule,
-      file: fix.file,
-      ...toPosition(content, fix.start),
-      before: content.slice(fix.start, fix.end),
-      after: fix.text,
-    };
-    chosen.set(fix.file, [...(chosen.get(fix.file) ?? []), { fix, change }]);
-  }
-
-  const snippets = new Set(
-    site.files.filter(({ kind }) => kind === 'snippet').map(({ file }) => file)
-  );
-  const level = (file: string, content: string) =>
-    parseLevel(
-      file,
-      snippets.has(file) ? replaceVariables(content, site.variables) : content,
-      site.baseDir
-    );
-
-  const applied: Change[] = [];
-  for (const [file, picks] of chosen) {
-    const content = read(file);
-    const updated = applyEdits(content, selectEdits(picks.map(({ fix }) => fix)));
-    if (/\.mdx?$/.test(file) && level(file, updated) < level(file, content)) {
-      continue;
-    }
-    await fs.writeFile(path.join(site.baseDir, file), updated);
-    applied.push(...picks.map(({ change }) => change));
-  }
-  return applied;
-};
-
-// Fixes can unlock others (a self-closed <br> lets a page parse), so --fix runs a few passes
-const MAX_FIX_PASSES = 5;
-
-/**
- * Loads the site and runs the selected rules. With fix, applies the fixes, rechecks only the
- * files that changed for further fixes, then runs every rule once more for the final report.
- */
-export const checkSite = async (
-  baseDir: string,
-  rules: Rule[],
-  options: { selected?: ReadonlySet<string>; localSchema: boolean; fix: boolean }
-) => {
-  const fixed: Change[] = [];
-  let site = await loadSite(baseDir, options);
-  const { selected } = options;
-  if (selected && !site.files.some(({ file }) => selected.has(file))) {
-    throw new UsageError(
-      `none of the given files are pages or snippets of this site: ${[...selected].join(', ')}`
-    );
-  }
-  const diagnostics = await runChecks(site, rules);
-  if (!options.fix) return { site, diagnostics, fixed };
-
-  // Only file rules offer fixes, so passes after the first recheck just the files that changed
-  let pending = diagnostics;
-  for (let pass = 0; pass < MAX_FIX_PASSES; pass++) {
-    const changes = await applyFixes(site, pending);
-    if (changes.length === 0) break;
-    fixed.push(...changes);
-    site = await loadSite(baseDir, options);
-    const changed = new Set(changes.map(({ file }) => file));
-    pending = sortDiagnostics(await checkFiles({ ...site, selected: changed }, fileRulesOf(rules)));
-  }
-  if (fixed.length === 0) return { site, diagnostics, fixed };
-  return { site, diagnostics: await runChecks(site, rules), fixed };
-};

package/src/validate/files.ts

@@ -1,249 +0,0 @@
-import { getAST, getFileCategory, parseFrontmatter, replaceVariables } from '@mintlify/common';
-import {
-  categorizeMdxFiles,
-  getErrorPosition,
-  getMintIgnore,
-  listContentFiles,
-} from '@mintlify/prebuild';
-import type { Root } from 'mdast';
-
-import {
-  applyEdits,
-  collectAnchorLinks,
-  parseContent,
-  relocate,
-  selectEdits,
-  toOffset,
-  unmapEdit,
-} from './mdx.js';
-import { PARSE_ERROR } from './rules/parseError.js';
-import type {
-  Diagnostic,
-  Edit,
-  FileContext,
-  FileFinding,
-  FileKind,
-  FileRule,
-  Site,
-  SiteFile,
-} from './types.js';
-
-const CHECKED_CATEGORIES = new Set<string | null>(['page', 'snippet', 'snippet-v2']);
-
-export const readSiteFiles = async (baseDir: string): Promise<SiteFile[]> => {
-  const { mdxCandidates: candidates } = await listContentFiles(
-    baseDir,
-    await getMintIgnore(baseDir)
-  );
-  const { snippets, snippetsV2 } = await categorizeMdxFiles(baseDir, candidates);
-  const snippetFiles = new Set([...snippets, ...snippetsV2]);
-  return candidates
-    .filter((name) => /\.mdx?$/.test(name) && CHECKED_CATEGORIES.has(getFileCategory(name)))
-    .map((name) => ({
-      file: name.replace(/^\//, ''),
-      kind: (snippetFiles.has(name) ? 'snippet' : 'page') as FileKind,
-    }));
-};
-
-const readFrontmatter = (content: string): Record<string, unknown> => {
-  try {
-    const { attributes } = parseFrontmatter<unknown>(content);
-    return attributes && typeof attributes === 'object' ? { ...attributes } : {};
-  } catch {
-    return {};
-  }
-};
-
-type ParseError = { line?: number; column?: number; message: string };
-
-const REASON_POSITION = /\s*\(\d+:\d+(?:-\d+:\d+)?\)$/;
-const TAG_NAME_RULES = new Set(['unexpected-character', 'unexpected-eof']);
-const ESCAPE_HINT = "; if this < isn't a tag, escape it as \\<";
-
-const isStrayLessThan = (
-  error: unknown,
-  content: string,
-  position: { line?: number; column?: number } | null
-) => {
-  const { source, ruleId } = (error ?? {}) as { source?: unknown; ruleId?: unknown };
-  return (
-    source === 'micromark-extension-mdx-jsx' &&
-    typeof ruleId === 'string' &&
-    TAG_NAME_RULES.has(ruleId) &&
-    position?.line != null &&
-    position.column != null &&
-    content[toOffset(content, position.line, position.column) - 1] === '<'
-  );
-};
-
-export const toParseError = (error: unknown, content = ''): ParseError => {
-  const reason = (error as { reason?: unknown } | null)?.reason;
-  const fallback = error instanceof Error ? error.message : 'could not parse this file';
-  const text = typeof reason === 'string' ? reason : fallback;
-  const position = error && typeof error === 'object' ? getErrorPosition(error) : null;
-  const hint = isStrayLessThan(error, content, position) ? ESCAPE_HINT : '';
-  return {
-    ...(position?.line != null && { line: position.line }),
-    ...(position?.column != null && { column: position.column }),
-    message: text.replace(REASON_POSITION, '') + hint,
-  };
-};
-
-type Extras = Pick<FileContext, 'readFile' | 'anchorLinks' | 'variables'>;
-
-const parseErrorDiagnostic = (file: string, error: ParseError): Diagnostic => ({
-  ...error,
-  rule: PARSE_ERROR.id,
-  group: PARSE_ERROR.group,
-  severity: PARSE_ERROR.severity,
-  file,
-  message: `${error.message} (other checks were skipped for this file)`,
-});
-
-type Parsed = { context: FileContext; approximate: boolean } | { error: ParseError };
-
-const tryParseContent = (content: string): Root | undefined => {
-  try {
-    return parseContent(content);
-  } catch {
-    return undefined;
-  }
-};
-
-export const parseFile = (
-  file: string,
-  content: string,
-  baseDir: string,
-  extras: Extras = {}
-): Parsed => {
-  const context = { file, content, baseDir, frontmatter: readFrontmatter(content), ...extras };
-  const tree = tryParseContent(content);
-  if (tree) return { context: { ...context, tree }, approximate: false };
-  try {
-    return { context: { ...context, tree: getAST(content, file) }, approximate: true };
-  } catch (error) {
-    return { error: toParseError(error, content) };
-  }
-};
-
-const EMPTY_TREE = { type: 'root' as const, children: [] };
-
-const SOURCE_STAGE = 1;
-const AFTER_RAW_STAGE = 2;
-
-type Stage = { content: string; edits: Edit[] };
-
-const VARIABLE = /\{\{\s*([\w.\-]+)\s*\}\}/g;
-
-const variableEdits = (content: string, variables: Record<string, string> = {}): Edit[] =>
-  [...content.matchAll(VARIABLE)]
-    .filter((match) => match[1] !== undefined && variables[match[1]] !== undefined)
-    .map((match) => ({
-      start: match.index,
-      end: match.index + match[0].length,
-      text: replaceVariables(match[0], variables),
-    }));
-
-const toDiagnostic = (
-  rule: FileRule,
-  file: string,
-  { edit, ...finding }: FileFinding,
-  stages: Stage[],
-  stage: number
-): Diagnostic => {
-  const original = edit && unmapEdit(stages, stage, edit);
-  return {
-    ...finding,
-    ...relocate(stages, stage, finding),
-    rule: rule.id,
-    group: rule.group,
-    severity: rule.severity,
-    file,
-    ...(original && { fix: { file, ...original } }),
-  };
-};
-
-const checkFile = (
-  allRules: FileRule[],
-  { file, kind }: SiteFile,
-  content: string,
-  baseDir: string,
-  extras: Extras,
-  variables?: Record<string, string>
-): Diagnostic[] => {
-  const rules = kind === 'snippet' ? allRules.filter((rule) => !rule.pagesOnly) : allRules;
-  const raw = rules.filter((rule) => rule.raw);
-  const treeRules = rules.filter((rule) => !rule.raw);
-  const varEdits = kind === 'snippet' ? variableEdits(content, variables) : [];
-  const source = applyEdits(content, varEdits);
-  const rawContext = {
-    file,
-    content: source,
-    baseDir,
-    frontmatter: {},
-    tree: EMPTY_TREE,
-    variables,
-  };
-
-  const rawFound = raw.flatMap((rule) =>
-    rule.check(rawContext).map((finding) => ({ rule, finding }))
-  );
-  const rawEdits = selectEdits(
-    rawFound.flatMap(({ finding }) => (finding.edit ? [finding.edit] : []))
-  );
-  const afterRaw = applyEdits(source, rawEdits);
-  const stages: Stage[] = [
-    { content, edits: varEdits },
-    { content: source, edits: rawEdits },
-    { content: afterRaw, edits: [] },
-  ];
-  const diagnostics = rawFound.map(({ rule, finding }) =>
-    toDiagnostic(rule, file, finding, stages, SOURCE_STAGE)
-  );
-
-  const parsed = parseFile(file, afterRaw, baseDir, { ...extras, variables });
-  if ('error' in parsed) {
-    diagnostics.unshift(
-      parseErrorDiagnostic(file, {
-        ...parsed.error,
-        ...relocate(stages, AFTER_RAW_STAGE, parsed.error),
-      })
-    );
-    return diagnostics;
-  }
-  for (const rule of treeRules) {
-    for (const finding of rule.check(parsed.context)) {
-      const found = parsed.approximate ? { ...finding, edit: undefined } : finding;
-      diagnostics.push(toDiagnostic(rule, file, found, stages, AFTER_RAW_STAGE));
-    }
-  }
-  return diagnostics;
-};
-
-const collectSiteAnchorLinks = async (site: Site): Promise<ReadonlySet<string>> => {
-  const pages = await Promise.all(
-    site.files.map(({ file }) => collectAnchorLinks(file, site.read(file) ?? ''))
-  );
-  return new Set(pages.flat());
-};
-
-export const checkFiles = async (site: Site, rules: FileRule[]): Promise<Diagnostic[]> => {
-  const anchorRules = new Set(rules.filter((rule) => rule.needsAnchorLinks).map(({ id }) => id));
-  const targets = site.files.filter(({ file }) => !site.selected || site.selected.has(file));
-  const checkTarget = (entry: SiteFile, extras: Extras) => {
-    const content = site.read(entry.file);
-    if (content === undefined) {
-      return [parseErrorDiagnostic(entry.file, { message: 'could not read this file' })];
-    }
-    return checkFile(rules, entry, content, site.baseDir, extras, site.variables);
-  };
-  const needsLinks = (diagnostics: Diagnostic[]) =>
-    diagnostics.some(({ rule }) => anchorRules.has(rule));
-  const checked = targets.map((entry) => checkTarget(entry, { readFile: site.read }));
-  if (!checked.some(needsLinks)) return checked.flat();
-  const extras = { readFile: site.read, anchorLinks: await collectSiteAnchorLinks(site) };
-  return targets.flatMap((entry, index) => {
-    const diagnostics = checked[index] ?? [];
-    return needsLinks(diagnostics) ? checkTarget(entry, extras) : diagnostics;
-  });
-};