@mintlify/cli 4.0.1740 → 4.0.1741

package/__test__/validateCommand.test.ts

@@ -366,6 +366,26 @@ describe('mint validate', () => {
     expect(processExitMock).toHaveBeenCalledWith(2);
   });
 
+  it('applies fixes with --fix and lists them', async () => {
+    writeSite({ 'index.mdx': '---\ntitle: Home\n---\n\nline<br>\n' });
+
+    const result = await report('validate', '--no-build', '--fix');
+
+    expect(fs.readFileSync(path.join(dir, 'index.mdx'), 'utf-8')).toContain('line<br />');
+    expect(result.fixed).toEqual([
+      {
+        rule: 'void-tags',
+        file: 'index.mdx',
+        line: 5,
+        column: 5,
+        before: '<br>',
+        after: '<br />',
+      },
+    ]);
+    expect(rules(result)).toEqual([]);
+    expect(processExitMock).toHaveBeenCalledWith(0);
+  });
+
   it('turns rules and groups on and off', async () => {
     writeSite({
       'index.mdx': '---\ntitle: Home\n---\n\nline<br>\n',

package/__test__/validateEngine.test.ts

@@ -1,6 +1,17 @@
-import { selectRules, UsageError } from '../src/validate/engine.js';
+import fs from 'fs-extra';
+import fsp from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { applyFixes, checkSite, selectRules, UsageError } from '../src/validate/engine.js';
 import { RULES } from '../src/validate/rules/index.js';
-import { GROUPS } from '../src/validate/types.js';
+import {
+  GROUPS,
+  type Diagnostic,
+  type FileRule,
+  type Site,
+  type SiteRule,
+} from '../src/validate/types.js';
 
 const ids = (rules: { id: string }[]) => rules.map(({ id }) => id);
 
@@ -44,3 +55,176 @@ describe('selectRules', () => {
     expect(new Set(ids(RULES)).size).toBe(RULES.length);
   });
 });
+
+describe('applyFixes', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'validate-engine-'));
+  });
+
+  afterEach(() => {
+    fs.removeSync(dir);
+  });
+
+  const site = () => ({ baseDir: dir, files: [] }) as unknown as Site;
+
+  const diagnostic = (fix: Diagnostic['fix'], rule = 'r'): Diagnostic => ({
+    rule,
+    group: 'content',
+    severity: 'error',
+    file: 'a.mdx',
+    message: 'm',
+    fix,
+  });
+
+  it('applies fixes across files, skipping ones that overlap an applied fix', async () => {
+    fs.writeFileSync(path.join(dir, 'a.mdx'), 'one two three');
+    fs.writeFileSync(path.join(dir, 'b.json'), '{}');
+
+    const changes = await applyFixes(site(), [
+      diagnostic({ file: 'a.mdx', start: 0, end: 3, text: '1' }),
+      diagnostic({ file: 'a.mdx', start: 8, end: 13, text: '3' }),
+      diagnostic({ file: 'b.json', start: 1, end: 1, text: '"k":1' }),
+      // Overlaps the first fix, so it waits for the next pass
+      diagnostic({ file: 'a.mdx', start: 2, end: 5, text: 'x' }),
+    ]);
+
+    expect(fs.readFileSync(path.join(dir, 'a.mdx'), 'utf-8')).toBe('1 two 3');
+    expect(fs.readFileSync(path.join(dir, 'b.json'), 'utf-8')).toBe('{"k":1}');
+    expect(changes.map(({ file, before, after }) => [file, before, after])).toEqual([
+      ['a.mdx', 'one', '1'],
+      ['a.mdx', 'three', '3'],
+      ['b.json', '', '"k":1'],
+    ]);
+  });
+
+  it('applies two insertions at the same point', async () => {
+    fs.writeFileSync(path.join(dir, 'b.json'), '{}');
+
+    const changes = await applyFixes(site(), [
+      diagnostic({ file: 'b.json', start: 1, end: 1, text: ',"j":2' }),
+      diagnostic({ file: 'b.json', start: 1, end: 1, text: '"k":1' }),
+    ]);
+
+    expect(fs.readFileSync(path.join(dir, 'b.json'), 'utf-8')).toBe('{"k":1,"j":2}');
+    expect(changes).toHaveLength(2);
+  });
+
+  it('applies a replacement and an insertion at its start', async () => {
+    fs.writeFileSync(path.join(dir, 'a.mdx'), 'a<br>b');
+
+    const changes = await applyFixes(site(), [
+      diagnostic({ file: 'a.mdx', start: 1, end: 5, text: '<br />' }),
+      diagnostic({ file: 'a.mdx', start: 1, end: 1, text: 'x' }),
+    ]);
+
+    expect(fs.readFileSync(path.join(dir, 'a.mdx'), 'utf-8')).toBe('ax<br />b');
+    expect(changes.map(({ after }) => after)).toEqual(['<br />', 'x']);
+  });
+
+  it('skips writing a Markdown file whose fixed content no longer parses', async () => {
+    fs.writeFileSync(path.join(dir, 'a.mdx'), 'hello world\n');
+    fs.writeFileSync(path.join(dir, 'b.mdx'), 'line<br>\n');
+
+    const changes = await applyFixes(site(), [
+      diagnostic({ file: 'a.mdx', start: 0, end: 5, text: '<Note>' }),
+      diagnostic({ file: 'b.mdx', start: 4, end: 8, text: '<br />' }),
+    ]);
+
+    expect(fs.readFileSync(path.join(dir, 'a.mdx'), 'utf-8')).toBe('hello world\n');
+    expect(fs.readFileSync(path.join(dir, 'b.mdx'), 'utf-8')).toBe('line<br />\n');
+    expect(changes.map(({ file, after }) => [file, after])).toEqual([['b.mdx', '<br />']]);
+  });
+
+  it('fixes a page that only parses after the build preprocesses its <MDX> fragments', async () => {
+    const fragment = '{true ? <MDX>\n```bash\n<root>/{arch}/app.vpkg\n```\n</MDX> : null}\n';
+    fs.writeFileSync(path.join(dir, 'a.mdx'), `${fragment}\nline<br>\n`);
+    const start = fragment.length + 5;
+
+    const changes = await applyFixes(site(), [
+      diagnostic({ file: 'a.mdx', start, end: start + 4, text: '<br />' }),
+    ]);
+
+    expect(fs.readFileSync(path.join(dir, 'a.mdx'), 'utf-8')).toBe(`${fragment}\nline<br />\n`);
+    expect(changes).toHaveLength(1);
+  });
+
+  it('fixes an unparseable page even when another error keeps it unparseable', async () => {
+    fs.writeFileSync(path.join(dir, 'a.mdx'), 'line<br>\n');
+    fs.writeFileSync(path.join(dir, 'b.mdx'), 'line<br>\n\nText {broken\n');
+
+    const changes = await applyFixes(site(), [
+      diagnostic({ file: 'a.mdx', start: 4, end: 8, text: '<br />' }),
+      diagnostic({ file: 'b.mdx', start: 4, end: 8, text: '<br />' }),
+    ]);
+
+    expect(fs.readFileSync(path.join(dir, 'a.mdx'), 'utf-8')).toBe('line<br />\n');
+    expect(fs.readFileSync(path.join(dir, 'b.mdx'), 'utf-8')).toBe('line<br />\n\nText {broken\n');
+    expect(changes).toHaveLength(2);
+  });
+});
+
+describe('checkSite with fix', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'validate-fix-passes-'));
+    fs.writeJSONSync(path.join(dir, 'docs.json'), {
+      name: 'Test',
+      navigation: { pages: ['index', 'other'] },
+    });
+    fs.writeFileSync(path.join(dir, 'index.mdx'), '---\ntitle: Home\n---\n\nText\n');
+    fs.writeFileSync(path.join(dir, 'other.mdx'), '---\ntitle: Other\n---\n\nText!!!\n');
+  });
+
+  afterEach(() => {
+    fs.removeSync(dir);
+  });
+
+  /** Offers one "!" at a time until a page ends with `limit` of them, so each pass unlocks the next. */
+  const bang = (limit: number): FileRule => ({
+    id: 'bang',
+    group: 'content',
+    severity: 'warning',
+    scope: 'file',
+    raw: true,
+    description: 'test rule',
+    check: ({ content }) => {
+      const end = content.trimEnd().length;
+      return content.endsWith(`${'!'.repeat(limit)}\n`)
+        ? []
+        : [{ message: 'needs a bang', edit: { start: end, end, text: '!' } }];
+    },
+  });
+
+  const siteRule = (): SiteRule => ({
+    id: 'site',
+    group: 'config',
+    severity: 'warning',
+    scope: 'site',
+    description: 'test rule',
+    check: vi.fn(() => []),
+  });
+
+  it('rechecks only changed files between passes and runs site rules once more at the end', async () => {
+    const site = siteRule();
+    const reads = vi.spyOn(fsp, 'readFile');
+
+    const result = await checkSite(dir, [bang(3), site], { localSchema: false, fix: true });
+
+    const otherReads = reads.mock.calls.filter(([file]) => String(file).endsWith('other.mdx'));
+    reads.mockRestore();
+    expect(result.fixed.map(({ file }) => file)).toEqual(['index.mdx', 'index.mdx', 'index.mdx']);
+    expect(fs.readFileSync(path.join(dir, 'index.mdx'), 'utf-8')).toContain('Text!!!\n');
+    expect(result.diagnostics).toEqual([]);
+    expect(site.check).toHaveBeenCalledTimes(2);
+    expect(otherReads).toHaveLength(2);
+  });
+
+  it('applies up to five passes of fixes', async () => {
+    const result = await checkSite(dir, [bang(10)], { localSchema: false, fix: true });
+
+    expect(result.fixed.filter(({ file }) => file === 'index.mdx')).toHaveLength(5);
+  });
+});

