doc-freshness-checker 1.0.0

package/dist/utils/illustrativePatterns.js

@@ -0,0 +1,80 @@
+/**
+ * Centralized patterns for detecting illustrative/placeholder content in documentation
+ *
+ * These patterns identify paths, filenames, and code symbols that are commonly used
+ * as examples in tutorials and documentation but don't represent actual files/code.
+ */
+/**
+ * Patterns for detecting illustrative file/directory paths
+ * Used by: FilePathExtractor, DirectoryStructureExtractor, FileValidator, DirectoryValidator
+ */
+export const ILLUSTRATIVE_PATH_PATTERNS = [
+    // Generic placeholder prefixes (case-insensitive)
+    /^(?:Your|My|Example|Sample|Demo|Test|Foo|Bar|Baz|Dummy|Mock|Fake|Stub)/i,
+    // Common tutorial placeholders
+    /^(?:first|second|third|another|some|new)\./i,
+    // Very short generic names without extensions
+    /^(?:foo|bar|baz|qux|quux)$/i,
+    // Paths containing angle brackets or curly braces (template syntax)
+    /<[^>]+>/,
+    /\{[^}]+\}/,
+    // Paths with obvious placeholder segments
+    /\/(?:your|my|example|sample)-/i,
+    /\/\[.*\]\//,
+];
+/**
+ * Patterns for detecting illustrative code symbol names
+ * Used by: CodePatternExtractor, CodePatternValidator
+ */
+export const ILLUSTRATIVE_SYMBOL_PATTERNS = [
+    // Generic placeholder prefixes followed by PascalCase
+    /^(?:Your|My|Example|Sample|Demo|Test|Foo|Bar|Baz|Dummy|Mock|Fake|Stub)[A-Z]/i,
+    // HTTP methods used as function names in REST tutorials
+    /^(?:POST|GET|PUT|DELETE|PATCH)$/,
+    // Very short names (1-2 chars) are likely false positives from word parsing
+    /^[a-z]{1,2}$/,
+    // Common tutorial component/function names
+    /^(?:Chat|App|Button|Card|Modal|Form|Input|List|Item|Header|Footer|Sidebar|Nav|Menu|Page|Home|About|Contact|Login|Signup|Profile|Dashboard|Settings)$/,
+];
+/**
+ * Check if a path looks like an illustrative/placeholder path
+ */
+export function isIllustrativePath(itemPath, customPatterns = []) {
+    const patterns = [...ILLUSTRATIVE_PATH_PATTERNS, ...customPatterns];
+    const segments = itemPath.split('/');
+    const filename = segments[segments.length - 1];
+    // Check filename against patterns
+    for (const pattern of patterns) {
+        if (pattern.test(filename)) {
+            return true;
+        }
+    }
+    // Check if any segment in the path looks illustrative
+    for (const segment of segments.slice(0, -1)) {
+        for (const pattern of patterns) {
+            if (pattern.test(segment)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Check if a code symbol name looks like an illustrative/placeholder name
+ */
+export function isIllustrativeSymbol(name, customPatterns = []) {
+    const patterns = [...ILLUSTRATIVE_SYMBOL_PATTERNS, ...customPatterns];
+    for (const pattern of patterns) {
+        if (pattern.test(name)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Convert string patterns from config to RegExp objects
+ */
+export function compilePatterns(patterns) {
+    return patterns.map((p) => new RegExp(p, 'i'));
+}
+//# sourceMappingURL=illustrativePatterns.js.map

package/dist/utils/illustrativePatterns.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"illustrativePatterns.js","sourceRoot":"","sources":["../../src/utils/illustrativePatterns.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAa;IAClD,kDAAkD;IAClD,yEAAyE;IACzE,+BAA+B;IAC/B,6CAA6C;IAC7C,8CAA8C;IAC9C,6BAA6B;IAC7B,oEAAoE;IACpE,SAAS;IACT,WAAW;IACX,0CAA0C;IAC1C,gCAAgC;IAChC,YAAY;CACb,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAa;IACpD,sDAAsD;IACtD,8EAA8E;IAC9E,wDAAwD;IACxD,iCAAiC;IACjC,4EAA4E;IAC5E,cAAc;IACd,2CAA2C;IAC3C,sJAAsJ;CACvJ,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAgB,EAAE,iBAA2B,EAAE;IAChF,MAAM,QAAQ,GAAG,CAAC,GAAG,0BAA0B,EAAE,GAAG,cAAc,CAAC,CAAC;IACpE,MAAM,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACrC,MAAM,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAE/C,kCAAkC;IAClC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC3B,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,sDAAsD;IACtD,KAAK,MAAM,OAAO,IAAI,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5C,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;YAC/B,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC1B,OAAO,IAAI,CAAC;YACd,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAY,EAAE,iBAA2B,EAAE;IAC9E,MAAM,QAAQ,GAAG,CAAC,GAAG,4BAA4B,EAAE,GAAG,cAAc,CAAC,CAAC;IAEtE,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACvB,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,QAAkB;IAChD,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,MAAM,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;AACjD,CAAC"}

package/dist/utils/illustrativePatterns.test.d.ts

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

package/dist/utils/illustrativePatterns.test.js

@@ -0,0 +1,48 @@
+import { isIllustrativePath, isIllustrativeSymbol, compilePatterns, ILLUSTRATIVE_PATH_PATTERNS, ILLUSTRATIVE_SYMBOL_PATTERNS, } from './illustrativePatterns.js';
+describe('compilePatterns', () => {
+    it('converts string patterns to case-insensitive RegExp', () => {
+        const patterns = compilePatterns(['^test', 'example$']);
+        expect(patterns).toHaveLength(2);
+        expect(patterns[0].test('TestFile')).toBe(true);
+        expect(patterns[1].test('myExample')).toBe(true);
+    });
+});
+describe('isIllustrativePath', () => {
+    it.each([
+        'YourProject/file.ts',
+        'my-project/src/index.ts',
+        'Example.tsx',
+        'sample-app/main.py',
+        'foo',
+        'src/<component>/file.ts',
+        'src/{name}/file.ts',
+        'first.ts',
+    ])('detects illustrative path: %s', (p) => {
+        expect(isIllustrativePath(p)).toBe(true);
+    });
+    it.each(['src/utils/helper.ts', 'package.json', 'tsconfig.json'])('does not flag real path: %s', (p) => {
+        expect(isIllustrativePath(p)).toBe(false);
+    });
+    it('supports custom patterns', () => {
+        const custom = [/^custom-placeholder/i];
+        expect(isIllustrativePath('custom-placeholder.ts', custom)).toBe(true);
+        expect(isIllustrativePath('real-file.ts', custom)).toBe(false);
+    });
+});
+describe('isIllustrativeSymbol', () => {
+    it.each(['YourComponent', 'ExampleService', 'FooBar', 'MockAdapter', 'POST', 'a', 'Chat', 'Dashboard'])('detects illustrative symbol: %s', (s) => {
+        expect(isIllustrativeSymbol(s)).toBe(true);
+    });
+    it.each(['DocumentParser', 'ValidationEngine', 'runParallel'])('does not flag real symbol: %s', (s) => {
+        expect(isIllustrativeSymbol(s)).toBe(false);
+    });
+});
+describe('pattern arrays are non-empty', () => {
+    it('ILLUSTRATIVE_PATH_PATTERNS has entries', () => {
+        expect(ILLUSTRATIVE_PATH_PATTERNS.length).toBeGreaterThan(0);
+    });
+    it('ILLUSTRATIVE_SYMBOL_PATTERNS has entries', () => {
+        expect(ILLUSTRATIVE_SYMBOL_PATTERNS.length).toBeGreaterThan(0);
+    });
+});
+//# sourceMappingURL=illustrativePatterns.test.js.map

package/dist/utils/illustrativePatterns.test.js.map

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

package/dist/utils/incremental.d.ts

@@ -0,0 +1,36 @@
+import type { Document, IncrementalStats } from '../types.js';
+/**
+ * Incremental checker for skipping unchanged documentation files
+ * Uses file hashes to detect changes between runs
+ */
+export declare class IncrementalChecker {
+    private stateDir;
+    private stateFile;
+    private previousHashes;
+    private currentHashes;
+    constructor(stateDir?: string);
+    /**
+     * Load previous state from cache
+     */
+    loadState(): Promise<void>;
+    /**
+     * Save current state to cache
+     */
+    saveState(): Promise<void>;
+    /**
+     * Get MD5 hash of a file
+     */
+    getHash(filePath: string): Promise<string>;
+    /**
+     * Check if a file has changed since last run
+     */
+    shouldCheck(filePath: string): Promise<boolean>;
+    /**
+     * Filter documents to only include changed ones
+     */
+    filterChanged(documents: Document[]): Promise<Document[]>;
+    /**
+     * Get statistics about the incremental check
+     */
+    getStats(totalDocs: number, changedDocs: number): IncrementalStats;
+}

package/dist/utils/incremental.js

@@ -0,0 +1,87 @@
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+/**
+ * Incremental checker for skipping unchanged documentation files
+ * Uses file hashes to detect changes between runs
+ */
+export class IncrementalChecker {
+    stateDir;
+    stateFile;
+    previousHashes;
+    currentHashes;
+    constructor(stateDir = '.doc-freshness-cache') {
+        this.stateDir = stateDir;
+        this.stateFile = path.join(stateDir, 'file-hashes.json');
+        this.previousHashes = new Map();
+        this.currentHashes = new Map();
+    }
+    /**
+     * Load previous state from cache
+     */
+    async loadState() {
+        try {
+            const data = await fs.promises.readFile(this.stateFile, 'utf-8');
+            const parsed = JSON.parse(data);
+            this.previousHashes = new Map(Object.entries(parsed));
+        }
+        catch {
+            // No previous state
+        }
+    }
+    /**
+     * Save current state to cache
+     */
+    async saveState() {
+        await fs.promises.mkdir(this.stateDir, { recursive: true });
+        const data = Object.fromEntries(this.currentHashes);
+        await fs.promises.writeFile(this.stateFile, JSON.stringify(data, null, 2));
+    }
+    /**
+     * Get MD5 hash of a file
+     */
+    async getHash(filePath) {
+        const content = await fs.promises.readFile(filePath, 'utf-8');
+        return crypto.createHash('md5').update(content).digest('hex');
+    }
+    /**
+     * Check if a file has changed since last run
+     */
+    async shouldCheck(filePath) {
+        try {
+            const hash = await this.getHash(filePath);
+            this.currentHashes.set(filePath, hash);
+            const previousHash = this.previousHashes.get(filePath);
+            return hash !== previousHash;
+        }
+        catch {
+            // File read error - should check
+            return true;
+        }
+    }
+    /**
+     * Filter documents to only include changed ones
+     */
+    async filterChanged(documents) {
+        await this.loadState();
+        const changed = [];
+        for (const doc of documents) {
+            if (await this.shouldCheck(doc.absolutePath)) {
+                changed.push(doc);
+            }
+        }
+        return changed;
+    }
+    /**
+     * Get statistics about the incremental check
+     */
+    getStats(totalDocs, changedDocs) {
+        return {
+            total: totalDocs,
+            changed: changedDocs,
+            skipped: totalDocs - changedDocs,
+            percentSkipped: totalDocs > 0 ? Math.round(((totalDocs - changedDocs) / totalDocs) * 100) : 0,
+        };
+    }
+}
+//# sourceMappingURL=incremental.js.map

package/dist/utils/incremental.js.map

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

package/dist/utils/incremental.test.d.ts

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

package/dist/utils/incremental.test.js

@@ -0,0 +1,84 @@
+import fs from 'fs';
+import crypto from 'crypto';
+import { IncrementalChecker } from './incremental.js';
+function makeDoc(docPath) {
+    return {
+        path: docPath,
+        absolutePath: `/project/${docPath}`,
+        content: 'content',
+        format: 'markdown',
+        lines: ['content'],
+        references: [],
+    };
+}
+describe('IncrementalChecker', () => {
+    let checker;
+    beforeEach(() => {
+        checker = new IncrementalChecker('/tmp/test-cache');
+    });
+    describe('getStats', () => {
+        it.each([
+            { total: 10, changed: 3, skipped: 7, pct: 70 },
+            { total: 0, changed: 0, skipped: 0, pct: 0 },
+            { total: 5, changed: 5, skipped: 0, pct: 0 },
+        ])('computes stats for total=$total changed=$changed', ({ total, changed, skipped, pct }) => {
+            const stats = checker.getStats(total, changed);
+            expect(stats).toEqual({ total, changed, skipped, percentSkipped: pct });
+        });
+    });
+    describe('loadState', () => {
+        it('loads previous hashes from disk', async () => {
+            vi.spyOn(fs.promises, 'readFile').mockResolvedValue(JSON.stringify({ 'file.md': 'abc123' }));
+            await checker.loadState();
+        });
+        it('handles missing state file gracefully', async () => {
+            vi.spyOn(fs.promises, 'readFile').mockRejectedValue(new Error('ENOENT'));
+            await expect(checker.loadState()).resolves.not.toThrow();
+        });
+    });
+    describe('saveState', () => {
+        it('writes current hashes to disk', async () => {
+            const mkdirSpy = vi.spyOn(fs.promises, 'mkdir').mockResolvedValue(undefined);
+            const writeSpy = vi.spyOn(fs.promises, 'writeFile').mockResolvedValue(undefined);
+            await checker.saveState();
+            expect(mkdirSpy).toHaveBeenCalledWith('/tmp/test-cache', { recursive: true });
+            expect(writeSpy).toHaveBeenCalled();
+        });
+    });
+    describe('shouldCheck', () => {
+        it('returns true for new files not in previous state', async () => {
+            vi.spyOn(fs.promises, 'readFile').mockResolvedValueOnce(JSON.stringify({})).mockResolvedValueOnce('file content');
+            await checker.loadState();
+            expect(await checker.shouldCheck('/project/new.md')).toBe(true);
+        });
+        it('returns false for unchanged files', async () => {
+            const content = 'file content';
+            const expectedHash = crypto.createHash('md5').update(content).digest('hex');
+            vi.spyOn(fs.promises, 'readFile')
+                .mockResolvedValueOnce(JSON.stringify({ '/project/same.md': expectedHash }))
+                .mockResolvedValueOnce(content);
+            await checker.loadState();
+            expect(await checker.shouldCheck('/project/same.md')).toBe(false);
+        });
+        it('returns true when file read fails', async () => {
+            vi.spyOn(fs.promises, 'readFile').mockResolvedValueOnce(JSON.stringify({})).mockRejectedValueOnce(new Error('read error'));
+            await checker.loadState();
+            expect(await checker.shouldCheck('/project/broken.md')).toBe(true);
+        });
+    });
+    describe('filterChanged', () => {
+        it('returns only documents whose content has changed', async () => {
+            const content = 'unchanged';
+            const hash = crypto.createHash('md5').update(content).digest('hex');
+            vi.spyOn(fs.promises, 'readFile')
+                .mockResolvedValueOnce(JSON.stringify({ '/project/unchanged.md': hash }))
+                .mockResolvedValueOnce(content)
+                .mockResolvedValueOnce('new content');
+            const docs = [makeDoc('unchanged.md'), makeDoc('changed.md')];
+            const changed = await checker.filterChanged(docs);
+            expect(changed).toHaveLength(1);
+            expect(changed[0].path).toBe('changed.md');
+        });
+    });
+});
+//# sourceMappingURL=incremental.test.js.map

package/dist/utils/incremental.test.js.map

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

package/dist/utils/parallel.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Run tasks in parallel with concurrency limit.
+ * Individual task failures don't abort remaining tasks --
+ * all rejections are collected and re-thrown via Promise.allSettled + Promise.all.
+ */
+export declare function runParallel<T>(tasks: Array<() => Promise<T>>, concurrency?: number): Promise<T[]>;
+/**
+ * Batch an array into chunks
+ */
+export declare function batch<T>(array: T[], size: number): T[][];
+/**
+ * Delay execution
+ */
+export declare function delay(ms: number): Promise<void>;

package/dist/utils/parallel.js

@@ -0,0 +1,43 @@
+/**
+ * Run tasks in parallel with concurrency limit.
+ * Individual task failures don't abort remaining tasks --
+ * all rejections are collected and re-thrown via Promise.allSettled + Promise.all.
+ */
+export async function runParallel(tasks, concurrency = 10) {
+    const results = [];
+    const executing = new Set();
+    for (const task of tasks) {
+        const promise = task();
+        results.push(promise);
+        const cleanup = promise
+            .then(() => { }, () => { })
+            .then(() => {
+            executing.delete(cleanup);
+        });
+        executing.add(cleanup);
+        if (executing.size >= concurrency) {
+            await Promise.race(executing);
+        }
+    }
+    return Promise.all(results);
+}
+/**
+ * Batch an array into chunks
+ */
+export function batch(array, size) {
+    if (size <= 0) {
+        throw new Error('Batch size must be greater than 0');
+    }
+    const batches = [];
+    for (let i = 0; i < array.length; i += size) {
+        batches.push(array.slice(i, i + size));
+    }
+    return batches;
+}
+/**
+ * Delay execution
+ */
+export function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=parallel.js.map

package/dist/utils/parallel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parallel.js","sourceRoot":"","sources":["../../src/utils/parallel.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAI,KAA8B,EAAE,cAAsB,EAAE;IAC3F,MAAM,OAAO,GAAiB,EAAE,CAAC;IACjC,MAAM,SAAS,GAAuB,IAAI,GAAG,EAAE,CAAC;IAEhD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,OAAO,GAAG,IAAI,EAAE,CAAC;QACvB,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAEtB,MAAM,OAAO,GAAG,OAAO;aACpB,IAAI,CACH,GAAG,EAAE,GAAE,CAAC,EACR,GAAG,EAAE,GAAE,CAAC,CACT;aACA,IAAI,CAAC,GAAG,EAAE;YACT,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC5B,CAAC,CAAC,CAAC;QACL,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAEvB,IAAI,SAAS,CAAC,IAAI,IAAI,WAAW,EAAE,CAAC;YAClC,MAAM,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;AAC9B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,KAAK,CAAI,KAAU,EAAE,IAAY;IAC/C,IAAI,IAAI,IAAI,CAAC,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;IACvD,CAAC;IACD,MAAM,OAAO,GAAU,EAAE,CAAC;IAC1B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC;QAC5C,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;IACzC,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,KAAK,CAAC,EAAU;IAC9B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC"}

package/dist/utils/parallel.test.d.ts

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

package/dist/utils/parallel.test.js

@@ -0,0 +1,48 @@
+import { runParallel, batch, delay } from './parallel.js';
+describe('batch', () => {
+    it.each([
+        { input: [1, 2, 3, 4, 5], size: 2, expected: [[1, 2], [3, 4], [5]] },
+        { input: [1, 2, 3], size: 5, expected: [[1, 2, 3]] },
+        { input: [], size: 3, expected: [] },
+    ])('splits array of $input.length into chunks of $size', ({ input, size, expected }) => {
+        expect(batch(input, size)).toEqual(expected);
+    });
+    it('throws when batch size is non-positive', () => {
+        expect(() => batch([1, 2, 3], 0)).toThrow('Batch size must be greater than 0');
+        expect(() => batch([1, 2, 3], -1)).toThrow('Batch size must be greater than 0');
+    });
+});
+describe('delay', () => {
+    it('resolves after the specified time', async () => {
+        const start = Date.now();
+        await delay(50);
+        expect(Date.now() - start).toBeGreaterThanOrEqual(40);
+    });
+});
+describe('runParallel', () => {
+    it('runs all tasks and returns results in order', async () => {
+        const tasks = [() => Promise.resolve(1), () => Promise.resolve(2), () => Promise.resolve(3)];
+        const results = await runParallel(tasks);
+        expect(results).toEqual([1, 2, 3]);
+    });
+    it('respects concurrency limit', async () => {
+        let concurrent = 0;
+        let maxConcurrent = 0;
+        const makeTask = (val) => async () => {
+            concurrent++;
+            maxConcurrent = Math.max(maxConcurrent, concurrent);
+            await delay(20);
+            concurrent--;
+            return val;
+        };
+        const tasks = Array.from({ length: 6 }, (_, i) => makeTask(i));
+        const results = await runParallel(tasks, 2);
+        expect(results).toEqual([0, 1, 2, 3, 4, 5]);
+        expect(maxConcurrent).toBeLessThanOrEqual(2);
+    });
+    it('propagates errors from tasks', async () => {
+        const tasks = [() => Promise.resolve(1), () => Promise.reject(new Error('fail'))];
+        await expect(runParallel(tasks)).rejects.toThrow('fail');
+    });
+});
+//# sourceMappingURL=parallel.test.js.map

package/dist/utils/parallel.test.js.map

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

package/dist/utils/pathSecurity.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Returns true if candidatePath is equal to or nested within rootDir.
+ */
+export declare function isWithinRoot(candidatePath: string, rootDir: string): boolean;
+/**
+ * Resolve project root from config or process cwd.
+ */
+export declare function resolveProjectRoot(configRootDir?: string): string;
+/**
+ * Resolve a document directory relative to project root.
+ */
+export declare function resolveDocumentDir(rootDir: string, documentPath: string): string;

package/dist/utils/pathSecurity.js

@@ -0,0 +1,22 @@
+import path from 'path';
+/**
+ * Returns true if candidatePath is equal to or nested within rootDir.
+ */
+export function isWithinRoot(candidatePath, rootDir) {
+    const resolvedRoot = path.resolve(rootDir);
+    const resolvedCandidate = path.resolve(candidatePath);
+    return resolvedCandidate === resolvedRoot || resolvedCandidate.startsWith(resolvedRoot + path.sep);
+}
+/**
+ * Resolve project root from config or process cwd.
+ */
+export function resolveProjectRoot(configRootDir) {
+    return path.resolve(configRootDir || process.cwd());
+}
+/**
+ * Resolve a document directory relative to project root.
+ */
+export function resolveDocumentDir(rootDir, documentPath) {
+    return path.dirname(path.resolve(rootDir, documentPath));
+}
+//# sourceMappingURL=pathSecurity.js.map

package/dist/utils/pathSecurity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pathSecurity.js","sourceRoot":"","sources":["../../src/utils/pathSecurity.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAC;AAExB;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,aAAqB,EAAE,OAAe;IACjE,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3C,MAAM,iBAAiB,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;IACtD,OAAO,iBAAiB,KAAK,YAAY,IAAI,iBAAiB,CAAC,UAAU,CAAC,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;AACrG,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,aAAsB;IACvD,OAAO,IAAI,CAAC,OAAO,CAAC,aAAa,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;AACtD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe,EAAE,YAAoB;IACtE,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC;AAC3D,CAAC"}

package/dist/utils/pathSecurity.test.d.ts

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

package/dist/utils/pathSecurity.test.js

@@ -0,0 +1,34 @@
+import path from 'path';
+import { isWithinRoot, resolveProjectRoot, resolveDocumentDir } from './pathSecurity.js';
+describe('isWithinRoot', () => {
+    const root = '/project';
+    it.each([
+        ['/project/src/file.ts', true],
+        ['/project', true],
+        ['/project/deep/nested/file.ts', true],
+        ['/other/place', false],
+        ['/projectExtra/file.ts', false],
+    ])('isWithinRoot(%s, /project) => %s', (candidate, expected) => {
+        expect(isWithinRoot(candidate, root)).toBe(expected);
+    });
+    it('resolves relative paths before comparing', () => {
+        expect(isWithinRoot('/project/src/../src/file.ts', root)).toBe(true);
+        expect(isWithinRoot('/project/../other', root)).toBe(false);
+    });
+});
+describe('resolveProjectRoot', () => {
+    it('returns resolved configRootDir when provided', () => {
+        expect(resolveProjectRoot('/my/project')).toBe(path.resolve('/my/project'));
+    });
+    it('falls back to process.cwd() when no arg', () => {
+        expect(resolveProjectRoot()).toBe(path.resolve(process.cwd()));
+        expect(resolveProjectRoot(undefined)).toBe(path.resolve(process.cwd()));
+    });
+});
+describe('resolveDocumentDir', () => {
+    it('returns the directory of the document relative to rootDir', () => {
+        const result = resolveDocumentDir('/project', 'docs/guide/README.md');
+        expect(result).toBe(path.resolve('/project', 'docs/guide'));
+    });
+});
+//# sourceMappingURL=pathSecurity.test.js.map

package/dist/utils/pathSecurity.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pathSecurity.test.js","sourceRoot":"","sources":["../../src/utils/pathSecurity.test.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEzF,QAAQ,CAAC,cAAc,EAAE,GAAG,EAAE;IAC5B,MAAM,IAAI,GAAG,UAAU,CAAC;IAExB,EAAE,CAAC,IAAI,CAAC;QACN,CAAC,sBAAsB,EAAE,IAAI,CAAC;QAC9B,CAAC,UAAU,EAAE,IAAI,CAAC;QAClB,CAAC,8BAA8B,EAAE,IAAI,CAAC;QACtC,CAAC,cAAc,EAAE,KAAK,CAAC;QACvB,CAAC,uBAAuB,EAAE,KAAK,CAAC;KACjC,CAAC,CAAC,kCAAkC,EAAE,CAAC,SAAS,EAAE,QAAQ,EAAE,EAAE;QAC7D,MAAM,CAAC,YAAY,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACvD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0CAA0C,EAAE,GAAG,EAAE;QAClD,MAAM,CAAC,YAAY,CAAC,6BAA6B,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrE,MAAM,CAAC,YAAY,CAAC,mBAAmB,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC9D,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,oBAAoB,EAAE,GAAG,EAAE;IAClC,EAAE,CAAC,8CAA8C,EAAE,GAAG,EAAE;QACtD,MAAM,CAAC,kBAAkB,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC;IAC9E,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yCAAyC,EAAE,GAAG,EAAE;QACjD,MAAM,CAAC,kBAAkB,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QAC/D,MAAM,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IAC1E,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,oBAAoB,EAAE,GAAG,EAAE;IAClC,EAAE,CAAC,2DAA2D,EAAE,GAAG,EAAE;QACnE,MAAM,MAAM,GAAG,kBAAkB,CAAC,UAAU,EAAE,sBAAsB,CAAC,CAAC;QACtE,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC,CAAC;IAC9D,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/utils/similarity.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Find the most similar string from a list using Levenshtein distance
+ */
+export declare function findSimilar(target: string, candidates: string[], maxDistance?: number): string | null;
+/**
+ * Calculate Levenshtein distance between two strings
+ */
+export declare function levenshteinDistance(a: string, b: string): number;
+/**
+ * Calculate similarity ratio (0-1) between two strings
+ */
+export declare function similarityRatio(a: string, b: string): number;