doc-freshness-checker 2.0.22 → 2.1.0

package/dist/runner.test.js

@@ -4,10 +4,16 @@ import path from 'path';
 import { glob } from 'glob';
 import { run, runWithConfig } from './runner.js';
 import { BUILT_IN_RULE_TYPES } from './config/defaults.js';
+import { GraphBuilder } from './graph/graphBuilder.js';
 import { VectorSearch } from './semantic/vectorSearch.js';
+import { SourceIndex } from './source/sourceIndex.js';
+import { DocumentParser } from './parsers/documentParser.js';
+import { ManifestInventory } from './manifests/manifestInventory.js';
 import { ValidationEngine } from './validators/validationEngine.js';
 import { IncrementalChecker } from './utils/incremental.js';
 import { FileValidator } from './validators/fileValidator.js';
+import { CacheManager } from './cache/cacheManager.js';
+import { FreshnessScorer } from './scoring/freshnessScorer.js';
 import { withOutputFile } from './test-utils/tempFiles.js';
 import { captureConsoleLog, captureConsoleWarn } from './test-utils/console.js';
 vi.mock('fastembed', () => ({
@@ -38,6 +44,9 @@ describe('runner', () => {
         '.doc-freshness-cache/runner-vs-nograph',
         '.doc-freshness-cache/runner-vs-reporters',
         '.doc-freshness-cache/rv-clear',
+        '.doc-freshness-cache/runner-clear-root',
+        '.doc-freshness-cache/runner-policy-root',
+        '.doc-freshness-cache/runner-incremental-disabled',
     ];
     const captureLog = captureConsoleLog;
     const captureWarn = captureConsoleWarn;
@@ -76,7 +85,7 @@ describe('runner', () => {
         sourcePatterns: [],
         manifestFiles: [],
         incremental: { enabled: true },
-        cache: { enabled: false, dir: '.cache' },
+        cache: { enabled: true, dir: '.cache' },
         ...overrides,
         rules: { ...baseConfig.rules, ...overrides.rules },
     });
@@ -106,12 +115,14 @@ describe('runner', () => {
         expect(results.documents).toEqual([]);
     });
     it('clears cache when clearCache is set', async () => {
-        const cacheDir = path.join(process.cwd(), '.doc-freshness-cache', 'runner-test');
+        const rootDir = path.join(cacheRoot, 'runner-clear-root');
+        const cacheDir = path.join(rootDir, '.result-cache');
         await fs.promises.mkdir(cacheDir, { recursive: true });
         await fs.promises.writeFile(path.join(cacheDir, 'dummy.json'), '{}');
         await run({
             ...baseConfig,
-            cache: { enabled: true, dir: '.doc-freshness-cache/runner-test' },
+            rootDir,
+            cache: { enabled: false, dir: '.result-cache' },
             clearCache: true,
         });
         const exists = await fs.promises
@@ -120,15 +131,71 @@ describe('runner', () => {
             .catch(() => false);
         expect(exists).toBe(false);
     });
-    it('registers custom extractors and validators', async () => {
-        const extract = vi.fn().mockReturnValue([]);
-        const validateBatch = vi.fn().mockResolvedValue([]);
-        await run({
-            ...baseConfig,
-            customExtractors: [{ extract, supportsFormat: () => true }],
-            customValidators: { custom: { validateBatch } },
+    it('ignores an unused outside cache directory when caching is disabled', async () => {
+        const outsideDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'doc-freshness-disabled-cache-'));
+        await expect(run({ ...baseConfig, cache: { enabled: false, dir: outsideDir } })).resolves.toBeDefined();
+        expect(await fs.promises.readdir(outsideDir)).toEqual([]);
+        await fs.promises.rm(outsideDir, { recursive: true, force: true });
+    });
+    it('continues when an enabled cache file is unreadable', async () => {
+        const cacheDir = '.doc-freshness-cache/runner-unreadable';
+        const readSpy = vi.spyOn(fs.promises, 'readFile').mockRejectedValueOnce(Object.assign(new Error('denied'), { code: 'EACCES' }));
+        await expect(run({ ...baseConfig, cache: { enabled: true, dir: cacheDir } })).resolves.toBeDefined();
+        readSpy.mockRestore();
+        await fs.promises.rm(path.join(process.cwd(), cacheDir), { recursive: true, force: true });
+    });
+    it('round-trips a two-method custom extractor through an overriding custom validator', async () => {
+        await fs.promises.mkdir(cacheRoot, { recursive: true });
+        await withOutputFile(cacheRoot, 'custom-extractor.md', async (filePath) => {
+            const content = '# Custom\n\nprose';
+            await fs.promises.writeFile(filePath, content, 'utf-8');
+            vi.mocked(glob).mockResolvedValueOnce([filePath]);
+            const reference = {
+                type: 'file-path',
+                value: 'prose',
+                lineNumber: 3,
+                raw: 'prose',
+                sourceFile: 'custom-extractor.md',
+            };
+            const customExtractor = {
+                supportsFormat: vi.fn((format) => format === 'markdown'),
+                extract: vi.fn(() => [reference]),
+            };
+            const invalidResult = {
+                reference,
+                valid: false,
+                severity: 'error',
+                message: 'Custom reference is stale',
+            };
+            const customValidator = {
+                validateBatch: vi.fn(async () => [invalidResult]),
+            };
+            const config = {
+                ...baseConfig,
+                rootDir: cacheRoot,
+                include: ['**/*.md'],
+                rules: { ...baseConfig.rules, 'file-path': { enabled: true } },
+                customExtractors: [customExtractor],
+                customValidators: { 'file-path': customValidator },
+            };
+            const results = await run(config);
+            const document = {
+                path: 'custom-extractor.md',
+                absolutePath: filePath,
+                content,
+                format: 'markdown',
+                lines: ['# Custom', '', 'prose'],
+                references: [reference],
+            };
+            expect(vi.mocked(glob).mock.calls).toEqual([[['**/*.md'], { ignore: [], cwd: cacheRoot, absolute: true }]]);
+            expect(customExtractor.supportsFormat.mock.calls).toEqual([['markdown']]);
+            expect(customExtractor.extract.mock.calls).toEqual([[document]]);
+            expect(customValidator.validateBatch.mock.calls).toEqual([[[reference], document, config]]);
+            expect(results).toEqual({
+                documents: [{ path: 'custom-extractor.md', issues: [invalidResult] }],
+                summary: { total: 1, valid: 0, errors: 1, warnings: 0, info: 0, skipped: 0 },
+            });
         });
-        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')]);
@@ -175,9 +242,7 @@ describe('runner', () => {
             await expect(run({
                 ...baseConfig,
                 rules: { ...baseConfig.rules, 'file-path': { enabled: true } },
-                customExtractors: [
-                    { extract: () => [reference], supportsFormat: () => true },
-                ],
+                customExtractors: [{ extract: () => [reference], supportsFormat: () => true }],
             })).rejects.toThrow('file validator crashed');
         }
         finally {
@@ -218,6 +283,73 @@ describe('runner', () => {
             });
         });
     });
+    describe('shared manifest inventory', () => {
+        afterEach(() => vi.restoreAllMocks());
+        const manifestDocument = {
+            path: 'doc.md',
+            absolutePath: '/doc.md',
+            content: '',
+            format: 'markdown',
+            lines: [],
+            references: [
+                {
+                    type: 'version',
+                    value: 'TypeScript 5.0',
+                    technology: 'typescript',
+                    version: '5.0',
+                    lineNumber: 1,
+                    raw: 'TypeScript 5.0',
+                    sourceFile: 'doc.md',
+                },
+                { type: 'dependency', value: 'typescript', lineNumber: 2, raw: 'typescript', sourceFile: 'doc.md' },
+            ],
+        };
+        it('reads a manifest once for both built-in validators', async () => {
+            const rootDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'doc-freshness-runner-manifest-'));
+            await fs.promises.writeFile(path.join(rootDir, 'package.json'), JSON.stringify({ dependencies: { typescript: '5.9.0' } }));
+            vi.spyOn(DocumentParser.prototype, 'scanDocuments').mockResolvedValue([manifestDocument]);
+            const readFile = vi.spyOn(fs.promises, 'readFile');
+            try {
+                const results = await run({
+                    ...baseConfig,
+                    rootDir,
+                    manifestFiles: ['package.json'],
+                    rules: { ...baseConfig.rules, version: { enabled: true }, dependency: { enabled: true } },
+                });
+                expect(results.summary).toMatchObject({ total: 2, valid: 2 });
+                expect(readFile).toHaveBeenCalledOnce();
+            }
+            finally {
+                await fs.promises.rm(rootDir, { recursive: true, force: true });
+            }
+        });
+        it('does no manifest work when there are no references or both rules are disabled', async () => {
+            const dependencyNames = vi.spyOn(ManifestInventory.prototype, 'dependencyNames');
+            const packageVersions = vi.spyOn(ManifestInventory.prototype, 'packageVersions');
+            await run(baseConfig);
+            vi.spyOn(DocumentParser.prototype, 'scanDocuments').mockResolvedValue([manifestDocument]);
+            await run(baseConfig);
+            expect(dependencyNames).not.toHaveBeenCalled();
+            expect(packageVersions).not.toHaveBeenCalled();
+        });
+        it('does no built-in manifest work when custom validators replace both types', async () => {
+            vi.spyOn(DocumentParser.prototype, 'scanDocuments').mockResolvedValue([manifestDocument]);
+            const dependencyNames = vi.spyOn(ManifestInventory.prototype, 'dependencyNames');
+            const packageVersions = vi.spyOn(ManifestInventory.prototype, 'packageVersions');
+            const validateBatch = vi.fn().mockResolvedValue([]);
+            await run({
+                ...baseConfig,
+                rules: { ...baseConfig.rules, version: { enabled: true }, dependency: { enabled: true } },
+                customValidators: {
+                    version: { validateBatch },
+                    dependency: { validateBatch },
+                },
+            });
+            expect(validateBatch).toHaveBeenCalledTimes(2);
+            expect(dependencyNames).not.toHaveBeenCalled();
+            expect(packageVersions).not.toHaveBeenCalled();
+        });
+    });
     describe('verbose mode', () => {
         it('logs config file path and source patterns', async () => {
             const spy = captureLog();
@@ -252,9 +384,11 @@ describe('runner', () => {
         });
     });
     describe('reporters', () => {
-        it('generates console report', async () => {
+        it('routes the Console emitter to stdout incrementally', async () => {
             const spy = captureLog();
             await run({ ...baseConfig, reporters: ['console'] });
+            expect(spy.mock.calls.length).toBeGreaterThan(1);
+            expect(spy.mock.calls.every((call) => call.length === 1)).toBe(true);
             expect(spy.mock.calls.flat().join('\n')).toContain('Documentation Freshness Report');
         });
         it('falls back to console when the reporter list is empty', async () => {
@@ -312,50 +446,255 @@ describe('runner', () => {
                 expect(spy.mock.calls.flat().join('\n')).toContain('written to');
             });
         });
+        it('defaults an absent reporter list to Console', async () => {
+            const log = captureLog();
+            await run({ ...baseConfig, reporters: undefined });
+            expect(log.mock.calls.flat().join('\n')).toContain('Documentation Freshness Report');
+        });
+        it('preserves configured reporter order and duplicates', async () => {
+            const log = captureLog();
+            await run({ ...baseConfig, reporters: ['json', 'markdown', 'json'] });
+            const reports = log.mock.calls
+                .map(([value]) => value)
+                .filter((value) => typeof value === 'string' && (value.startsWith('{') || value.startsWith('#')));
+            expect(reports).toHaveLength(3);
+            expect(reports[0]).toMatch(/^\{/);
+            expect(reports[1]).toMatch(/^# Documentation Freshness Report/);
+            expect(reports[2]).toMatch(/^\{/);
+        });
+        it('treats inherited registry keys as unknown', async () => {
+            const inheritedKeys = ['toString', 'constructor', '__proto__'];
+            const log = captureLog();
+            const warn = captureWarn();
+            await expect(run({ ...baseConfig, reporters: inheritedKeys })).resolves.toBeDefined();
+            expect(warn.mock.calls).toEqual([
+                ['Unknown reporter type: toString'],
+                ['Unknown reporter type: constructor'],
+                ['Unknown reporter type: __proto__'],
+            ]);
+            expect(log.mock.calls.some(([value]) => typeof value === 'string' && value.startsWith('{'))).toBe(false);
+            const output = log.mock.calls.flat().join('\n');
+            expect(output).not.toContain('Documentation Freshness Report');
+            expect(output).not.toContain('Documentation Freshness Scan Report');
+        });
+        it('keeps Console on stdout and ignores outputPath', async () => {
+            await withOutputFile(cacheRoot, 'console-must-not-write.out', async (outputPath) => {
+                const log = captureLog();
+                await run({ ...baseConfig, reporters: ['console'], outputPath });
+                expect(log.mock.calls.flat().join('\n')).toContain('Documentation Freshness Report');
+                await expect(fs.promises.access(outputPath)).rejects.toThrow();
+            });
+        });
+        it('overwrites a shared outputPath sequentially so the last string reporter wins', async () => {
+            await withOutputFile(cacheRoot, 'shared-reporter.out', async (outputPath) => {
+                captureLog();
+                await run({ ...baseConfig, reporters: ['json', 'markdown'], outputPath });
+                expect(await fs.promises.readFile(outputPath, 'utf-8')).toMatch(/^# Documentation Freshness Report/);
+                await run({ ...baseConfig, reporters: ['markdown', 'json'], outputPath });
+                expect(await fs.promises.readFile(outputPath, 'utf-8')).toMatch(/^\{/);
+            });
+        });
+        it('creates recursive output directories and reports each verbose label', async () => {
+            const outputRoot = path.join(cacheRoot, 'reporter-routing');
+            const outputPath = path.join(outputRoot, 'nested', 'report.out');
+            const log = captureLog();
+            try {
+                await run({ ...baseConfig, reporters: ['json', 'markdown'], outputPath, verbose: true });
+                expect(await fs.promises.readFile(outputPath, 'utf-8')).toMatch(/^# Documentation Freshness Report/);
+                expect(log.mock.calls.flat()).toContain(`JSON report written to ${outputPath}`);
+                expect(log.mock.calls.flat()).toContain(`Markdown report written to ${outputPath}`);
+            }
+            finally {
+                await fs.promises.rm(outputRoot, { recursive: true, force: true });
+            }
+        });
+        it('rejects when writing a string report fails', async () => {
+            const outputPath = path.join(cacheRoot, 'reporter-write-directory');
+            await fs.promises.mkdir(outputPath, { recursive: true });
+            try {
+                captureLog();
+                await expect(run({ ...baseConfig, reporters: ['json'], outputPath })).rejects.toThrow();
+            }
+            finally {
+                await fs.promises.rm(outputPath, { recursive: true, force: true });
+            }
+        });
+        it('reads the clock only for timestamped reporter paths and propagates clock failures', async () => {
+            const toISOString = vi.spyOn(Date.prototype, 'toISOString').mockImplementation(() => {
+                throw new Error('timestamp failed');
+            });
+            const log = captureLog();
+            try {
+                await expect(run({ ...baseConfig, reporters: ['console'] })).resolves.toBeDefined();
+                await expect(run({ ...baseConfig, reporters: ['json'] })).resolves.toBeDefined();
+                expect(toISOString).not.toHaveBeenCalled();
+                expect(log).toHaveBeenCalled();
+                await expect(run({ ...baseConfig, reporters: ['markdown'] })).rejects.toThrow('timestamp failed');
+            }
+            finally {
+                toISOString.mockRestore();
+            }
+        });
     });
     describe('graph and scoring', () => {
-        it('builds graph with git and saves cache', async () => {
+        it('builds graph without persisting an unused graph cache', async () => {
             captureLog();
             const cacheDir = '.doc-freshness-cache/runner-graph';
             try {
                 await run({ ...baseConfig, graph: { enabled: true }, cache: { enabled: true, dir: cacheDir } });
-                const exists = await fs.promises
-                    .access(path.join(process.cwd(), cacheDir, 'graph-cache.json'))
-                    .then(() => true)
-                    .catch(() => false);
-                expect(exists).toBe(true);
+                await expect(fs.promises.access(path.join(process.cwd(), cacheDir, 'graph-cache.json'))).rejects.toThrow();
+                await expect(fs.promises.access(path.join(process.cwd(), cacheDir, 'url-cache.json'))).resolves.toBeUndefined();
             }
             finally {
                 await fs.promises.rm(path.join(process.cwd(), cacheDir), { recursive: true, force: true }).catch(() => { });
             }
         });
-        it('generates json with scores to file', async () => {
-            await withOutputFile(cacheRoot, 'test-scored.json', async (outputPath) => {
+        it('does not read the clock when runner scored-result spreading fails', async () => {
+            const validationResults = {
+                documents: [],
+                summary: { total: 0, valid: 0, errors: 0, warnings: 0, skipped: 0 },
+            };
+            const proxiedResults = new Proxy(validationResults, {
+                get(target, property, receiver) {
+                    if (property === 'documents') {
+                        throw new Error('runner result getter failed');
+                    }
+                    return Reflect.get(target, property, receiver);
+                },
+            });
+            const scores = {
+                projectScore: 100,
+                projectGrade: 'A',
+                documents: [],
+                summary: { total: 0, gradeA: 0, gradeB: 0, gradeC: 0, gradeD: 0, gradeF: 0 },
+            };
+            const validate = vi.spyOn(ValidationEngine.prototype, 'validate').mockResolvedValue(proxiedResults);
+            const calculateScores = vi.spyOn(FreshnessScorer.prototype, 'calculateProjectScores').mockReturnValue(scores);
+            const clock = vi.spyOn(Date.prototype, 'toISOString');
+            try {
                 captureLog();
-                await run({
+                await expect(run({
                     ...baseConfig,
                     reporters: ['json'],
-                    outputPath,
                     graph: { enabled: true },
                     freshnessScoring: { enabled: true },
                     cache: { enabled: false },
-                });
-                expect(JSON.parse(await fs.promises.readFile(outputPath, 'utf-8'))).toHaveProperty('summary');
-            });
+                })).rejects.toThrow('runner result getter failed');
+                expect(clock).not.toHaveBeenCalled();
+            }
+            finally {
+                validate.mockRestore();
+                calculateScores.mockRestore();
+                clock.mockRestore();
+            }
         });
-        it('generates markdown with scores to file', async () => {
-            await withOutputFile(cacheRoot, 'test-scored.md', async (outputPath) => {
-                captureLog();
+        it('captures Markdown result references before the clock, then renders the base before scores', async () => {
+            const events = [];
+            const summary = { total: 1, valid: 1, errors: 0, warnings: 0, skipped: 0 };
+            const documents = [];
+            let currentSummary = summary;
+            let currentDocuments = documents;
+            const validationResults = {
+                get summary() {
+                    events.push('results:summary');
+                    return currentSummary;
+                },
+                set summary(value) {
+                    currentSummary = value;
+                },
+                get documents() {
+                    events.push('results:documents');
+                    return currentDocuments;
+                },
+                set documents(value) {
+                    currentDocuments = value;
+                },
+            };
+            const scores = {
+                get projectScore() {
+                    events.push('scores:projectScore');
+                    summary.total = 99;
+                    return 100;
+                },
+                projectGrade: 'A',
+                documents: [],
+                summary: { total: 0, gradeA: 0, gradeB: 0, gradeC: 0, gradeD: 0, gradeF: 0 },
+            };
+            const validate = vi.spyOn(ValidationEngine.prototype, 'validate').mockResolvedValue(validationResults);
+            const calculateScores = vi.spyOn(FreshnessScorer.prototype, 'calculateProjectScores').mockReturnValue(scores);
+            const clock = vi.spyOn(Date.prototype, 'toISOString').mockImplementation(() => {
+                events.push('clock');
+                summary.total = 7;
+                documents.push({ path: 'docs/captured.md', issues: [] });
+                validationResults.summary = { total: 50, valid: 50, errors: 0, warnings: 0, skipped: 0 };
+                validationResults.documents = [];
+                return '2025-01-02T03:04:05.678Z';
+            });
+            try {
+                const log = captureLog();
                 await run({
                     ...baseConfig,
                     reporters: ['markdown'],
-                    outputPath,
                     graph: { enabled: true },
                     freshnessScoring: { enabled: true },
                     cache: { enabled: false },
                 });
-                expect(await fs.promises.readFile(outputPath, 'utf-8')).toContain('Freshness Scores');
-            });
+                const report = log.mock.calls.flat().find((value) => typeof value === 'string' && value.startsWith('#'));
+                expect(events).toEqual(['results:summary', 'results:documents', 'clock', 'scores:projectScore']);
+                expect(report).toContain('| Total Checked | 7 |');
+                expect(report).toContain('docs/captured.md');
+                expect(report).not.toContain('| Total Checked | 99 |');
+                expect(report).not.toContain('| Total Checked | 50 |');
+            }
+            finally {
+                validate.mockRestore();
+                calculateScores.mockRestore();
+                clock.mockRestore();
+            }
+        });
+        it('does not inspect Markdown documents, clock, or scores when the summary getter fails', async () => {
+            const events = [];
+            let scoreRead = false;
+            const validationResults = {
+                get summary() {
+                    events.push('results:summary');
+                    throw new Error('Markdown summary failed');
+                },
+                get documents() {
+                    events.push('results:documents');
+                    return [];
+                },
+            };
+            const scores = {
+                get projectScore() {
+                    scoreRead = true;
+                    return 100;
+                },
+                projectGrade: 'A',
+                documents: [],
+                summary: { total: 0, gradeA: 0, gradeB: 0, gradeC: 0, gradeD: 0, gradeF: 0 },
+            };
+            const validate = vi.spyOn(ValidationEngine.prototype, 'validate').mockResolvedValue(validationResults);
+            const calculateScores = vi.spyOn(FreshnessScorer.prototype, 'calculateProjectScores').mockReturnValue(scores);
+            const clock = vi.spyOn(Date.prototype, 'toISOString');
+            try {
+                captureLog();
+                await expect(run({
+                    ...baseConfig,
+                    reporters: ['markdown'],
+                    graph: { enabled: true },
+                    freshnessScoring: { enabled: true },
+                    cache: { enabled: false },
+                })).rejects.toThrow('Markdown summary failed');
+                expect(events).toEqual(['results:summary']);
+                expect(clock).not.toHaveBeenCalled();
+                expect(scoreRead).toBe(false);
+            }
+            finally {
+                validate.mockRestore();
+                calculateScores.mockRestore();
+                clock.mockRestore();
+            }
         });
         it('generates enhanced with scores to file', async () => {
             await withOutputFile(cacheRoot, 'test-enhanced-scored.md', async (outputPath) => {
@@ -372,6 +711,50 @@ describe('runner', () => {
             });
         });
     });
+    describe('result cache policy', () => {
+        const modes = [false, true].flatMap((cache) => [false, true].flatMap((graph) => [false, true].flatMap((incremental) => [false, true].map((vector) => ({ cache, graph, incremental, vector })))));
+        it.each(modes)('applies cache=$cache graph=$graph incremental=$incremental vector=$vector under rootDir', async ({ cache, graph, incremental, vector }) => {
+            captureLog();
+            const rootDir = path.join(cacheRoot, 'runner-policy-root', `${Number(cache)}${Number(graph)}${Number(incremental)}${Number(vector)}`);
+            const resultDir = path.join(rootDir, '.result-cache');
+            const docPath = path.join(rootDir, 'README.md');
+            await fs.promises.mkdir(rootDir, { recursive: true });
+            await fs.promises.writeFile(docPath, '# Test');
+            vi.mocked(glob).mockResolvedValueOnce([docPath]);
+            await run({
+                ...baseConfig,
+                rootDir,
+                include: ['README.md'],
+                cache: { enabled: cache, dir: '.result-cache' },
+                graph: { enabled: graph },
+                incremental: { enabled: incremental },
+                vectorSearch: { enabled: vector },
+            });
+            const exists = (file) => fs.promises
+                .access(path.join(resultDir, file))
+                .then(() => true)
+                .catch(() => false);
+            expect(await exists('url-cache.json')).toBe(cache);
+            expect(await exists('file-hashes.json')).toBe(cache && incremental);
+            expect(await exists('embedding-cache.json')).toBe(cache && vector);
+            expect(await exists('graph-cache.json')).toBe(false);
+            if (!cache) {
+                await expect(fs.promises.access(resultDir)).rejects.toThrow();
+            }
+        });
+        it('continues when the URL cache cannot be saved', async () => {
+            const saveSpy = vi.spyOn(CacheManager.prototype, 'saveUrlCache').mockRejectedValueOnce(new Error('read only'));
+            const warnSpy = captureWarn();
+            try {
+                await expect(run({ ...baseConfig, cache: { enabled: true }, verbose: true })).resolves.toBeDefined();
+                expect(warnSpy).toHaveBeenCalledWith('Could not save the URL cache: read only');
+            }
+            finally {
+                saveSpy.mockRestore();
+                warnSpy.mockRestore();
+            }
+        });
+    });
     describe('incremental mode', () => {
         it('reports changed files in verbose mode', async () => {
             const spy = captureLog();
@@ -394,7 +777,7 @@ describe('runner', () => {
                     include: ['*.md'],
                     incremental: { enabled: true },
                     graph: { enabled: false },
-                    cache: { enabled: false, dir: '.cache' },
+                    cache: { enabled: true, dir: '.cache' },
                     reporters: [],
                 };
                 mockDocumentScan(docPath);
@@ -629,7 +1012,7 @@ describe('runner', () => {
                 const config = incrementalConfig(rootDir, {
                     manifestFiles: ['package.json'],
                     rules: { dependency: { enabled: true, severity: 'info' } },
-                    cache: { enabled: false, dir: cacheDir },
+                    cache: { enabled: true, dir: cacheDir },
                 });
                 mockDocumentScan(docPath);
                 expect((await run(config)).summary.total).toBe(1);
@@ -760,7 +1143,7 @@ describe('runner', () => {
                 await fs.promises.writeFile(docPath, 'No references');
                 const config = incrementalConfig(rootDir, {
                     rules: { 'file-path': { enabled: true } },
-                    cache: { enabled: false, dir: cacheDir },
+                    cache: { enabled: true, dir: cacheDir },
                 });
                 mockDocumentScan(docPath);
                 await run(config);
@@ -787,14 +1170,41 @@ describe('runner', () => {
                 expect((await run(config)).summary.errors).toBe(1);
             });
         });
+        it('checks every document without reading or saving state when caching is disabled', async () => {
+            const rootDir = path.join(cacheRoot, 'runner-incremental-disabled');
+            const docPath = path.join(rootDir, 'README.md');
+            const stateFile = path.join(rootDir, '.result-cache', 'file-hashes.json');
+            await fs.promises.mkdir(path.dirname(stateFile), { recursive: true });
+            await fs.promises.writeFile(docPath, '# Test');
+            await fs.promises.writeFile(stateFile, 'sentinel');
+            vi.mocked(glob).mockResolvedValueOnce([docPath]);
+            const readSpy = vi.spyOn(fs.promises, 'readFile');
+            const spy = captureLog();
+            await run({
+                ...baseConfig,
+                rootDir,
+                include: ['README.md'],
+                incremental: { enabled: true },
+                cache: { enabled: false, dir: '.result-cache' },
+                verbose: true,
+            });
+            expect(spy.mock.calls.flat().join('\n')).toContain('checking 1 changed files, skipping 0 unchanged');
+            expect(readSpy).not.toHaveBeenCalledWith(stateFile, 'utf-8');
+            expect(await fs.promises.readFile(stateFile, 'utf-8')).toBe('sentinel');
+            readSpy.mockRestore();
+            await fs.promises.rm(rootDir, { recursive: true, force: true });
+        });
     });
-    it('loads URL cache when cache is enabled', async () => {
+    it('loads and saves URL cache when graph is disabled', async () => {
         const cacheDir = '.doc-freshness-cache/runner-url';
         const fullDir = path.join(process.cwd(), cacheDir);
+        const cacheFile = path.join(fullDir, 'url-cache.json');
+        const cached = { 'https://cached.example': { result: { valid: true }, timestamp: Date.now() } };
         await fs.promises.mkdir(fullDir, { recursive: true });
-        await fs.promises.writeFile(path.join(fullDir, 'url-cache.json'), '{}');
+        await fs.promises.writeFile(cacheFile, JSON.stringify(cached));
         try {
             expect(await run({ ...baseConfig, cache: { enabled: true, dir: cacheDir } })).toBeDefined();
+            expect(await fs.promises.readFile(cacheFile, 'utf-8')).toBe(JSON.stringify(cached, null, 2));
         }
         finally {
             await fs.promises.rm(fullDir, { recursive: true, force: true }).catch(() => { });
@@ -854,6 +1264,7 @@ describe('runner', () => {
             const output = spy.mock.calls.flat().join('\n');
             expect(output).toContain('Indexing documentation');
             expect(output).toContain('Finding semantic mismatches');
+            expect(output).not.toContain('Building source code index');
         });
     });
     describe('runWithConfig', () => {
@@ -869,6 +1280,7 @@ describe('runner', () => {
         });
     });
     describe('vector search without prior graph', () => {
+        afterEach(() => vi.restoreAllMocks());
         it('builds source index independently when graph not enabled', async () => {
             const spy = captureLog();
             await run({
@@ -881,36 +1293,113 @@ describe('runner', () => {
             const output = spy.mock.calls.flat().join('\n');
             expect(output).toContain('Building source code index');
         });
-    });
-    describe('reporters with freshness scores', () => {
-        it('console reporter uses generateWithScores when scores available', async () => {
+        it('does not report index building when code-pattern validation already loaded it', async () => {
+            vi.spyOn(DocumentParser.prototype, 'scanDocuments').mockResolvedValue([
+                {
+                    path: 'doc.md',
+                    absolutePath: '/doc.md',
+                    content: '',
+                    format: 'markdown',
+                    lines: [],
+                    references: [{ type: 'code-pattern', value: 'RealSymbol', lineNumber: 1, raw: 'RealSymbol', sourceFile: 'doc.md' }],
+                },
+            ]);
             const spy = captureLog();
             await run({
                 ...baseConfig,
-                reporters: ['console'],
-                graph: { enabled: true },
-                freshnessScoring: { enabled: true },
-                cache: { enabled: false },
+                rules: { ...baseConfig.rules, 'code-pattern': { enabled: true } },
+                vectorSearch: { enabled: true },
+                graph: { enabled: false },
+                verbose: true,
             });
-            expect(spy.mock.calls.flat().join('\n')).toContain('Freshness Scores');
+            expect(spy.mock.calls.flat().join('\n')).not.toContain('Building source code index');
         });
-        it('json reporter generates with scores', async () => {
-            const spy = captureLog();
+    });
+    describe('shared source index', () => {
+        afterEach(() => vi.restoreAllMocks());
+        it('does not load source when no validator, graph, or vector consumer needs it', async () => {
+            const load = vi.spyOn(SourceIndex.prototype, 'load');
+            await run(baseConfig);
+            expect(load).not.toHaveBeenCalled();
+        });
+        it('uses one index instance for both built-in validators', async () => {
+            vi.spyOn(DocumentParser.prototype, 'scanDocuments').mockResolvedValue([
+                {
+                    path: 'doc.md',
+                    absolutePath: '/doc.md',
+                    content: '',
+                    format: 'markdown',
+                    lines: [],
+                    references: [
+                        { type: 'code-pattern', value: 'RealSymbol', lineNumber: 1, raw: 'RealSymbol', sourceFile: 'doc.md' },
+                        { type: 'code-snippet', kind: 'function-call', value: 'realFunction', lineNumber: 2, raw: '', sourceFile: 'doc.md' },
+                    ],
+                },
+            ]);
+            const load = vi.spyOn(SourceIndex.prototype, 'load');
+            await run({
+                ...baseConfig,
+                rules: {
+                    ...baseConfig.rules,
+                    'code-pattern': { enabled: true },
+                    'code-snippet': { enabled: true },
+                },
+            });
+            expect(load).toHaveBeenCalledTimes(2);
+            expect(new Set(load.mock.contexts).size).toBe(1);
+        });
+        it('feeds symbols to graph and all pattern files to vector search', async () => {
+            const symbols = new Map();
+            const patternFiles = new Map([['src/no-symbol.ts', { content: '// a useful comment', language: 'typescript' }]]);
+            const snapshot = {
+                symbols,
+                patternFiles,
+                snippetFiles: new Map(),
+                functionSignatures: new Map(),
+                interfaceKeys: new Map(),
+                exportsByFile: new Map(),
+                patternInputs: [],
+            };
+            const load = vi.spyOn(SourceIndex.prototype, 'load').mockResolvedValue(snapshot);
+            const buildGraph = vi.spyOn(GraphBuilder.prototype, 'buildGraph');
+            const indexCodeComments = vi.spyOn(VectorSearch.prototype, 'indexCodeComments');
+            captureLog();
+            await run({ ...baseConfig, graph: { enabled: true }, vectorSearch: { enabled: true } });
+            expect(buildGraph).toHaveBeenCalledWith([], symbols);
+            expect(indexCodeComments).toHaveBeenCalledWith([
+                { path: 'src/no-symbol.ts', content: '// a useful comment', language: 'typescript' },
+            ]);
+            expect(new Set(load.mock.contexts).size).toBe(1);
+        });
+        it('keeps custom validator overwrite independent from graph source loading', async () => {
+            const validateBatch = vi.fn().mockResolvedValue([]);
+            vi.spyOn(DocumentParser.prototype, 'scanDocuments').mockResolvedValue([
+                {
+                    path: 'doc.md',
+                    absolutePath: '/doc.md',
+                    content: '',
+                    format: 'markdown',
+                    lines: [],
+                    references: [{ type: 'code-pattern', value: 'Custom', lineNumber: 1, raw: 'Custom', sourceFile: 'doc.md' }],
+                },
+            ]);
+            const load = vi.spyOn(SourceIndex.prototype, 'load');
             await run({
                 ...baseConfig,
-                reporters: ['json'],
                 graph: { enabled: true },
-                freshnessScoring: { enabled: true },
-                cache: { enabled: false },
+                rules: { ...baseConfig.rules, 'code-pattern': { enabled: true } },
+                customValidators: { 'code-pattern': { validateBatch } },
             });
-            const jsonStr = spy.mock.calls.flat().find((a) => typeof a === 'string' && a.startsWith('{'));
-            expect(JSON.parse(jsonStr)).toHaveProperty('summary');
+            expect(validateBatch).toHaveBeenCalledOnce();
+            expect(load).toHaveBeenCalledOnce();
         });
-        it('markdown reporter generates with scores to stdout', async () => {
+    });
+    describe('reporters with freshness scores', () => {
+        it('console reporter uses generateWithScores when scores available', async () => {
             const spy = captureLog();
             await run({
                 ...baseConfig,
-                reporters: ['markdown'],
+                reporters: ['console'],
                 graph: { enabled: true },
                 freshnessScoring: { enabled: true },
                 cache: { enabled: false },