package/__test__/validateRules.test.ts

@@ -20,11 +20,15 @@ const hasErrors = (diagnostics: Diagnostic[]) =>
   diagnostics.some(({ severity }) => severity === 'error');
 
 /** Runs the file rules (all defaults, or exactly `rules`) the way mint validate --no-build does. */
-const check = async (dir: string, { rules, files }: { rules?: string[]; files?: string[] }) => {
+const check = async (
+  dir: string,
+  { rules, fix = false, files }: { rules?: string[]; fix?: boolean; files?: string[] }
+) => {
   const selected = selectRules({ disable: ['all'], enable: rules ?? ['content'] });
   const result = await checkSite(dir, selected, {
     selected: files && new Set(files),
     localSchema: false,
+    fix,
   });
   const issues = result.diagnostics.map((diagnostic) => ({
     ...diagnostic,
@@ -32,6 +36,8 @@ const check = async (dir: string, { rules, files }: { rules?: string[]; files?:
   }));
   return {
     issues,
+    fixed: result.fixed,
+    filesFixed: [...new Set(result.fixed.map(({ file }) => file))].sort(),
     filesChecked: result.site.files.filter(({ file }) => !files || files.includes(file)).length,
   };
 };
@@ -59,26 +65,23 @@ describe('validate rules', () => {
 
   const read = (file: string) => fs.readFileSync(path.join(dir, file), 'utf-8');
 
-  /** The edit each diagnostic carries, as the text it would replace and its replacement. */
-  const previews = (issues: Diagnostic[]) =>
-    issues.map(
-      ({ file, fix }) => fix && { before: read(file).slice(fix.start, fix.end), after: fix.text }
-    );
-
-  it('flags lowercase void tags with edits, skipping code and components', async () => {
+  it('self-closes lowercase void tags, skipping code and components', async () => {
     write(dir, {
       'index.mdx':
         '---\ntitle: Home\n---\n\nline<br>\n\n<hr>\n\n<img src="/a.png" alt="a">\n\n<Link>x</Link>\n\n`<br>`\n\n```html\n<br>\n```\n',
     });
 
-    const result = await check(dir, {});
+    const plain = await check(dir, {});
+    expect(plain.issues.map(({ rule }) => rule)).toEqual(['void-tags', 'void-tags', 'void-tags']);
 
-    expect(result.issues.map(({ rule }) => rule)).toEqual(['void-tags', 'void-tags', 'void-tags']);
-    expect(previews(result.issues)).toEqual([
-      { before: '<br>', after: '<br />' },
-      { before: '<hr>', after: '<hr />' },
-      { before: '<img src="/a.png" alt="a">', after: '<img src="/a.png" alt="a" />' },
-    ]);
+    const fixed = await check(dir, { fix: true });
+    expect(fixed.issues).toEqual([]);
+    const content = read('index.mdx');
+    expect(content).toContain('line<br />');
+    expect(content).toContain('<hr />');
+    expect(content).toContain('<img src="/a.png" alt="a" />');
+    expect(content).toContain('`<br>`');
+    expect(content).toContain('```html\n<br>\n```');
   });
 
   it('skips void tags inside block-quoted code fences', async () => {
@@ -87,16 +90,13 @@ describe('validate rules', () => {
       'other.mdx': '---\ntitle: Other\n---\n\n> ```\n> <br>\n\nafter<br>\n',
     });
 
-    const result = await check(dir, {});
+    const result = await check(dir, { fix: true });
 
-    expect(result.issues.map(({ file, line }) => [file, line])).toEqual([
-      ['index.mdx', 9],
-      ['other.mdx', 8],
-    ]);
-    expect(previews(result.issues)).toEqual([
-      { before: '<br>', after: '<br />' },
-      { before: '<br>', after: '<br />' },
-    ]);
+    expect(result.fixed.map(({ before }) => before).sort()).toEqual(['<br>', '<br>']);
+    expect(read('index.mdx')).toContain('> <br>\n');
+    expect(read('index.mdx')).toContain('line<br />');
+    expect(read('other.mdx')).toContain('> <br>\n');
+    expect(read('other.mdx')).toContain('after<br />');
   });
 
   it('keeps an info-string fence line from closing an open fence', async () => {
@@ -105,10 +105,12 @@ describe('validate rules', () => {
         '---\ntitle: Home\n---\n\n```bash\n$ one\n\nStep 2\n\n```bash\n$ two <br>\n```\n\nafter<br>\n',
     });
 
-    const result = await check(dir, {});
+    const result = await check(dir, { fix: true });
 
-    expect(result.issues.map(({ line }) => line)).toEqual([14]);
-    expect(previews(result.issues)).toEqual([{ before: '<br>', after: '<br />' }]);
+    expect(result.fixed.map(({ before }) => before)).toEqual(['<br>']);
+    const content = read('index.mdx');
+    expect(content).toContain('$ two <br>\n');
+    expect(content).toContain('after<br />');
   });
 
   it('does not close a block-quoted fence with an info-string fence line', async () => {
@@ -117,10 +119,12 @@ describe('validate rules', () => {
         '---\ntitle: Home\n---\n\n> ```\n> <br>\n> ```bash\n> <hr>\n> ```\n\nafter<br>\n',
     });
 
-    const result = await check(dir, {});
+    const result = await check(dir, { fix: true });
 
-    expect(result.issues.map(({ line }) => line)).toEqual([11]);
-    expect(previews(result.issues)).toEqual([{ before: '<br>', after: '<br />' }]);
+    expect(result.fixed.map(({ before }) => before)).toEqual(['<br>']);
+    const content = read('index.mdx');
+    expect(content).toContain('> <hr>\n');
+    expect(content).toContain('after<br />');
   });
 
   it('skips custom elements, frontmatter, ESM and attribute strings for void tags', async () => {
@@ -130,11 +134,15 @@ describe('validate rules', () => {
     });
 
     const { issues } = await check(dir, { rules: ['void-tags'] });
-
     expect(issues.map(({ line }) => line)).toEqual([12]);
-    expect(previews(issues)).toEqual([
-      { before: '<img src="/a.png" alt="<hr>">', after: '<img src="/a.png" alt="<hr>" />' },
-    ]);
+
+    await check(dir, { rules: ['void-tags'], fix: true });
+    const content = read('index.mdx');
+    expect(content).toContain('<img src="/a.png" alt="<hr>" />');
+    expect(content).toContain('title: "a<br>b"');
+    expect(content).toContain('export const html = "<br>";');
+    expect(content).toContain('<Card title="one<br>two">');
+    expect(content).toContain('`` a`<br>`b ``');
   });
 
   it('leaves escaped void tags alone', async () => {
@@ -159,7 +167,9 @@ describe('validate rules', () => {
     expect(issues.map(({ rule, line, column }) => [rule, line, column])).toEqual([
       ['void-tags', 1, 23],
     ]);
-    expect(previews(issues)).toEqual([{ before: '<br>', after: '<br />' }]);
+
+    await check(dir, { fix: true });
+    expect(read('snippets/note.mdx')).toBe('Hello {{foo.bar}} line<br />\n');
   });
 
   it('leaves void tags that already have a closing tag', async () => {
@@ -167,6 +177,8 @@ describe('validate rules', () => {
     write(dir, { 'index.mdx': page });
 
     expect((await check(dir, { rules: ['void-tags'] })).issues).toEqual([]);
+    await check(dir, { rules: ['void-tags'], fix: true });
+    expect(read('index.mdx')).toBe(page);
   });
 
   it('accepts <MDX> fragments the build preprocesses', async () => {
@@ -222,15 +234,17 @@ describe('validate rules', () => {
     });
 
     const { issues } = await check(dir, { rules: ['void-tags'] });
-
     expect(issues.map(({ rule, line }) => [rule, line])).toEqual([
       ['void-tags', 7],
       ['void-tags', 11],
     ]);
-    expect(previews(issues)).toEqual([
-      { before: '<br>', after: '<br />' },
-      { before: '<br>', after: '<br />' },
-    ]);
+
+    await check(dir, { rules: ['void-tags'], fix: true });
+    const content = read('index.mdx');
+    expect(content).toContain("s.replace(/<br>/g, '')");
+    expect(content).toContain("replace(/\\/<hr>/, '')");
+    expect(content).toContain('and<br />');
+    expect(content).toContain('line<br />');
   });
 
   it('masks line comments inside expressions', async () => {
@@ -262,11 +276,11 @@ describe('validate rules', () => {
     );
     write(dir, Object.fromEntries(names.map((name) => [name, '---\ntitle: T\n---\n\nline<br>\n'])));
 
-    const result = await check(dir, { rules: ['void-tags'] });
+    const plain = await check(dir, { rules: ['void-tags'] });
+    expect(plain.issues.map(({ file }) => file)).toEqual(names);
 
-    const flagged = result.issues.map(({ file }) => file);
-    expect(flagged).toEqual([...flagged].sort());
-    expect(flagged).toHaveLength(40);
+    const fixed = await check(dir, { rules: ['void-tags'], fix: true });
+    expect(fixed.fixed.map(({ file }) => file)).toEqual(names);
   });
 
   it('rejects unknown rule ids', async () => {
@@ -368,8 +382,9 @@ describe('validate rules', () => {
 
     const { issues } = await check(dir, { rules: ['void-tags'] });
 
-    expect(issues.map(({ line }) => line)).toEqual([7]);
-    expect(previews(issues)).toEqual([{ before: '<br>', after: '<br />' }]);
+    expect(issues.map(({ line, message }) => [line, message])).toEqual([
+      [7, '<br> must be self-closed'],
+    ]);
   });
 
   it('does not pair backticks across table cells', async () => {
@@ -403,9 +418,9 @@ describe('validate rules', () => {
 
     const { issues } = await check(dir, { rules: ['void-tags'] });
 
-    expect(previews(issues)).toEqual([
-      { before: '<br>', after: '<br />' },
-      { before: '<hr>', after: '<hr />' },
+    expect(issues.map(({ message }) => message)).toEqual([
+      '<br> must be self-closed',
+      '<hr> must be self-closed',
     ]);
   });
 });

package/bin/cli.js

@@ -328,6 +328,11 @@ export const cli = ({ packageName = 'mint' }) => {
         array: true,
         coerce: splitList,
         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([
@@ -336,7 +341,7 @@ export const cli = ({ packageName = 'mint' }) => {
         `  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 --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')
         .strict(), (argv) => validateHandler(argv, packageName))
         .command('export', 'Export a static site for air-gapped deployment', (yargs) => yargs