@mintlify/cli 4.0.1739 → 4.0.1740

package/bin/validate/command.js

@@ -7,19 +7,31 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
 import { jsx as _jsx } from "react/jsx-runtime";
-import { addLog, clearLogs, ErrorLog, SpinnerLog } from '@mintlify/previewing';
+import { addLog, checkBuild, clearLogs, ErrorLog, SpinnerLog } from '@mintlify/previewing';
 import path from 'node:path';
-import { CMD_EXEC_PATH, terminate } from '../helpers.js';
-import { NoMatchingFilesError, resolveExplicitFiles } from '../resolveFiles.js';
-import { checkSite, selectRules, UsageError } from './engine.js';
-import { logDiagnostics } from './output.js';
+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 } from './report.js';
 export const EXIT = { passed: 0, failed: 1, crashed: 2 };
 export const splitList = (values) => values.flatMap((value) => value
     .split(',')
     .map((item) => item.trim())
     .filter(Boolean));
-const errorMessage = (error) => (error instanceof Error ? error.message : String(error));
 const resolveSelection = (baseDir, values) => __awaiter(void 0, void 0, void 0, function* () {
     const args = (values !== null && values !== void 0 ? values : []).map(String).filter(Boolean);
     if (args.length === 0)
@@ -27,7 +39,8 @@ const resolveSelection = (baseDir, values) => __awaiter(void 0, void 0, void 0,
     const files = yield resolveExplicitFiles(CMD_EXEC_PATH, args);
     return new Set(files.map((file) => path.relative(baseDir, path.resolve(CMD_EXEC_PATH, file)).split(path.sep).join('/')));
 });
-export const runLintStep = (argv_1, ...args_1) => __awaiter(void 0, [argv_1, ...args_1], void 0, function* (argv, baseDir = CMD_EXEC_PATH) {
+/** mint validate: one pass over every selected rule, then the strict build when nothing failed. */
+export const validateHandler = (argv_1, packageName_1, ...args_1) => __awaiter(void 0, [argv_1, packageName_1, ...args_1], void 0, function* (argv, packageName, baseDir = CMD_EXEC_PATH) {
     var _a;
     try {
         const rules = selectRules({
@@ -36,23 +49,41 @@ export const runLintStep = (argv_1, ...args_1) => __awaiter(void 0, [argv_1, ...
         });
         const selected = yield resolveSelection(baseDir, argv.files);
         addLog(_jsx(SpinnerLog, { message: "validating..." }));
-        const { diagnostics } = yield checkSite(baseDir, rules, {
+        const _b = yield checkSite(baseDir, rules, {
             selected,
             localSchema: argv['local-schema'],
-        });
-        clearLogs();
-        const failed = logDiagnostics(diagnostics);
-        if (failed) {
-            yield terminate(EXIT.failed);
-            return false;
+        }), { site } = _b, checked = __rest(_b, ["site"]);
+        let { diagnostics } = checked;
+        const buildRules = rules.some(({ needsBuild }) => needsBuild);
+        let build;
+        if (!argv.build) {
+            build = { ran: false, reason: 'disabled' };
         }
-        return true;
+        else if (!buildRules) {
+            build = { ran: false, reason: 'no build rules' };
+        }
+        else if (diagnostics.some(({ severity }) => severity === 'error')) {
+            build = { ran: false, reason: 'errors found' };
+        }
+        else {
+            addLog(_jsx(SpinnerLog, { message: "building..." }));
+            const { cli: cliVersion } = getVersions(packageName);
+            site.build = yield checkBuild(Object.assign(Object.assign({}, argv), { _: [], $0: packageName, packageName,
+                cliVersion, disableOpenapi: !rules.some(({ group }) => group === 'openapi') }));
+            diagnostics = yield runBuildChecks(site, rules, diagnostics);
+            build = { ran: true, passed: site.build.passed };
+        }
+        const report = toReport(diagnostics, build);
+        clearLogs();
+        logReport(report);
+        if (report.passed && build.ran && build.passed)
+            yield sendPublishPrompt();
+        yield terminate(report.passed ? EXIT.passed : EXIT.failed);
     }
     catch (error) {
-        const usage = error instanceof UsageError || error instanceof NoMatchingFilesError;
+        // Bad arguments and crashes alike mean validate could not run
         clearLogs();
         addLog(_jsx(ErrorLog, { message: errorMessage(error) }));
-        yield terminate(usage ? EXIT.failed : EXIT.crashed);
-        return false;
+        yield terminate(EXIT.crashed);
     }
 });

package/bin/validate/engine.js

@@ -8,6 +8,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 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';
@@ -52,6 +53,17 @@ const sortDiagnostics = (diagnostics) => diagnostics.sort((a, b) => {
         ((_c = a.column) !== null && _c !== void 0 ? _c : 0) - ((_d = b.column) !== null && _d !== void 0 ? _d : 0) ||
         ((_e = RULE_ORDER.get(a.rule)) !== null && _e !== void 0 ? _e : 0) - ((_f = RULE_ORDER.get(b.rule)) !== null && _f !== void 0 ? _f : 0);
 });
+/** Adds findings for a rule unless a diagnostic of that rule already has the same key. */
+const merge = (diagnostics, source, extra, key) => {
+    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, diagnostics, extra) => 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 = (site, rules) => __awaiter(void 0, void 0, void 0, function* () {
     const fileRules = rules.filter((rule) => rule.scope === 'file');
@@ -64,6 +76,18 @@ export const runChecks = (site, rules) => __awaiter(void 0, void 0, void 0, func
     }
     return sortDiagnostics(diagnostics);
 });
+/** Adds the build's findings to a site whose build has run. */
+export const runBuildChecks = (site, rules, diagnostics) => __awaiter(void 0, void 0, void 0, function* () {
+    for (const rule of rules) {
+        if (rule.scope !== 'site' || !rule.needsBuild)
+            continue;
+        for (const finding of yield 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 = (baseDir, rules, options) => __awaiter(void 0, void 0, void 0, function* () {
     const site = yield loadSite(baseDir, options);

package/bin/validate/output.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { addLog, ErrorLog } from '@mintlify/previewing';
+import { addLog, ErrorLog, InfoLog, SuccessLog } from '@mintlify/previewing';
 import { Box, Text } from 'ink';
 const location = ({ line, column }) => line ? `${line}${column ? `:${column}` : ''}` : '';
 const DiagnosticLine = ({ diagnostic }) => {
@@ -7,22 +7,27 @@ const DiagnosticLine = ({ diagnostic }) => {
     return (_jsxs(Text, { children: ['  ', diagnostic.severity === 'error' ? (_jsx(Text, { color: "red", children: "\u2717" })) : (_jsx(Text, { color: "yellow", children: "!" })), ' ', at && _jsxs(Text, { dimColor: true, children: [at, " "] }), _jsx(Text, { dimColor: true, children: diagnostic.rule }), " ", diagnostic.message, diagnostic.fix && _jsx(Text, { dimColor: true, children: " (fixable)" })] }));
 };
 const plural = (count, word) => `${count} ${word}${count === 1 ? '' : 's'}`;
-export const logDiagnostics = (all) => {
+export const logReport = (report) => {
     var _a, _b;
     const byFile = new Map();
-    for (const diagnostic of all) {
+    for (const diagnostic of report.diagnostics) {
         (_b = (_a = byFile.get(diagnostic.file)) === null || _a === void 0 ? void 0 : _a.push(diagnostic)) !== null && _b !== void 0 ? _b : byFile.set(diagnostic.file, [diagnostic]);
     }
     for (const [file, diagnostics] of byFile) {
         addLog(_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { bold: true, children: file }), diagnostics.map((diagnostic, index) => (_jsx(DiagnosticLine, { diagnostic: diagnostic }, index)))] }));
     }
-    const errors = all.filter(({ severity }) => severity === 'error').length;
-    const warnings = all.length - errors;
-    if (errors > 0) {
-        addLog(_jsx(ErrorLog, { message: `${plural(errors, 'error')}${warnings > 0 ? `, ${plural(warnings, 'warning')}` : ''}` }));
-    }
-    else if (warnings > 0) {
-        addLog(_jsx(Text, { dimColor: true, children: plural(warnings, 'warning') }));
-    }
-    return errors > 0;
+    const { build } = report;
+    if (build.ran && build.passed)
+        addLog(_jsx(SuccessLog, { message: "build passed" }));
+    else if (build.ran && report.passed)
+        addLog(_jsx(InfoLog, { message: "build failed only on disabled rules" }));
+    else if (build.ran)
+        addLog(_jsx(ErrorLog, { message: "build failed" }));
+    else if (build.reason === 'errors found')
+        addLog(_jsx(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 ? _jsx(SuccessLog, { message: passed }) : _jsx(ErrorLog, { message: failed }));
 };

package/bin/validate/report.js

@@ -0,0 +1,16 @@
+export const toReport = (diagnostics, build) => {
+    var _a;
+    const byRule = {};
+    for (const { rule } of diagnostics)
+        byRule[rule] = ((_a = byRule[rule]) !== null && _a !== void 0 ? _a : 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 }) => (Object.assign(Object.assign(Object.assign(Object.assign({ rule,
+            group,
+            severity,
+            file }, (line !== undefined && { line })), (column !== undefined && { column })), { message }), (fix && { fix })))),
+        build,
+    };
+};

package/bin/validate/rules/build.js

@@ -0,0 +1,94 @@
+import { normalizeRelativePath, toPosixPath } from '@mintlify/common';
+import { stripVTControlCharacters } from 'node:util';
+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([
+    '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, { type, message }) => {
+    var _a;
+    const clean = stripVTControlCharacters(message).trim();
+    const importer = IMPORT_TYPES.has(type)
+        ? IMPORTERS.map((pattern) => { var _a; return (_a = pattern.exec(clean)) === null || _a === void 0 ? void 0 : _a[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 !== null && importer !== void 0 ? importer : match === null || match === void 0 ? void 0 : 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 ? (_a = QUOTED.exec(clean)) === null || _a === void 0 ? void 0 : _a[0] : undefined;
+    return Object.assign(Object.assign(Object.assign({ file }, (position && Object.assign({ 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(['parse-error']);
+const buildRule = (id, group, types, description) => {
+    for (const type of types)
+        COVERED_TYPES.add(type);
+    return {
+        id,
+        group,
+        severity: 'error',
+        needsBuild: true,
+        scope: 'site',
+        description,
+        check: (site) => {
+            var _a, _b;
+            return ((_b = (_a = site.build) === null || _a === void 0 ? void 0 : _a.warnings) !== null && _b !== void 0 ? _b : [])
+                .filter(({ type }) => types.includes(type))
+                .map((warning) => toFinding(site, warning));
+        },
+    };
+};
+export const BUILD_RULES = [
+    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.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, type) => {
+    var _a, _b;
+    return ((_b = (_a = site.build) === null || _a === void 0 ? void 0 : _a.warnings) !== null && _b !== void 0 ? _b : [])
+        .filter((warning) => warning.type === type)
+        .map((warning) => toFinding(site, warning));
+};

package/bin/validate/rules/index.js

@@ -1,3 +1,5 @@
+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 = [voidTags];
+export const RULES = [voidTags, openApiSpec, ...BUILD_RULES];

package/bin/validate/rules/openapi.js

@@ -0,0 +1,50 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { errorMessage } from '../../helpers.js';
+import { buildOverlayRegistryForCheck, checkOpenApiFile, getOpenApiFilenamesFromDocsConfig, } from '../../openApiCheck.js';
+export const openApiSpec = {
+    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: (site) => __awaiter(void 0, void 0, void 0, function* () {
+        let filenames = [];
+        try {
+            const config = JSON.parse(yield 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) {
+            // A missing or invalid config file is the build's to report
+        }
+        if (filenames.length === 0)
+            return [];
+        let overlayRegistry;
+        try {
+            overlayRegistry = yield buildOverlayRegistryForCheck(site.localSchema);
+        }
+        catch (error) {
+            return [{ file: site.configFile, message: `OpenAPI overlays: ${errorMessage(error)}` }];
+        }
+        const perFile = yield Promise.all(filenames.map((file) => __awaiter(void 0, void 0, void 0, function* () {
+            const messages = [];
+            yield checkOpenApiFile(file, site.localSchema, overlayRegistry, (message) => messages.push(message));
+            return messages.flatMap(({ level, message }) => level === 'error'
+                ? [{ file, message }]
+                : level === 'warning'
+                    ? [{ file, message, severity: 'warning' }]
+                    : []);
+        })));
+        return perFile.flat();
+    }),
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mintlify/cli",
-  "version": "4.0.1739",
+  "version": "4.0.1740",
   "description": "The Mintlify CLI",
   "engines": {
     "node": ">=18.0.0"
@@ -46,11 +46,11 @@
   "dependencies": {
     "@inquirer/prompts": "7.9.0",
     "@mintlify/common": "1.0.1307",
-    "@mintlify/link-rot": "3.0.1536",
+    "@mintlify/link-rot": "3.0.1537",
     "@mintlify/models": "0.0.379",
     "@mintlify/og": "0.0.106",
-    "@mintlify/prebuild": "1.0.1473",
-    "@mintlify/previewing": "4.0.1554",
+    "@mintlify/prebuild": "1.0.1474",
+    "@mintlify/previewing": "4.0.1555",
     "@mintlify/validation": "0.1.944",
     "adm-zip": "0.6.0",
     "chalk": "5.2.0",
@@ -101,5 +101,5 @@
     "vitest": "2.1.9",
     "vitest-mock-process": "1.0.4"
   },
-  "gitHead": "bc5883bc2e0ace9696ffa286bf8cb2b2c32c2c81"
+  "gitHead": "17769e5210e7861c4b9c751f8b0cbf5e7bdd3143"
 }

package/src/cli.tsx

@@ -2,7 +2,6 @@ import {
   addLog,
   dev,
   exportSite,
-  validateBuild,
   ErrorLog,
   SuccessLog,
   Logs,
@@ -10,8 +9,6 @@ import {
 } from '@mintlify/previewing';
 import { thumbnailOverrideSchema } from '@mintlify/validation';
 import { render, Text } from 'ink';
-import fs from 'node:fs/promises';
-import path from 'path';
 import yargs, { type Argv } from 'yargs';
 import { hideBin } from 'yargs/helpers';
 
@@ -30,7 +27,6 @@ import { DEPLOY_HELP, deploymentInstructions } from './deploy-instructions.js';
 import { formatDeployment, prepareAgentDeployment } from './deploy.js';
 import { formatHandler } from './format.js';
 import {
-  CMD_EXEC_PATH,
   checkPort,
   checkNodeVersion,
   autoUpgradeIfNeeded,
@@ -46,17 +42,16 @@ import { logout } from './logout.js';
 import { mdxLinter } from './mdxLinter.js';
 import { createTelemetryMiddleware } from './middlewares/telemetryMiddleware.js';
 import { ogCommand } from './og.js';
-import {
-  buildOverlayRegistryForCheck,
-  checkOpenApiFile,
-  getOpenApiFilenamesFromDocsConfig,
-} from './openApiCheck.js';
+import { buildOverlayRegistryForCheck, checkOpenApiFile } from './openApiCheck.js';
 import { scoreHandler } from './score/index.js';
-import { sendPublishPrompt, signup } from './signup.js';
+import { signup } from './signup.js';
 import { status, getCliSubdomains } from './status.js';
 import { trackTelemetryPreferenceChange } from './telemetry/track.js';
 import { update } from './update.js';
-import { runLintStep, splitList } from './validate/command.js';
+import { splitList, validateHandler } from './validate/command.js';
+import { RULES } from './validate/rules/index.js';
+import { PARSE_ERROR } from './validate/rules/parseError.js';
+import { GROUPS } from './validate/types.js';
 import { renderWelcome } from './welcome.js';
 import { workflowsBuilder } from './workflows/index.js';
 
@@ -362,7 +357,7 @@ export const cli = ({ packageName = 'mint' }: { packageName?: string }) => {
       )
       .command(
         'validate',
-        'Validate the documentation build (strict mode, exits on warnings or errors)',
+        'Check the docs: content, OpenAPI specs, then a strict build. Exits 0 with no errors, 1 with errors, 2 when validate itself could not run',
         (yargs) =>
           yargs
             .option('local-schema', {
@@ -380,17 +375,18 @@ export const cli = ({ packageName = 'mint' }: { packageName?: string }) => {
               type: 'array',
               description: 'Mock user groups for validation',
             })
-            .option('disable-openapi', {
-              type: 'boolean',
-              default: false,
-              description: 'Disable OpenAPI file generation',
-            })
             .option('files', {
               type: 'string',
               array: true,
               description:
                 'Limit page checks to these files or globs; site-wide checks and the build still cover the whole site',
             })
+            .option('build', {
+              type: 'boolean',
+              default: true,
+              description:
+                'Run the strict build after the other checks pass; --no-build skips it, so no client download is needed. Remote OpenAPI specs are still fetched unless openapi rules are disabled',
+            })
             .option('enable', {
               type: 'string',
               array: true,
@@ -405,50 +401,22 @@ export const cli = ({ packageName = 'mint' }: { packageName?: string }) => {
               description:
                 'Turn off rules or groups (comma-separated), or all; parse errors are still reported',
             })
-            .usage('usage: mintlify validate [options]')
-            .example('mintlify validate', 'validate the build'),
-        async (argv) => {
-          const lintPassed = await runLintStep(argv);
-          if (!lintPassed) return;
-
-          if (!argv['disable-openapi']) {
-            let openApiFilenames: string[] = [];
-
-            try {
-              const docsJson = await fs.readFile(path.join(CMD_EXEC_PATH, 'docs.json'), 'utf-8');
-              openApiFilenames = getOpenApiFilenamesFromDocsConfig(JSON.parse(docsJson));
-            } catch {}
-
-            let overlayRegistry;
-            try {
-              overlayRegistry = await buildOverlayRegistryForCheck(argv['local-schema']);
-            } catch (error) {
-              addLog(<ErrorLog message={error instanceof Error ? error.message : String(error)} />);
-              await terminate(1);
-              return;
-            }
-            const results = await Promise.all(
-              openApiFilenames.map((file) =>
-                checkOpenApiFile(file, argv['local-schema'], overlayRegistry)
-              )
-            );
-
-            if (results.some((valid) => !valid)) {
-              await terminate(1);
-              return;
-            }
-          }
-
-          const { cli: cliVersion } = getVersions(packageName);
-          await validateBuild(
-            {
-              ...argv,
-              packageName,
-              cliVersion,
-            },
-            sendPublishPrompt
-          );
-        }
+            .usage('usage: mint validate [options]')
+            .epilogue(
+              [
+                `Groups: ${GROUPS.join(', ')}. Rules:`,
+                ...RULES.map(({ id, description }) => `  ${id} — ${description}`),
+                `  parse-error — ${PARSE_ERROR.description} (always runs)`,
+              ].join('\n')
+            )
+            .example('mint validate', 'run every check and the build')
+            .example('mint validate --files "guides/**/*.mdx"', 'check some pages')
+            .example(
+              'mint validate --disable all --enable content',
+              'run the content rules only; missing-file and import-error still run the build'
+            )
+            .strict(),
+        (argv) => validateHandler(argv, packageName)
       )
       .command(
         'export',

package/src/helpers.tsx

@@ -248,6 +248,9 @@ export const readLocalOpenApiFile = async (
   return document;
 };
 
+export const errorMessage = (error: unknown) =>
+  error instanceof Error ? error.message : String(error);
+
 export const terminate = async (code: number) => {
   // Wait for the logs to be fully rendered before exiting
   await new Promise((resolve) => setTimeout(resolve, 50));

package/src/validate/command.tsx

@@ -1,16 +1,19 @@
-import { addLog, clearLogs, ErrorLog, SpinnerLog } from '@mintlify/previewing';
+import { addLog, checkBuild, clearLogs, ErrorLog, SpinnerLog } from '@mintlify/previewing';
 import path from 'node:path';
 
-import { CMD_EXEC_PATH, terminate } from '../helpers.js';
-import { NoMatchingFilesError, resolveExplicitFiles } from '../resolveFiles.js';
-import { checkSite, selectRules, UsageError } from './engine.js';
-import { logDiagnostics } from './output.js';
+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[];
 };
@@ -25,8 +28,6 @@ export const splitList = (values: string[]) =>
       .filter(Boolean)
   );
 
-const errorMessage = (error: unknown) => (error instanceof Error ? error.message : String(error));
-
 const resolveSelection = async (baseDir: string, values: (string | number)[] | undefined) => {
   const args = (values ?? []).map(String).filter(Boolean);
   if (args.length === 0) return undefined;
@@ -38,10 +39,12 @@ const resolveSelection = async (baseDir: string, values: (string | number)[] | u
   );
 };
 
-export const runLintStep = async (
+/** 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
-): Promise<boolean> => {
+) => {
   try {
     const rules = selectRules({
       enable: argv.enable,
@@ -50,22 +53,44 @@ export const runLintStep = async (
     const selected = await resolveSelection(baseDir, argv.files);
     addLog(<SpinnerLog message="validating..." />);
 
-    const { diagnostics } = await checkSite(baseDir, rules, {
+    const { site, ...checked } = await checkSite(baseDir, rules, {
       selected,
       localSchema: argv['local-schema'],
     });
-    clearLogs();
-    const failed = logDiagnostics(diagnostics);
-    if (failed) {
-      await terminate(EXIT.failed);
-      return false;
+    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 {
+      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 };
     }
-    return true;
+
+    const report = toReport(diagnostics, build);
+    clearLogs();
+    logReport(report);
+    if (report.passed && build.ran && build.passed) await sendPublishPrompt();
+    await terminate(report.passed ? EXIT.passed : EXIT.failed);
   } catch (error) {
-    const usage = error instanceof UsageError || error instanceof NoMatchingFilesError;
+    // Bad arguments and crashes alike mean validate could not run
     clearLogs();
     addLog(<ErrorLog message={errorMessage(error)} />);
-    await terminate(usage ? EXIT.failed : EXIT.crashed);
-    return false;
+    await terminate(EXIT.crashed);
   }
 };