@eduardo-afonso/codebase-intelligence 0.1.0 → 2.0.0

package/dist/context/ContextEngine.js

@@ -0,0 +1,179 @@
+import * as path from 'path';
+import { ShallowStrategy } from './strategies/ShallowStrategy.js';
+import { SignatureStrategy } from './strategies/SignatureStrategy.js';
+import { DeepStrategy } from './strategies/DeepStrategy.js';
+import { FileContextBuilder } from './FileContextBuilder.js';
+const DEFAULT_STRATEGY = 'signature';
+const DEFAULT_MAX_TOKENS = 8_000;
+/**
+ * Builds LLM-ready context payloads from an analysed `Codebase`.
+ *
+ * Consumers should obtain an instance via `codebase.context()` rather than
+ * constructing one directly.
+ *
+ * @example
+ * ```ts
+ * const payload = await codebase.context().forFile('src/auth/AuthService.ts', {
+ *   strategy: 'signature',
+ *   maxTokens: 6000,
+ * });
+ * ```
+ */
+export class ContextEngine {
+    graph;
+    symbolIndex;
+    fileIndex;
+    codebaseRoot;
+    strategies = {
+        shallow: new ShallowStrategy(),
+        signature: new SignatureStrategy(),
+        deep: new DeepStrategy(),
+    };
+    builder = new FileContextBuilder();
+    constructor(graph, symbolIndex, fileIndex, codebaseRoot) {
+        this.graph = graph;
+        this.symbolIndex = symbolIndex;
+        this.fileIndex = fileIndex;
+        this.codebaseRoot = codebaseRoot;
+    }
+    // ---- Public API -------------------------------------------------------
+    async forFile(file, options = {}) {
+        const absolutePath = this.resolveFilePath(file);
+        const codebaseFile = this.requireFile(absolutePath);
+        return this.buildPayload(codebaseFile, options);
+    }
+    async forSymbol(symbolName, options = {}) {
+        const symbol = this.symbolIndex.findSymbol(symbolName);
+        if (!symbol) {
+            throw new Error(`ContextEngine: symbol "${symbolName}" not found in the index. ` +
+                `Make sure codebase.analyze() has been called.`);
+        }
+        const codebaseFile = this.requireFile(symbol.file);
+        return this.buildPayload(codebaseFile, options);
+    }
+    // ---- Core build logic -------------------------------------------------
+    async buildPayload(targetFile, options) {
+        const strategy = options.strategy ?? DEFAULT_STRATEGY;
+        const maxTokens = options.maxTokens ?? DEFAULT_MAX_TOKENS;
+        // 1. Gather metadata from the graph
+        const directDeps = this.graph.dependenciesOf(targetFile.path);
+        const directDependents = this.graph.dependentsOf(targetFile.path);
+        const relatedTests = this.findRelatedTests(targetFile.path);
+        const metadata = {
+            directDependencies: directDeps,
+            directDependents,
+            relatedTests,
+        };
+        // 2. Resolve dependency CodebaseFile objects
+        const dependencyFiles = directDeps
+            .map(depPath => this.fileIndex.getByPath(depPath))
+            .filter((f) => f !== undefined);
+        // 3. Delegate to the selected strategy
+        const strategyImpl = this.strategies[strategy];
+        const strategyNodes = await strategyImpl.buildNodes(targetFile, dependencyFiles, this.symbolIndex, this.codebaseRoot);
+        // 4. Optionally include dependents (always as shallow/full-file nodes)
+        const dependentNodes = [];
+        if (options.includeDependents) {
+            for (const depPath of directDependents) {
+                const depFile = this.fileIndex.getByPath(depPath);
+                if (!depFile)
+                    continue;
+                dependentNodes.push(await this.builder.buildFileNode(depFile, this.codebaseRoot));
+            }
+        }
+        // 5. Optionally include related test files
+        const testNodes = [];
+        if (options.includeTests) {
+            for (const testPath of relatedTests) {
+                const testFile = this.fileIndex.getByPath(testPath);
+                if (!testFile)
+                    continue;
+                testNodes.push(await this.builder.buildFileNode(testFile, this.codebaseRoot));
+            }
+        }
+        // 6. Assemble: strategy nodes first, then dependents, then tests.
+        //    Respect the maxTokens budget by dropping lower-priority nodes from the end.
+        const allNodes = [...strategyNodes, ...dependentNodes, ...testNodes];
+        const nodes = this.applyTokenBudget(allNodes, maxTokens);
+        const totalTokenEstimate = estimateTokens(nodes);
+        return {
+            target: targetFile.relativePath,
+            strategy,
+            nodes,
+            totalTokenEstimate,
+            metadata,
+        };
+    }
+    // ---- Token budget enforcement -----------------------------------------
+    /**
+     * Drops nodes from the *end* of the list (lower priority) until the
+     * total token estimate fits within the budget.
+     *
+     * The first node (the target) is NEVER dropped.
+     */
+    applyTokenBudget(nodes, maxTokens) {
+        if (nodes.length === 0)
+            return nodes;
+        // nodes[0] is guaranteed to exist — the length check above ensures it.
+        const target = nodes[0];
+        const result = [target];
+        let tokensSoFar = estimateTokens(result);
+        for (let i = 1; i < nodes.length; i++) {
+            const candidate = nodes[i];
+            const candidateTokens = estimateTokens([candidate]);
+            if (tokensSoFar + candidateTokens <= maxTokens) {
+                result.push(candidate);
+                tokensSoFar += candidateTokens;
+            }
+            // Drop the node silently — the metadata still records it existed
+        }
+        return result;
+    }
+    // ---- Path resolution --------------------------------------------------
+    /**
+     * Resolves a file argument to an absolute path.
+     * Accepts both absolute paths and paths relative to the codebase root.
+     */
+    resolveFilePath(file) {
+        if (path.isAbsolute(file))
+            return file;
+        return path.resolve(this.codebaseRoot, file);
+    }
+    /**
+     * Returns the `CodebaseFile` for the given absolute path.
+     * Throws a descriptive error if the file is not in the index.
+     */
+    requireFile(absolutePath) {
+        const file = this.fileIndex.getByPath(absolutePath) ??
+            this.fileIndex.getByRelativePath(path.relative(this.codebaseRoot, absolutePath));
+        if (!file) {
+            throw new Error(`ContextEngine: file "${absolutePath}" is not in the codebase index. ` +
+                `Make sure codebase.analyze() has been called and the path is correct.`);
+        }
+        return file;
+    }
+    // ---- Related tests ----------------------------------------------------
+    /**
+     * Finds test files related to `filePath` by naming convention only.
+     * No graph proof is used — this mirrors the behaviour of `ImpactAnalyzer`.
+     */
+    findRelatedTests(filePath) {
+        const basename = path.basename(filePath, path.extname(filePath));
+        const testSuffixes = ['.test.ts', '.spec.ts', '.test.js', '.spec.js'];
+        const candidates = new Set(testSuffixes.map(s => `${basename}${s}`));
+        return this.graph.nodes().filter(node => candidates.has(path.basename(node)));
+    }
+}
+// ---------------------------------------------------------------------------
+// Token estimation
+// ---------------------------------------------------------------------------
+/**
+ * Rough token estimate: `totalChars / 4`.
+ * Avoids a hard dependency on a tokeniser library while being accurate enough
+ * for budget planning (typical ratio for English/code text).
+ */
+function estimateTokens(nodes) {
+    const totalChars = nodes.reduce((sum, n) => sum + n.content.length, 0);
+    return Math.ceil(totalChars / 4);
+}
+//# sourceMappingURL=ContextEngine.js.map

