@mintlify/cli 4.0.1743 → 4.0.1744

package/__test__/validateRules.test.ts

@@ -1,6 +1,6 @@
 import { getAST } from '@mintlify/common';
 import fs from 'fs-extra';
-import fsp from 'node:fs/promises';
+import fsSync from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
@@ -84,6 +84,128 @@ describe('validate rules', () => {
     expect(content).toContain('```html\n<br>\n```');
   });
 
+  it('removes a first heading that matches the title, except in custom mode', async () => {
+    write(dir, {
+      'index.mdx': '---\ntitle: Hello  World\n---\n\n# Hello World\n\nBody\n',
+      'custom.mdx': '---\ntitle: Hello\nmode: custom\n---\n\n# Hello\n',
+      'other.mdx': '---\ntitle: Hello\n---\n\n# Different\n',
+    });
+
+    const result = await check(dir, { fix: true });
+
+    expect(result.filesFixed).toEqual(['index.mdx']);
+    expect(read('index.mdx')).toBe('---\ntitle: Hello  World\n---\n\nBody\n');
+    expect(read('custom.mdx')).toContain('# Hello');
+  });
+
+  it('adds an import for a snippet and reports components it cannot find', async () => {
+    write(dir, {
+      'snippets/Widget.jsx': 'export const Widget = () => <div />;\n',
+      'index.mdx':
+        '---\ntitle: Home\n---\n\n<Widget />\n\n<Missing />\n\n<Card title="x">ok</Card>\n',
+    });
+
+    const result = await check(dir, { fix: true });
+
+    expect(read('index.mdx')).toContain('import { Widget } from "/snippets/Widget.jsx";');
+    expect(result.issues.map(({ message }) => message)).toEqual([
+      expect.stringContaining('<Missing>'),
+    ]);
+  });
+
+  it('adds an import for a tsx snippet', async () => {
+    write(dir, {
+      'snippets/Widget.tsx': 'export const Widget = ({ label }: { label: string }) => <div />;\n',
+      'index.mdx': '---\ntitle: Home\n---\n\n<Widget />\n',
+    });
+
+    const result = await check(dir, { rules: ['unknown-component'], fix: true });
+
+    expect(read('index.mdx')).toContain('import { Widget } from "/snippets/Widget.tsx";');
+    expect(result.issues).toEqual([]);
+  });
+
+  it.each([
+    ['export { Widget } from "/snippets/impl.jsx";'],
+    ['import { Widget } from "/snippets/impl.jsx";\nexport { Widget };'],
+  ])('imports a re-exported component by name: %s', async (reexport) => {
+    write(dir, {
+      'snippets/impl.jsx': 'export const Widget = () => <div />;\n',
+      'snippets/Widget.jsx': `${reexport}\nexport default function Other() { return null; }\n`,
+      'index.mdx': '---\ntitle: Home\n---\n\n<Widget />\n',
+    });
+
+    await check(dir, { rules: ['unknown-component'], fix: true });
+
+    expect(read('index.mdx')).toContain('import { Widget } from "/snippets/Widget.jsx";');
+  });
+
+  it('adds every missing snippet import in one run', async () => {
+    const names = ['One', 'Two', 'Three', 'Four', 'Five'];
+    write(dir, {
+      ...Object.fromEntries(
+        names.map((name) => [`snippets/${name}.jsx`, `export const ${name} = () => <div />;\n`])
+      ),
+      'index.mdx': `---\ntitle: Home\n---\n\n${names.map((name) => `<${name} />`).join('\n\n')}\n`,
+    });
+
+    const result = await check(dir, { fix: true });
+
+    expect(result.issues).toEqual([]);
+    for (const name of names) {
+      expect(read('index.mdx')).toContain(`import { ${name} } from "/snippets/${name}.jsx";`);
+    }
+  });
+
+  it('imports a component exported only as the default through a specifier', async () => {
+    write(dir, {
+      'snippets/Widget.jsx': 'const Widget = () => <div />;\nexport { Widget as default };\n',
+      'snippets/Other.jsx': 'const Hidden = () => <div />;\nexport { Hidden };\n',
+      'index.mdx': '---\ntitle: Home\n---\n\n<Widget />\n\n<Other />\n',
+    });
+
+    const result = await check(dir, { rules: ['unknown-component'], fix: true });
+
+    const content = read('index.mdx');
+    expect(content).toContain('import Widget from "/snippets/Widget.jsx";');
+    expect(content).not.toContain('Other.jsx');
+    expect(result.issues).toEqual([
+      expect.objectContaining({ message: expect.stringContaining('<Other>'), fixable: false }),
+    ]);
+  });
+
+  it('treats names bound by destructuring exports as declared', async () => {
+    write(dir, {
+      'snippets/Widget.jsx': 'export const Widget = () => <div />;\n',
+      'snippets/Panel.jsx': 'export const Panel = () => <div />;\n',
+      'index.mdx':
+        '---\ntitle: Home\n---\n\nexport const { Widget, inner: { Panel = null }, ...Rest } = {};\nexport const [Gallery] = [];\n\n<Widget />\n\n<Panel />\n\n<Rest />\n\n<Gallery />\n',
+    });
+
+    expect((await check(dir, { rules: ['unknown-component'] })).issues).toEqual([]);
+  });
+
+  it('uses the default export when the name is only exported under an alias', async () => {
+    write(dir, {
+      'snippets/Widget.jsx':
+        'const Widget = () => <div />;\nexport { Widget as Renamed };\nexport default Widget;\n',
+      'index.mdx': '---\ntitle: Home\n---\n\n<Widget />\n',
+    });
+
+    await check(dir, { fix: true });
+
+    expect(read('index.mdx')).toContain('import Widget from "/snippets/Widget.jsx";');
+  });
+
+  it('treats a named default export as declared', async () => {
+    write(dir, {
+      'index.mdx':
+        '---\ntitle: Home\n---\n\nexport default function Hero() {\n  return <div />;\n}\n\n<Hero />\n',
+    });
+
+    expect((await check(dir, {})).issues).toEqual([]);
+  });
+
   it('skips void tags inside block-quoted code fences', async () => {
     write(dir, {
       'index.mdx': '---\ntitle: Home\n---\n\n> ~~~html\n> <br>\n> ~~~\n\nline<br>\n',
@@ -99,6 +221,120 @@ describe('validate rules', () => {
     expect(read('other.mdx')).toContain('after<br />');
   });
 
+  it('keeps a duplicate heading that reference-style links point to', async () => {
+    write(dir, {
+      'index.mdx': '---\ntitle: Quickstart\n---\n\n# Quickstart\n\nBody\n',
+      'other.mdx': '---\ntitle: Other\n---\n\nSee [top][start].\n\n[start]: /index#quickstart\n',
+    });
+
+    const result = await check(dir, { fix: true });
+
+    expect(read('index.mdx')).toContain('# Quickstart');
+    expect(result.issues.map(({ message }) => message)).toEqual([
+      expect.stringContaining('links point to #quickstart'),
+    ]);
+  });
+
+  it.each([
+    ["The User's Settings", '"The User\'s Settings"', "the-user's-settings", 'the-users-settings'],
+    ["The User's Settings", '"The User\'s Settings"', 'the-user’s-settings', 'the-user’s-settings'],
+    [
+      "The User's Settings",
+      '"The User\'s Settings"',
+      'the-user%E2%80%99s-settings',
+      'the-user’s-settings',
+    ],
+    ['"Pending" Status', '\'"Pending" Status\'', 'pending-status', 'pending-status'],
+    ['"Pending" Status', '\'"Pending" Status\'', '“pending”-status', '“pending”-status'],
+  ])(
+    'keeps a duplicate heading with quotes that a link points to: %s, title %s, link #%s',
+    async (heading, title, link, anchor) => {
+      write(dir, {
+        'settings.mdx': `---\ntitle: ${title}\n---\n\n# ${heading}\n\nBody\n`,
+        'other.mdx': `---\ntitle: Other\n---\n\nSee [settings](/settings#${link}).\n`,
+      });
+
+      const result = await check(dir, { rules: ['duplicate-h1'], fix: true });
+
+      expect(read('settings.mdx')).toContain(`# ${heading}`);
+      expect(result.issues.map(({ message }) => message)).toEqual([
+        expect.stringContaining(`links point to #${anchor}`),
+      ]);
+    }
+  );
+
+  it('reads the heading text the way the table of contents does', async () => {
+    write(dir, { 'index.mdx': '---\ntitle: Install\n---\n\n# Install {/* draft */}\n\nBody\n' });
+
+    const { issues } = await check(dir, { rules: ['duplicate-h1'] });
+
+    expect(issues).toEqual([expect.objectContaining({ rule: 'duplicate-h1', fixable: true })]);
+  });
+
+  it('removes a duplicate heading with quotes that no link points to', async () => {
+    write(dir, {
+      'settings.mdx': '---\ntitle: "The User\'s Settings"\n---\n\n# The User\'s Settings\n\nBody\n',
+      'other.mdx': '---\ntitle: Other\n---\n\nSee [settings](/settings#other-heading).\n',
+    });
+
+    await check(dir, { rules: ['duplicate-h1'], fix: true });
+
+    expect(read('settings.mdx')).not.toContain("# The User's Settings");
+  });
+
+  it('reports and imports components used inside expressions', async () => {
+    write(dir, {
+      'snippets/Widget.jsx': 'export const Widget = () => <div />;\n',
+      'index.mdx':
+        '---\ntitle: Home\n---\n\n{open && <Widget />}\n\n{items.map((Item) => <Item />)}\n\nText {flag ? <Missing /> : null} and {Math.max(1, 2)}.\n',
+    });
+
+    const { issues } = await check(dir, { rules: ['unknown-component'] });
+    expect(
+      issues.map(({ line, column, message, fixable }) => [line, column, message, fixable])
+    ).toEqual([
+      [5, 10, '<Widget> is not built in, imported or exported on this page', true],
+      [9, 14, '<Missing> is not built in, imported or exported on this page', false],
+    ]);
+
+    await check(dir, { rules: ['unknown-component'], fix: true });
+    expect(read('index.mdx')).toContain('import { Widget } from "/snippets/Widget.jsx";');
+  });
+
+  it('reports components used inside attribute values', async () => {
+    write(dir, {
+      'index.mdx':
+        '---\ntitle: Home\n---\n\n<Card title="a" icon={<Glyph />}>x</Card>\n\n<Card {...{ icon: <Dot /> }}>y</Card>\n',
+    });
+
+    const { issues } = await check(dir, { rules: ['unknown-component'] });
+
+    expect(issues.map(({ line, column, message }) => [line, column, message])).toEqual([
+      [5, 23, '<Glyph> is not built in, imported or exported on this page'],
+      [7, 19, '<Dot> is not built in, imported or exported on this page'],
+    ]);
+  });
+
+  it('does not flag imported or exported components', async () => {
+    write(dir, {
+      'index.mdx':
+        '---\ntitle: Home\n---\n\nimport Thing from "/snippets/Thing.jsx";\nimport { A as B } from "/snippets/b.jsx";\n\nexport const Local = () => <p />;\n\n<Thing /><B /><Local /><Color.Row />\n',
+    });
+
+    expect((await check(dir, {})).issues).toEqual([]);
+  });
+
+  it('reports math KaTeX cannot render', async () => {
+    write(dir, {
+      'index.mdx': '---\ntitle: Home\n---\n\nGood $x^2$ bad $\\frac{1$\n',
+    });
+
+    const { issues } = await check(dir, {});
+
+    expect(issues.map(({ rule }) => rule)).toEqual(['katex']);
+    expect(issues[0]?.fixable).toBe(false);
+  });
+
   it('keeps an info-string fence line from closing an open fence', async () => {
     write(dir, {
       'index.mdx':
@@ -145,6 +381,174 @@ describe('validate rules', () => {
     expect(content).toContain('`` a`<br>`b ``');
   });
 
+  it('reports but does not remove a duplicate heading with a custom id', async () => {
+    write(dir, {
+      'index.mdx': '---\ntitle: Hello\n---\n\n# Hello {#intro}\n\nBody\n',
+    });
+
+    const result = await check(dir, { fix: true });
+
+    expect(result.filesFixed).toEqual([]);
+    expect(result.issues).toEqual([
+      expect.objectContaining({ rule: 'duplicate-h1', fixable: false }),
+    ]);
+    expect(read('index.mdx')).toContain('# Hello {#intro}');
+  });
+
+  it('only treats a top-level heading as the first heading', async () => {
+    write(dir, {
+      'index.mdx': '---\ntitle: Hello\n---\n\n<Tab title="a">\n\n# Hello\n\n</Tab>\n',
+      'imports.mdx':
+        '---\ntitle: Hello\n---\n\nimport { A } from "/snippets/a.jsx";\n\n# Hello\n\n<A />\n',
+    });
+
+    const result = await check(dir, { rules: ['duplicate-h1'], fix: true });
+
+    expect(result.filesFixed).toEqual(['imports.mdx']);
+    expect(read('index.mdx')).toContain('# Hello');
+    expect(read('imports.mdx')).not.toContain('# Hello');
+  });
+
+  it('reads imports from the ESM tree, including side-effect imports', async () => {
+    write(dir, {
+      'index.mdx':
+        '---\ntitle: Home\n---\n\nimport "./styles.css";\nimport Thing from "/snippets/Thing.jsx";\nimport * as Lib from "/snippets/lib.js";\nexport { Other } from "/snippets/other.jsx";\nexport function Fn() { return null; }\n\n<Thing /><Lib.X /><Other /><Fn />\n',
+    });
+
+    expect((await check(dir, { rules: ['unknown-component'] })).issues).toEqual([]);
+  });
+
+  it('leaves a blank line after an inserted import wherever it goes', async () => {
+    const widget = 'import { Widget } from "/snippets/Widget.jsx";';
+    write(dir, {
+      'snippets/Widget.jsx': 'export const Widget = () => <div />;\n',
+      'tight.mdx': '---\ntitle: Tight\n---\n<Widget />\n',
+      'top.mdx': '<Widget />\n',
+      'imports.mdx':
+        '---\ntitle: Imports\n---\nexport const A = () => null;\n\n<A />\n\n<Widget />\n',
+    });
+
+    const result = await check(dir, { rules: ['unknown-component'], fix: true });
+
+    expect(result.issues).toEqual([]);
+    expect(read('tight.mdx')).toBe(`---\ntitle: Tight\n---\n\n${widget}\n\n<Widget />\n`);
+    expect(read('top.mdx')).toBe(`${widget}\n\n<Widget />\n`);
+    expect(read('imports.mdx')).toBe(
+      `---\ntitle: Imports\n---\n\n${widget}\n\nexport const A = () => null;\n\n<A />\n\n<Widget />\n`
+    );
+  });
+
+  it('inserts snippet imports after TOML frontmatter', async () => {
+    write(dir, {
+      'snippets/Widget.jsx': 'export const Widget = () => <div />;\n',
+      'index.mdx': "+++\ntitle = 'Home'\n+++\n\n<Widget />\n",
+    });
+
+    await check(dir, { rules: ['unknown-component'], fix: true });
+
+    expect(read('index.mdx')).toBe(
+      '+++\ntitle = \'Home\'\n+++\n\nimport { Widget } from "/snippets/Widget.jsx";\n\n<Widget />\n'
+    );
+  });
+
+  it('prefers a named import when the snippet exports the component by name', async () => {
+    write(dir, {
+      'snippets/Named.jsx':
+        'export const Named = () => <div />;\nexport default function Other() { return null; }\n',
+      'snippets/Listed.jsx':
+        'const Listed = () => <div />;\nexport { Listed };\nexport default {};\n',
+      'snippets/Default.jsx': 'export default function Default() { return null; }\n',
+      'index.mdx': '---\ntitle: Home\n---\n\n<Named />\n\n<Listed />\n\n<Default />\n',
+    });
+
+    await check(dir, { rules: ['unknown-component'], fix: true });
+
+    const content = read('index.mdx');
+    expect(content).toContain('import { Named } from "/snippets/Named.jsx";');
+    expect(content).toContain('import { Listed } from "/snippets/Listed.jsx";');
+    expect(content).toContain('import Default from "/snippets/Default.jsx";');
+  });
+
+  it('skips price-like spans, which the site renders as text', async () => {
+    write(dir, {
+      'index.mdx': '---\ntitle: Home\n---\n\nPlans cost $5 & up, or $10 a seat.\n',
+    });
+
+    expect((await check(dir, {})).issues).toEqual([]);
+  });
+
+  it('tags each issue with its rule severity', async () => {
+    write(dir, {
+      'void.mdx': '---\ntitle: Void\n---\n\nline<br>\n',
+      'index.mdx':
+        '---\ntitle: Home\n---\n\n# Home\n\n<Missing />\n\nbad $\\frac{1$ and $5 and $10\n',
+    });
+
+    const { issues } = await check(dir, {
+      rules: ['void-tags', 'duplicate-h1', 'unknown-component', 'katex'],
+    });
+    const severities = Object.fromEntries(issues.map(({ rule, severity }) => [rule, severity]));
+
+    expect(severities).toEqual({
+      'void-tags': 'error',
+      'duplicate-h1': 'warning',
+      'unknown-component': 'warning',
+      katex: 'warning',
+    });
+    expect(hasErrors(issues)).toBe(true);
+    expect(hasErrors(issues.filter(({ severity }) => severity === 'warning'))).toBe(false);
+  });
+
+  it('previews the fixes --fix applies without writing, accounting for interacting fixes', async () => {
+    const page = '---\ntitle: Hello\n---\n\n# Hello\n\nline<br>\n\n<Missing />\n\nbad $\\frac{1$\n';
+    write(dir, { 'index.mdx': page });
+
+    const plain = await check(dir, {});
+    expect(read('index.mdx')).toBe(page);
+    expect(plain.fixed).toEqual([]);
+    expect(plain.filesFixed).toEqual([]);
+    const preview = plain.issues.map(({ rule, line, fixable, fix }) => ({
+      rule,
+      line,
+      fixable,
+      fix: fix && { before: page.slice(fix.start, fix.end), after: fix.text },
+    }));
+    expect(preview).toEqual([
+      {
+        rule: 'duplicate-h1',
+        line: 5,
+        fixable: true,
+        fix: { before: '# Hello\n\n', after: '' },
+      },
+      { rule: 'void-tags', line: 7, fixable: true, fix: { before: '<br>', after: '<br />' } },
+      { rule: 'unknown-component', line: 9, fixable: false, fix: undefined },
+      { rule: 'katex', line: 11, fixable: false, fix: undefined },
+    ]);
+
+    const fixed = await check(dir, { fix: true });
+    expect(
+      fixed.fixed.map(({ rule, line, before, after }) => ({ rule, line, before, after }))
+    ).toEqual(
+      preview.filter(({ fix }) => fix).map(({ rule, line, fix }) => ({ rule, line, ...fix }))
+    );
+    expect(fixed.issues.map(({ rule }) => rule)).toEqual(['unknown-component', 'katex']);
+    expect(read('index.mdx')).toBe(
+      '---\ntitle: Hello\n---\n\nline<br />\n\n<Missing />\n\nbad $\\frac{1$\n'
+    );
+  });
+
+  it('accepts every component the build keeps or rewrites', async () => {
+    write(dir, {
+      'snippets/part.mdx': 'Part\n',
+      'index.mdx':
+        '---\ntitle: Home\n---\n\n<Snippet file="part.mdx" />\n\n<Example>x</Example>\n\n<Param name="a">x</Param>\n\n<ApiPlayground />\n\n<MDXContentController />\n\n<Color>\n  <Color.Row title="a">\n    <Color.Item name="b" value="#fff" />\n  </Color.Row>\n</Color>\n\n<Tree>\n  <Tree.Folder name="a">\n    <Tree.File name="b" />\n  </Tree.Folder>\n</Tree>\n\n<Color.Nope />\n',
+    });
+
+    const { issues } = await check(dir, { rules: ['unknown-component'] });
+
+    expect(issues.map(({ message }) => message)).toEqual([expect.stringContaining('<Color.Nope>')]);
+  });
+
   it('leaves escaped void tags alone', async () => {
     write(dir, { 'index.mdx': '---\ntitle: Home\n---\n\nText \\<br> and \\<img src="/a.png">\n' });
 
@@ -181,6 +585,16 @@ describe('validate rules', () => {
     expect(read('index.mdx')).toBe(page);
   });
 
+  it('parses headings with a spaced custom id and keeps their fixes', async () => {
+    write(dir, {
+      'index.mdx': '---\ntitle: Hello\n---\n\n# Hello\n\n## Setup { #setup }\n\nBody\n',
+    });
+
+    const { issues } = await check(dir, {});
+
+    expect(issues).toEqual([expect.objectContaining({ rule: 'duplicate-h1', fixable: true })]);
+  });
+
   it('accepts <MDX> fragments the build preprocesses', async () => {
     write(dir, {
       'index.mdx':
@@ -194,12 +608,12 @@ describe('validate rules', () => {
     write(dir, {
       '.mintignore': 'drafts/\n',
       'openapi.yaml': 'openapi: [unclosed\n',
-      'drafts/wip.mdx': '---\ntitle: Wip\n---\n\nline<br>\n',
-      'SKILL.md': 'line<br>\n',
-      'index.mdx': '---\ntitle: Home\n---\n\nline<br>\n',
+      'drafts/wip.mdx': '---\ntitle: Wip\n---\n\n<Missing />\n',
+      'SKILL.md': '<Missing />\n',
+      'index.mdx': '---\ntitle: Home\n---\n\n<Missing />\n',
     });
 
-    const result = await check(dir, { rules: ['void-tags'] });
+    const result = await check(dir, { rules: ['unknown-component'] });
 
     expect(result.filesChecked).toBe(1);
     expect(result.issues.map(({ file }) => file)).toEqual(['index.mdx']);
@@ -269,6 +683,122 @@ describe('validate rules', () => {
     expect(issues.map(({ line }) => line)).toEqual([7, 11]);
   });
 
+  it('reports but does not remove a duplicate heading that other pages link to', async () => {
+    write(dir, {
+      'guides/start.mdx': '---\ntitle: Quickstart\n---\n\n# Quickstart\n\nBody\n',
+      'index.mdx': '---\ntitle: Home\n---\n\nSee [the start](/guides/start#quickstart).\n',
+      'guides/other.mdx': '---\ntitle: Other\n---\n\nUnrelated [link](./start#install).\n',
+      'plain.mdx': '---\ntitle: Plain\n---\n\n# Plain\n\nBody\n',
+    });
+
+    const result = await check(dir, { rules: ['duplicate-h1'], fix: true });
+
+    expect(result.filesFixed).toEqual(['plain.mdx']);
+    expect(read('guides/start.mdx')).toContain('# Quickstart');
+    expect(result.issues).toEqual([
+      expect.objectContaining({
+        file: 'guides/start.mdx',
+        fixable: false,
+        message: expect.stringContaining('#quickstart'),
+      }),
+    ]);
+  });
+
+  it('finds relative and same-page links to the heading anchor', async () => {
+    write(dir, {
+      'guides/start.mdx':
+        '---\ntitle: Quickstart\n---\n\n# Quickstart\n\nBack to [top](#quickstart).\n',
+      'guides/next.mdx': '---\ntitle: Next\n---\n\n# Next\n\n',
+      'guides/after.mdx': '---\ntitle: After\n---\n\nRead <a href="next#next">next</a>.\n',
+    });
+
+    const { issues } = await check(dir, { rules: ['duplicate-h1'] });
+
+    expect(issues.map(({ file, fixable }) => [file, fixable])).toEqual([
+      ['guides/next.mdx', false],
+      ['guides/start.mdx', false],
+    ]);
+  });
+
+  it('ignores heading links inside code', async () => {
+    write(dir, {
+      'guides/start.mdx': '---\ntitle: Quickstart\n---\n\n# Quickstart\n\nBody\n',
+      'index.mdx':
+        '---\ntitle: Home\n---\n\n```md\n[start](/guides/start#quickstart)\n```\n\nUse `<a href="/guides/start#quickstart">`.\n',
+    });
+
+    const result = await check(dir, { rules: ['duplicate-h1'], fix: true });
+
+    expect(result.filesFixed).toEqual(['guides/start.mdx']);
+  });
+
+  it('keeps a duplicate homepage heading that a root hash link points to', async () => {
+    write(dir, {
+      'index.mdx': '---\ntitle: Home\n---\n\n# Home\n\nBody\n',
+      'guides/start.mdx': '---\ntitle: Start\n---\n\nBack [home](/#home).\n',
+    });
+
+    const result = await check(dir, { rules: ['duplicate-h1'], fix: true });
+
+    expect(result.filesFixed).toEqual([]);
+    expect(read('index.mdx')).toContain('# Home');
+  });
+
+  it('finds heading links that carry a query string', async () => {
+    write(dir, {
+      'guides/start.mdx': '---\ntitle: Quickstart\n---\n\n# Quickstart\n\nBody\n',
+      'index.mdx': '---\ntitle: Home\n---\n\nSee [the start](/guides/start?tab=api#quickstart).\n',
+    });
+
+    const result = await check(dir, { rules: ['duplicate-h1'], fix: true });
+
+    expect(result.filesFixed).toEqual([]);
+    expect(read('guides/start.mdx')).toContain('# Quickstart');
+  });
+
+  it('keeps a duplicate heading when links point to a later heading that would take its id', async () => {
+    write(dir, {
+      'index.mdx': '---\ntitle: Setup\n---\n\n# Setup\n\n## Setup\n\nBody\n',
+      'other.mdx': '---\ntitle: Other\n---\n\nSee [the details](/index#setup-2).\n',
+    });
+
+    const result = await check(dir, { rules: ['duplicate-h1'], fix: true });
+
+    expect(result.filesFixed).toEqual([]);
+    expect(read('index.mdx')).toContain('# Setup\n');
+    expect(result.issues).toEqual([
+      expect.objectContaining({ fixable: false, message: expect.stringContaining('#setup-2') }),
+    ]);
+  });
+
+  it('finds anchor links in string-literal expression hrefs', async () => {
+    write(dir, {
+      'double.mdx': '---\ntitle: Double\n---\n\n# Double\n',
+      'template.mdx': '---\ntitle: Template\n---\n\n# Template\n',
+      'dynamic.mdx': '---\ntitle: Dynamic\n---\n\n# Dynamic\n',
+      'links.mdx':
+        '---\ntitle: Links\n---\n\n<a href={"/double#double"}>a</a>\n\n<a href={`/template#template`}>b</a>\n\n<a href={`/dynamic#${slug}`}>c</a>\n',
+    });
+
+    const result = await check(dir, { rules: ['duplicate-h1'], fix: true });
+
+    expect(result.filesFixed).toEqual(['dynamic.mdx']);
+    expect(read('double.mdx')).toContain('# Double');
+    expect(read('template.mdx')).toContain('# Template');
+  });
+
+  it('finds anchor links in hrefs with spaces around the equals sign', async () => {
+    write(dir, {
+      'guides/start.mdx': '---\ntitle: Quickstart\n---\n\n# Quickstart\n\nBody\n',
+      'index.mdx': '---\ntitle: Home\n---\n\n<a href = "/guides/start#quickstart">Start</a>\n',
+    });
+
+    const result = await check(dir, { rules: ['duplicate-h1'], fix: true });
+
+    expect(result.filesFixed).toEqual([]);
+    expect(read('guides/start.mdx')).toContain('# Quickstart');
+  });
+
   it('keeps file order when linting many files concurrently', async () => {
     const names = Array.from(
       { length: 40 },
@@ -319,10 +849,21 @@ describe('validate rules', () => {
     );
   });
 
-  it('lints snippets', async () => {
+  it('accepts pages the build parses, such as code inside <MDX>, without offering edits', async () => {
+    write(dir, {
+      'index.mdx': '---\ntitle: Home\n---\n\n<MDX>\nif (a < b) { run() }\n</MDX>\n\n<Missing />\n',
+    });
+
+    const result = await check(dir, {});
+
+    expect(result.issues.map(({ rule }) => rule)).toEqual(['unknown-component']);
+    expect(result.issues[0]?.fixable).toBe(false);
+  });
+
+  it('lints snippets, skipping page-only rules', async () => {
     write(dir, {
       'index.mdx': '---\ntitle: Home\n---\n\nok\n',
-      'snippets/note.mdx': '---\ntitle: Same\n---\n\nline<br>\n',
+      'snippets/note.mdx': '---\ntitle: Same\n---\n\n# Same\n\nline<br>\n\n<FromPage />\n',
     });
 
     const result = await check(dir, {});
@@ -332,6 +873,60 @@ describe('validate rules', () => {
     ]);
   });
 
+  it('orders findings on one line left to right across rules', async () => {
+    write(dir, {
+      'index.mdx': '---\ntitle: Home\n---\n\nSee <Missing /> and a line break here <br>\n',
+    });
+
+    const result = await check(dir, { rules: ['void-tags', 'unknown-component'] });
+
+    expect(result.issues.map(({ rule, line, column }) => [rule, line, column])).toEqual([
+      ['unknown-component', 5, 5],
+      ['void-tags', 5, 39],
+    ]);
+  });
+
+  it('names leftover GitBook syntax even when the page does not parse', async () => {
+    write(dir, {
+      'index.mdx': '---\ntitle: Home\n---\n\n{% hint style="info" %}\nRead this\n{% endhint %}\n',
+    });
+
+    const result = await check(dir, {});
+
+    expect(result.issues.map(({ rule, line }) => [rule, line])).toEqual([
+      ['foreign-syntax', 5],
+      ['parse-error', 5],
+    ]);
+    expect(result.issues[0]?.message).toContain('use <Info>');
+  });
+
+  it('skips foreign syntax inside JSX attribute and JavaScript strings', async () => {
+    write(dir, {
+      'index.mdx':
+        '---\ntitle: Home\n---\n\n<Card title="{{ site.title }}" href="doc:intro" />\n\n{"{{ page.title }}"}\n\n{{ site.name }}\n\n[Intro](doc:intro)\n',
+    });
+
+    const { issues } = await check(dir, { rules: ['foreign-syntax'] });
+    const found = issues.filter(({ rule }) => rule === 'foreign-syntax');
+
+    expect(found.map(({ line, message }) => [line, message.split(' ')[0]])).toEqual([
+      [5, 'doc:intro'],
+      [9, '{{'],
+      [11, 'doc:intro'],
+    ]);
+  });
+
+  it('reports foreign syntax the build accepts without failing lint', async () => {
+    write(dir, { 'index.mdx': '---\ntitle: Home\n---\n\n:::note\nRead this\n:::\n' });
+
+    const result = await check(dir, {});
+
+    expect(result.issues.map(({ rule, severity }) => [rule, severity])).toEqual([
+      ['foreign-syntax', 'warning'],
+    ]);
+    expect(hasErrors(result.issues)).toBe(false);
+  });
+
   it('rejects --files that name no page or snippet of the site', async () => {
     write(dir, { 'index.mdx': '---\ntitle: Home\n---\n\nok\n', 'README.md': '# Readme\n' });
 
@@ -355,7 +950,7 @@ describe('validate rules', () => {
       'index.mdx': '---\ntitle: Home\n---\n\nline<br>\n',
       'other.mdx': '---\ntitle: Other\n---\n\nline<br>\n',
     });
-    const spy = vi.spyOn(fsp, 'readFile');
+    const spy = vi.spyOn(fsSync, 'readFileSync');
 
     const result = await check(dir, { rules: ['void-tags'], files: ['other.mdx'] });
 
@@ -366,6 +961,62 @@ describe('validate rules', () => {
     expect(result.issues.map(({ file }) => file)).toEqual(['other.mdx']);
   });
 
+  it('does no anchor reads when duplicate-h1 is disabled', async () => {
+    write(dir, {
+      'index.mdx': '---\ntitle: Home\n---\n\n# Home\n',
+      'other.mdx': '---\ntitle: Other\n---\n\nSee [home](/index#home).\n',
+    });
+    const spy = vi.spyOn(fsSync, 'readFileSync');
+
+    const result = await checkSite(dir, selectRules({ disable: ['duplicate-h1'] }), {
+      selected: new Set(['index.mdx']),
+      localSchema: false,
+      fix: false,
+    });
+
+    const reads = spy.mock.calls.map(([file]) => String(file));
+    spy.mockRestore();
+    expect(reads.some((file) => file.endsWith('other.mdx'))).toBe(false);
+    expect(result.diagnostics.filter(({ rule }) => rule === 'duplicate-h1')).toEqual([]);
+  });
+
+  it('collects no anchor links when no page has a duplicate first heading', async () => {
+    write(dir, {
+      'index.mdx': '---\ntitle: Home\n---\n\n# Welcome\n',
+      'other.mdx': '---\ntitle: Other\n---\n\nSee [home](/index#welcome).\n',
+    });
+    const spy = vi.spyOn(fsSync, 'readFileSync');
+
+    const result = await check(dir, { rules: ['duplicate-h1'], files: ['index.mdx'] });
+
+    const reads = spy.mock.calls.map(([file]) => String(file));
+    spy.mockRestore();
+    expect(reads.some((file) => file.endsWith('other.mdx'))).toBe(false);
+    expect(result.issues).toEqual([]);
+  });
+
+  it('reads every file once when duplicate-h1 runs on a selection', async () => {
+    write(dir, {
+      'index.mdx': '---\ntitle: Home\n---\n\n# Home\n',
+      'other.mdx': '---\ntitle: Other\n---\n\nSee [home](/index#home).\n',
+    });
+    const spy = vi.spyOn(fsSync, 'readFileSync');
+
+    const result = await check(dir, { rules: ['duplicate-h1'], files: ['index.mdx'] });
+
+    const reads = spy.mock.calls.map(([file]) => String(file));
+    spy.mockRestore();
+    expect(reads.filter((file) => file.endsWith('other.mdx'))).toHaveLength(1);
+    expect(reads.filter((file) => file.endsWith('index.mdx'))).toHaveLength(1);
+    expect(result.issues).toEqual([
+      expect.objectContaining({
+        file: 'index.mdx',
+        fixable: false,
+        message: expect.stringContaining('#home'),
+      }),
+    ]);
+  });
+
   it('skips void tags in block-quoted fences and inline code', async () => {
     write(dir, {
       'index.mdx': '---\ntitle: Home\n---\n\n> Quote\n>\n> ```html\n> <br>\n> ```\n\nSee `<hr>`.\n',