@mintlify/cli 4.0.1739 → 4.0.1741

package/__test__/validateCommand.test.ts

@@ -1,8 +1,10 @@
-import { addLog, validateBuild } from '@mintlify/previewing';
+import { addLog, checkBuild } from '@mintlify/previewing';
 import fs from 'fs-extra';
 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 { runCommand } from './utils.js';
 
 const { dir } = vi.hoisted(() => ({
@@ -14,9 +16,19 @@ vi.mock('../src/helpers.js', async (importOriginal) => {
   return { ...mod, CMD_EXEC_PATH: dir, autoUpgradeIfNeeded: vi.fn() };
 });
 
+vi.mock('../src/signup.js', async (importOriginal) => {
+  const mod = await importOriginal<typeof import('../src/signup.js')>();
+  return { ...mod, sendPublishPrompt: vi.fn() };
+});
+
 vi.mock('@mintlify/previewing', async (importOriginal) => {
   const mod = await importOriginal<typeof import('@mintlify/previewing')>();
-  return { ...mod, addLog: vi.fn(), validateBuild: vi.fn() };
+  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();
@@ -37,80 +49,373 @@ const writeSite = (files: Record<string, string>, config: Record<string, unknown
   }
 };
 
+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 logged = () => JSON.stringify(vi.mocked(addLog).mock.calls);
 
+const rules = (result: { diagnostics: { rule: string }[] }) =>
+  result.diagnostics.map(({ rule }) => rule);
+
 describe('mint validate', () => {
   beforeEach(() => {
     vi.clearAllMocks();
-    vi.mocked(validateBuild).mockResolvedValue(undefined as never);
+    vi.mocked(checkBuild).mockResolvedValue({ passed: true, warnings: [] });
   });
 
   afterAll(() => {
     fs.removeSync(dir);
   });
 
-  it('logs lint findings by file and exits 1 before the build', async () => {
+  it('builds one 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',
     });
 
-    await runCommand('validate');
+    const result = await report('validate', '--no-build');
 
-    const text = logged();
-    expect(text).toContain('index.mdx');
-    expect(text).toContain('must be self-closed');
-    expect(text).toContain('other.mdx');
-    expect(text).toContain('other checks were skipped for this file');
-    expect(text).toContain('2 errors');
-    expect(validateBuild).not.toHaveBeenCalled();
+    expect(result).toEqual({
+      passed: false,
+      summary: { errors: 2, warnings: 0, byRule: { 'parse-error': 1, 'void-tags': 1 } },
+      diagnostics: [
+        expect.objectContaining({
+          rule: 'void-tags',
+          group: 'content',
+          severity: 'error',
+          file: 'index.mdx',
+          line: 5,
+          fix: { file: 'index.mdx', start: 25, end: 29, text: '<br />' },
+        }),
+        expect.objectContaining({
+          rule: 'parse-error',
+          severity: 'error',
+          file: 'other.mdx',
+          message: expect.stringContaining('(other checks were skipped for this file)'),
+        }),
+      ],
+      build: { ran: false, reason: 'disabled' },
+    });
     expect(processExitMock).toHaveBeenCalledWith(1);
   });
 
-  it('continues into the build when the lint pass is clean', async () => {
+  it('passes and runs the build', async () => {
     writeSite({ 'index.mdx': HOME });
 
-    await runCommand('validate');
+    const result = await report('validate');
 
-    expect(validateBuild).toHaveBeenCalledWith(
-      expect.objectContaining({ packageName: 'mint' }),
-      expect.any(Function)
-    );
-    expect(processExitMock).not.toHaveBeenCalled();
+    expect(result).toMatchObject({ passed: true, build: { ran: true, passed: true } });
+    expect(rules(result)).toEqual([]);
+    expect(checkBuild).toHaveBeenCalled();
+    expect(sendPublishPrompt).toHaveBeenCalled();
+    expect(processExitMock).toHaveBeenCalledWith(0);
   });
 
-  it('keeps --disable-openapi working', async () => {
-    writeSite({ 'index.mdx': HOME }, { api: { openapi: 'missing.json' } });
+  it('skips the build while there are errors', async () => {
+    writeSite({ 'index.mdx': '---\ntitle: Home\n---\n\nline<br>\n' });
 
-    await runCommand('validate', '--disable-openapi');
+    const result = await report('validate');
 
-    expect(validateBuild).toHaveBeenCalled();
+    expect(result.build).toEqual({ ran: false, reason: 'errors found' });
+    expect(checkBuild).not.toHaveBeenCalled();
+    expect(processExitMock).toHaveBeenCalledWith(1);
   });
 
-  it('turns rules and groups on and off', async () => {
-    writeSite({ 'index.mdx': '---\ntitle: Home\n---\n\nline<br>\n' });
+  it('turns build warnings into diagnostics', async () => {
+    writeSite({ 'index.mdx': HOME });
+    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 referenced in the docs.json navigation but the file does not exist.',
+        },
+      ],
+    });
 
-    await runCommand('validate', '--disable', 'content');
-    expect(logged()).toContain('parse-error');
-    expect(logged()).not.toContain('void-tags');
+    const result = await report('validate');
 
-    vi.clearAllMocks();
-    await runCommand('validate', '--disable', 'all', '--enable', 'void-tags');
-    expect(logged()).toContain('void-tags');
+    expect(result.diagnostics).toEqual([
+      expect.objectContaining({ rule: 'missing-nav-page', group: 'nav', file: 'docs.json' }),
+    ]);
+    expect(result.build).toEqual({ ran: true, passed: false });
+    expect(processExitMock).toHaveBeenCalledWith(1);
+  });
+
+  it('attributes a missing nav page that looks like a file to the config', async () => {
+    writeSite({ 'index.mdx': HOME }, { navigation: { pages: ['index', 'guides/setup.md'] } });
+    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:
+            '"guides/setup.md" is referenced in the docs.json navigation but the file does not exist.',
+        },
+      ],
+    });
+
+    const result = await report('validate');
+
+    expect(result.diagnostics).toEqual([
+      expect.objectContaining({
+        rule: 'missing-nav-page',
+        file: 'docs.json',
+        line: expect.any(Number),
+      }),
+    ]);
+  });
+
+  it('reports a build failure no rule explains', async () => {
+    writeSite({ 'index.mdx': HOME });
+    vi.mocked(checkBuild).mockResolvedValue({
+      passed: false,
+      error: 'boom',
+      strict: false,
+      warnings: [],
+    });
+
+    const result = await report('validate');
+
+    expect(result.diagnostics).toEqual([
+      expect.objectContaining({ rule: 'build-failed', message: 'boom' }),
+    ]);
+  });
+
+  it('passes when the build fails only on disabled rules', async () => {
+    writeSite({ 'index.mdx': HOME });
+    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 referenced in the docs.json navigation but the file does not exist.',
+        },
+      ],
+    });
+
+    const result = await report('validate', '--disable', 'missing-nav-page');
+
+    expect(result).toMatchObject({ passed: true, build: { ran: true, passed: false } });
+    expect(rules(result)).toEqual([]);
+    expect(sendPublishPrompt).not.toHaveBeenCalled();
+    expect(processExitMock).toHaveBeenCalledWith(0);
+  });
+
+  it('fails on a build error even when a disabled rule covers its warnings', async () => {
+    writeSite({ 'index.mdx': HOME });
+    vi.mocked(checkBuild).mockResolvedValue({
+      passed: false,
+      error: 'Unexpected token } in docs.json',
+      strict: false,
+      warnings: [{ type: 'openapi', message: 'Could not read OpenAPI overlay settings' }],
+    });
+
+    const result = await report('validate', '--disable', 'openapi');
+
+    expect(result.passed).toBe(false);
+    expect(result.diagnostics).toEqual([
+      expect.objectContaining({ rule: 'build-failed', message: 'Unexpected token } in docs.json' }),
+    ]);
     expect(processExitMock).toHaveBeenCalledWith(1);
   });
 
