doc-freshness-checker 1.0.0

package/dist/validators/directoryValidator.test.js

@@ -0,0 +1,193 @@
+import fs from 'fs';
+import path from 'path';
+import { DirectoryValidator } from './directoryValidator.js';
+import { makeDoc as makeBaseDoc, makeRef as makeBaseRef } from '../test-utils/factories.js';
+function makeRef(value, overrides = {}) {
+    return makeBaseRef('directory-structure', value, overrides);
+}
+const doc = makeBaseDoc({
+    path: 'docs/README.md',
+    absolutePath: `${process.cwd()}/docs/README.md`,
+});
+describe('DirectoryValidator', () => {
+    const config = {
+        rootDir: process.cwd(),
+        rules: { 'directory-structure': { enabled: true, severity: 'warning', skipIllustrative: true } },
+    };
+    it('validates existing directories as valid (from project root)', async () => {
+        const validator = new DirectoryValidator();
+        const results = await validator.validateBatch([makeRef('src')], doc, config);
+        expect(results[0].valid).toBe(true);
+        expect(results[0].foundAt).toBe('src');
+    });
+    it('validates paths relative to document location', async () => {
+        const validator = new DirectoryValidator();
+        const results = await validator.validateBatch([makeRef('../src')], doc, config);
+        expect(results[0].valid).toBe(true);
+    });
+    it('marks missing paths as invalid', async () => {
+        const validator = new DirectoryValidator();
+        const results = await validator.validateBatch([makeRef('nonexistent-dir-xyz')], doc, config);
+        expect(results[0].valid).toBe(false);
+        expect(results[0].severity).toBe('warning');
+        expect(results[0].message).toContain('not found');
+    });
+    it('skips illustrative paths when configured', async () => {
+        const validator = new DirectoryValidator();
+        const results = await validator.validateBatch([makeRef('YourProject')], doc, config);
+        expect(results[0].skipped).toBe(true);
+    });
+    it('validates illustrative paths when skipIllustrative is false', async () => {
+        const validator = new DirectoryValidator();
+        const noSkipConfig = {
+            ...config,
+            rules: { 'directory-structure': { enabled: true, severity: 'warning', skipIllustrative: false } },
+        };
+        const results = await validator.validateBatch([makeRef('YourProject')], doc, noSkipConfig);
+        expect(results[0].valid).toBe(false);
+        expect(results[0].message).toContain('illustrative');
+    });
+    it('handles extractor-marked illustrative paths', async () => {
+        const validator = new DirectoryValidator();
+        const results = await validator.validateBatch([makeRef('example-dir', { isIllustrative: true })], doc, config);
+        expect(results[0].skipped).toBe(true);
+    });
+    it('caches results for repeated path lookups', async () => {
+        const validator = new DirectoryValidator();
+        await validator.validateBatch([makeRef('src')], doc, config);
+        const results = await validator.validateBatch([makeRef('src')], doc, config);
+        expect(results[0].valid).toBe(true);
+    });
+    it('caches invalid results too', async () => {
+        const validator = new DirectoryValidator();
+        await validator.validateBatch([makeRef('xyz-missing')], doc, config);
+        const results = await validator.validateBatch([makeRef('xyz-missing')], doc, config);
+        expect(results[0].valid).toBe(false);
+    });
+    it('provides suggestions for similar paths (e.g., case mismatch)', async () => {
+        const validator = new DirectoryValidator();
+        const results = await validator.validateBatch([makeRef('SRC')], doc, config);
+        if (!results[0].valid && results[0].suggestion) {
+            expect(results[0].suggestion).toContain('src');
+        }
+    });
+    it('provides suggestions for similar names (similarity ratio)', async () => {
+        const validator = new DirectoryValidator();
+        const results = await validator.validateBatch([makeRef('scr')], doc, config);
+        if (results[0].suggestion) {
+            expect(results[0].suggestion).toBeTruthy();
+        }
+    });
+    it('rejects paths that escape project root', async () => {
+        const validator = new DirectoryValidator();
+        const results = await validator.validateBatch([makeRef('../../../../etc/passwd')], doc, config);
+        expect(results[0].valid).toBe(false);
+        expect(results[0].message).toContain('escapes project root');
+    });
+    it('uses custom illustrative patterns from config', async () => {
+        const validator = new DirectoryValidator();
+        const customConfig = {
+            rootDir: process.cwd(),
+            rules: { 'directory-structure': { enabled: true, skipIllustrative: true, illustrativePatterns: ['^custom-example'] } },
+        };
+        const results = await validator.validateBatch([makeRef('custom-example-dir')], doc, customConfig);
+        expect(results[0].skipped).toBe(true);
+    });
+    it('uses default severity when not configured', async () => {
+        const validator = new DirectoryValidator();
+        const minConfig = { rootDir: process.cwd() };
+        const results = await validator.validateBatch([makeRef('nonexistent-abc')], doc, minConfig);
+        expect(results[0].valid).toBe(false);
+        expect(results[0].severity).toBe('warning');
+    });
+    it('returns cached invalid result with correct fields', async () => {
+        const validator = new DirectoryValidator();
+        await validator.validateBatch([makeRef('xyz-cached-miss')], doc, config);
+        const results = await validator.validateBatch([makeRef('xyz-cached-miss')], doc, config);
+        expect(results[0].valid).toBe(false);
+        expect(results[0].message).toContain('not found');
+        expect(results[0].severity).toBe('warning');
+    });
+    it('suggests singular/plural matches', async () => {
+        const validator = new DirectoryValidator();
+        const results = await validator.validateBatch([makeRef('src/validator')], doc, config);
+        if (!results[0].valid && results[0].suggestion) {
+            expect(results[0].suggestion).toBeTruthy();
+        }
+    });
+    it('returns null suggestion when parent dir does not exist', async () => {
+        const validator = new DirectoryValidator();
+        const results = await validator.validateBatch([makeRef('zzznope/xyzabc123/deep/child')], doc, config);
+        expect(results[0].valid).toBe(false);
+        expect(results[0].suggestion).toBeNull();
+    });
+    it('reports illustrative not-found path with correct message when skipIllustrative is false', async () => {
+        const validator = new DirectoryValidator();
+        const noSkipConfig = {
+            ...config,
+            rules: { 'directory-structure': { enabled: true, skipIllustrative: false } },
+        };
+        const results = await validator.validateBatch([makeRef('ExampleProject/nonexistent-file-zzz.ts')], doc, noSkipConfig);
+        expect(results[0].valid).toBe(false);
+        expect(results[0].message).toContain('illustrative');
+    });
+    it('handles illustrative path escaping project root', async () => {
+        const validator = new DirectoryValidator();
+        const noSkipConfig = {
+            ...config,
+            rules: { 'directory-structure': { enabled: true, skipIllustrative: false } },
+        };
+        const results = await validator.validateBatch([makeRef('../../../../etc/YourProject')], doc, noSkipConfig);
+        expect(results[0].valid).toBe(false);
+        expect(results[0].message).toContain('escapes project root');
+    });
+    it('does not leak custom illustrative patterns across validations', async () => {
+        const validator = new DirectoryValidator();
+        const firstConfig = {
+            rootDir: process.cwd(),
+            rules: { 'directory-structure': { enabled: true, skipIllustrative: true, illustrativePatterns: ['^custom-leak-dir'] } },
+        };
+        const secondConfig = {
+            rootDir: process.cwd(),
+            rules: { 'directory-structure': { enabled: true, severity: 'warning', skipIllustrative: false } },
+        };
+        const first = await validator.validateBatch([makeRef('custom-leak-dir/path')], doc, firstConfig);
+        expect(first[0].skipped).toBe(true);
+        const second = await validator.validateBatch([makeRef('custom-leak-dir/path')], doc, secondConfig);
+        expect(second[0].valid).toBe(false);
+        expect(second[0].message).toContain('Directory/file not found:');
+    });
+    it('does not reuse cache across different document contexts', async () => {
+        const validator = new DirectoryValidator();
+        const root = path.join(process.cwd(), '.doc-freshness-cache', 'directory-context');
+        const docsA = path.join(root, 'docs-a');
+        const docsB = path.join(root, 'docs-b');
+        await fs.promises.mkdir(docsA, { recursive: true });
+        await fs.promises.mkdir(docsB, { recursive: true });
+        await fs.promises.writeFile(path.join(docsA, 'target.txt'), 'exists in docs-a only');
+        const firstDoc = {
+            ...doc,
+            path: 'docs-a/readme.md',
+            absolutePath: `${root}/docs-a/readme.md`,
+        };
+        const secondDoc = {
+            ...doc,
+            path: 'docs-b/readme.md',
+            absolutePath: `${root}/docs-b/readme.md`,
+        };
+        const contextConfig = {
+            ...config,
+            rootDir: root,
+        };
+        try {
+            const first = await validator.validateBatch([makeRef('./target.txt')], firstDoc, contextConfig);
+            expect(first[0].valid).toBe(true);
+            const second = await validator.validateBatch([makeRef('./target.txt')], secondDoc, contextConfig);
+            expect(second[0].valid).toBe(false);
+        }
+        finally {
+            await fs.promises.rm(root, { recursive: true, force: true }).catch(() => { });
+        }
+    });
+});
+//# sourceMappingURL=directoryValidator.test.js.map

