doc-freshness-checker 1.0.0

package/dist/validators/dependencyValidator.js

@@ -0,0 +1,102 @@
+import fs from 'fs';
+import path from 'path';
+/**
+ * Validates that mentioned dependencies exist in manifest files
+ */
+export class DependencyValidator {
+    dependencies;
+    loadedFromKey;
+    constructor() {
+        this.dependencies = null;
+        this.loadedFromKey = null;
+    }
+    async loadDependencies(config) {
+        const rootDir = config.rootDir || process.cwd();
+        const manifestFiles = config.manifestFiles || ['package.json'];
+        const configKey = `${rootDir}::${manifestFiles.join('|')}`;
+        if (this.dependencies && this.loadedFromKey === configKey)
+            return;
+        this.dependencies = new Set();
+        this.loadedFromKey = configKey;
+        for (const manifestPath of manifestFiles) {
+            const fullPath = path.join(rootDir, manifestPath);
+            const fileName = path.basename(manifestPath);
+            try {
+                const content = await fs.promises.readFile(fullPath, 'utf-8');
+                const deps = await this.parseManifest(fileName, content);
+                for (const dep of deps) {
+                    this.dependencies.add(dep.toLowerCase());
+                }
+            }
+            catch {
+                // Manifest not found
+            }
+        }
+    }
+    async parseManifest(fileName, content) {
+        const parser = manifestDependencyParsers[fileName];
+        return parser ? parser(content) : [];
+    }
+    async validateBatch(references, _document, config) {
+        await this.loadDependencies(config);
+        const results = [];
+        for (const ref of references) {
+            const pkg = ref.value.toLowerCase();
+            // Check if package exists in dependencies
+            const found = this.dependencies.has(pkg);
+            if (found) {
+                results.push({
+                    reference: ref,
+                    valid: true,
+                });
+            }
+            else {
+                results.push({
+                    reference: ref,
+                    valid: false,
+                    severity: config.rules?.dependency?.severity || 'info',
+                    message: `Package not found in dependencies: ${ref.value}`,
+                });
+            }
+        }
+        return results;
+    }
+}
+const manifestDependencyParsers = {
+    'package.json': (content) => {
+        const json = JSON.parse(content);
+        return ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'].flatMap((key) => Object.keys(json[key] || {}));
+    },
+    'requirements.txt': (content) => content
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line && !line.startsWith('#'))
+        .map((line) => line.match(/^([a-zA-Z0-9\-_]+)/)?.[1])
+        .filter((dep) => Boolean(dep)),
+    'pyproject.toml': (content) => {
+        const depsMatch = content.match(/\[project\.dependencies\]([\s\S]*?)(?:\[|$)/);
+        if (!depsMatch)
+            return [];
+        return Array.from(depsMatch[1].matchAll(/"([^"<>=!]+)/g), (match) => match[1].split(/[<>=!]/)[0]);
+    },
+    'go.mod': (content) => {
+        const requireMatch = content.match(/require\s+\(([\s\S]*?)\)/);
+        if (!requireMatch)
+            return [];
+        return requireMatch[1]
+            .split('\n')
+            .map((line) => line.trim().match(/^([^\s]+)/)?.[1])
+            .filter((dep) => Boolean(dep));
+    },
+    'Cargo.toml': (content) => {
+        const depsMatch = content.match(/\[dependencies\]([\s\S]*?)(?:\[|$)/);
+        if (!depsMatch)
+            return [];
+        return depsMatch[1]
+            .split('\n')
+            .map((line) => line.match(/^([a-zA-Z0-9\-_]+)\s*=/)?.[1])
+            .filter((dep) => Boolean(dep));
+    },
+    'pom.xml': (content) => Array.from(content.matchAll(/<artifactId>([^<]+)<\/artifactId>/g), (match) => match[1]),
+};
+//# sourceMappingURL=dependencyValidator.js.map

package/dist/validators/dependencyValidator.js.map

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

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

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

package/dist/validators/dependencyValidator.test.js

