@mintlify/cli 4.0.1743 → 4.0.1745

package/__test__/foreignSyntax.test.ts

@@ -0,0 +1,73 @@
+import { foreignSyntax } from '../src/validate/rules/content/foreignSyntax.js';
+
+const check = (content: string) =>
+  foreignSyntax.check({
+    file: 'page.mdx',
+    content,
+    baseDir: '/',
+    frontmatter: {},
+    tree: { type: 'root', children: [] },
+  });
+
+const messages = (content: string) => check(content).map(({ message }) => message);
+
+describe('foreign-syntax', () => {
+  it.each([
+    ['GitBook hint', '{% hint style="warning" %}\nCareful\n{% endhint %}\n', '<Warning>'],
+    ['Liquid tag', '{% include note.html %}\n', 'snippet import'],
+    ['Hugo shortcode', '{{< figure src="a.png" >}}\n', 'Hugo shortcode'],
+    ['Liquid variable', 'Version {{ site.version }}\n', 'Liquid variable'],
+    ['Liquid filter', '[Home]({{ "/" | relative_url }})\n', 'Liquid variable'],
+    ['Docusaurus admonition', ':::tip\nUse it\n:::\n', '<Tip>'],
+    ['VitePress admonition with title', '::: warning Heads up\nx\n:::\n', '<Warning>'],
+    ['MDC block', '::note\nx\n::\n', 'MDC'],
+    ['MkDocs admonition', '!!! note "Title"\n    Body\n', '<Note>'],
+    ['MkDocs collapsible', '??? info\n    Body\n', '<Accordion>'],
+    ['MkDocs tab', '=== "Python"\n    code\n', '<Tabs>'],
+    ['MkDocs snippet in a fence', '```py\n--8<-- "example.py"\n```\n', 'snippet include'],
+    ['Kramdown IAL', 'Text\n{: .note }\n', 'Kramdown'],
+    ['wiki link', 'See [[Getting Started]].\n', 'wiki link'],
+    ['wiki link with label', 'See [[setup|Install]].\n', 'wiki link'],
+    ['ReadMe doc link', 'See [setup](doc:setup).\n', 'such as /setup'],
+    ['ReadMe ref link in href', '<a href="ref:create-user">x</a>\n', 'such as /create-user'],
+    [
+      'Docusaurus @site import',
+      "import Img from '@site/static/img/a.png';\n\n<img src={Img} />\n",
+      '@site',
+    ],
+  ])('flags %s', (_name, content, expected) => {
+    const found = messages(content);
+    expect(found).toHaveLength(1);
+    expect(found[0]).toContain(expected);
+  });
+
+  it('flags each opening GitBook tag once, not its closing tag', () => {
+    expect(messages('{% tabs %}\n{% tab title="A" %}\nx\n{% endtab %}\n{% endtabs %}\n')).toEqual([
+      expect.stringContaining('use <Tabs>'),
+      expect.stringContaining('use <Tab title="…">'),
+    ]);
+  });
+
+  it.each([
+    ['fenced code', '```liquid\n{% hint style="info" %}\n{{ site.title }}\n:::note\n```\n'],
+    ['inline code', 'Write `{% hint %}`, `:::note` and `[[Page]]` like this.\n'],
+    ['frontmatter', '---\ntitle: "{% hint %}"\ndescription: "[[Page]]"\n---\n\nBody\n'],
+    ['MDX expressions', 'Total: {a | b} and {{ x: 1 }.x} and {[[1, 2]].length} and {{page}}\n'],
+    ['closing tags and bare fences', ':::\n\n::\n'],
+    ['Markdown link after a bracket', '[[1]](#note-1) and [a][ref]\n'],
+    ['ordinary prose', 'Use doc: the guide. Wow!!! Equal === sign.\n'],
+    ['custom heading ids', '## Install {#install}\n'],
+  ])('ignores %s', (_name, content) => {
+    expect(messages(content)).toEqual([]);
+  });
+
+  it('reports positions in the original file', () => {
+    expect(check('---\ntitle: A\n---\n\nText\n  :::note\nx\n:::\n')).toEqual([
+      expect.objectContaining({ line: 6, column: 3 }),
+    ]);
+  });
+
+  it('never offers edits', () => {
+    expect(check('{% hint %}\n').every(({ edit }) => edit === undefined)).toBe(true);
+  });
+});