+  it('skips OpenAPI generation in the build only when no openapi rule is selected', async () => {
+    writeSite({ 'index.mdx': HOME });
+
+    await report('validate', '--disable', 'openapi');
+    expect(checkBuild).toHaveBeenLastCalledWith(expect.objectContaining({ disableOpenapi: true }));
+
+    await report('validate');
+    expect(checkBuild).toHaveBeenLastCalledWith(expect.objectContaining({ disableOpenapi: false }));
+  });
+
+  it('cleans build warning messages and lifts their position', async () => {
+    writeSite({ 'index.mdx': HOME });
+    vi.mocked(checkBuild).mockResolvedValue({
+      passed: false,
+      error: 'Build validation failed with 1 warning(s). See above for details.',
+      strict: true,
+      warnings: [
+        { type: 'parse-error', message: '\n\u001b[31m./index.mdx:3:7 Unexpected token\u001b[39m' },
+      ],
+    });
+
+    const result = await report('validate');
+
+    expect(result.diagnostics).toEqual([
+      expect.objectContaining({
+        rule: 'parse-error',
+        file: 'index.mdx',
+        line: 3,
+        column: 7,
+        message: './index.mdx:3:7 Unexpected token',
+      }),
+    ]);
+  });
+
+  it('fails when the build fails on a parse error outside --files', async () => {
+    writeSite({ 'index.mdx': HOME, 'other.mdx': HOME });
+    vi.mocked(checkBuild).mockResolvedValue({
+      passed: false,
+      error: 'Build validation failed with 1 warning(s). See above for details.',
+      strict: true,
+      warnings: [{ type: 'parse-error', message: './other.mdx:3:7 Unexpected token' }],
+    });
+
+    const result = await report('validate', '--files', 'index.mdx');
+
+    expect(result.passed).toBe(false);
+    expect(result.diagnostics).toEqual([
+      expect.objectContaining({ rule: 'build-failed', file: 'other.mdx' }),
+    ]);
+    expect(processExitMock).toHaveBeenCalledWith(1);
+  });
+
+  it('attributes import warnings to the importing page', async () => {
+    writeSite({ 'index.mdx': HOME });
+    vi.mocked(checkBuild).mockResolvedValue({
+      passed: false,
+      error: 'Build validation failed with 3 warning(s). See above for details.',
+      strict: true,
+      warnings: [
+        {
+          type: 'missing-file',
+          message: 'Could not find file snippets/gone.mdx - imported from index.mdx',
+        },
+        {
+          type: 'invalid-import-path',
+          message:
+            'Invalid import path https://example.com/a.jsx in index.mdx. Only local imports are supported.',
+        },
+        {
+          type: 'export-collision',
+          message: 'Widget is exported by snippets/a.jsx (in index.mdx, importing snippets/b.mdx)',
+        },
+      ],
+    });
+
+    const result = await report('validate');
+
+    expect(result.diagnostics.map(({ file }) => file)).toEqual([
+      'index.mdx',
+      'index.mdx',
+      'index.mdx',
+    ]);
+  });
+
+  it('reports missing imported files with the content group', async () => {
+    writeSite({ 'index.mdx': HOME });
+    vi.mocked(checkBuild).mockResolvedValue({
+      passed: false,
+      error: 'Build validation failed with 1 warning(s). See above for details.',
+      strict: true,
+      warnings: [
+        {
+          type: 'missing-file',
+          message: 'Could not find file snippets/gone.mdx - imported from index.mdx',
+        },
+      ],
+    });
+
+    const result = await report('validate', '--disable', 'all', '--enable', 'content');
+
+    expect(result.diagnostics).toEqual([
+      expect.objectContaining({ rule: 'missing-file', group: 'content', file: 'index.mdx' }),
+    ]);
+    expect(processExitMock).toHaveBeenCalledWith(1);
+  });
+
+  it('keeps skipped-spec notices as warnings', async () => {
+    writeSite({ 'index.mdx': HOME }, { api: { openapi: 'http://example.com/openapi.json' } });
+
+    const result = await report('validate', '--no-build');
+
+    expect(result.passed).toBe(true);
+    expect(result.diagnostics).toEqual([
+      expect.objectContaining({
+        rule: 'openapi-spec',
+        severity: 'warning',
+        message: expect.stringContaining('--local-schema'),
+      }),
+      expect.objectContaining({
+        rule: 'openapi-spec',
+        severity: 'warning',
+        message: 'only https protocol is supported in production',
+      }),
+    ]);
+  });
+
+  it('exits 2 when the build could not be prepared', async () => {
+    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(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',
+    });
+
+    // Without void-tags, nothing makes the page parseable
+    expect(rules(await report('validate', '--no-build', '--disable', 'content'))).toEqual([
+      'parse-error',
+    ]);
+    expect(rules(await report('validate', '--no-build', '--disable', 'all'))).toEqual([
+      'parse-error',
+    ]);
+    expect(
+      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'))
+    ).toEqual(['void-tags']);
+  });
+
   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(processExitMock).toHaveBeenLastCalledWith(1);