@@ -0,0 +1,179 @@
+import fs from 'fs';
+import path from 'path';
+import { DependencyValidator } from './dependencyValidator.js';
+import { makeDoc, makeRef as makeBaseRef } from '../test-utils/factories.js';
+function makeRef(value) {
+    return makeBaseRef('dependency', value, { ecosystem: 'npm' });
+}
+const doc = makeDoc();
+const tmpBase = path.join(process.cwd(), '.doc-freshness-cache', 'dep-test');
+async function writeManifestAndValidate(dirName, fileName, content, pkgNames) {
+    const dir = path.join(tmpBase, dirName);
+    const filePath = path.join(dir, fileName);
+    await fs.promises.mkdir(dir, { recursive: true });
+    await fs.promises.writeFile(filePath, content);
+    const validator = new DependencyValidator();
+    const config = {
+        rootDir: process.cwd(),
+        manifestFiles: [path.relative(process.cwd(), filePath)],
+    };
+    const results = await validator.validateBatch(pkgNames.map(makeRef), doc, config);
+    return results.map((r) => r.valid);
+}
+describe('DependencyValidator', () => {
+    afterAll(async () => {
+        await fs.promises.rm(tmpBase, { recursive: true, force: true }).catch(() => { });
+    });
+    it('validates dependencies found in package.json', async () => {
+        const validator = new DependencyValidator();
+        const config = { rootDir: process.cwd(), manifestFiles: ['package.json'] };
+        const results = await validator.validateBatch([makeRef('vitest')], doc, config);
+        expect(results[0].valid).toBe(true);
+    });
+    it('marks unknown dependencies as invalid with default severity', async () => {
+        const validator = new DependencyValidator();
+        const config = { rootDir: process.cwd(), manifestFiles: ['package.json'] };
+        const results = await validator.validateBatch([makeRef('nonexistent-pkg-xyz')], doc, config);
+        expect(results[0].valid).toBe(false);
+        expect(results[0].severity).toBe('info');
+        expect(results[0].message).toContain('nonexistent-pkg-xyz');
+    });
+    it('respects custom severity from config', async () => {
+        const validator = new DependencyValidator();
+        const config = {
+            rootDir: process.cwd(),
+            manifestFiles: ['package.json'],
+            rules: { dependency: { severity: 'error' } },
+        };
+        const results = await validator.validateBatch([makeRef('nonexistent-pkg')], doc, config);
+        expect(results[0].severity).toBe('error');
+    });
+    it('handles missing manifest files gracefully', async () => {
+        const validator = new DependencyValidator();
+        const config = { rootDir: process.cwd(), manifestFiles: ['nonexistent.json'] };
+        const results = await validator.validateBatch([makeRef('anything')], doc, config);
+        expect(results[0].valid).toBe(false);
+    });
+    it('uses default manifestFiles when not specified', async () => {
+        const validator = new DependencyValidator();
+        const config = { rootDir: process.cwd() };
+        const results = await validator.validateBatch([makeRef('vitest')], doc, config);
+        expect(results[0].valid).toBe(true);
+    });
+    describe('manifest format parsing', () => {
+        async function writeAndValidate(fileName, content, pkgNames) {
+            const dirName = fileName.replace(/\./g, '-');
+            return writeManifestAndValidate(dirName, fileName, content, pkgNames);
+        }
+        it('parses requirements.txt', async () => {
+            const results = await writeAndValidate('requirements.txt', 'flask>=2.0\nrequests\n# comment\ndjango==4.0', [
+                'flask',
+                'requests',
+                'django',
+            ]);
+            expect(results).toEqual([true, true, true]);
+        });
+        it('parses pyproject.toml', async () => {
+            const results = await writeAndValidate('pyproject.toml', '[project.dependencies]\n"fastapi>=0.100"\n"uvicorn"', [
+                'fastapi',
+                'uvicorn',
+            ]);
+            expect(results).toEqual([true, true]);
+        });
+        it('parses go.mod', async () => {
+            const results = await writeAndValidate('go.mod', 'module example.com/app\n\ngo 1.21\n\nrequire (\n\tgithub.com/gin-gonic/gin v1.9.1\n\tgolang.org/x/text v0.14.0\n)', ['github.com/gin-gonic/gin', 'golang.org/x/text']);
+            expect(results).toEqual([true, true]);
+        });
+        it('parses Cargo.toml', async () => {
+            const results = await writeAndValidate('Cargo.toml', '[dependencies]\nserde = "1.0"\ntokio = "1.28"', ['serde', 'tokio']);
+            expect(results).toEqual([true, true]);
+        });
+        it('parses pom.xml', async () => {
+            const results = await writeAndValidate('pom.xml', '<project><dependencies><dependency><artifactId>spring-boot</artifactId></dependency></dependencies></project>', ['spring-boot']);
+            expect(results).toEqual([true]);
+        });
+    });
+    it('is case-insensitive for dependency names', async () => {
+        const validator = new DependencyValidator();
+        const config = { rootDir: process.cwd(), manifestFiles: ['package.json'] };
+        const results = await validator.validateBatch([makeRef('Vitest'), makeRef('VITEST')], doc, config);
+        expect(results.every((r) => r.valid)).toBe(true);
+    });
+    describe('manifest edge cases', () => {
+        async function writeAndValidate(fileName, content, pkgNames) {
+            const dirName = `edge-${fileName.replace(/\./g, '-')}`;
+            return writeManifestAndValidate(dirName, fileName, content, pkgNames);
+        }
+        it('handles go.mod without require block', async () => {
+            const results = await writeAndValidate('go.mod', 'module example.com/app\n\ngo 1.22\n', ['example.com/app']);
+            expect(results).toEqual([false]);
+        });
+        it('handles pyproject.toml without project.dependencies section', async () => {
+            const results = await writeAndValidate('pyproject.toml', '[project]\nname = "myapp"\nversion = "1.0"\n', ['myapp']);
+            expect(results).toEqual([false]);
+        });
+        it('handles Cargo.toml without dependencies section', async () => {
+            const results = await writeAndValidate('Cargo.toml', '[package]\nname = "myapp"\nversion = "0.1.0"\n', ['myapp']);
+            expect(results).toEqual([false]);
+        });
+        it('handles unknown manifest format gracefully', async () => {
+            const results = await writeAndValidate('build.gradle', 'implementation "org.something:artifact:1.0"\n', ['org.something']);
+            expect(results).toEqual([false]);
+        });
+        it('handles requirements.txt with blank lines and comments only', async () => {
+            const results = await writeAndValidate('requirements.txt', '# this is a comment\n\n# another comment\n', ['flask']);
+            expect(results).toEqual([false]);
+        });
+        it('handles pom.xml with no artifactId', async () => {
+            const results = await writeAndValidate('pom.xml', '<project><groupId>com.example</groupId></project>', ['anything']);
+            expect(results).toEqual([false]);
+        });
+        it('parses package.json with peerDependencies and optionalDependencies', async () => {
+            const results = await writeAndValidate('package.json', JSON.stringify({
+                dependencies: { 'dep-a': '1.0' },
+                devDependencies: { 'dev-b': '2.0' },
+                peerDependencies: { 'peer-c': '>=3.0' },
+                optionalDependencies: { 'opt-d': '4.0' },
+            }), ['dep-a', 'dev-b', 'peer-c', 'opt-d']);
+            expect(results).toEqual([true, true, true, true]);
+        });
+        it('parses package.json with only dependencies (no devDependencies)', async () => {
+            const results = await writeAndValidate('package.json', JSON.stringify({ dependencies: { 'only-dep': '1.0' } }), ['only-dep']);
+            expect(results).toEqual([true]);
+        });
+        it('parses requirements.txt with pip editable installs (non-matching lines)', async () => {
+            const results = await writeAndValidate('requirements.txt', '-e git+https://github.com/org/repo.git#egg=mypackage\nflask>=2.0\n-r other-requirements.txt', ['flask']);
+            expect(results).toEqual([true]);
+        });
+    });
+    it('uses process.cwd when rootDir is not specified', async () => {
+        const validator = new DependencyValidator();
+        const config = { manifestFiles: ['package.json'] };
+        const results = await validator.validateBatch([makeRef('vitest')], doc, config);
+        expect(results[0].valid).toBe(true);
+    });
+    it('reloads dependencies when manifest config changes on the same instance', async () => {
+        const validator = new DependencyValidator();
+        const dirA = path.join(tmpBase, 'reload-a');
+        const dirB = path.join(tmpBase, 'reload-b');
+        await fs.promises.mkdir(dirA, { recursive: true });
+        await fs.promises.mkdir(dirB, { recursive: true });
+        const manifestA = path.join(dirA, 'package.json');
+        const manifestB = path.join(dirB, 'package.json');
+        await fs.promises.writeFile(manifestA, JSON.stringify({ dependencies: { 'pkg-a': '1.0.0' } }));
+        await fs.promises.writeFile(manifestB, JSON.stringify({ dependencies: { 'pkg-b': '1.0.0' } }));
+        const configA = {
+            rootDir: process.cwd(),
+            manifestFiles: [path.relative(process.cwd(), manifestA)],
+        };
+        const configB = {
+            rootDir: process.cwd(),
+            manifestFiles: [path.relative(process.cwd(), manifestB)],
+        };
+        const first = await validator.validateBatch([makeRef('pkg-a')], doc, configA);
+        expect(first[0].valid).toBe(true);
+        const second = await validator.validateBatch([makeRef('pkg-b')], doc, configB);
+        expect(second[0].valid).toBe(true);
+    });
+});
+//# sourceMappingURL=dependencyValidator.test.js.map

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

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