package/__test__/validateCommand.test.ts

@@ -109,30 +109,27 @@ describe('mint validate', () => {
   });
 
   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',
-    });
+    writeSite({ 'index.mdx': '---\ntitle: Home\n---\n\n# Home\n\nline<br>\n' });
 
     const result = await report('validate', '--no-build');
 
     expect(result).toEqual({
       passed: false,
-      summary: { errors: 2, warnings: 0, byRule: { 'parse-error': 1, 'void-tags': 1 } },
+      summary: { errors: 1, warnings: 1, byRule: { 'duplicate-h1': 1, 'void-tags': 1 } },
       diagnostics: [
         expect.objectContaining({
-          rule: 'void-tags',
+          rule: 'duplicate-h1',
           group: 'content',
-          severity: 'error',
+          severity: 'warning',
           file: 'index.mdx',
           line: 5,
-          fix: { file: 'index.mdx', start: 25, end: 29, text: '<br />' },
+          fix: { file: 'index.mdx', start: 21, end: 29, text: '' },
         }),
         expect.objectContaining({
-          rule: 'parse-error',
+          rule: 'void-tags',
           severity: 'error',
-          file: 'other.mdx',
-          message: expect.stringContaining('(other checks were skipped for this file)'),
+          line: 7,
+          fix: { file: 'index.mdx', start: 33, end: 37, text: '<br />' },
         }),
       ],
       build: { ran: false, reason: 'disabled' },
@@ -141,13 +138,13 @@ describe('mint validate', () => {
     expect(processExitMock).toHaveBeenCalledWith(1);
   });
 
-  it('passes and runs the build', async () => {
-    writeSite({ 'index.mdx': HOME });
+  it('passes with warnings and runs the build', async () => {
+    writeSite({ 'index.mdx': '---\ntitle: Home\n---\n\n# Home\n' });
 
     const result = await report('validate');
 
     expect(result).toMatchObject({ passed: true, build: { ran: true, passed: true } });
-    expect(rules(result)).toEqual([]);
+    expect(rules(result)).toEqual(['duplicate-h1']);
     expect(checkBuild).toHaveBeenCalled();
     expect(sendPublishPrompt).not.toHaveBeenCalled();
     expect(processExitMock).toHaveBeenCalledWith(0);
@@ -301,6 +298,53 @@ describe('mint validate', () => {
     ]);
   });
 
+  it('prefers structured warning fields over the message text', async () => {
+    writeSite(
+      { 'index.mdx': HOME, 'guides/real.mdx': HOME },
+      { navigation: { pages: ['index', 'guides/real', 'gone'] } }
+    );
+    vi.mocked(checkBuild).mockResolvedValue({
+      passed: false,
+      error: 'Build validation failed with 2 warning(s). See above for details.',
+      strict: true,
+      warnings: [
+        {
+          type: 'parse-error',
+          message: '\u001b[31m./wrong.mdx:9:9 Unexpected token\u001b[39m',
+          file: 'guides/real.mdx',
+          line: 3,
+          column: 7,
+        },
+        {
+          type: 'missing-nav-page',
+          message: '"gone" is referenced in the docs.json navigation but the file does not exist.',
+          file: 'docs.json',
+          ref: 'gone',
+        },
+      ],
+    });
+
+    const result = await report('validate');
+
+    expect(result.diagnostics).toHaveLength(2);
+    expect(result.diagnostics).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          rule: 'parse-error',
+          file: 'guides/real.mdx',
+          line: 3,
+          column: 7,
+          message: './wrong.mdx:9:9 Unexpected token',
+        }),
+        expect.objectContaining({
+          rule: 'missing-nav-page',
+          file: 'docs.json',
+          line: expect.any(Number),
+        }),
+      ])
+    );
+  });
+
   it('fails when the build fails on a parse error outside --files', async () => {
     writeSite({ 'index.mdx': HOME, 'other.mdx': HOME });
     vi.mocked(checkBuild).mockResolvedValue({
@@ -417,8 +461,8 @@ describe('mint validate', () => {
     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' });
+  it('applies fixes with --fix, lists them and leaves unfixable issues', async () => {
+    writeSite({ 'index.mdx': '---\ntitle: Home\n---\n\nline<br>\n\n<Missing />\n' });
 
     const result = await report('validate', '--no-build', '--fix');
 
@@ -433,13 +477,13 @@ describe('mint validate', () => {
         after: '<br />',
       },
     ]);
-    expect(rules(result)).toEqual([]);
+    expect(rules(result)).toEqual(['unknown-component']);
     expect(processExitMock).toHaveBeenCalledWith(0);
   });
 
   it('turns rules and groups on and off', async () => {
     writeSite({
-      'index.mdx': '---\ntitle: Home\n---\n\nline<br>\n',
+      'index.mdx': '---\ntitle: Home\n---\n\n# Home\n\nline<br>\n',
     });
 
     // Without void-tags, nothing makes the page parseable
@@ -453,7 +497,7 @@ describe('mint validate', () => {
       rules(await report('validate', '--no-build', '--disable', 'all', '--enable', 'void-tags'))
     ).toEqual(['void-tags']);
     expect(
-      rules(await report('validate', '--no-build', '--disable', 'openapi, missing-nav-page'))
+      rules(await report('validate', '--no-build', '--disable', 'openapi, duplicate-h1'))
     ).toEqual(['void-tags']);
   });
 
@@ -474,7 +518,7 @@ describe('mint validate', () => {
     writeSite(
       {
         'index.mdx': '---\ntitle: Home\n---\n\nline<br>\n',
-        'other.mdx': '---\ntitle: Other\n---\n\nline<br>\n\nmore<hr>\n',
+        'other.mdx': '---\ntitle: Other\n---\n\n# Other\n\nline<br>\n',
       },
       { navigation: { pages: ['index', 'other'] } }
     );

package/__test__/validateEngine.test.ts

@@ -1,5 +1,5 @@
 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';
 
@@ -24,7 +24,15 @@ describe('selectRules', () => {
   it('turns on the rules of an enabled group', () => {
     const content = ids(selectRules({ disable: ['all'], enable: ['content'] }));
 
-    expect(content).toEqual(['void-tags', 'missing-file', 'import-error']);
+    expect(content).toEqual([
+      'void-tags',
+      'duplicate-h1',
+      'unknown-component',
+      'katex',
+      'foreign-syntax',
+      'missing-file',
+      'import-error',
+    ]);
   });
 
   it('applies --enable after --disable', () => {
@@ -67,7 +75,12 @@ describe('applyFixes', () => {
     fs.removeSync(dir);
   });
 
-  const site = () => ({ baseDir: dir, files: [] }) as unknown as Site;
+  const site = () =>
+    ({
+      baseDir: dir,
+      files: [],
+      read: (file: string) => fs.readFileSync(path.join(dir, file), 'utf-8'),
+    }) as unknown as Site;
 
   const diagnostic = (fix: Diagnostic['fix'], rule = 'r'): Diagnostic => ({
     rule,
@@ -209,7 +222,7 @@ describe('checkSite with fix', () => {
 
   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 reads = vi.spyOn(fsSync, 'readFileSync');
 
     const result = await checkSite(dir, [bang(3), site], { localSchema: false, fix: true });