doc-freshness-checker 2.0.6 → 2.0.8

package/dist/runner.test.js

@@ -1,6 +1,11 @@
 import fs from 'fs';
+import os from 'os';
 import path from 'path';
+import { glob } from 'glob';
 import { run, runWithConfig } from './runner.js';
+import { ValidationEngine } from './validators/validationEngine.js';
+import { IncrementalChecker } from './utils/incremental.js';
+import { FileValidator } from './validators/fileValidator.js';
 import { withOutputFile } from './test-utils/tempFiles.js';
 import { captureConsoleLog, captureConsoleWarn } from './test-utils/console.js';
 vi.mock('fastembed', () => ({
@@ -33,6 +38,19 @@ describe('runner', () => {
     ];
     const captureLog = captureConsoleLog;
     const captureWarn = captureConsoleWarn;
+    const mockDocumentScan = (docPath) => {
+        vi.mocked(glob).mockResolvedValueOnce([docPath]);
+    };
+    const withIncrementalRoot = async (name, test) => {
+        const rootDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), `runner-inc-${name}-`));
+        try {
+            await test(rootDir);
+        }
+        finally {
+            vi.mocked(glob).mockResolvedValue([]);
+            await fs.promises.rm(rootDir, { recursive: true, force: true });
+        }
+    };
     const baseConfig = {
         rootDir: process.cwd(),
         include: [],
@@ -55,6 +73,17 @@ describe('runner', () => {
         reporters: [],
         verbose: false,
     };
+    const incrementalConfig = (rootDir, overrides = {}) => ({
+        ...baseConfig,
+        rootDir,
+        include: ['*.md'],
+        sourcePatterns: [],
+        manifestFiles: [],
+        incremental: { enabled: true },
+        cache: { enabled: false, dir: '.cache' },
+        ...overrides,
+        rules: { ...baseConfig.rules, ...overrides.rules },
+    });
     afterAll(async () => {
         await Promise.all(transientCacheDirs.map((dir) => fs.promises.rm(path.join(process.cwd(), dir), { recursive: true, force: true }).catch(() => { })));
     });
@@ -95,6 +124,70 @@ describe('runner', () => {
         });
         expect(true).toBe(true);
     });
+    it.each(['supportsFormat', 'extract'])('propagates custom extractor %s failures', async (hook) => {
+        vi.mocked(glob).mockResolvedValueOnce([path.join(process.cwd(), 'README.md')]);
+        const failure = () => {
+            throw new Error(`${hook} crashed`);
+        };
+        const extractor = {
+            supportsFormat: hook === 'supportsFormat' ? failure : () => true,
+            extract: hook === 'extract' ? failure : () => [],
+        };
+        await expect(run({
+            ...baseConfig,
+            customExtractors: [extractor],
+        })).rejects.toThrow(`${hook} crashed`);
+    });
+    it('propagates custom validator execution failures', async () => {
+        const reference = {
+            type: 'custom',
+            value: 'value',
+            lineNumber: 1,
+            raw: 'value',
+            sourceFile: 'README.md',
+        };
+        vi.mocked(glob).mockResolvedValueOnce([path.join(process.cwd(), 'README.md')]);
+        await expect(run({
+            ...baseConfig,
+            customExtractors: [{ extract: () => [reference], supportsFormat: () => true }],
+            customValidators: {
+                custom: { validateBatch: vi.fn().mockRejectedValue(new Error('custom validator crashed')) },
+            },
+        })).rejects.toThrow('custom validator crashed');
+    });
+    it('propagates built-in validator execution failures', async () => {
+        const reference = {
+            type: 'file-path',
+            value: './src/index.ts',
+            lineNumber: 1,
+            raw: './src/index.ts',
+            sourceFile: 'README.md',
+        };
+        vi.mocked(glob).mockResolvedValueOnce([path.join(process.cwd(), 'README.md')]);
+        const validateSpy = vi.spyOn(FileValidator.prototype, 'validateBatch').mockRejectedValueOnce(new Error('file validator crashed'));
+        try {
+            await expect(run({
+                ...baseConfig,
+                rules: { ...baseConfig.rules, 'file-path': { enabled: true } },
+                customExtractors: [
+                    { extract: () => [reference], supportsFormat: () => true },
+                ],
+            })).rejects.toThrow('file validator crashed');
+        }
+        finally {
+            validateSpy.mockRestore();
+        }
+    });
+    it('propagates matched-document read failures', async () => {
+        vi.mocked(glob).mockResolvedValueOnce([path.join(process.cwd(), 'README.md')]);
+        const readSpy = vi.spyOn(fs.promises, 'readFile').mockRejectedValueOnce(new Error('Permission denied'));
+        try {
+            await expect(run(baseConfig)).rejects.toThrow('Permission denied');
+        }
+        finally {
+            readSpy.mockRestore();
+        }
+    });
     describe('verbose mode', () => {
         it('logs config file path and source patterns', async () => {
             const spy = captureLog();
@@ -245,7 +338,7 @@ describe('runner', () => {
         });
     });
     describe('incremental mode', () => {
-        it('filters changed files with verbose logging', async () => {
+        it('reports changed files in verbose mode', async () => {
             const spy = captureLog();
             await run({
                 ...baseConfig,
@@ -255,6 +348,410 @@ describe('runner', () => {
             });
             expect(spy.mock.calls.flat().join('\n')).toContain('Incremental');
         });
+        it('skips a second clean run with default validator configuration', async () => {
+            await withIncrementalRoot('defaults', async (rootDir) => {
+                const docPath = path.join(rootDir, 'guide.md');
+                const targetPath = path.join(rootDir, 'target.ts');
+                await fs.promises.writeFile(docPath, '[target](target.ts)');
+                await fs.promises.writeFile(targetPath, 'export const target = true;');
+                const config = {
+                    rootDir,
+                    include: ['*.md'],
+                    incremental: { enabled: true },
+                    graph: { enabled: false },
+                    cache: { enabled: false, dir: '.cache' },
+                    reporters: [],
+                };
+                mockDocumentScan(docPath);
+                expect((await run(config)).summary.total).toBe(1);
+                mockDocumentScan(docPath);
+                expect((await run(config)).summary.total).toBe(0);
+            });
+        });
+        it('allows reuse when git tracking is enabled without freshness scoring', async () => {
+            await withIncrementalRoot('git-only', async (rootDir) => {
+                const docPath = path.join(rootDir, 'guide.md');
+                const targetPath = path.join(rootDir, 'target.ts');
+                await fs.promises.writeFile(docPath, '[target](target.ts)');
+                await fs.promises.writeFile(targetPath, 'export const target = true;');
+                const config = incrementalConfig(rootDir, {
+                    git: { enabled: true },
+                    rules: { 'file-path': { enabled: true } },
+                });
+                mockDocumentScan(docPath);
+                expect((await run(config)).summary.total).toBe(1);
+                mockDocumentScan(docPath);
+                expect((await run(config)).summary.total).toBe(0);
+            });
+        });
+        it('reuses expected skips but revalidates when a disabled unsafe rule is enabled', async () => {
+            await withIncrementalRoot('disabled-rule', async (rootDir) => {
+                const docPath = path.join(rootDir, 'guide.md');
+                await fs.promises.writeFile(docPath, '[site](https://example.com)');
+                const config = incrementalConfig(rootDir, {
+                    rules: { 'external-url': { enabled: false } },
+                });
+                mockDocumentScan(docPath);
+                expect((await run(config)).summary.skipped).toBe(1);
+                mockDocumentScan(docPath);
+                expect((await run(config)).summary.total).toBe(0);
+                mockDocumentScan(docPath);
+                expect((await run({ ...config, rules: { ...config.rules, 'external-url': { enabled: true } } })).summary.total).toBe(1);
+            });
+        });
+        it('reuses a clean run containing an illustrative safe-rule skip', async () => {
+            await withIncrementalRoot('illustrative-skip', async (rootDir) => {
+                const docPath = path.join(rootDir, 'guide.md');
+                await fs.promises.writeFile(docPath, '[example](YourProject/file.ts)');
+                const config = incrementalConfig(rootDir, {
+                    rules: { 'file-path': { enabled: true, skipIllustrative: true } },
+                });
+                mockDocumentScan(docPath);
+                expect((await run(config)).summary.skipped).toBe(1);
+                mockDocumentScan(docPath);
+                expect((await run(config)).summary.total).toBe(0);
+            });
+        });
+        it('keeps state dirty when a validator is missing or throws', async () => {
+            await withIncrementalRoot('incomplete', async (rootDir) => {
+                const docPath = path.join(rootDir, 'guide.md');
+                const cacheDir = path.join(rootDir, '.cache');
+                await fs.promises.writeFile(docPath, 'unknown input');
+                const unknownExtractor = {
+                    type: 'unknown-type',
+                    supportedFormats: ['markdown'],
+                    supportsFormat: () => true,
+                    extract: (document) => [{ type: 'unknown-type', value: 'value', lineNumber: 1, raw: 'value', sourceFile: document.path }],
+                    findLineNumber: () => 1,
+                    getContext: () => '',
+                };
+                const missingConfig = incrementalConfig(rootDir, { customExtractors: [unknownExtractor] });
+                mockDocumentScan(docPath);
+                await run(missingConfig);
+                expect(JSON.parse(await fs.promises.readFile(path.join(cacheDir, 'file-hashes.json'), 'utf-8')).clean).toBe(false);
+                const throwingValidator = {
+                    async validateBatch() {
+                        throw new Error('validator failed');
+                    },
+                };
+                const throwingConfig = incrementalConfig(rootDir, {
+                    customValidators: { 'file-path': throwingValidator },
+                    rules: { 'file-path': { enabled: true } },
+                });
+                await fs.promises.writeFile(docPath, '[target](target.ts)');
+                mockDocumentScan(docPath);
+                await expect(run(throwingConfig)).rejects.toThrow('validator failed');
+                expect(JSON.parse(await fs.promises.readFile(path.join(cacheDir, 'file-hashes.json'), 'utf-8')).clean).toBe(false);
+            });
+        });
+        it('revalidates unchanged docs when a referenced source file is renamed', async () => {
+            await withIncrementalRoot('source', async (rootDir) => {
+                const docsDir = path.join(rootDir, 'docs');
+                const sourceDir = path.join(rootDir, 'src');
+                const docPath = path.join(docsDir, 'guide.md');
+                const sourcePath = path.join(sourceDir, 'server.ts');
+                const renamedSourcePath = path.join(sourceDir, 'renamed.ts');
+                const cacheDir = path.join(rootDir, '.cache');
+                await fs.promises.mkdir(docsDir, { recursive: true });
+                await fs.promises.mkdir(sourceDir, { recursive: true });
+                await fs.promises.writeFile(docPath, '[source](../src/server.ts)');
+                await fs.promises.writeFile(sourcePath, 'export const server = true;');
+                const config = incrementalConfig(rootDir, {
+                    include: ['docs/**/*.md'],
+                    sourcePatterns: ['src/**/*.ts'],
+                    rules: { 'file-path': { enabled: true } },
+                });
+                mockDocumentScan(docPath);
+                expect((await run(config)).summary.errors).toBe(0);
+                await expect(fs.promises.access(path.join(cacheDir, 'file-hashes.json'))).resolves.toBeUndefined();
+                mockDocumentScan(docPath);
+                expect((await run(config)).summary.total).toBe(0);
+                await fs.promises.rename(sourcePath, renamedSourcePath);
+                mockDocumentScan(docPath);
+                expect((await run(config)).summary.errors).toBe(1);
+                const stateFile = path.join(cacheDir, 'file-hashes.json');
+                expect(JSON.parse(await fs.promises.readFile(stateFile, 'utf-8')).clean).toBe(false);
+                mockDocumentScan(docPath);
+                expect((await run(config)).summary.errors).toBe(1);
+            });
+        });
+        it('reuses the code-pattern source index and fingerprints excluded source matches', async () => {
+            await withIncrementalRoot('code-pattern-source', async (rootDir) => {
+                const docPath = path.join(rootDir, 'guide.md');
+                const sourceDir = path.join(rootDir, '.git');
+                const sourcePath = path.join(sourceDir, 'source.ts');
+                await fs.promises.mkdir(sourceDir);
+                await fs.promises.writeFile(docPath, ['```typescript', 'class StableService {}', '```'].join('\n'));
+                await fs.promises.writeFile(sourcePath, 'export class StableService {}');
+                const config = incrementalConfig(rootDir, {
+                    sourcePatterns: ['.g{it,noop}/**/*.ts'],
+                    rules: { 'code-pattern': { enabled: true, severity: 'warning' } },
+                });
+                const mockScans = () => {
+                    mockDocumentScan(docPath);
+                    vi.mocked(glob).mockResolvedValueOnce([sourcePath]);
+                };
+                mockScans();
+                expect((await run(config)).summary.warnings).toBe(0);
+                mockScans();
+                expect((await run(config)).summary.total).toBe(0);
+                await fs.promises.writeFile(sourcePath, 'export class ReplacementService {}');
+                mockScans();
+                expect((await run(config)).summary.warnings).toBe(1);
+            });
+        });
+        it('captures graph-only source inputs once per run and skips unchanged validation', async () => {
+            await withIncrementalRoot('graph-source', async (rootDir) => {
+                const docPath = path.join(rootDir, 'guide.md');
+                const sourceDir = path.join(rootDir, 'src');
+                const sourcePath = path.join(sourceDir, 'source.ts');
+                await fs.promises.mkdir(sourceDir);
+                await fs.promises.writeFile(docPath, 'No code-pattern references');
+                await fs.promises.writeFile(sourcePath, 'export class GraphSource {}');
+                const config = incrementalConfig(rootDir, {
+                    graph: { enabled: true },
+                    sourcePatterns: ['src/**/*.ts'],
+                });
+                const mockScans = () => {
+                    mockDocumentScan(docPath);
+                    vi.mocked(glob).mockResolvedValueOnce([sourcePath]);
+                };
+                const validateSpy = vi.spyOn(ValidationEngine.prototype, 'validate');
+                const readSpy = vi.spyOn(fs.promises, 'readFile');
+                vi.mocked(glob).mockClear();
+                try {
+                    mockScans();
+                    await run(config);
+                    mockScans();
+                    await run(config);
+                    expect(validateSpy.mock.calls[0][0]).toHaveLength(1);
+                    expect(validateSpy.mock.calls[1][0]).toEqual([]);
+                    expect(vi.mocked(glob).mock.calls.filter(([pattern]) => pattern === 'src/**/*.ts')).toHaveLength(2);
+                    expect(readSpy.mock.calls.filter(([file]) => file === sourcePath)).toHaveLength(2);
+                }
+                finally {
+                    validateSpy.mockRestore();
+                    readSpy.mockRestore();
+                }
+            });
+        });
+        it('bypasses incremental inventory for an empty graph-enabled scan', async () => {
+            await withIncrementalRoot('empty-graph', async (rootDir) => {
+                const sourceDir = path.join(rootDir, 'src');
+                const sourcePath = path.join(sourceDir, 'source.ts');
+                await fs.promises.mkdir(sourceDir);
+                await fs.promises.writeFile(sourcePath, 'export class GraphSource {}');
+                const config = incrementalConfig(rootDir, {
+                    graph: { enabled: true },
+                    sourcePatterns: ['src/**/*.ts'],
+                });
+                const filterSpy = vi.spyOn(IncrementalChecker.prototype, 'filterChanged');
+                const readSpy = vi.spyOn(fs.promises, 'readFile');
+                vi.mocked(glob).mockClear();
+                try {
+                    vi.mocked(glob).mockResolvedValueOnce([]).mockResolvedValueOnce([sourcePath]);
+                    await run(config);
+                    expect(filterSpy).not.toHaveBeenCalled();
+                    await expect(fs.promises.access(path.join(rootDir, '.cache', 'file-hashes.json'))).rejects.toThrow();
+                    expect(vi.mocked(glob).mock.calls.filter(([pattern]) => pattern === 'src/**/*.ts')).toHaveLength(1);
+                    expect(readSpy.mock.calls.filter(([file]) => file === sourcePath)).toHaveLength(1);
+                }
+                finally {
+                    filterSpy.mockRestore();
+                    readSpy.mockRestore();
+                }
+            });
+        });
+        it('revalidates code-snippet fallbacks under excluded directories', async () => {
+            await withIncrementalRoot('snippet', async (rootDir) => {
+                const docsDir = path.join(rootDir, 'docs');
+                const dependencyDir = path.join(rootDir, 'node_modules');
+                const docPath = path.join(docsDir, 'guide.md');
+                const sourcePath = path.join(dependencyDir, 'generated.js');
+                await fs.promises.mkdir(docsDir);
+                await fs.promises.mkdir(dependencyDir);
+                await fs.promises.writeFile(docPath, "```js\nimport * as generated from '../node_modules/generated';\n```");
+                await fs.promises.writeFile(sourcePath, 'export const generated = true;');
+                const config = incrementalConfig(rootDir, {
+                    include: ['docs/**/*.md'],
+                    rules: { 'code-snippet': { enabled: true } },
+                });
+                mockDocumentScan(docPath);
+                expect((await run(config)).summary.warnings).toBe(0);
+                mockDocumentScan(docPath);
+                expect((await run(config)).summary.total).toBe(1);
+                await fs.promises.rm(sourcePath);
+                mockDocumentScan(docPath);
+                expect((await run(config)).summary.warnings).toBe(1);
+            });
+        });
+        it('revalidates unchanged docs after an unreported info finding', async () => {
+            await withIncrementalRoot('info', async (rootDir) => {
+                const docPath = path.join(rootDir, 'guide.md');
+                const cacheDir = path.join(rootDir, '.cache');
+                await fs.promises.writeFile(docPath, 'Install `missingpkg`.');
+                await fs.promises.writeFile(path.join(rootDir, 'package.json'), '{}');
+                const config = incrementalConfig(rootDir, {
+                    manifestFiles: ['package.json'],
+                    rules: { dependency: { enabled: true, severity: 'info' } },
+                    cache: { enabled: false, dir: cacheDir },
+                });
+                mockDocumentScan(docPath);
+                expect((await run(config)).summary.total).toBe(1);
+                mockDocumentScan(docPath);
+                expect((await run(config)).summary.total).toBe(1);
+                expect(JSON.parse(await fs.promises.readFile(path.join(cacheDir, 'file-hashes.json'), 'utf-8')).clean).toBe(false);
+            });
+        });
+        it('revalidates after generated output changes the project inventory', async () => {
+            await withIncrementalRoot('output', async (rootDir) => {
+                const docPath = path.join(rootDir, 'guide.md');
+                const targetPath = path.join(rootDir, 'target.ts');
+                const outputPath = path.join(rootDir, 'report.json');
+                await fs.promises.writeFile(docPath, '[target](target.ts)');
+                await fs.promises.writeFile(targetPath, 'export const target = true;');
+                const config = incrementalConfig(rootDir, {
+                    rules: { 'file-path': { enabled: true } },
+                    reporters: ['json'],
+                    outputPath,
+                });
+                mockDocumentScan(docPath);
+                expect((await run(config)).summary.total).toBe(1);
+                mockDocumentScan(docPath);
+                expect((await run(config)).summary.total).toBe(1);
+                mockDocumentScan(docPath);
+                expect((await run(config)).summary.total).toBe(0);
+                mockDocumentScan(docPath);
+                expect((await run(config)).summary.total).toBe(1);
+            });
+        });
+        it.each(['markdown', 'enhanced'])('skips unchanged docs when %s output is inside rootDir', async (reporter) => {
+            await withIncrementalRoot(`output-${reporter}`, async (rootDir) => {
+                const docPath = path.join(rootDir, 'guide.md');
+                const targetPath = path.join(rootDir, 'target.ts');
+                const outputPath = path.join(rootDir, `${reporter}.out`);
+                await fs.promises.writeFile(docPath, '[target](target.ts)');
+                await fs.promises.writeFile(targetPath, 'export const target = true;');
+                const config = incrementalConfig(rootDir, {
+                    rules: { 'file-path': { enabled: true } },
+                    reporters: [reporter],
+                    outputPath,
+                });
+                mockDocumentScan(docPath);
+                expect((await run(config)).summary.total).toBe(1);
+                await expect(fs.promises.access(outputPath)).resolves.toBeUndefined();
+                mockDocumentScan(docPath);
+                expect((await run(config)).summary.total).toBe(0);
+                mockDocumentScan(docPath);
+                expect((await run(config)).summary.total).toBe(0);
+            });
+        });
+        it.each([
+            { reporters: ['markdown', 'json'], expectedTotals: [1, 1, 0, 1] },
+            { reporters: ['json', 'markdown'], expectedTotals: [1, 0, 0, 0] },
+        ])('keeps mixed reporter ordering stable for incremental output', async ({ reporters, expectedTotals }) => {
+            await withIncrementalRoot(`mixed-output-${reporters.join('-')}`, async (rootDir) => {
+                const docPath = path.join(rootDir, 'guide.md');
+                const targetPath = path.join(rootDir, 'target.ts');
+                const outputPath = path.join(rootDir, 'report.out');
+                await fs.promises.writeFile(docPath, '[target](target.ts)');
+                await fs.promises.writeFile(targetPath, 'export const target = true;');
+                const config = incrementalConfig(rootDir, {
+                    rules: { 'file-path': { enabled: true } },
+                    reporters,
+                    outputPath,
+                });
+                const totals = [];
+                for (let runNumber = 0; runNumber < expectedTotals.length; runNumber++) {
+                    mockDocumentScan(docPath);
+                    totals.push((await run(config)).summary.total);
+                }
+                expect(totals).toEqual(expectedTotals);
+            });
+        });
+        it('does not throw for markdown reporting without outputPath', async () => {
+            await withIncrementalRoot('markdown-stdout', async (rootDir) => {
+                const docPath = path.join(rootDir, 'guide.md');
+                await fs.promises.writeFile(docPath, 'No references');
+                const config = incrementalConfig(rootDir, { reporters: ['markdown'] });
+                const log = captureLog();
+                try {
+                    mockDocumentScan(docPath);
+                    await expect(run(config)).resolves.toBeDefined();
+                }
+                finally {
+                    log.mockRestore();
+                }
+            });
+        });
+        it('revalidates when reporting mutates a validation input', async () => {
+            await withIncrementalRoot('output-overlap', async (rootDir) => {
+                const docPath = path.join(rootDir, 'guide.md');
+                const targetPath = path.join(rootDir, 'target.ts');
+                await fs.promises.writeFile(docPath, '[target](target.ts)');
+                await fs.promises.writeFile(targetPath, 'export const target = true;');
+                const config = incrementalConfig(rootDir, {
+                    rules: { 'file-path': { enabled: true } },
+                    reporters: ['json'],
+                    outputPath: targetPath,
+                });
+                mockDocumentScan(docPath);
+                expect((await run(config)).summary.total).toBe(1);
+                mockDocumentScan(docPath);
+                expect((await run(config)).summary.total).toBe(1);
+            });
+        });
+        it('excludes lexical and real symlinked cache directories', async () => {
+            await withIncrementalRoot('cache-link', async (rootDir) => {
+                const docPath = path.join(rootDir, 'guide.md');
+                const targetPath = path.join(rootDir, 'target.ts');
+                const realCacheDir = path.join(rootDir, '.real-cache');
+                await fs.promises.writeFile(docPath, '[target](target.ts)');
+                await fs.promises.writeFile(targetPath, 'export const target = true;');
+                await fs.promises.mkdir(realCacheDir);
+                await fs.promises.symlink('.real-cache', path.join(rootDir, '.cache'), 'dir');
+                const config = incrementalConfig(rootDir, { rules: { 'file-path': { enabled: true } } });
+                mockDocumentScan(docPath);
+                expect((await run(config)).summary.total).toBe(1);
+                await expect(fs.promises.access(path.join(realCacheDir, 'file-hashes.json'))).resolves.toBeUndefined();
+                mockDocumentScan(docPath);
+                expect((await run(config)).summary.total).toBe(0);
+            });
+        });
+        it('does not advance state when validation or reporting throws', async () => {
+            await withIncrementalRoot('report', async (rootDir) => {
+                const docPath = path.join(rootDir, 'guide.md');
+                const cacheDir = path.join(rootDir, '.cache');
+                await fs.promises.writeFile(docPath, 'No references');
+                const config = incrementalConfig(rootDir, {
+                    rules: { 'file-path': { enabled: true } },
+                    cache: { enabled: false, dir: cacheDir },
+                });
+                mockDocumentScan(docPath);
+                await run(config);
+                const stateFile = path.join(cacheDir, 'file-hashes.json');
+                const baselineState = await fs.promises.readFile(stateFile, 'utf-8');
+                await fs.promises.writeFile(docPath, '[missing](missing.ts)');
+                const validateSpy = vi.spyOn(ValidationEngine.prototype, 'validate').mockRejectedValueOnce(new Error('validation failed'));
+                try {
+                    mockDocumentScan(docPath);
+                    await expect(run(config)).rejects.toThrow('validation failed');
+                    expect(await fs.promises.readFile(stateFile, 'utf-8')).toBe(baselineState);
+                }
+                finally {
+                    validateSpy.mockRestore();
+                }
+                mockDocumentScan(docPath);
+                await expect(run({
+                    ...config,
+                    reporters: ['json'],
+                    outputPath: rootDir,
+                })).rejects.toThrow();
+                expect(await fs.promises.readFile(stateFile, 'utf-8')).toBe(baselineState);
+                mockDocumentScan(docPath);
+                expect((await run(config)).summary.errors).toBe(1);
+            });
+        });
     });
     it('loads URL cache when cache is enabled', async () => {
         const cacheDir = '.doc-freshness-cache/runner-url';