@mintlify/cli 4.0.1741 → 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,26 @@ 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' });
 
@@ -409,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 () => {
@@ -493,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();
   });
@@ -515,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/bin/cli.js

@@ -333,6 +333,12 @@ export const cli = ({ packageName = 'mint' }) => {
         type: 'boolean',
         default: false,
         description: 'Apply the fixes and check again',
+    })
+        .option('format', {
+        type: 'string',
+        choices: ['text', 'json'],
+        default: 'text',
+        description: 'Output format; json prints one report ({ passed, summary, diagnostics, build }) and nothing else on stdout, and errors to stderr',
     })
         .usage('usage: mint validate [options]')
         .epilogue([
@@ -341,6 +347,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 --no-build --format json', 'fast offline check for scripts and agents')
         .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))