package/dist/context/ContextEngine.js.map

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

package/dist/context/FileContextBuilder.d.ts

@@ -0,0 +1,49 @@
+import type { ContextNode } from './types.js';
+import type { CodebaseFile, CodeSymbol } from '../core/types.js';
+/**
+ * Reads a source file from disk and constructs a `ContextNode` of kind `'file'`
+ * that represents the full content of that file.
+ *
+ * This is the low-level primitive used by strategies. Strategies decide *which*
+ * files to pass here and how to compose the resulting nodes into a payload.
+ */
+export declare class FileContextBuilder {
+    /**
+     * Builds a single `ContextNode` for a whole file.
+     *
+     * @param file     - The `CodebaseFile` descriptor (path, relativePath, etc.).
+     * @param codebaseRoot - Absolute path to the codebase root, used to compute
+     *                       `relativePath` as a fallback when `file.relativePath`
+     *                       is an absolute path.
+     */
+    buildFileNode(file: CodebaseFile, codebaseRoot: string): Promise<ContextNode>;
+    /**
+     * Builds a `ContextNode` of kind `'signature'` for a given file.
+     *
+     * A signature node contains only the lines that correspond to top-level
+     * symbol declarations (class, function, interface, etc.) as extracted by
+     * the `SymbolIndex`. This gives the LLM full type information without the
+     * implementation body.
+     *
+     * When no symbols are found for the file, falls back to returning a full
+     * file node so the payload is never empty.
+     *
+     * @param file     - The `CodebaseFile` descriptor.
+     * @param symbols  - Symbols extracted for this file by the `SymbolIndex`.
+     * @param codebaseRoot - Absolute codebase root for relativePath computation.
+     */
+    buildSignatureNode(file: CodebaseFile, symbols: CodeSymbol[], codebaseRoot: string): Promise<ContextNode>;
+    /**
+     * Returns a normalised relative path for `file`, computing it from the
+     * absolute path when `file.relativePath` is itself absolute (can happen
+     * with older index builds).
+     */
+    resolveRelativePath(file: CodebaseFile, codebaseRoot: string): string;
+    private readFile;
+    private normaliseRelativePath;
+}
+/**
+ * Builds a stable, unique node ID in the format `relativePath:start-end`.
+ */
+export declare function buildNodeId(relativePath: string, start: number, end: number): string;
+//# sourceMappingURL=FileContextBuilder.d.ts.map

