@mintlify/cli 4.0.1740 → 4.0.1742

package/bin/validate/command.js

@@ -21,6 +21,7 @@ var __rest = (this && this.__rest) || function (s, e) {
 import { jsx as _jsx } from "react/jsx-runtime";
 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';
@@ -32,6 +33,26 @@ export const splitList = (values) => values.flatMap((value) => value
     .split(',')
     .map((item) => item.trim())
     .filter(Boolean));
+const write = (text) => new Promise((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) => {
+        process.stderr.write(`${format(...args)}\n`);
+    };
+    console.log = console.info = console.warn = console.error = toStderr;
+    return () => Object.assign(console, original);
+};
 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)
@@ -42,17 +63,21 @@ const resolveSelection = (baseDir, values) => __awaiter(void 0, void 0, void 0,
 /** 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;
+    const json = argv.format === 'json';
+    const restoreConsole = json ? consoleToStderr() : undefined;
     try {
         const rules = selectRules({
             enable: argv.enable,
             disable: (_a = argv.disable) !== null && _a !== void 0 ? _a : [],
         });
         const selected = yield resolveSelection(baseDir, argv.files);
-        addLog(_jsx(SpinnerLog, { message: "validating..." }));
+        if (!json)
+            addLog(_jsx(SpinnerLog, { message: "validating..." }));
         const _b = yield checkSite(baseDir, rules, {
             selected,
             localSchema: argv['local-schema'],
-        }), { site } = _b, checked = __rest(_b, ["site"]);
+            fix: argv.fix,
+        }), { site, fixed } = _b, checked = __rest(_b, ["site", "fixed"]);
         let { diagnostics } = checked;
         const buildRules = rules.some(({ needsBuild }) => needsBuild);
         let build;
@@ -66,24 +91,37 @@ export const validateHandler = (argv_1, packageName_1, ...args_1) => __awaiter(v
             build = { ran: false, reason: 'errors found' };
         }
         else {
-            addLog(_jsx(SpinnerLog, { message: "building..." }));
+            if (!json)
+                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();
+        const report = toReport(diagnostics, build, argv.fix ? fixed : undefined);
+        if (json) {
+            restoreConsole === null || restoreConsole === void 0 ? void 0 : restoreConsole();
+            yield write(`${JSON.stringify(report)}\n`);
+        }
+        else {
+            clearLogs();
+            logReport(report);
+            if (report.passed && build.ran && build.passed)
+                yield sendPublishPrompt();
+        }
         yield terminate(report.passed ? EXIT.passed : EXIT.failed);
     }
     catch (error) {
         // Bad arguments and crashes alike mean validate could not run
-        clearLogs();
-        addLog(_jsx(ErrorLog, { message: errorMessage(error) }));
+        if (json) {
+            restoreConsole === null || restoreConsole === void 0 ? void 0 : restoreConsole();
+            process.stderr.write(`Error: ${errorMessage(error)}\n`);
+        }
+        else {
+            clearLogs();
+            addLog(_jsx(ErrorLog, { message: errorMessage(error) }));
+        }
         yield terminate(EXIT.crashed);
     }
 });

package/bin/validate/engine.js

@@ -7,7 +7,11 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-import { checkFiles } from './files.js';
+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';
@@ -64,37 +68,94 @@ const merge = (diagnostics, source, extra, key) => {
     }
 };
 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');
-    const diagnostics = yield checkFiles(site, fileRules);
+const fileRulesOf = (rules) => rules.filter((rule) => rule.scope === 'file');
+const runSiteRules = (site, rules, needsBuild, diagnostics) => __awaiter(void 0, void 0, void 0, function* () {
     for (const rule of rules) {
-        if (rule.scope !== 'site' || rule.needsBuild)
+        if (rule.scope !== 'site' || Boolean(rule.needsBuild) !== needsBuild)
             continue;
         for (const finding of yield rule.check(site))
             diagnostics.push(toDiagnostic(rule, finding));
     }
+});
+/** Runs every selected rule that doesn't need the build. */
+export const runChecks = (site, rules) => __awaiter(void 0, void 0, void 0, function* () {
+    const diagnostics = yield checkFiles(site, fileRulesOf(rules));
+    yield runSiteRules(site, rules, false, diagnostics);
     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));
-    }
+    yield 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);
 });