+    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(1);
-    expect(validateBuild).not.toHaveBeenCalled();
+    expect(processExitMock).toHaveBeenLastCalledWith(2);
   });
 
   it('limits page findings to --files', async () => {
@@ -122,11 +427,67 @@ describe('mint validate', () => {
       { navigation: { pages: ['index', 'other'] } }
     );
 
-    await runCommand('validate', '--files', 'other.mdx');
+    const result = await report('validate', '--no-build', '--files', 'other.mdx');
 
-    expect(logged()).toContain('other.mdx');
-    expect(logged()).not.toContain('index.mdx');
-    expect(processExitMock).toHaveBeenCalledWith(1);
+    expect(result.diagnostics.map(({ file }: { file: string }) => file)).toEqual([
+      'other.mdx',
+      'other.mdx',
+    ]);
+  });
+
+  it('posix-normalizes Windows paths in build warnings', async () => {
+    writeSite({ 'index.mdx': HOME, 'snippets/card.mdx': 'Card\n' });
+    vi.mocked(checkBuild).mockResolvedValue({
+      passed: false,
+      error: 'Build validation failed with 1 warning(s). See above for details.',
+      strict: true,
+      warnings: [{ type: 'parse-error', message: '.\\snippets\\card.mdx:2:1 Unexpected token' }],
+    });
+
+    const result = await report('validate');
+
+    expect(result.diagnostics).toEqual([
+      expect.objectContaining({ rule: 'parse-error', file: 'snippets/card.mdx', line: 2 }),
+    ]);
+  });
+
+  it('checks every OpenAPI spec and sorts findings by file', async () => {
+    writeSite({ 'index.mdx': HOME }, { api: { openapi: ['b.json', 'a.json'] } });
+    fs.writeFileSync(path.join(dir, 'a.json'), '{ not json');
+    fs.writeFileSync(path.join(dir, 'b.json'), '{ not json');
+
+    const result = await report('validate', '--no-build');
+
+    expect(result.diagnostics.map(({ rule, file }) => [rule, file])).toEqual([
+      ['openapi-spec', 'a.json'],
+      ['openapi-spec', 'b.json'],
+    ]);
+  });
+
+  it('reports invalid OpenAPI specs and skips them with --disable openapi', async () => {
+    writeSite({ 'index.mdx': HOME }, { api: { openapi: 'openapi.json' } });
+    fs.writeFileSync(path.join(dir, 'openapi.json'), '{ not json');
+
+    expect(rules(await report('validate', '--no-build'))).toEqual(['openapi-spec']);
+    expect(rules(await report('validate', '--no-build', '--disable', 'openapi'))).toEqual([]);
+  });
+
+  it('checks the OpenAPI specs a mint.json lists', async () => {
+    writeSite({ 'index.mdx': HOME });
+    fs.removeSync(path.join(dir, 'docs.json'));
+    fs.writeJSONSync(path.join(dir, 'mint.json'), {
+      name: 'Test',
+      colors: { primary: '#000000' },
+      navigation: [{ group: 'Home', pages: ['index'] }],
+      openapi: 'openapi.json',
+    });
+    fs.writeFileSync(path.join(dir, 'openapi.json'), '{ not json');
+
+    const result = await report('validate', '--no-build');
+
+    expect(result.diagnostics).toEqual([
+      expect.objectContaining({ rule: 'openapi-spec', file: 'openapi.json' }),
+    ]);
   });
 
   it('rejects --files that match nothing', async () => {
@@ -135,7 +496,29 @@ describe('mint validate', () => {
     await runCommand('validate', '--files', 'missing.mdx');
 
     expect(logged()).toContain('No matching files');
+    expect(processExitMock).toHaveBeenCalledWith(2);
+    expect(checkBuild).not.toHaveBeenCalled();
+  });
+
+  it('rejects the removed --disable-openapi flag', async () => {
+    writeSite({ 'index.mdx': HOME });
+    const error = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+
+    await expect(runCommand('validate', '--no-build', '--disable-openapi')).rejects.toThrow();
+
+    expect(error).toHaveBeenCalledWith(expect.stringContaining('Unknown argument'));
+    error.mockRestore();
+  });
+
+  it('logs diagnostics by file and a verdict in text mode', async () => {
+    writeSite({ 'index.mdx': '---\ntitle: Home\n---\n\nline<br>\n' });
+
+    await runCommand('validate', '--no-build');
+
+    const text = logged();
+    expect(text).toContain('index.mdx');
+    expect(text).toContain('must be self-closed');
+    expect(text).toContain('1 error');
     expect(processExitMock).toHaveBeenCalledWith(1);
-    expect(validateBuild).not.toHaveBeenCalled();
   });
 });