package/dist/context/FileContextBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileContextBuilder.d.ts","sourceRoot":"","sources":["../../src/context/FileContextBuilder.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEjE;;;;;;GAMG;AACH,qBAAa,kBAAkB;IAC7B;;;;;;;OAOG;IACU,aAAa,CACxB,IAAI,EAAE,YAAY,EAClB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,WAAW,CAAC,CAgBtB;IAED;;;;;;;;;;;;;;OAcG;IACU,kBAAkB,CAC7B,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,UAAU,EAAE,EACrB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,WAAW,CAAC,CA0CtB;IAID;;;;OAIG;IACI,mBAAmB,CAAC,IAAI,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAE3E;YAIa,QAAQ;IAUtB,OAAO,CAAC,qBAAqB;CAY9B;AAMD;;GAEG;AACH,wBAAgB,WAAW,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEpF"}

package/dist/context/FileContextBuilder.js

@@ -0,0 +1,124 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+/**
+ * Reads a source file from disk and constructs a `ContextNode` of kind `'file'`
+ * that represents the full content of that file.
+ *
+ * This is the low-level primitive used by strategies. Strategies decide *which*
+ * files to pass here and how to compose the resulting nodes into a payload.
+ */
+export class FileContextBuilder {
+    /**
+     * Builds a single `ContextNode` for a whole file.
+     *
+     * @param file     - The `CodebaseFile` descriptor (path, relativePath, etc.).
+     * @param codebaseRoot - Absolute path to the codebase root, used to compute
+     *                       `relativePath` as a fallback when `file.relativePath`
+     *                       is an absolute path.
+     */
+    async buildFileNode(file, codebaseRoot) {
+        const content = await this.readFile(file.path);
+        const lines = content.split('\n');
+        const totalLines = lines.length;
+        const relativePath = this.normaliseRelativePath(file.relativePath, file.path, codebaseRoot);
+        return {
+            id: buildNodeId(relativePath, 1, totalLines),
+            file: file.path,
+            relativePath,
+            content,
+            kind: 'file',
+            startLine: 1,
+            endLine: totalLines,
+        };
+    }
+    /**
+     * Builds a `ContextNode` of kind `'signature'` for a given file.
+     *
+     * A signature node contains only the lines that correspond to top-level
+     * symbol declarations (class, function, interface, etc.) as extracted by
+     * the `SymbolIndex`. This gives the LLM full type information without the
+     * implementation body.
+     *
+     * When no symbols are found for the file, falls back to returning a full
+     * file node so the payload is never empty.
+     *
+     * @param file     - The `CodebaseFile` descriptor.
+     * @param symbols  - Symbols extracted for this file by the `SymbolIndex`.
+     * @param codebaseRoot - Absolute codebase root for relativePath computation.
+     */
+    async buildSignatureNode(file, symbols, codebaseRoot) {
+        const content = await this.readFile(file.path);
+        const lines = content.split('\n');
+        const relativePath = this.normaliseRelativePath(file.relativePath, file.path, codebaseRoot);
+        if (symbols.length === 0) {
+            // No symbols — fall back to the full file node
+            return this.buildFileNode(file, codebaseRoot);
+        }
+        // Collect only the declaration lines (startLine) of top-level symbols.
+        // Children (methods inside a class) are intentionally excluded because
+        // the class signature line already signals the class's existence.
+        const topLevelSymbols = symbols.filter(s => s.parentId === undefined);
+        const declarationLineNumbers = new Set(topLevelSymbols.map(s => s.startLine));
+        const signatureLines = lines
+            .map((line, i) => ({ line, lineNumber: i + 1 })) // 1-based
+            .filter(({ lineNumber }) => declarationLineNumbers.has(lineNumber))
+            .map(({ line }) => line);
+        // Always include import lines — they communicate the dependency surface.
+        const importLines = lines.filter(l => l.trimStart().startsWith('import '));
+        // Deduplicate (import lines may already be declaration lines for re-exports)
+        const signatureContent = [
+            ...importLines,
+            ...(importLines.length > 0 ? [''] : []), // blank separator
+            ...signatureLines,
+        ]
+            .join('\n')
+            .trim();
+        return {
+            id: buildNodeId(relativePath, 1, lines.length),
+            file: file.path,
+            relativePath,
+            content: signatureContent || content, // never return empty content
+            kind: 'signature',
+            startLine: 1,
+            endLine: lines.length,
+        };
+    }
+    // ---- Public helpers -----------------------------------------------------
+    /**
+     * Returns a normalised relative path for `file`, computing it from the
+     * absolute path when `file.relativePath` is itself absolute (can happen
+     * with older index builds).
+     */
+    resolveRelativePath(file, codebaseRoot) {
+        return this.normaliseRelativePath(file.relativePath, file.path, codebaseRoot);
+    }
+    // ---- Private helpers ----------------------------------------------------
+    async readFile(filePath) {
+        try {
+            return await fs.readFile(filePath, 'utf-8');
+        }
+        catch (err) {
+            // Surface a clear error rather than a generic ENOENT stack trace.
+            const message = err instanceof Error ? err.message : String(err);
+            throw new Error(`ContextEngine: could not read file "${filePath}": ${message}`);
+        }
+    }
+    normaliseRelativePath(relativePath, absolutePath, codebaseRoot) {
+        // If the stored relativePath happens to be an absolute path (older index
+        // versions), compute it from scratch.
+        if (path.isAbsolute(relativePath)) {
+            return path.relative(codebaseRoot, absolutePath);
+        }
+        return relativePath;
+    }
+}
+// ---------------------------------------------------------------------------
+// Utility
+// ---------------------------------------------------------------------------
+/**
+ * Builds a stable, unique node ID in the format `relativePath:start-end`.
+ */
+export function buildNodeId(relativePath, start, end) {
+    return `${relativePath}:${start}-${end}`;
+}
+//# sourceMappingURL=FileContextBuilder.js.map