-/** Loads the site and runs the selected rules. */
+const parseLevel = (file, content, baseDir) => {
+    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 = (site, diagnostics) => __awaiter(void 0, void 0, void 0, function* () {
+    var _a;
+    const contents = new Map();
+    const read = (file) => __awaiter(void 0, void 0, void 0, function* () {
+        var _a;
+        if (!contents.has(file)) {
+            contents.set(file, yield fs.readFile(path.join(site.baseDir, file), 'utf-8'));
+        }
+        return (_a = contents.get(file)) !== null && _a !== void 0 ? _a : '';
+    });
+    const chosen = new Map();
+    const overlaps = ({ file, start, end }) => { var _a; return ((_a = chosen.get(file)) !== null && _a !== void 0 ? _a : []).some(({ fix }) => start < fix.end && fix.start < end); };
+    for (const { rule, fix } of diagnostics) {
+        if (!fix || overlaps(fix))
+            continue;
+        const content = yield read(fix.file);
+        const change = Object.assign(Object.assign({ rule, file: fix.file }, toPosition(content, fix.start)), { before: content.slice(fix.start, fix.end), after: fix.text });
+        chosen.set(fix.file, [...((_a = chosen.get(fix.file)) !== null && _a !== void 0 ? _a : []), { fix, change }]);
+    }
+    const snippets = new Set(site.files.filter(({ kind }) => kind === 'snippet').map(({ file }) => file));
+    const level = (file, content) => parseLevel(file, snippets.has(file) ? replaceVariables(content, site.variables) : content, site.baseDir);
+    const applied = [];
+    for (const [file, picks] of chosen) {
+        const content = yield read(file);
+        const updated = applyEdits(content, selectEdits(picks.map(({ fix }) => fix)));
+        if (/\.mdx?$/.test(file) && level(file, updated) < level(file, content)) {
+            continue;
+        }
+        yield 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 = (baseDir, rules, options) => __awaiter(void 0, void 0, void 0, function* () {
+    const fixed = [];
     const site = yield 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 = yield runChecks(site, rules);
-    return { site, diagnostics };
+    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 = yield applyFixes(site, pending);
+        if (changes.length === 0)
+            break;
+        fixed.push(...changes);
+        const changed = new Set(changes.map(({ file }) => file));
+        pending = sortDiagnostics(yield checkFiles(Object.assign(Object.assign({}, site), { selected: changed }), fileRulesOf(rules)));
+    }
+    if (fixed.length === 0)
+        return { site, diagnostics, fixed };
+    const fixedSite = yield loadSite(baseDir, options);
+    return { site: fixedSite, diagnostics: yield runChecks(fixedSite, rules), fixed };
 });

package/bin/validate/files.js

@@ -74,7 +74,7 @@ const tryParseContent = (content) => {
         return undefined;
     }
 };
-const parseFile = (file, content, baseDir) => {
+export const parseFile = (file, content, baseDir) => {
     const context = { file, content, baseDir, frontmatter: readFrontmatter(content) };
     const tree = tryParseContent(content);
     if (tree)

package/bin/validate/output.js

@@ -1,6 +1,10 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { addLog, ErrorLog, InfoLog, SuccessLog } from '@mintlify/previewing';
 import { Box, Text } from 'ink';
+const preview = (value) => {
+    const text = JSON.stringify(value);
+    return text.length > 60 ? `${text.slice(0, 57)}..."` : text;
+};
 const location = ({ line, column }) => line ? `${line}${column ? `:${column}` : ''}` : '';
 const DiagnosticLine = ({ diagnostic }) => {
     const at = location(diagnostic);
@@ -8,14 +12,21 @@ const DiagnosticLine = ({ diagnostic }) => {
 };
 const plural = (count, word) => `${count} ${word}${count === 1 ? '' : 's'}`;
 export const logReport = (report) => {
-    var _a, _b;
+    var _a, _b, _c;
+    for (const change of (_a = report.fixed) !== null && _a !== void 0 ? _a : []) {
+        addLog(_jsx(SuccessLog, { message: `fixed ${change.file}${change.line ? `:${change.line}` : ''} ${change.rule}: ${preview(change.before)} → ${preview(change.after)}` }));
+    }
     const byFile = new Map();
     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]);
+        (_c = (_b = byFile.get(diagnostic.file)) === null || _b === void 0 ? void 0 : _b.push(diagnostic)) !== null && _c !== void 0 ? _c : 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 fixable = report.diagnostics.filter(({ fix }) => fix).length;
+    if (fixable > 0 && !report.fixed) {
+        addLog(_jsx(InfoLog, { message: `\`--fix\` would fix ${plural(fixable, 'issue')}.` }));
+    }
     const { build } = report;
     if (build.ran && build.passed)
         addLog(_jsx(SuccessLog, { message: "build passed" }));

package/bin/validate/report.js

@@ -1,16 +1,11 @@
-export const toReport = (diagnostics, build) => {
+export const toReport = (diagnostics, build, fixed) => {
     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,
+    return Object.assign({ 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,
-    };
+            file }, (line !== undefined && { line })), (column !== undefined && { column })), { message }), (fix && { fix })))), build }, (fixed && { fixed }));
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mintlify/cli",
-  "version": "4.0.1740",
+  "version": "4.0.1742",
   "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.1537",
+    "@mintlify/link-rot": "3.0.1538",
     "@mintlify/models": "0.0.379",
     "@mintlify/og": "0.0.106",
     "@mintlify/prebuild": "1.0.1474",
-    "@mintlify/previewing": "4.0.1555",
+    "@mintlify/previewing": "4.0.1556",
     "@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": "17769e5210e7861c4b9c751f8b0cbf5e7bdd3143"
+  "gitHead": "d186b90eab824aece48724f71d3b71f2cdebdbe2"
 }