package/dist/validators/directoryValidator.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"directoryValidator.test.js","sourceRoot":"","sources":["../../src/validators/directoryValidator.test.ts"],"names":[],"mappings":"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"}

package/dist/validators/fileValidator.d.ts

@@ -0,0 +1,16 @@
+import type { DocFreshnessConfig, Document, Reference, ValidationResult } from '../types.js';
+/**
+ * Validates that file path references exist
+ */
+export declare class FileValidator {
+    private directoryCache;
+    private customPatterns;
+    constructor();
+    /**
+     * Initialize custom illustrative patterns from config
+     */
+    private initCustomPatterns;
+    validateBatch(references: Reference[], document: Document, config: DocFreshnessConfig): Promise<ValidationResult[]>;
+    private validateReference;
+    private findSuggestion;
+}

package/dist/validators/fileValidator.js

@@ -0,0 +1,114 @@
+import fs from 'fs';
+import path from 'path';
+import { findSimilar } from '../utils/similarity.js';
+import { isIllustrativePath, compilePatterns } from '../utils/illustrativePatterns.js';
+import { isWithinRoot, resolveDocumentDir, resolveProjectRoot } from '../utils/pathSecurity.js';
+import { createIllustrativeSkippedResult, getRuleSeverity, severityForIllustrative } from '../utils/validation.js';
+/**
+ * Validates that file path references exist
+ */
+export class FileValidator {
+    directoryCache;
+    customPatterns;
+    constructor() {
+        this.directoryCache = new Map();
+        this.customPatterns = [];
+    }
+    /**
+     * Initialize custom illustrative patterns from config
+     */
+    initCustomPatterns(config) {
+        const configPatterns = config.rules?.['file-path']?.illustrativePatterns;
+        this.customPatterns = configPatterns && configPatterns.length > 0 ? compilePatterns(configPatterns) : [];
+    }
+    async validateBatch(references, document, config) {
+        this.initCustomPatterns(config);
+        const results = [];
+        const rootDir = resolveProjectRoot(config.rootDir);
+        const docDir = resolveDocumentDir(rootDir, document.path);
+        const skipIllustrative = config.rules?.['file-path']?.skipIllustrative !== false;
+        for (const ref of references) {
+            // Check if this is an illustrative path
+            const illustrative = ref.isIllustrative || isIllustrativePath(ref.value, this.customPatterns);
+            if (illustrative && skipIllustrative) {
+                results.push(createIllustrativeSkippedResult(ref, 'Skipped: illustrative/example path'));
+                continue;
+            }
+            const result = await this.validateReference(ref, docDir, rootDir, config, illustrative);
+            results.push(result);
+        }
+        return results;
+    }
+    async validateReference(ref, docDir, rootDir, config, isIllustrative = false) {
+        // Handle both relative and absolute paths
+        let resolvedPath;
+        if (path.isAbsolute(ref.value)) {
+            resolvedPath = path.resolve(ref.value);
+        }
+        else {
+            resolvedPath = path.resolve(docDir, ref.value);
+        }
+        // Normalize path
+        resolvedPath = path.normalize(resolvedPath);
+        const baseSeverity = getRuleSeverity(config, 'file-path', 'error');
+        // Prevent probing files outside the configured project root
+        if (!isWithinRoot(resolvedPath, rootDir)) {
+            return {
+                reference: ref,
+                valid: false,
+                severity: severityForIllustrative(isIllustrative, baseSeverity),
+                message: isIllustrative ? `Path escapes project root (illustrative): ${ref.value}` : `Path escapes project root: ${ref.value}`,
+                suggestion: null,
+                resolvedPath,
+            };
+        }
+        try {
+            await fs.promises.access(resolvedPath);
+            return {
+                reference: ref,
+                valid: true,
+                resolvedPath,
+            };
+        }
+        catch {
+            // File doesn't exist - try to find similar files
+            const suggestion = await this.findSuggestion(ref.value, docDir, rootDir);
+            // Reduce severity for illustrative paths that weren't skipped
+            return {
+                reference: ref,
+                valid: false,
+                severity: severityForIllustrative(isIllustrative, baseSeverity),
+                message: isIllustrative ? `File not found (illustrative): ${ref.value}` : `File not found: ${ref.value}`,
+                suggestion: suggestion ? `Did you mean: ${suggestion}?` : null,
+                resolvedPath,
+            };
+        }
+    }
+    async findSuggestion(refPath, docDir, rootDir) {
+        const dir = path.dirname(path.resolve(docDir, refPath));
+        const fileName = path.basename(refPath);
+        if (!isWithinRoot(dir, rootDir)) {
+            return null;
+        }
+        // Check if directory exists
+        try {
+            await fs.promises.access(dir);
+        }
+        catch {
+            return null;
+        }
+        // Get cached directory listing or create new one
+        if (!this.directoryCache.has(dir)) {
+            try {
+                const files = await fs.promises.readdir(dir);
+                this.directoryCache.set(dir, files);
+            }
+            catch {
+                return null;
+            }
+        }
+        const files = this.directoryCache.get(dir);
+        return findSimilar(fileName, files);
+    }
+}
+//# sourceMappingURL=fileValidator.js.map

