@mintlify/cli 4.0.1740 → 4.0.1742

package/__test__/validateCommand.test.ts

@@ -4,7 +4,7 @@ import path from 'node:path';
 import { mockProcessExit } from 'vitest-mock-process';
 
 import { sendPublishPrompt } from '../src/signup.js';
-import { toReport } from '../src/validate/report.js';
+import type { Report } from '../src/validate/report.js';
 import { runCommand } from './utils.js';
 
 const { dir } = vi.hoisted(() => ({
@@ -26,11 +26,6 @@ vi.mock('@mintlify/previewing', async (importOriginal) => {
   return { ...mod, addLog: vi.fn(), checkBuild: vi.fn() };
 });
 
-vi.mock('../src/validate/report.js', async (importOriginal) => {
-  const mod = await importOriginal<typeof import('../src/validate/report.js')>();
-  return { ...mod, toReport: vi.fn(mod.toReport) };
-});
-
 const processExitMock = mockProcessExit();
 
 const HOME = '---\ntitle: Home\n---\n\nBody\n';
@@ -49,14 +44,35 @@ const writeSite = (files: Record<string, string>, config: Record<string, unknown
   }
 };
 
+const runJson = async (...args: string[]) => {
+  const write = vi.spyOn(process.stdout, 'write').mockImplementation((...params: unknown[]) => {
+    params.find((param): param is () => void => typeof param === 'function')?.();
+    return true;
+  });
+  try {
+    await runCommand(...args, '--format', 'json');
+    return write.mock.calls.map(([chunk]) => String(chunk));
+  } finally {
+    write.mockRestore();
+  }
+};
+
 const report = async (...args: string[]) => {
-  await runCommand(...args);
-  const result = vi.mocked(toReport).mock.results.at(-1);
-  expect(result?.type).toBe('return');
-  return result?.value as ReturnType<typeof toReport>;
+  const chunks = await runJson(...args);
+  expect(chunks).toHaveLength(1);
+  return JSON.parse(chunks[0] ?? '') as Report;
 };
 
-const logged = () => JSON.stringify(vi.mocked(addLog).mock.calls);
+/** Runs in json mode expecting a failure: nothing on stdout, the error on stderr. */
+const jsonError = async (...args: string[]) => {
+  const stderr = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+  try {
+    expect(await runJson(...args)).toEqual([]);
+    return stderr.mock.calls.map(([chunk]) => String(chunk)).join('');
+  } finally {
+    stderr.mockRestore();
+  }
+};
 
 const rules = (result: { diagnostics: { rule: string }[] }) =>
   result.diagnostics.map(({ rule }) => rule);
@@ -71,7 +87,28 @@ describe('mint validate', () => {
     fs.removeSync(dir);
   });
 
-  it('builds one report with a summary and every diagnostic', async () => {
+  it('exits only after stdout has flushed the JSON report', async () => {
+    writeSite({ 'index.mdx': HOME });
+    let flush: (() => void) | undefined;
+    const write = vi.spyOn(process.stdout, 'write').mockImplementation((...params: unknown[]) => {
+      flush = params.find((param): param is () => void => typeof param === 'function');
+      return true;
+    });
+    try {
+      const run = runCommand('validate', '--no-build', '--format', 'json');
+      await vi.waitFor(() => expect(write).toHaveBeenCalled());
+      await new Promise((resolve) => setTimeout(resolve, 100));
+      expect(processExitMock).not.toHaveBeenCalled();
+
+      flush?.();
+      await run;
+      expect(processExitMock).toHaveBeenCalledWith(0);
+    } finally {
+      write.mockRestore();
+    }
+  });
+
+  it('prints one JSON report with a summary and every diagnostic', async () => {
     writeSite({
       'index.mdx': '---\ntitle: Home\n---\n\nline<br>\n',
       'other.mdx': '---\ntitle: Other\n---\n\nText {broken\n',
@@ -100,6 +137,7 @@ describe('mint validate', () => {
       ],
       build: { ran: false, reason: 'disabled' },
     });
+    expect(addLog).not.toHaveBeenCalled();
     expect(processExitMock).toHaveBeenCalledWith(1);
   });
 
@@ -111,7 +149,7 @@ describe('mint validate', () => {
     expect(result).toMatchObject({ passed: true, build: { ran: true, passed: true } });
     expect(rules(result)).toEqual([]);
     expect(checkBuild).toHaveBeenCalled();
-    expect(sendPublishPrompt).toHaveBeenCalled();
+    expect(sendPublishPrompt).not.toHaveBeenCalled();
     expect(processExitMock).toHaveBeenCalledWith(0);
   });
 
@@ -208,7 +246,6 @@ describe('mint validate', () => {
 
     expect(result).toMatchObject({ passed: true, build: { ran: true, passed: false } });
     expect(rules(result)).toEqual([]);
-    expect(sendPublishPrompt).not.toHaveBeenCalled();
     expect(processExitMock).toHaveBeenCalledWith(0);
   });
 
@@ -307,7 +344,7 @@ describe('mint validate', () => {
 
     const result = await report('validate');
 
-    expect(result.diagnostics.map(({ file }) => file)).toEqual([
+    expect(result.diagnostics.map(({ file }: { file: string }) => file)).toEqual([
       'index.mdx',
       'index.mdx',
       'index.mdx',
@@ -360,12 +397,46 @@ describe('mint validate', () => {
     writeSite({ 'index.mdx': HOME });
     vi.mocked(checkBuild).mockRejectedValue(new Error('requires an internet connection'));
 
-    await runCommand('validate');
-
-    expect(logged()).toContain('requires an internet connection');
+    expect(await jsonError('validate')).toBe('Error: requires an internet connection\n');
     expect(processExitMock).toHaveBeenCalledWith(2);
   });
 
+  it('keeps console output during the build off stdout in json mode', async () => {
+    writeSite({ 'index.mdx': HOME });
+    vi.mocked(checkBuild).mockImplementation(async () => {
+      console.log('progress line');
+      return { passed: true, warnings: [] };
+    });
+    const stderr = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+
+    const result = await report('validate');
+
+    const errors = stderr.mock.calls.map(([chunk]) => String(chunk));
+    stderr.mockRestore();
+    expect(result.passed).toBe(true);
+    expect(errors).toContain('progress line\n');
+  });
+
+  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',
@@ -389,13 +460,14 @@ describe('mint validate', () => {
   it('rejects unknown rules and disabling parse-error', async () => {
     writeSite({ 'index.mdx': HOME });
 
-    await runCommand('validate', '--disable', 'nope');
-    expect(logged()).toContain('unknown rule or group');
+    expect(await jsonError('validate', '--disable', 'nope')).toContain(
+      'Error: unknown rule or group "nope"'
+    );
     expect(processExitMock).toHaveBeenLastCalledWith(2);
 
-    await runCommand('validate', '--disable', 'parse-error');
-    expect(logged()).toContain("parse-error always runs and can't be disabled");
-    expect(processExitMock).toHaveBeenLastCalledWith(2);
+    expect(await jsonError('validate', '--disable', 'parse-error')).toBe(
+      "Error: parse-error always runs and can't be disabled\n"
+    );
   });
 
   it('limits page findings to --files', async () => {
@@ -473,9 +545,9 @@ describe('mint validate', () => {
   it('rejects --files that match nothing', async () => {
     writeSite({ 'index.mdx': HOME });
 
-    await runCommand('validate', '--files', 'missing.mdx');
-
-    expect(logged()).toContain('No matching files');
+    expect(await jsonError('validate', '--files', 'missing.mdx')).toContain(
+      'Error: No matching files'
+    );
     expect(processExitMock).toHaveBeenCalledWith(2);
     expect(checkBuild).not.toHaveBeenCalled();
   });
@@ -495,10 +567,37 @@ describe('mint validate', () => {
 
     await runCommand('validate', '--no-build');
 
-    const text = logged();
+    const text = JSON.stringify(vi.mocked(addLog).mock.calls);
     expect(text).toContain('index.mdx');
     expect(text).toContain('must be self-closed');
     expect(text).toContain('1 error');
     expect(processExitMock).toHaveBeenCalledWith(1);
   });
+
+  it('prompts to publish in text mode only when the build passed', async () => {
+    writeSite({ 'index.mdx': HOME });
+
+    await runCommand('validate');
+    expect(sendPublishPrompt).toHaveBeenCalledTimes(1);
+
+    vi.mocked(checkBuild).mockResolvedValue({
+      passed: false,
+      error: 'Build validation failed with 1 warning(s). See above for details.',
+      strict: true,
+      warnings: [{ type: 'missing-nav-page', message: '"gone" is missing.' }],
+    });
+    await runCommand('validate', '--disable', 'missing-nav-page');
+    expect(sendPublishPrompt).toHaveBeenCalledTimes(1);
+    expect(processExitMock).toHaveBeenLastCalledWith(0);
+  });
+
+  it('rejects --format values other than text and json', async () => {
+    writeSite({ 'index.mdx': HOME });
+    const error = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+
+    await expect(runCommand('validate', '--format', 'table')).rejects.toThrow();
+
+    expect(error).toHaveBeenCalledWith(expect.stringContaining('Invalid values'));
+    error.mockRestore();
+  });
 });

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',
     ]);
   });
 });