@mintlify/cli 4.0.1740 → 4.0.1741

package/bin/validate/command.js

@@ -52,7 +52,8 @@ export const validateHandler = (argv_1, packageName_1, ...args_1) => __awaiter(v
         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;
@@ -73,7 +74,7 @@ export const validateHandler = (argv_1, packageName_1, ...args_1) => __awaiter(v
             diagnostics = yield runBuildChecks(site, rules, diagnostics);
             build = { ran: true, passed: site.build.passed };
         }
-        const report = toReport(diagnostics, build);
+        const report = toReport(diagnostics, build, argv.fix ? fixed : undefined);
         clearLogs();
         logReport(report);
         if (report.passed && build.ran && build.passed)

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.1741",
   "description": "The Mintlify CLI",
   "engines": {
     "node": ">=18.0.0"
@@ -101,5 +101,5 @@
     "vitest": "2.1.9",
     "vitest-mock-process": "1.0.4"
   },
-  "gitHead": "17769e5210e7861c4b9c751f8b0cbf5e7bdd3143"
+  "gitHead": "4e0cdb6a51f1b140f02f0579f9e4c32592220434"
 }

package/src/cli.tsx

@@ -401,6 +401,11 @@ 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',
+            })
             .usage('usage: mint validate [options]')
             .epilogue(
               [
@@ -410,7 +415,10 @@ 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 --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

@@ -16,6 +16,7 @@ export type ValidateArgs = {
   build: boolean;
   enable?: string[];
   disable?: string[];
+  fix: boolean;
 };
 
 export const EXIT = { passed: 0, failed: 1, crashed: 2 } as const;
@@ -53,9 +54,10 @@ export const validateHandler = async (
     const selected = await resolveSelection(baseDir, argv.files);
     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;
 
@@ -82,7 +84,7 @@ export const validateHandler = async (
       build = { ran: true, passed: site.build.passed };
     }
 
-    const report = toReport(diagnostics, build);
+    const report = toReport(diagnostics, build, argv.fix ? fixed : undefined);
     clearLogs();
     logReport(report);
     if (report.passed && build.ran && build.passed) await sendPublishPrompt();

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 };

package/src/validate/output.tsx

@@ -4,6 +4,11 @@ import { Box, Text } from 'ink';
 import type { Report } from './report.js';
 import type { Diagnostic } from './types.js';
 
+const preview = (value: string) => {
+  const text = JSON.stringify(value);
+  return text.length > 60 ? `${text.slice(0, 57)}..."` : text;
+};
+
 const location = ({ line, column }: Pick<Diagnostic, 'line' | 'column'>) =>
   line ? `${line}${column ? `:${column}` : ''}` : '';
 
@@ -27,6 +32,14 @@ const DiagnosticLine = ({ diagnostic }: { diagnostic: Diagnostic }) => {
 const plural = (count: number, word: string) => `${count} ${word}${count === 1 ? '' : 's'}`;
 
 export const logReport = (report: Report) => {
+  for (const change of report.fixed ?? []) {
+    addLog(
+      <SuccessLog
+        message={`fixed ${change.file}${change.line ? `:${change.line}` : ''} ${change.rule}: ${preview(change.before)} → ${preview(change.after)}`}
+      />
+    );
+  }
+
   const byFile = new Map<string, Diagnostic[]>();
   for (const diagnostic of report.diagnostics) {
     byFile.get(diagnostic.file)?.push(diagnostic) ?? byFile.set(diagnostic.file, [diagnostic]);
@@ -42,6 +55,11 @@ export const logReport = (report: Report) => {
     );
   }
 
+  const fixable = report.diagnostics.filter(({ fix }) => fix).length;
+  if (fixable > 0 && !report.fixed) {
+    addLog(<InfoLog message={`\`--fix\` would fix ${plural(fixable, 'issue')}.`} />);
+  }
+
   const { build } = report;
   if (build.ran && build.passed) addLog(<SuccessLog message="build passed" />);
   else if (build.ran && report.passed)

package/src/validate/report.ts

@@ -1,4 +1,4 @@
-import type { Diagnostic } from './types.js';
+import type { Change, Diagnostic } from './types.js';
 
 export type BuildStatus =
   | { ran: true; passed: boolean }
@@ -9,9 +9,15 @@ export type Report = {
   summary: { errors: number; warnings: number; byRule: Record<string, number> };
   diagnostics: Diagnostic[];
   build: BuildStatus;
+  /** With --fix: the edits that were applied. */
+  fixed?: Change[];
 };
 
-export const toReport = (diagnostics: Diagnostic[], build: BuildStatus): Report => {
+export const toReport = (
+  diagnostics: Diagnostic[],
+  build: BuildStatus,
+  fixed?: Change[]
+): 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;
@@ -29,5 +35,6 @@ export const toReport = (diagnostics: Diagnostic[], build: BuildStatus): Report
       ...(fix && { fix }),
     })),
     build,
+    ...(fixed && { fixed }),
   };
 };

package/src/validate/types.ts

@@ -11,6 +11,16 @@ export type Edit = { start: number; end: number; text: string };
 
 export type FileEdit = Edit & { file: string };
 
+/** A fix --fix applied: where it was and the text it replaced. */
+export type Change = {
+  rule: string;
+  file: string;
+  line?: number;
+  column?: number;
+  before: string;
+  after: string;
+};
+
 export type Diagnostic = {
   rule: string;
   group: Group;