package/dist/validators/fileValidator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileValidator.js","sourceRoot":"","sources":["../../src/validators/fileValidator.ts"],"names":[],"mappings":"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"}

package/dist/validators/fileValidator.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/validators/fileValidator.test.js

@@ -0,0 +1,108 @@
+import { FileValidator } from './fileValidator.js';
+import { makeDoc as makeBaseDoc, makeRef as makeBaseRef } from '../test-utils/factories.js';
+function makeRef(value, overrides = {}) {
+    return makeBaseRef('file-path', value, overrides);
+}
+function makeDoc(docPath = 'docs/README.md') {
+    return makeBaseDoc({ path: docPath, absolutePath: `/project/${docPath}` });
+}
+describe('FileValidator', () => {
+    const validator = new FileValidator();
+    const config = {
+        rootDir: process.cwd(),
+        rules: { 'file-path': { enabled: true, severity: 'error', skipIllustrative: true } },
+    };
+    it('validates existing files as valid', async () => {
+        const results = await validator.validateBatch([makeRef('../package.json')], makeDoc(), { ...config, rootDir: process.cwd() });
+        expect(results[0].valid).toBe(true);
+    });
+    it('marks missing files as invalid', async () => {
+        const results = await validator.validateBatch([makeRef('../nonexistent-xyz.json')], makeDoc(), { ...config, rootDir: process.cwd() });
+        expect(results[0].valid).toBe(false);
+        expect(results[0].severity).toBe('error');
+        expect(results[0].message).toContain('File not found');
+    });
+    it('skips illustrative paths when configured', async () => {
+        const results = await validator.validateBatch([makeRef('YourProject/file.ts')], makeDoc(), config);
+        expect(results[0].valid).toBe(true);
+        expect(results[0].skipped).toBe(true);
+    });
+    it('flags illustrative paths when skipIllustrative is false', async () => {
+        const noSkipConfig = {
+            ...config,
+            rules: { 'file-path': { enabled: true, severity: 'error', skipIllustrative: false } },
+        };
+        const results = await validator.validateBatch([makeRef('ExampleFile.ts')], makeDoc(), noSkipConfig);
+        expect(results[0].severity).toBe('info');
+    });
+    it('rejects paths that escape project root', async () => {
+        const results = await validator.validateBatch([makeRef('/etc/passwd')], makeDoc(), config);
+        expect(results[0].valid).toBe(false);
+        expect(results[0].message).toContain('escapes project root');
+    });
+    it('handles pre-marked illustrative references', async () => {
+        const results = await validator.validateBatch([makeRef('real-looking-path.ts', { isIllustrative: true })], makeDoc(), config);
+        expect(results[0].skipped).toBe(true);
+    });
+    it('suggests similar files for typos', async () => {
+        const results = await validator.validateBatch([makeRef('../package.jso')], makeDoc(), { ...config, rootDir: process.cwd() });
+        expect(results[0].valid).toBe(false);
+        if (results[0].suggestion) {
+            expect(results[0].suggestion).toContain('package.json');
+        }
+    });
+    it('returns null suggestion when file directory does not exist', async () => {
+        const results = await validator.validateBatch([makeRef('zzz-nonexistent-dir/some-file.ts')], makeDoc(), {
+            ...config,
+            rootDir: process.cwd(),
+        });
+        expect(results[0].valid).toBe(false);
+    });
+    it('reports illustrative path escaping project root', async () => {
+        const noSkipConfig = {
+            ...config,
+            rules: { 'file-path': { enabled: true, severity: 'error', skipIllustrative: false } },
+        };
+        const results = await validator.validateBatch([makeRef('/etc/YourProject/file.ts')], makeDoc(), noSkipConfig);
+        expect(results[0].valid).toBe(false);
+        expect(results[0].message).toContain('illustrative');
+        expect(results[0].message).toContain('escapes project root');
+    });
+    it('uses custom illustrative patterns from config', async () => {
+        const customConfig = {
+            rootDir: process.cwd(),
+            rules: { 'file-path': { enabled: true, skipIllustrative: true, illustrativePatterns: ['^custom-prefix'] } },
+        };
+        const validator2 = new FileValidator();
+        const results = await validator2.validateBatch([makeRef('custom-prefix-file.ts')], makeDoc(), customConfig);
+        expect(results[0].skipped).toBe(true);
+    });
+    it('caches directory listings for repeated lookups', async () => {
+        const validator2 = new FileValidator();
+        await validator2.validateBatch([makeRef('../package-typo.json')], makeDoc(), { ...config, rootDir: process.cwd() });
+        const results = await validator2.validateBatch([makeRef('../another-typo.json')], makeDoc(), { ...config, rootDir: process.cwd() });
+        expect(results[0].valid).toBe(false);
+    });
+    it('handles absolute paths within project root', async () => {
+        const absPath = `${process.cwd()}/package.json`;
+        const results = await validator.validateBatch([makeRef(absPath)], makeDoc(), { ...config, rootDir: process.cwd() });
+        expect(results[0].valid).toBe(true);
+    });
+    it('does not leak custom illustrative patterns across validations', async () => {
+        const validator2 = new FileValidator();
+        const firstConfig = {
+            rootDir: process.cwd(),
+            rules: { 'file-path': { enabled: true, skipIllustrative: true, illustrativePatterns: ['^custom-leak-test'] } },
+        };
+        const secondConfig = {
+            rootDir: process.cwd(),
+            rules: { 'file-path': { enabled: true, severity: 'error', skipIllustrative: false } },
+        };
+        const first = await validator2.validateBatch([makeRef('custom-leak-test-file.ts')], makeDoc(), firstConfig);
+        expect(first[0].skipped).toBe(true);
+        const second = await validator2.validateBatch([makeRef('custom-leak-test-file.ts')], makeDoc(), secondConfig);
+        expect(second[0].valid).toBe(false);
+        expect(second[0].message).toContain('File not found:');
+    });
+});
+//# sourceMappingURL=fileValidator.test.js.map

package/dist/validators/fileValidator.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileValidator.test.js","sourceRoot":"","sources":["../../src/validators/fileValidator.test.ts"],"names":[],"mappings":"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"}

package/dist/validators/urlValidator.d.ts

@@ -0,0 +1,25 @@
+import type { DocFreshnessConfig, Document, Reference, UrlCacheEntry, ValidationResult } from '../types.js';
+/**
+ * Validates external URLs are accessible
+ */
+export declare class UrlValidator {
+    private cache;
+    constructor();
+    validateBatch(references: Reference[], _document: Document, config: DocFreshnessConfig): Promise<ValidationResult[]>;
+    private validateUrl;
+    private fetchWithTimeout;
+    /**
+     * Check if URL is a GitHub URL (repos can be private)
+     */
+    private isGitHubUrl;
+    /**
+     * Load cache from external source
+     */
+    loadCache(cacheData: Record<string, UrlCacheEntry>): void;
+    /**
+     * Export cache for persistence
+     */
+    exportCache(): Record<string, UrlCacheEntry>;
+    private resolvesToPrivateAddress;
+    private setCacheEntry;
+}