package/dist/context/FileContextBuilder.js.map

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

package/dist/context/SemanticChunker.d.ts

@@ -0,0 +1,105 @@
+import type { CodebaseFile, SymbolKind } from '../core/types.js';
+/**
+ * A semantically complete fragment of a source file, suitable for embedding
+ * or retrieval in a RAG pipeline.
+ *
+ * Unlike character-based splits, every `SemanticChunk` is guaranteed to
+ * correspond to a complete AST declaration (class, function, method, etc.) so
+ * it can always be understood in isolation when paired with the file header.
+ */
+export interface SemanticChunk {
+    /**
+     * Stable unique identifier: `<relativePath>:<startLine>-<endLine>`.
+     * Matches the format used by `ContextNode.id`.
+     */
+    id: string;
+    /** Absolute path to the source file. */
+    file: string;
+    /** Path relative to the codebase root. */
+    relativePath: string;
+    /**
+     * The content of this chunk.
+     *
+     * For `symbolKind !== 'file'`, the content always starts with the file
+     * header (imports) so the chunk can be understood in isolation.
+     */
+    content: string;
+    /**
+     * The granularity of this chunk:
+     * - `'file'`      — the entire file (used when a small file fits in one chunk)
+     * - a `SymbolKind` — a top-level declaration or one of its methods
+     */
+    symbolKind: SymbolKind | 'file';
+    /** Name of the top-level symbol (or the method name for sub-chunks). */
+    symbolName?: string;
+    /** 1-based start line in the source file. */
+    startLine: number;
+    /** 1-based end line in the source file. */
+    endLine: number;
+    /** Rough token estimate: `Math.ceil(content.length / 4)`. */
+    tokenEstimate: number;
+}
+/** Options for `SemanticChunker.chunk()`. */
+export interface ChunkerOptions {
+    /**
+     * Maximum token budget for a single chunk before it is split by methods.
+     * @default 512
+     */
+    maxChunkTokens?: number;
+    /**
+     * Whether to prepend the file header (imports + top-of-file comments) to
+     * each symbol chunk. Recommended so each chunk is self-contained.
+     * @default true
+     */
+    includeFileHeader?: boolean;
+}
+/**
+ * Divides TypeScript/JavaScript source files into semantically coherent
+ * chunks using the `ts-morph` AST.
+ *
+ * Unlike character or line-based splitters, `SemanticChunker` guarantees that:
+ * - No chunk cuts across a declaration boundary.
+ * - Large symbols (classes with many methods) are split **by method**, not
+ *   arbitrarily.
+ * - Each chunk includes the file header (imports) so it can be embedded
+ *   and understood without additional context.
+ *
+ * @example
+ * ```ts
+ * const chunker = new SemanticChunker();
+ * const chunks = await chunker.chunk(codebase.files(), { maxChunkTokens: 512 });
+ * ```
+ */
+export declare class SemanticChunker {
+    private readonly project;
+    constructor();
+    /**
+     * Chunks the given list of files into semantically complete fragments.
+     *
+     * Only TypeScript and JavaScript files are processed via AST chunking.
+     * Other file types (JSON, config files) are returned as a single whole-file
+     * chunk if they fit within `maxChunkTokens`, or omitted otherwise.
+     *
+     * @param files   - The list of `CodebaseFile`s to chunk.
+     * @param options - Chunking configuration.
+     * @returns Ordered list of `SemanticChunk`s across all processed files.
+     */
+    chunk(files: CodebaseFile[], options?: ChunkerOptions): Promise<SemanticChunk[]>;
+    private chunkFile;
+    private chunksForDeclaration;
+    /**
+     * Emits the class as one chunk. If that chunk exceeds `maxChunkTokens`,
+     * falls back to per-method sub-chunking.
+     */
+    private chunksForClass;
+    /**
+     * Splits an oversized class into one chunk per method/constructor.
+     * Properties and the class header are included in every method chunk.
+     */
+    private subChunkByMethod;
+    private buildSymbolChunk;
+    private buildWholeFileChunk;
+    private chunkNonTsFile;
+    private buildChunk;
+}
+//# sourceMappingURL=SemanticChunker.d.ts.map

package/dist/context/SemanticChunker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SemanticChunker.d.ts","sourceRoot":"","sources":["../../src/context/SemanticChunker.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAMjE;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,EAAE,EAAE,MAAM,CAAC;IACX,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,UAAU,EAAE,UAAU,GAAG,MAAM,CAAC;IAChC,wEAAwE;IACxE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,6CAA6C;AAC7C,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAElC,cASC;IAED;;;;;;;;;;OAUG;IACU,KAAK,CAChB,KAAK,EAAE,YAAY,EAAE,EACrB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,aAAa,EAAE,CAAC,CAU1B;YAIa,SAAS;IA0CvB,OAAO,CAAC,oBAAoB;IAmB5B;;;OAGG;IACH,OAAO,CAAC,cAAc;IA+BtB;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IA4ExB,OAAO,CAAC,gBAAgB;IAiBxB,OAAO,CAAC,mBAAmB;IAK3B,OAAO,CAAC,cAAc;IAatB,OAAO,CAAC,UAAU;CAwBnB"}