package/dist/validators/directoryValidator.d.ts

@@ -0,0 +1,30 @@
+import type { DocFreshnessConfig, Document, Reference, ValidationResult } from '../types.js';
+/**
+ * Validates that directory structure references exist
+ *
+ * Simple approach: The extractor builds full paths from the tree structure,
+ * so we just check if each path exists from the project root.
+ */
+export declare class DirectoryValidator {
+    private pathCache;
+    private customPatterns;
+    constructor();
+    /**
+     * Initialize custom illustrative patterns from config
+     */
+    private initCustomPatterns;
+    validateBatch(references: Reference[], document: Document, config: DocFreshnessConfig): Promise<ValidationResult[]>;
+    private validateReference;
+    private pathExists;
+    /**
+     * Try to find a similar path for suggestions
+     * Handles common issues like singular/plural mismatches
+     */
+    private findSimilarPath;
+    /**
+     * Calculate similarity between two strings (0-1)
+     * Uses a combination of techniques for better matching
+     */
+    private calculateSimilarity;
+    private toSingular;
+}

package/dist/validators/directoryValidator.js

@@ -0,0 +1,192 @@
+import fs from 'fs';
+import path from 'path';
+import { isIllustrativePath, compilePatterns } from '../utils/illustrativePatterns.js';
+import { similarityRatio } from '../utils/similarity.js';
+import { isWithinRoot, resolveDocumentDir, resolveProjectRoot } from '../utils/pathSecurity.js';
+import { createIllustrativeSkippedResult, getRuleSeverity, severityForIllustrative } from '../utils/validation.js';
+/**
+ * Validates that directory structure references exist
+ *
+ * Simple approach: The extractor builds full paths from the tree structure,
+ * so we just check if each path exists from the project root.
+ */
+export class DirectoryValidator {
+    pathCache;
+    customPatterns;
+    constructor() {
+        this.pathCache = new Map();
+        this.customPatterns = [];
+    }
+    /**
+     * Initialize custom illustrative patterns from config
+     */
+    initCustomPatterns(config) {
+        const configPatterns = config.rules?.['directory-structure']?.illustrativePatterns;
+        this.customPatterns = configPatterns && configPatterns.length > 0 ? compilePatterns(configPatterns) : [];
+    }
+    async validateBatch(references, document, config) {
+        this.initCustomPatterns(config);
+        const results = [];
+        const skipIllustrative = config.rules?.['directory-structure']?.skipIllustrative !== false;
+        for (const ref of references) {
+            // Check if this is an illustrative path (marked by extractor or detected here)
+            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, document, config, illustrative);
+            results.push(result);
+        }
+        return results;
+    }
+    async validateReference(ref, document, config, isIllustrative = false) {
+        const itemPath = ref.value;
+        const rootDir = resolveProjectRoot(config.rootDir);
+        const baseSeverity = getRuleSeverity(config, 'directory-structure', 'warning');
+        const cacheKey = `${rootDir}::${document.path}::${itemPath}`;
+        // Check cache first
+        if (this.pathCache.has(cacheKey)) {
+            const cached = this.pathCache.get(cacheKey);
+            return {
+                reference: ref,
+                valid: cached.found,
+                foundAt: cached.foundAt,
+                severity: cached.found ? undefined : baseSeverity,
+                message: cached.found ? undefined : `Directory/file not found: ${itemPath}`,
+                suggestion: cached.suggestion,
+            };
+        }
+        // Strategy 1: Check if the path exists from project root
+        // This handles full paths like "frontend/src/apps/domains"
+        const fullPath = path.resolve(rootDir, itemPath);
+        if (isWithinRoot(fullPath, rootDir) && (await this.pathExists(fullPath))) {
+            this.pathCache.set(cacheKey, { found: true, foundAt: itemPath });
+            return {
+                reference: ref,
+                valid: true,
+                foundAt: itemPath,
+            };
+        }
+        // Strategy 2: The path might be relative to the document's location
+        // e.g., a doc in "docs/" might reference "../src/..."
+        const docDir = resolveDocumentDir(rootDir, document.path);
+        const relativeToDoc = path.resolve(docDir, itemPath);
+        if (isWithinRoot(relativeToDoc, rootDir) && (await this.pathExists(relativeToDoc))) {
+            const foundAt = path.relative(rootDir, relativeToDoc);
+            this.pathCache.set(cacheKey, { found: true, foundAt });
+            return {
+                reference: ref,
+                valid: true,
+                foundAt,
+            };
+        }
+        // If both candidate paths resolve outside root, fail early with explicit message.
+        if (!isWithinRoot(fullPath, rootDir) && !isWithinRoot(relativeToDoc, rootDir)) {
+            return {
+                reference: ref,
+                valid: false,
+                severity: severityForIllustrative(isIllustrative, baseSeverity),
+                message: isIllustrative ? `Path escapes project root (illustrative): ${itemPath}` : `Path escapes project root: ${itemPath}`,
+                suggestion: null,
+            };
+        }
+        // Strategy 3: Try to find a similar path (for suggestions)
+        const suggestion = await this.findSimilarPath(itemPath, config);
+        // Not found - reduce severity for illustrative paths that weren't skipped
+        this.pathCache.set(cacheKey, { found: false, suggestion });
+        return {
+            reference: ref,
+            valid: false,
+            severity: severityForIllustrative(isIllustrative, baseSeverity),
+            message: isIllustrative ? `Directory/file not found (illustrative): ${itemPath}` : `Directory/file not found: ${itemPath}`,
+            suggestion,
+        };
+    }
+    async pathExists(fullPath) {
+        try {
+            await fs.promises.access(fullPath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Try to find a similar path for suggestions
+     * Handles common issues like singular/plural mismatches
+     */
+    async findSimilarPath(itemPath, config) {
+        const rootDir = resolveProjectRoot(config.rootDir);
+        const segments = itemPath.split('/');
+        const lastSegment = segments[segments.length - 1];
+        // Get the parent directory path
+        const parentPath = segments.slice(0, -1).join('/');
+        const parentFullPath = path.resolve(rootDir, parentPath);
+        if (!isWithinRoot(parentFullPath, rootDir)) {
+            return null;
+        }
+        // Check if parent exists
+        if (!(await this.pathExists(parentFullPath))) {
+            return null;
+        }
+        // List files in parent directory
+        try {
+            const entries = await fs.promises.readdir(parentFullPath);
+            const lastLower = lastSegment.toLowerCase();
+            let bestMatch = null;
+            let bestScore = 0;
+            for (const entry of entries) {
+                const entryLower = entry.toLowerCase();
+                // Exact case-insensitive match
+                if (entryLower === lastLower && entry !== lastSegment) {
+                    return `${parentPath}/${entry}`;
+                }
+                // Calculate similarity score
+                const score = this.calculateSimilarity(lastLower, entryLower);
+                if (score > bestScore && score >= 0.7) {
+                    bestScore = score;
+                    bestMatch = entry;
+                }
+            }
+            if (bestMatch) {
+                return `${parentPath}/${bestMatch}`;
+            }
+        }
+        catch {
+            // Parent directory read failed
+        }
+        return null;
+    }
+    /**
+     * Calculate similarity between two strings (0-1)
+     * Uses a combination of techniques for better matching
+     */
+    calculateSimilarity(a, b) {
+        const aBase = a.replace(/\.[^.]+$/, '');
+        const bBase = b.replace(/\.[^.]+$/, '');
+        if (aBase === bBase)
+            return 1;
+        // Check for singular/plural by removing common plural suffixes
+        const aSingular = this.toSingular(aBase);
+        const bSingular = this.toSingular(bBase);
+        if (aSingular === bSingular)
+            return 0.95;
+        if (aSingular === bBase || aBase === bSingular)
+            return 0.95;
+        return similarityRatio(aBase, bBase);
+    }
+    toSingular(word) {
+        if (word.endsWith('ies')) {
+            return word.slice(0, -3) + 'y';
+        }
+        if (word.endsWith('es') && !word.endsWith('ses') && !word.endsWith('xes')) {
+            return word.slice(0, -2);
+        }
+        if (word.endsWith('s') && !word.endsWith('ss')) {
+            return word.slice(0, -1);
+        }
+        return word;
+    }
+}
+//# sourceMappingURL=directoryValidator.js.map

package/dist/validators/directoryValidator.js.map

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

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

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