@mintlify/cli 4.0.1739 → 4.0.1740

package/src/validate/engine.ts

@@ -1,4 +1,5 @@
 import { checkFiles } from './files.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';
@@ -63,6 +64,29 @@ const sortDiagnostics = (diagnostics: Diagnostic[]) =>
       (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
+  );
+
 /** Runs every selected rule that doesn't need the build. */
 export const runChecks = async (site: Site, rules: Rule[]) => {
   const fileRules = rules.filter((rule): rule is FileRule => rule.scope === 'file');
@@ -75,6 +99,17 @@ export const runChecks = async (site: Site, rules: Rule[]) => {
   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[]) => {
+  for (const rule of rules) {
+    if (rule.scope !== 'site' || !rule.needsBuild) continue;
+    for (const finding of await rule.check(site)) diagnostics.push(toDiagnostic(rule, finding));
+  }
+  // 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);
+};
+
 /** Loads the site and runs the selected rules. */
 export const checkSite = async (
   baseDir: string,

package/src/validate/output.tsx

@@ -1,6 +1,7 @@
-import { addLog, ErrorLog } from '@mintlify/previewing';
+import { addLog, ErrorLog, InfoLog, SuccessLog } from '@mintlify/previewing';
 import { Box, Text } from 'ink';
 
+import type { Report } from './report.js';
 import type { Diagnostic } from './types.js';
 
 const location = ({ line, column }: Pick<Diagnostic, 'line' | 'column'>) =>
@@ -25,9 +26,9 @@ const DiagnosticLine = ({ diagnostic }: { diagnostic: Diagnostic }) => {
 
 const plural = (count: number, word: string) => `${count} ${word}${count === 1 ? '' : 's'}`;
 
-export const logDiagnostics = (all: Diagnostic[]) => {
+export const logReport = (report: Report) => {
   const byFile = new Map<string, Diagnostic[]>();
-  for (const diagnostic of all) {
+  for (const diagnostic of report.diagnostics) {
     byFile.get(diagnostic.file)?.push(diagnostic) ?? byFile.set(diagnostic.file, [diagnostic]);
   }
   for (const [file, diagnostics] of byFile) {
@@ -41,16 +42,17 @@ export const logDiagnostics = (all: Diagnostic[]) => {
     );
   }
 
-  const errors = all.filter(({ severity }) => severity === 'error').length;
-  const warnings = all.length - errors;
-  if (errors > 0) {
-    addLog(
-      <ErrorLog
-        message={`${plural(errors, 'error')}${warnings > 0 ? `, ${plural(warnings, 'warning')}` : ''}`}
-      />
-    );
-  } else if (warnings > 0) {
-    addLog(<Text dimColor>{plural(warnings, 'warning')}</Text>);
-  }
-  return errors > 0;
+  const { build } = report;
+  if (build.ran && build.passed) addLog(<SuccessLog message="build passed" />);
+  else if (build.ran && report.passed)
+    addLog(<InfoLog message="build failed only on disabled rules" />);
+  else if (build.ran) addLog(<ErrorLog message="build failed" />);
+  else if (build.reason === 'errors found')
+    addLog(<InfoLog message="build skipped until the errors above are fixed" />);
+
+  const { errors, warnings } = report.summary;
+  const warned = plural(warnings, 'warning');
+  const passed = warnings > 0 ? `passed with ${warned}` : 'validation passed';
+  const failed = `${plural(errors, 'error')}${warnings > 0 ? `, ${warned}` : ''}`;
+  addLog(report.passed ? <SuccessLog message={passed} /> : <ErrorLog message={failed} />);
 };

package/src/validate/report.ts

@@ -0,0 +1,33 @@
+import type { Diagnostic } from './types.js';
+
+export type BuildStatus =
+  | { ran: true; passed: boolean }
+  | { ran: false; reason: 'disabled' | 'errors found' | 'no build rules' };
+
+export type Report = {
+  passed: boolean;
+  summary: { errors: number; warnings: number; byRule: Record<string, number> };
+  diagnostics: Diagnostic[];
+  build: BuildStatus;
+};
+
+export const toReport = (diagnostics: Diagnostic[], build: BuildStatus): Report => {
+  const byRule: Record<string, number> = {};
+  for (const { rule } of diagnostics) byRule[rule] = (byRule[rule] ?? 0) + 1;
+  const errors = diagnostics.filter(({ severity }) => severity === 'error').length;
+  return {
+    passed: errors === 0,
+    summary: { errors, warnings: diagnostics.length - errors, byRule },
+    diagnostics: diagnostics.map(({ rule, group, severity, file, line, column, message, fix }) => ({
+      rule,
+      group,
+      severity,
+      file,
+      ...(line !== undefined && { line }),
+      ...(column !== undefined && { column }),
+      message,
+      ...(fix && { fix }),
+    })),
+    build,
+  };
+};

package/src/validate/rules/build.ts

@@ -0,0 +1,132 @@
+import { normalizeRelativePath, toPosixPath } from '@mintlify/common';
+import type { Warning } from '@mintlify/prebuild';
+import { stripVTControlCharacters } from 'node:util';
+
+import type { Finding, Group, Site, SiteRule } from '../types.js';
+
+const FILE = String.raw`[\w@.\\/-]+\.(?:mdx?|jsx?|tsx?|json|ya?ml)\b`;
+
+const FILE_IN_MESSAGE = new RegExp(FILE);
+
+const IMPORTERS = [
+  new RegExp(String.raw`\(in (${FILE}),`),
+  new RegExp(String.raw`(?:\bin|imported from) (${FILE})`),
+];
+
+const IMPORT_TYPES = new Set<Warning['type']>([
+  'missing-file',
+  'invalid-import-path',
+  'import-resolution-error',
+  'default-import-no-default-export',
+  'export-collision',
+  'undeclared-package',
+  'package-import-conflict',
+]);
+
+const POSITION = /^:(\d+)(?::(\d+))?/;
+
+const QUOTED = /"([^"]+)"/;
+
+const toFinding = (site: Site, { type, message }: Warning): Finding => {
+  const clean = stripVTControlCharacters(message).trim();
+  const importer = IMPORT_TYPES.has(type)
+    ? IMPORTERS.map((pattern) => pattern.exec(clean)?.[1]).find(Boolean)
+    : undefined;
+  // Missing nav pages are always about the config, even when the page looks like a file
+  const match = importer || type === 'missing-nav-page' ? null : FILE_IN_MESSAGE.exec(clean);
+  const found = importer ?? match?.[0];
+  const file = found ? normalizeRelativePath(toPosixPath(found)) : site.configFile;
+  const position = match ? POSITION.exec(clean.slice(match.index + match[0].length)) : null;
+  // Config warnings quote the entry they're about, such as a navigation page
+  const quoted = file === site.configFile ? QUOTED.exec(clean)?.[0] : undefined;
+  return {
+    file,
+    ...(position && {
+      line: Number(position[1]),
+      ...(position[2] && { column: Number(position[2]) }),
+    }),
+    ...(quoted && site.locate(file, quoted)),
+    message: clean,
+  };
+};
+
+/** Warning types some rule turns into diagnostics, so a strict-build failure is explained. */
+const COVERED_TYPES = new Set<Warning['type']>(['parse-error']);
+
+const buildRule = (
+  id: string,
+  group: Group,
+  types: Warning['type'][],
+  description: string
+): SiteRule => {
+  for (const type of types) COVERED_TYPES.add(type);
+  return {
+    id,
+    group,
+    severity: 'error',
+    needsBuild: true,
+    scope: 'site',
+    description,
+    check: (site) =>
+      (site.build?.warnings ?? [])
+        .filter(({ type }) => types.includes(type))
+        .map((warning) => toFinding(site, warning)),
+  };
+};
+
+export const BUILD_RULES: SiteRule[] = [
+  buildRule(
+    'missing-nav-page',
+    'nav',
+    ['missing-nav-page'],
+    'pages in the navigation that have no file'
+  ),
+  buildRule('missing-file', 'content', ['missing-file'], "imported files that don't exist"),
+  buildRule(
+    'import-error',
+    'content',
+    [
+      'invalid-import-path',
+      'import-resolution-error',
+      'default-import-no-default-export',
+      'export-collision',
+    ],
+    "imports in pages and snippets that don't resolve"
+  ),
+  buildRule(
+    'package-import',
+    'config',
+    ['undeclared-package', 'package-import-conflict'],
+    'npm package imports that are undeclared or conflict'
+  ),
+  buildRule('openapi-build', 'openapi', ['openapi'], 'OpenAPI pages the build could not generate'),
+  {
+    id: 'build-failed',
+    group: 'config',
+    severity: 'error',
+    needsBuild: true,
+    scope: 'site',
+    description: 'the strict build failed for a reason no rule reports',
+    check: (site) => {
+      if (!site.build || site.build.passed) return [];
+      const unreported = (warning: Warning) =>
+        warning.type === 'parse-error' &&
+        site.selected !== undefined &&
+        !site.selected.has(toFinding(site, warning).file);
+      const uncovered = site.build.warnings.filter(
+        (warning) => !COVERED_TYPES.has(warning.type) || unreported(warning)
+      );
+      const findings = uncovered.map((warning) => toFinding(site, warning));
+      // Covered warnings are the selected rules' to report; disabled ones are meant to pass
+      return site.build.strict
+        ? findings
+        : [...findings, { file: site.configFile, message: site.build.error }];
+    },
+  },
+];
+
+/** Build warnings of one type, which the engine merges into the static rule that covers them. */
+export const buildFindings = (site: Site, type: Warning['type']): Finding[] =>
+  (site.build?.warnings ?? [])
+    .filter((warning) => warning.type === type)
+    .map((warning) => toFinding(site, warning));

package/src/validate/rules/index.ts

@@ -1,5 +1,7 @@
 import type { Rule } from '../types.js';
+import { BUILD_RULES } from './build.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];
+export const RULES: Rule[] = [voidTags, openApiSpec, ...BUILD_RULES];

package/src/validate/rules/openapi.ts

@@ -0,0 +1,59 @@
+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();
+  },
+};