package/src/cli.tsx

@@ -401,6 +401,18 @@ export const cli = ({ packageName = 'mint' }: { packageName?: string }) => {
               description:
                 'Turn off rules or groups (comma-separated), or all; parse errors are still reported',
             })
+            .option('fix', {
+              type: 'boolean',
+              default: false,
+              description: 'Apply the fixes and check again',
+            })
+            .option('format', {
+              type: 'string',
+              choices: ['text', 'json'] as const,
+              default: 'text' as const,
+              description:
+                'Output format; json prints one report ({ passed, summary, diagnostics, build }) and nothing else on stdout, and errors to stderr',
+            })
             .usage('usage: mint validate [options]')
             .epilogue(
               [
@@ -410,7 +422,14 @@ export const cli = ({ packageName = 'mint' }: { packageName?: string }) => {
               ].join('\n')
             )
             .example('mint validate', 'run every check and the build')
-            .example('mint validate --files "guides/**/*.mdx"', 'check some pages')
+            .example(
+              'mint validate --no-build --format json',
+              'fast offline check for scripts and agents'
+            )
+            .example(
+              'mint validate --files "guides/**/*.mdx" --fix',
+              'check some pages and apply fixes'
+            )
             .example(
               'mint validate --disable all --enable content',
               'run the content rules only; missing-file and import-error still run the build'

package/src/validate/command.tsx

@@ -1,5 +1,6 @@
 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';
@@ -16,6 +17,8 @@ export type ValidateArgs = {
   build: boolean;
   enable?: string[];
   disable?: string[];
+  fix: boolean;
+  format: 'text' | 'json';
 };
 
 export const EXIT = { passed: 0, failed: 1, crashed: 2 } as const;
@@ -28,6 +31,29 @@ export const splitList = (values: string[]) =>
       .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;
@@ -45,17 +71,20 @@ export const validateHandler = async (
   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);
-    addLog(<SpinnerLog message="validating..." />);
+    if (!json) addLog(<SpinnerLog message="validating..." />);
 
-    const { site, ...checked } = await checkSite(baseDir, rules, {
+    const { site, fixed, ...checked } = await checkSite(baseDir, rules, {
       selected,
       localSchema: argv['local-schema'],
+      fix: argv.fix,
     });
     let { diagnostics } = checked;
 
@@ -68,7 +97,7 @@ export const validateHandler = async (
     } else if (diagnostics.some(({ severity }) => severity === 'error')) {
       build = { ran: false, reason: 'errors found' };
     } else {
-      addLog(<SpinnerLog message="building..." />);
+      if (!json) addLog(<SpinnerLog message="building..." />);
       const { cli: cliVersion } = getVersions(packageName);
       site.build = await checkBuild({
         ...argv,
@@ -82,15 +111,25 @@ export const validateHandler = async (
       build = { ran: true, passed: site.build.passed };
     }
 
-    const report = toReport(diagnostics, build);
-    clearLogs();
-    logReport(report);
-    if (report.passed && build.ran && build.passed) await sendPublishPrompt();
+    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
-    clearLogs();
-    addLog(<ErrorLog message={errorMessage(error)} />);
+    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,12 +1,19 @@
-import { checkFiles } from './files.js';
+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,
@@ -87,35 +94,103 @@ const addParseErrors = (site: Site, diagnostics: Diagnostic[], extra: Finding[])
     ({ 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');
-  const diagnostics = await checkFiles(site, fileRules);
+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' || rule.needsBuild) continue;
+    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[]) => {
-  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));
-  }
+  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);
 };
 
-/** Loads the site and runs the selected rules. */
+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 contents = new Map<string, string>();
+  const read = async (file: string) => {
+    if (!contents.has(file)) {
+      contents.set(file, await fs.readFile(path.join(site.baseDir, file), 'utf-8'));
+    }
+    return contents.get(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 = await 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 = await 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 }
+  options: { selected?: ReadonlySet<string>; localSchema: boolean; fix: boolean }
 ) => {
+  const fixed: Change[] = [];
   const site = await loadSite(baseDir, options);
   const { selected } = options;
   if (selected && !site.files.some(({ file }) => selected.has(file))) {
@@ -124,5 +199,18 @@ export const checkSite = async (
     );
   }
   const diagnostics = await runChecks(site, rules);
-  return { site, diagnostics };
+  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);
+    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 };
+  const fixedSite = await loadSite(baseDir, options);
+  return { site: fixedSite, diagnostics: await runChecks(fixedSite, rules), fixed };
 };

package/src/validate/files.ts

@@ -99,7 +99,7 @@ const tryParseContent = (content: string): Root | undefined => {
   }
 };
 
-const parseFile = (file: string, content: string, baseDir: string): Parsed => {
+export const parseFile = (file: string, content: string, baseDir: string): Parsed => {
   const context = { file, content, baseDir, frontmatter: readFrontmatter(content) };
   const tree = tryParseContent(content);
   if (tree) return { context: { ...context, tree }, approximate: false };