doc-freshness-checker 1.0.0

package/dist/git/changeTracker.js

@@ -0,0 +1,149 @@
+import { execFileSync } from 'child_process';
+/**
+ * Tracks git changes for incremental documentation checking
+ */
+export class GitChangeTracker {
+    rootDir;
+    _isGitRepo;
+    constructor(config) {
+        this.rootDir = config.rootDir || process.cwd();
+        this._isGitRepo = null;
+    }
+    git(args) {
+        return execFileSync('git', args, {
+            cwd: this.rootDir,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+    }
+    /**
+     * Check if the project is a git repository
+     */
+    isGitRepo() {
+        if (this._isGitRepo !== null) {
+            return this._isGitRepo;
+        }
+        try {
+            this.git(['rev-parse', '--git-dir']);
+            this._isGitRepo = true;
+        }
+        catch {
+            this._isGitRepo = false;
+        }
+        return this._isGitRepo;
+    }
+    /**
+     * Get the current git commit hash
+     */
+    getCurrentCommit() {
+        if (!this.isGitRepo())
+            return null;
+        try {
+            return this.git(['rev-parse', 'HEAD']);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Get files changed between two commits
+     */
+    getChangedFiles(fromCommit, toCommit = 'HEAD') {
+        if (!this.isGitRepo())
+            return [];
+        try {
+            const output = this.git(['diff', '--name-only', `${fromCommit}..${toCommit}`]);
+            return output.split('\n').filter(Boolean);
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Get files changed since a timestamp
+     */
+    getChangedFilesSince(timestamp) {
+        if (!this.isGitRepo())
+            return [];
+        try {
+            const isoDate = new Date(timestamp).toISOString();
+            const output = this.git(['log', `--since=${isoDate}`, '--name-only', '--pretty=format:']);
+            const files = [...new Set(output.split('\n').filter(Boolean))];
+            return files;
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Get the last modification time of a file from git
+     */
+    getFileLastModified(filePath) {
+        if (!this.isGitRepo())
+            return null;
+        try {
+            const output = this.git(['log', '-1', '--format=%ct', '--', filePath]);
+            const timestamp = parseInt(output, 10);
+            return timestamp ? timestamp * 1000 : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Get commit info for a file.
+     * Uses NUL byte as separator to safely handle commit messages containing |
+     */
+    getFileCommitInfo(filePath) {
+        if (!this.isGitRepo())
+            return null;
+        try {
+            const output = this.git(['log', '-1', '--format=%H%x00%ct%x00%s', '--', filePath]);
+            if (!output)
+                return null;
+            const parts = output.split('\0');
+            if (parts.length < 3)
+                return null;
+            return {
+                hash: parts[0],
+                timestamp: parseInt(parts[1], 10) * 1000,
+                message: parts.slice(2).join('\0'),
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Determine which docs need re-checking based on code changes
+     */
+    getAffectedDocs(graph, changedFiles) {
+        const affectedDocs = new Set();
+        for (const changedFile of changedFiles) {
+            const docs = graph.getDocsReferencingCode(changedFile);
+            for (const doc of docs) {
+                affectedDocs.add(doc);
+            }
+        }
+        return [...affectedDocs];
+    }
+    /**
+     * Get change summary for reporting
+     */
+    getChangeSummary(graph, changedFiles) {
+        const summary = [];
+        for (const changedFile of changedFiles) {
+            const docs = graph.getDocsReferencingCode(changedFile);
+            if (docs.size > 0) {
+                const commitInfo = this.getFileCommitInfo(changedFile);
+                summary.push({
+                    codeFile: changedFile,
+                    affectedDocs: [...docs],
+                    lastCommit: commitInfo,
+                });
+            }
+        }
+        return summary;
+    }
+}
+//# sourceMappingURL=changeTracker.js.map

package/dist/git/changeTracker.js.map

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

package/dist/git/changeTracker.test.d.ts

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

package/dist/git/changeTracker.test.js

@@ -0,0 +1,184 @@
+import { execFileSync } from 'child_process';
+import { GitChangeTracker } from './changeTracker.js';
+import { CodeDocGraph } from '../graph/codeDocGraph.js';
+vi.mock('child_process');
+const mockExecFileSync = vi.mocked(execFileSync);
+function makeRef(value) {
+    return { type: 'file-path', value, lineNumber: 1, raw: value, sourceFile: 'doc.md' };
+}
+describe('GitChangeTracker', () => {
+    const config = { rootDir: '/project' };
+    beforeEach(() => {
+        mockExecFileSync.mockReset();
+    });
+    describe('isGitRepo', () => {
+        it('returns true when git rev-parse succeeds', () => {
+            mockExecFileSync.mockReturnValue('.git\n');
+            expect(new GitChangeTracker(config).isGitRepo()).toBe(true);
+        });
+        it('returns false when git rev-parse fails', () => {
+            mockExecFileSync.mockImplementation(() => {
+                throw new Error('not a git repo');
+            });
+            expect(new GitChangeTracker(config).isGitRepo()).toBe(false);
+        });
+        it('caches the result', () => {
+            mockExecFileSync.mockReturnValue('.git\n');
+            const tracker = new GitChangeTracker(config);
+            tracker.isGitRepo();
+            tracker.isGitRepo();
+            expect(mockExecFileSync).toHaveBeenCalledTimes(1);
+        });
+        it('uses process.cwd() when rootDir not specified', () => {
+            mockExecFileSync.mockReturnValue('.git\n');
+            new GitChangeTracker({}).isGitRepo();
+            expect(mockExecFileSync).toHaveBeenCalledWith('git', ['rev-parse', '--git-dir'], expect.objectContaining({ cwd: process.cwd() }));
+        });
+    });
+    describe('getCurrentCommit', () => {
+        it('returns commit hash', () => {
+            mockExecFileSync.mockReturnValueOnce('.git\n').mockReturnValueOnce('abc123\n');
+            expect(new GitChangeTracker(config).getCurrentCommit()).toBe('abc123');
+        });
+        it('returns null for non-git repos', () => {
+            mockExecFileSync.mockImplementation(() => {
+                throw new Error();
+            });
+            expect(new GitChangeTracker(config).getCurrentCommit()).toBeNull();
+        });
+        it('returns null when rev-parse HEAD fails', () => {
+            mockExecFileSync.mockReturnValueOnce('.git\n').mockImplementationOnce(() => {
+                throw new Error('no commits');
+            });
+            expect(new GitChangeTracker(config).getCurrentCommit()).toBeNull();
+        });
+    });
+    describe('getChangedFiles', () => {
+        it('returns changed file list', () => {
+            mockExecFileSync.mockReturnValueOnce('.git\n').mockReturnValueOnce('file1.ts\nfile2.ts\n');
+            expect(new GitChangeTracker(config).getChangedFiles('abc', 'def')).toEqual(['file1.ts', 'file2.ts']);
+        });
+        it('returns empty for non-git repos', () => {
+            mockExecFileSync.mockImplementation(() => {
+                throw new Error();
+            });
+            expect(new GitChangeTracker(config).getChangedFiles('a', 'b')).toEqual([]);
+        });
+        it('returns empty when git diff fails', () => {
+            mockExecFileSync.mockReturnValueOnce('.git\n').mockImplementationOnce(() => {
+                throw new Error('diff failed');
+            });
+            expect(new GitChangeTracker(config).getChangedFiles('a', 'b')).toEqual([]);
+        });
+    });
+    describe('getChangedFilesSince', () => {
+        it('returns unique changed files since timestamp', () => {
+            mockExecFileSync.mockReturnValueOnce('.git\n').mockReturnValueOnce('file1.ts\nfile1.ts\nfile2.ts\n');
+            const files = new GitChangeTracker(config).getChangedFilesSince(Date.now() - 7 * 24 * 60 * 60 * 1000);
+            expect(files).toEqual(['file1.ts', 'file2.ts']);
+        });
+        it('returns empty for non-git repos', () => {
+            mockExecFileSync.mockImplementation(() => {
+                throw new Error();
+            });
+            expect(new GitChangeTracker(config).getChangedFilesSince(Date.now())).toEqual([]);
+        });
+        it('returns empty when git log fails', () => {
+            mockExecFileSync.mockReturnValueOnce('.git\n').mockImplementationOnce(() => {
+                throw new Error('log failed');
+            });
+            expect(new GitChangeTracker(config).getChangedFilesSince(Date.now())).toEqual([]);
+        });
+    });
+    describe('getFileLastModified', () => {
+        it('returns timestamp in milliseconds', () => {
+            const ts = Math.floor(Date.now() / 1000);
+            mockExecFileSync.mockReturnValueOnce('.git\n').mockReturnValueOnce(`${ts}\n`);
+            expect(new GitChangeTracker(config).getFileLastModified('file.ts')).toBe(ts * 1000);
+        });
+        it('returns null for non-git repos', () => {
+            mockExecFileSync.mockImplementation(() => {
+                throw new Error();
+            });
+            expect(new GitChangeTracker(config).getFileLastModified('file.ts')).toBeNull();
+        });
+        it('returns null when file has no commits', () => {
+            mockExecFileSync.mockReturnValueOnce('.git\n').mockReturnValueOnce('\n');
+            expect(new GitChangeTracker(config).getFileLastModified('new-file.ts')).toBeNull();
+        });
+        it('returns null when git log fails', () => {
+            mockExecFileSync.mockReturnValueOnce('.git\n').mockImplementationOnce(() => {
+                throw new Error('log failed');
+            });
+            expect(new GitChangeTracker(config).getFileLastModified('file.ts')).toBeNull();
+        });
+    });
+    describe('getFileCommitInfo', () => {
+        it('parses NUL-separated commit info', () => {
+            const ts = Math.floor(Date.now() / 1000);
+            mockExecFileSync.mockReturnValueOnce('.git\n').mockReturnValueOnce(`abc123\0${ts}\0Fix bug\n`);
+            const info = new GitChangeTracker(config).getFileCommitInfo('file.ts');
+            expect(info).toEqual({ hash: 'abc123', timestamp: ts * 1000, message: 'Fix bug' });
+        });
+        it('returns null when no output', () => {
+            mockExecFileSync.mockReturnValueOnce('.git\n').mockReturnValueOnce('\n');
+            expect(new GitChangeTracker(config).getFileCommitInfo('file.ts')).toBeNull();
+        });
+        it('returns null when insufficient parts in output', () => {
+            mockExecFileSync.mockReturnValueOnce('.git\n').mockReturnValueOnce('abc123\n');
+            expect(new GitChangeTracker(config).getFileCommitInfo('file.ts')).toBeNull();
+        });
+        it('returns null for non-git repos', () => {
+            mockExecFileSync.mockImplementation(() => {
+                throw new Error();
+            });
+            expect(new GitChangeTracker(config).getFileCommitInfo('file.ts')).toBeNull();
+        });
+        it('returns null when git log fails', () => {
+            mockExecFileSync.mockReturnValueOnce('.git\n').mockImplementationOnce(() => {
+                throw new Error();
+            });
+            expect(new GitChangeTracker(config).getFileCommitInfo('file.ts')).toBeNull();
+        });
+    });
+    describe('getAffectedDocs', () => {
+        it('returns docs that reference changed code files', () => {
+            mockExecFileSync.mockReturnValue('.git\n');
+            const graph = new CodeDocGraph();
+            graph.addReference('docs/api.md', 'src/server.ts', makeRef('src/server.ts'));
+            expect(new GitChangeTracker(config).getAffectedDocs(graph, ['src/server.ts'])).toEqual(['docs/api.md']);
+        });
+        it('deduplicates affected docs', () => {
+            mockExecFileSync.mockReturnValue('.git\n');
+            const graph = new CodeDocGraph();
+            graph.addReference('docs/api.md', 'src/a.ts', makeRef('a.ts'));
+            graph.addReference('docs/api.md', 'src/b.ts', makeRef('b.ts'));
+            expect(new GitChangeTracker(config).getAffectedDocs(graph, ['src/a.ts', 'src/b.ts'])).toEqual(['docs/api.md']);
+        });
+        it('returns empty when no changed files match graph', () => {
+            mockExecFileSync.mockReturnValue('.git\n');
+            const graph = new CodeDocGraph();
+            expect(new GitChangeTracker(config).getAffectedDocs(graph, ['unrelated.ts'])).toEqual([]);
+        });
+    });
+    describe('getChangeSummary', () => {
+        it('returns summary with affected docs and commit info', () => {
+            const ts = Math.floor(Date.now() / 1000);
+            mockExecFileSync.mockReturnValueOnce('.git\n').mockReturnValueOnce(`hash1\0${ts}\0Update\n`);
+            const graph = new CodeDocGraph();
+            graph.addReference('docs/api.md', 'src/server.ts', makeRef('src/server.ts'));
+            const summary = new GitChangeTracker(config).getChangeSummary(graph, ['src/server.ts']);
+            expect(summary).toHaveLength(1);
+            expect(summary[0].codeFile).toBe('src/server.ts');
+            expect(summary[0].affectedDocs).toEqual(['docs/api.md']);
+        });
+        it('skips files with no affected docs', () => {
+            mockExecFileSync.mockReturnValue('.git\n');
+            const graph = new CodeDocGraph();
+            graph.addReference('docs/api.md', 'src/server.ts', makeRef('src/server.ts'));
+            const summary = new GitChangeTracker(config).getChangeSummary(graph, ['unrelated.ts']);
+            expect(summary).toHaveLength(0);
+        });
+    });
+});
+//# sourceMappingURL=changeTracker.test.js.map

package/dist/git/changeTracker.test.js.map

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

package/dist/graph/codeDocGraph.d.ts

@@ -0,0 +1,43 @@
+import type { GraphReference, Reference, SerializedGraph } from '../types.js';
+/**
+ * Represents the relationship graph between docs and code
+ * Uses adjacency list representation for efficient traversal
+ */
+export declare class CodeDocGraph {
+    docToCode: Map<string, Set<string>>;
+    codeToDoc: Map<string, Set<string>>;
+    codeSymbols: Map<string, Set<string>>;
+    docReferences: Map<string, GraphReference[]>;
+    buildTimestamp: number | null;
+    gitCommit: string | null;
+    configHash: string | null;
+    constructor();
+    /**
+     * Add a reference from a doc to a code file
+     */
+    addReference(docPath: string, codeFilePath: string, reference: Reference): void;
+    /**
+     * Get all docs that reference a specific code file
+     */
+    getDocsReferencingCode(codeFilePath: string): Set<string>;
+    /**
+     * Get all code files referenced by a doc
+     */
+    getCodeReferencedByDoc(docPath: string): Set<string>;
+    /**
+     * Get all document paths in the graph
+     */
+    getAllDocs(): string[];
+    /**
+     * Get all code file paths in the graph
+     */
+    getAllCodeFiles(): string[];
+    /**
+     * Serialize graph for caching
+     */
+    serialize(): SerializedGraph;
+    /**
+     * Deserialize from cache
+     */
+    static deserialize(data: SerializedGraph): CodeDocGraph;
+}

package/dist/graph/codeDocGraph.js

@@ -0,0 +1,103 @@
+/**
+ * Represents the relationship graph between docs and code
+ * Uses adjacency list representation for efficient traversal
+ */
+export class CodeDocGraph {
+    // Map: doc path -> Set of code file paths it references
+    docToCode;
+    // Map: code file path -> Set of doc paths that reference it
+    codeToDoc;
+    // Map: code file path -> Set of symbols defined in it
+    codeSymbols;
+    // Map: doc path -> references with metadata
+    docReferences;
+    // Metadata
+    buildTimestamp;
+    gitCommit;
+    configHash;
+    constructor() {
+        this.docToCode = new Map();
+        this.codeToDoc = new Map();
+        this.codeSymbols = new Map();
+        this.docReferences = new Map();
+        this.buildTimestamp = null;
+        this.gitCommit = null;
+        this.configHash = null;
+    }
+    /**
+     * Add a reference from a doc to a code file
+     */
+    addReference(docPath, codeFilePath, reference) {
+        // Doc -> Code edge
+        if (!this.docToCode.has(docPath)) {
+            this.docToCode.set(docPath, new Set());
+        }
+        this.docToCode.get(docPath).add(codeFilePath);
+        // Code -> Doc edge (reverse index)
+        if (!this.codeToDoc.has(codeFilePath)) {
+            this.codeToDoc.set(codeFilePath, new Set());
+        }
+        this.codeToDoc.get(codeFilePath).add(docPath);
+        // Store reference metadata
+        if (!this.docReferences.has(docPath)) {
+            this.docReferences.set(docPath, []);
+        }
+        this.docReferences.get(docPath).push({
+            ...reference,
+            resolvedCodeFile: codeFilePath,
+        });
+    }
+    /**
+     * Get all docs that reference a specific code file
+     */
+    getDocsReferencingCode(codeFilePath) {
+        return this.codeToDoc.get(codeFilePath) || new Set();
+    }
+    /**
+     * Get all code files referenced by a doc
+     */
+    getCodeReferencedByDoc(docPath) {
+        return this.docToCode.get(docPath) || new Set();
+    }
+    /**
+     * Get all document paths in the graph
+     */
+    getAllDocs() {
+        return Array.from(this.docToCode.keys());
+    }
+    /**
+     * Get all code file paths in the graph
+     */
+    getAllCodeFiles() {
+        return Array.from(this.codeToDoc.keys());
+    }
+    /**
+     * Serialize graph for caching
+     */
+    serialize() {
+        return {
+            docToCode: Object.fromEntries([...this.docToCode].map(([k, v]) => [k, [...v]])),
+            codeToDoc: Object.fromEntries([...this.codeToDoc].map(([k, v]) => [k, [...v]])),
+            codeSymbols: Object.fromEntries([...this.codeSymbols].map(([k, v]) => [k, [...v]])),
+            docReferences: Object.fromEntries(this.docReferences),
+            buildTimestamp: this.buildTimestamp,
+            gitCommit: this.gitCommit,
+            configHash: this.configHash,
+        };
+    }
+    /**
+     * Deserialize from cache
+     */
+    static deserialize(data) {
+        const graph = new CodeDocGraph();
+        graph.docToCode = new Map(Object.entries(data.docToCode || {}).map(([k, v]) => [k, new Set(v)]));
+        graph.codeToDoc = new Map(Object.entries(data.codeToDoc || {}).map(([k, v]) => [k, new Set(v)]));
+        graph.codeSymbols = new Map(Object.entries(data.codeSymbols || {}).map(([k, v]) => [k, new Set(v)]));
+        graph.docReferences = new Map(Object.entries(data.docReferences || {}));
+        graph.buildTimestamp = data.buildTimestamp;
+        graph.gitCommit = data.gitCommit;
+        graph.configHash = data.configHash;
+        return graph;
+    }
+}
+//# sourceMappingURL=codeDocGraph.js.map

package/dist/graph/codeDocGraph.js.map

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

package/dist/graph/codeDocGraph.test.d.ts

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

package/dist/graph/codeDocGraph.test.js

@@ -0,0 +1,78 @@
+import { CodeDocGraph } from './codeDocGraph.js';
+function makeRef(type, value) {
+    return { type, value, lineNumber: 1, raw: value, sourceFile: 'doc.md' };
+}
+describe('CodeDocGraph', () => {
+    let graph;
+    beforeEach(() => {
+        graph = new CodeDocGraph();
+    });
+    describe('addReference', () => {
+        it('creates doc-to-code and code-to-doc edges', () => {
+            graph.addReference('docs/api.md', 'src/server.ts', makeRef('file-path', 'src/server.ts'));
+            expect(graph.getCodeReferencedByDoc('docs/api.md').has('src/server.ts')).toBe(true);
+            expect(graph.getDocsReferencingCode('src/server.ts').has('docs/api.md')).toBe(true);
+        });
+        it('stores reference metadata', () => {
+            const ref = makeRef('code-pattern', 'MyClass');
+            graph.addReference('docs/api.md', 'src/myClass.ts', ref);
+            const docRefs = graph.docReferences.get('docs/api.md');
+            expect(docRefs).toHaveLength(1);
+            expect(docRefs[0].resolvedCodeFile).toBe('src/myClass.ts');
+        });
+        it('handles multiple references from same doc', () => {
+            graph.addReference('docs/api.md', 'src/a.ts', makeRef('file-path', 'a.ts'));
+            graph.addReference('docs/api.md', 'src/b.ts', makeRef('file-path', 'b.ts'));
+            expect(graph.getCodeReferencedByDoc('docs/api.md').size).toBe(2);
+        });
+    });
+    describe('query methods', () => {
+        beforeEach(() => {
+            graph.addReference('docs/a.md', 'src/x.ts', makeRef('file-path', 'x.ts'));
+            graph.addReference('docs/b.md', 'src/x.ts', makeRef('file-path', 'x.ts'));
+            graph.addReference('docs/a.md', 'src/y.ts', makeRef('file-path', 'y.ts'));
+        });
+        it('getDocsReferencingCode returns all docs referencing a code file', () => {
+            expect(graph.getDocsReferencingCode('src/x.ts').size).toBe(2);
+        });
+        it('returns empty set for unknown paths', () => {
+            expect(graph.getDocsReferencingCode('unknown').size).toBe(0);
+            expect(graph.getCodeReferencedByDoc('unknown').size).toBe(0);
+        });
+        it('getAllDocs returns all document paths', () => {
+            expect(graph.getAllDocs().sort()).toEqual(['docs/a.md', 'docs/b.md']);
+        });
+        it('getAllCodeFiles returns all code file paths', () => {
+            expect(graph.getAllCodeFiles().sort()).toEqual(['src/x.ts', 'src/y.ts']);
+        });
+    });
+    describe('serialize / deserialize', () => {
+        it('round-trips correctly', () => {
+            graph.addReference('docs/a.md', 'src/x.ts', makeRef('file-path', 'x.ts'));
+            graph.codeSymbols.set('src/x.ts', new Set(['MyClass', 'myFunc']));
+            graph.buildTimestamp = 12345;
+            graph.gitCommit = 'abc';
+            graph.configHash = 'def';
+            const serialized = graph.serialize();
+            const restored = CodeDocGraph.deserialize(serialized);
+            expect(restored.getCodeReferencedByDoc('docs/a.md').has('src/x.ts')).toBe(true);
+            expect(restored.codeSymbols.get('src/x.ts').has('MyClass')).toBe(true);
+            expect(restored.buildTimestamp).toBe(12345);
+            expect(restored.gitCommit).toBe('abc');
+            expect(restored.configHash).toBe('def');
+        });
+        it('handles empty graph', () => {
+            const serialized = graph.serialize();
+            const restored = CodeDocGraph.deserialize(serialized);
+            expect(restored.getAllDocs()).toEqual([]);
+        });
+        it('handles missing fields in serialized data gracefully', () => {
+            const partial = { buildTimestamp: null, gitCommit: null, configHash: null };
+            const restored = CodeDocGraph.deserialize(partial);
+            expect(restored.getAllDocs()).toEqual([]);
+            expect(restored.getAllCodeFiles()).toEqual([]);
+            expect(restored.codeSymbols.size).toBe(0);
+        });
+    });
+});
+//# sourceMappingURL=codeDocGraph.test.js.map

package/dist/graph/codeDocGraph.test.js.map

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

package/dist/graph/graphBuilder.d.ts

@@ -0,0 +1,17 @@
+import { CodeDocGraph } from './codeDocGraph.js';
+import type { DocFreshnessConfig, Document, SymbolLocation } from '../types.js';
+/**
+ * Builds the code-to-doc relationship graph
+ */
+export declare class GraphBuilder {
+    private config;
+    constructor(config: DocFreshnessConfig);
+    /**
+     * Build the complete code-to-doc graph
+     */
+    buildGraph(documents: Document[], codeIndex: Map<string, SymbolLocation[]> | null): Promise<CodeDocGraph>;
+    /**
+     * Resolve a reference to actual code files
+     */
+    private resolveReference;
+}