ragcode-context-engine 0.1.0

package/dist/src/context/context-builder.js

@@ -0,0 +1,277 @@
+import { nextQueriesForMode, resolveContextMode } from "../retrieval/query-planner.js";
+import { classifyEvidencePath, isExplicitSupportingEvidenceQuery } from "../retrieval/path-classification.js";
+import { renderSnippet } from "./snippet-renderer.js";
+const DEFAULT_BUDGET_CHARS = 18_000;
+export class ContextBuilder {
+    build(request, hits, edges = [], metadata) {
+        const budgetChars = request.budgetChars ?? DEFAULT_BUDGET_CHARS;
+        const mode = resolveContextMode(request.query, request.mode);
+        const { snippets, usedChars } = selectDiverseSnippets(request, hits, mode, budgetChars);
+        const ownerChain = ownerNodes(snippets);
+        const ownerPaths = ownerChain.map((owner) => owner.filePath);
+        const relationships = relationshipEvidence(edges, ownerPaths);
+        const topology = topologyEdges(edges, ownerPaths);
+        const confidence = confidenceFor(snippets);
+        return {
+            query: request.query,
+            repoRoot: metadata.repoRoot,
+            projectId: metadata.projectId,
+            mode,
+            answerable: snippets.length > 0,
+            confidence,
+            brief: briefFor(request.query, mode, confidence, ownerChain),
+            freshness: freshnessFor(metadata),
+            ownerChain,
+            topology,
+            snippets,
+            relationships,
+            nextQueries: nextQueriesForMode(request.query, mode),
+            missingEvidence: missingEvidenceFor(snippets, metadata),
+            budgetChars,
+            usedChars
+        };
+    }
+}
+function selectDiverseSnippets(request, hits, mode, budgetChars) {
+    const candidates = hits.map((hit, index) => {
+        const snippet = renderSnippet(hit, request.query, mode);
+        return {
+            index,
+            key: `${snippet.filePath}\0${snippet.startLine}\0${snippet.endLine}\0${snippet.role}`,
+            snippet,
+            cost: estimateSnippetCost(snippet)
+        };
+    });
+    const selected = [];
+    const selectedKeys = new Set();
+    const snippetsByFile = new Map();
+    let usedChars = 0;
+    const tryAdd = (candidate, maxForFile) => {
+        if (selectedKeys.has(candidate.key))
+            return;
+        const currentForFile = snippetsByFile.get(candidate.snippet.filePath) ?? 0;
+        if (currentForFile >= maxForFile)
+            return;
+        if (usedChars + candidate.cost > budgetChars)
+            return;
+        selectedKeys.add(candidate.key);
+        snippetsByFile.set(candidate.snippet.filePath, currentForFile + 1);
+        selected.push(candidate);
+        usedChars += candidate.cost;
+    };
+    for (const candidate of candidates) {
+        if ((snippetsByFile.get(candidate.snippet.filePath) ?? 0) === 0) {
+            tryAdd(candidate, 1);
+        }
+    }
+    for (const candidate of candidates) {
+        tryAdd(candidate, maxSnippetsForFile(candidate.snippet.filePath, request.query));
+    }
+    return {
+        snippets: selected.sort((a, b) => a.index - b.index).map((candidate) => candidate.snippet),
+        usedChars
+    };
+}
+function missingEvidenceFor(snippets, metadata) {
+    const missing = [];
+    if (snippets.length === 0)
+        missing.push("No indexed context matched the query.");
+    if (metadata.staleFiles?.length)
+        missing.push(`Stale indexed files excluded: ${metadata.staleFiles.slice(0, 8).join(", ")}.`);
+    if (metadata.pendingFiles?.length)
+        missing.push(`Pending files need indexing: ${metadata.pendingFiles.slice(0, 8).join(", ")}.`);
+    if (metadata.burstMode)
+        missing.push(`Watcher burst mode is active; ${metadata.droppedEvents ?? 0} event(s) were dropped or compressed.`);
+    return missing;
+}
+function estimateSnippetCost(snippet) {
+    return snippet.filePath.length + snippet.reason.length + snippet.content.length + 80;
+}
+function maxSnippetsForFile(filePath, query) {
+    const kind = classifyEvidencePath(filePath);
+    if (kind === "implementation")
+        return 3;
+    return isExplicitSupportingEvidenceQuery(query) ? 2 : 1;
+}
+function confidenceFor(snippets) {
+    if (snippets.length >= 3 && (snippets[0]?.score ?? 0) > 1)
+        return "high";
+    if (snippets.length > 0)
+        return "medium";
+    return "low";
+}
+function relationshipEvidence(edges, ownerChain) {
+    if (ownerChain.length === 0)
+        return [];
+    const ownerSet = new Set(ownerChain);
+    return edges
+        .filter((edge) => typeof edge.metadata?.sourceFile === "string" && ownerSet.has(edge.metadata.sourceFile))
+        .slice(0, 12)
+        .map((edge) => ({
+        source: String(edge.metadata?.sourceFile ?? edge.sourceId),
+        target: String(edge.metadata?.targetName ?? edge.metadata?.source ?? edge.targetId),
+        kind: edge.kind,
+        reason: `Graph ${edge.kind} edge from indexed structure`
+    }));
+}
+function ownerNodes(snippets) {
+    const byFile = new Map();
+    for (const snippet of snippets) {
+        const current = byFile.get(snippet.filePath) ?? {
+            filePath: snippet.filePath,
+            role: snippet.role,
+            reason: snippet.reason,
+            score: 0,
+            symbols: []
+        };
+        current.score += snippet.score;
+        current.reason = current.reason.length <= snippet.reason.length ? current.reason : snippet.reason;
+        addOwnerSymbol(current, snippet);
+        byFile.set(snippet.filePath, current);
+    }
+    return [...byFile.values()].sort((a, b) => b.score - a.score);
+}
+function addOwnerSymbol(owner, snippet) {
+    const symbol = symbolFromSnippet(snippet);
+    if (!symbol)
+        return;
+    const key = `${symbol.kind}\0${symbol.name}\0${symbol.startLine}\0${symbol.endLine}`;
+    const exists = owner.symbols.some((existing) => `${existing.kind}\0${existing.name}\0${existing.startLine}\0${existing.endLine}` === key);
+    if (!exists)
+        owner.symbols.push(symbol);
+}
+function symbolFromSnippet(snippet) {
+    const match = /^(function|class|method|type|variable|file):\s+(.+)$/.exec(snippet.role);
+    if (!match)
+        return undefined;
+    const [, kind, name] = match;
+    return {
+        name,
+        kind,
+        startLine: snippet.startLine,
+        endLine: snippet.endLine
+    };
+}
+function topologyEdges(edges, ownerPaths) {
+    const ownerSet = new Set(ownerPaths);
+    const seen = new Set();
+    const output = [];
+    const candidates = edges
+        .filter((edge) => isTopologyEdge(edge.kind) && typeof edge.metadata?.sourceFile === "string" && ownerSet.has(edge.metadata.sourceFile))
+        .sort((a, b) => topologyEdgePriority(b) - topologyEdgePriority(a));
+    for (const edge of candidates) {
+        const topologyEdge = toTopologyEdge(edge);
+        const key = topologyEdgeKey(topologyEdge);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        output.push(topologyEdge);
+        if (output.length >= 12)
+            break;
+    }
+    return output;
+}
+function toTopologyEdge(edge) {
+    return {
+        from: String(edge.metadata?.sourceFile ?? edge.sourceId),
+        to: String(edge.metadata?.route ?? edge.metadata?.targetName ?? edge.targetId),
+        edge: edge.kind,
+        confidence: confidenceForEdge(edge),
+        reason: reasonForEdge(edge),
+        sourceFile: typeof edge.metadata?.sourceFile === "string" ? edge.metadata.sourceFile : undefined,
+        targetFile: typeof edge.metadata?.targetFile === "string" ? edge.metadata.targetFile : undefined
+    };
+}
+function topologyEdgeKey(edge) {
+    return [edge.from, edge.to, edge.edge, edge.sourceFile ?? "", edge.targetFile ?? ""].join("\0");
+}
+function isTopologyEdge(kind) {
+    return kind === "calls"
+        || kind === "calls_api"
+        || kind === "routes_to"
+        || kind === "handles_webhook"
+        || kind === "handles_event"
+        || kind === "tested_by"
+        || kind === "uses_middleware"
+        || kind === "reads_from"
+        || kind === "writes_to";
+}
+function topologyEdgePriority(edge) {
+    if (edge.kind === "handles_webhook")
+        return 100;
+    if (edge.kind === "calls_api")
+        return 90;
+    if (edge.kind === "routes_to")
+        return 85;
+    if (edge.kind === "uses_middleware")
+        return 84;
+    if (edge.kind === "tested_by")
+        return 82;
+    if (edge.kind === "writes_to")
+        return 78;
+    if (edge.kind === "reads_from")
+        return 76;
+    if (edge.kind === "handles_event")
+        return 74;
+    if (edge.metadata?.resolution === "resolved_lsp")
+        return 80;
+    if (edge.metadata?.resolution === "resolved")
+        return 75;
+    if (edge.kind === "calls")
+        return 20;
+    return 10;
+}
+function confidenceForEdge(edge) {
+    if (typeof edge.metadata?.framework === "string")
+        return "high";
+    if (edge.metadata?.resolution === "test_import")
+        return "high";
+    if (edge.metadata?.resolution === "resource_static" || edge.metadata?.resolution === "event_static")
+        return "high";
+    if (edge.metadata?.resolution === "resolved" || edge.metadata?.resolution === "resolved_lsp")
+        return "high";
+    if (edge.metadata?.targetName)
+        return "medium";
+    return "low";
+}
+function reasonForEdge(edge) {
+    if (edge.kind === "calls_api")
+        return "Static framework topology edge from client API call to route handler.";
+    if (edge.kind === "routes_to")
+        return "Framework route-to-service edge derived from resolved call graph.";
+    if (edge.kind === "handles_webhook")
+        return "Framework webhook route recognized from route path.";
+    if (edge.kind === "tested_by")
+        return "Test coverage edge derived from a resolved test import.";
+    if (edge.kind === "uses_middleware")
+        return "Framework middleware usage edge derived from route and middleware files.";
+    if (edge.kind === "reads_from")
+        return "Resource read edge derived from a static data-access call.";
+    if (edge.kind === "writes_to")
+        return "Resource write edge derived from a static data-access call.";
+    if (edge.kind === "handles_event")
+        return "Event handler edge derived from a static event subscription.";
+    if (edge.metadata?.resolution === "resolved")
+        return "Resolved AST import/export call edge.";
+    if (edge.metadata?.resolution === "resolved_lsp")
+        return "Resolved TypeScript Language Service definition edge.";
+    return "AST call edge; may be unresolved until import/LSP resolution lands.";
+}
+function freshnessFor(metadata) {
+    return {
+        projectId: metadata.projectId,
+        indexGeneration: metadata.indexGeneration ?? 1,
+        indexedAtMs: metadata.indexedAtMs,
+        staleFiles: metadata.staleFiles ?? [],
+        pendingFiles: metadata.pendingFiles ?? [],
+        indexingFiles: metadata.indexingFiles ?? [],
+        skippedFiles: metadata.skippedFiles,
+        dirtyFiles: metadata.dirtyFiles ?? [],
+        burstMode: metadata.burstMode ?? false,
+        droppedEvents: metadata.droppedEvents ?? 0
+    };
+}
+function briefFor(query, mode, confidence, owners) {
+    const ownerText = owners.length > 0 ? owners.slice(0, 3).map((owner) => owner.filePath).join(", ") : "no indexed owner";
+    return `${mode} context for "${query}" (${confidence} confidence). Primary owner evidence: ${ownerText}.`;
+}

package/dist/src/context/expansion-policy.d.ts

@@ -0,0 +1,6 @@
+import type { CodeChunk, ContextMode, ExpansionLevel } from "../core/types.js";
+export interface ExpansionDecision {
+    expansionLevel: ExpansionLevel;
+    focusLine?: number;
+}
+export declare function chooseExpansion(chunk: CodeChunk, query: string, mode: Exclude<ContextMode, "auto">): ExpansionDecision;

package/dist/src/context/expansion-policy.js

@@ -0,0 +1,49 @@
+const LARGE_CHUNK_LINES = 80;
+export function chooseExpansion(chunk, query, mode) {
+    const originalLineCount = lineCount(chunk.content);
+    if (explicitFullRequest(query))
+        return { expansionLevel: "full_body" };
+    if (originalLineCount <= LARGE_CHUNK_LINES)
+        return { expansionLevel: "focused_body" };
+    const focusLine = bestMatchingLine(chunk.content, query);
+    if (focusLine !== undefined && shouldFocusLargeChunk(chunk, query, mode)) {
+        return { expansionLevel: "focused_body", focusLine };
+    }
+    if (mode === "debug" && focusLine !== undefined)
+        return { expansionLevel: "focused_body", focusLine };
+    return { expansionLevel: "skeleton" };
+}
+function explicitFullRequest(query) {
+    return /\b(full body|full source|entire file|完整|全部源码)\b/i.test(query);
+}
+function shouldFocusLargeChunk(chunk, query, mode) {
+    if (mode === "debug" || mode === "review")
+        return true;
+    if (chunk.symbolName && query.toLowerCase().includes(chunk.symbolName.toLowerCase()))
+        return true;
+    return false;
+}
+function bestMatchingLine(content, query) {
+    const terms = queryTerms(query);
+    if (terms.length === 0)
+        return undefined;
+    const lines = content.split(/\r?\n/);
+    let best;
+    for (let index = 0; index < lines.length; index += 1) {
+        const lower = lines[index].toLowerCase();
+        const score = terms.reduce((sum, term) => lower.includes(term) ? sum + term.length : sum, 0);
+        if (score > 0 && (!best || score > best.score))
+            best = { line: index + 1, score };
+    }
+    return best?.line;
+}
+function queryTerms(query) {
+    return query
+        .toLowerCase()
+        .split(/[^a-z0-9_:-]+/i)
+        .map((part) => part.trim())
+        .filter((part) => part.length >= 3);
+}
+function lineCount(content) {
+    return content.length === 0 ? 0 : content.split(/\r?\n/).length;
+}

package/dist/src/context/skeletonizer.d.ts

@@ -0,0 +1,2 @@
+import type { CodeChunk } from "../core/types.js";
+export declare function skeletonizeChunk(chunk: CodeChunk): string;

package/dist/src/context/skeletonizer.js

@@ -0,0 +1,79 @@
+import ts from "typescript";
+export function skeletonizeChunk(chunk) {
+    if (chunk.language !== "typescript" && chunk.language !== "javascript")
+        return genericSkeleton(chunk.content);
+    const sourceFile = ts.createSourceFile(chunk.filePath, chunk.content, ts.ScriptTarget.Latest, true, scriptKindForPath(chunk.filePath));
+    const declarations = [];
+    for (const statement of sourceFile.statements) {
+        const rendered = renderDeclaration(sourceFile, statement);
+        if (rendered)
+            declarations.push(rendered);
+    }
+    if (declarations.length === 0 && chunk.symbolName)
+        return `${chunk.kind} ${chunk.symbolName} { ... }`;
+    return declarations.length > 0 ? declarations.join("\n\n") : genericSkeleton(chunk.content);
+}
+function renderDeclaration(sourceFile, node) {
+    if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node))
+        return firstLine(sourceFile, node);
+    if (ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node))
+        return sourceText(sourceFile, node);
+    if (ts.isFunctionDeclaration(node))
+        return `${leadingComment(sourceFile, node)}${functionSignature(sourceFile, node)} { ... }`.trim();
+    if (ts.isClassDeclaration(node))
+        return renderClass(sourceFile, node);
+    if (ts.isVariableStatement(node))
+        return `${leadingComment(sourceFile, node)}${firstLine(sourceFile, node).replace(/=\s*.+;?$/, "= ...;")}`.trim();
+    return undefined;
+}
+function renderClass(sourceFile, node) {
+    const name = node.name?.text ?? "AnonymousClass";
+    const heritage = node.heritageClauses?.map((clause) => sourceText(sourceFile, clause)).join(" ") ?? "";
+    const members = node.members
+        .map((member) => renderClassMember(sourceFile, member))
+        .filter(Boolean)
+        .map((member) => `  ${member}`)
+        .join("\n");
+    return `${leadingComment(sourceFile, node)}class ${name}${heritage ? ` ${heritage}` : ""} {\n${members}\n}`.trim();
+}
+function renderClassMember(sourceFile, member) {
+    if (ts.isConstructorDeclaration(member))
+        return `${firstLine(sourceFile, member).replace(/\{\s*$/, "").trim()} { ... }`;
+    if (ts.isMethodDeclaration(member))
+        return `${firstLine(sourceFile, member).replace(/\{\s*$/, "").trim()} { ... }`;
+    if (ts.isPropertyDeclaration(member))
+        return firstLine(sourceFile, member).replace(/=\s*.+;?$/, "= ...;");
+    return undefined;
+}
+function functionSignature(sourceFile, node) {
+    const text = sourceText(sourceFile, node);
+    const bodyStart = text.indexOf("{");
+    return (bodyStart >= 0 ? text.slice(0, bodyStart) : text).trim();
+}
+function genericSkeleton(content) {
+    const first = content.split(/\r?\n/).find((line) => line.trim())?.trim() ?? "[empty chunk]";
+    return `${first}\n...`;
+}
+function leadingComment(sourceFile, node) {
+    const comments = ts.getLeadingCommentRanges(sourceFile.text, node.getFullStart()) ?? [];
+    const rendered = comments
+        .map((comment) => sourceFile.text.slice(comment.pos, comment.end).trim())
+        .filter((comment) => comment.startsWith("/**"))
+        .join("\n");
+    return rendered ? `${rendered}\n` : "";
+}
+function firstLine(sourceFile, node) {
+    return sourceText(sourceFile, node).split(/\r?\n/, 1)[0]?.trim() ?? "";
+}
+function sourceText(sourceFile, node) {
+    return sourceFile.text.slice(node.getStart(sourceFile), node.getEnd()).trim();
+}
+function scriptKindForPath(filePath) {
+    if (filePath.endsWith(".tsx"))
+        return ts.ScriptKind.TSX;
+    if (filePath.endsWith(".jsx"))
+        return ts.ScriptKind.JSX;
+    if (filePath.endsWith(".js") || filePath.endsWith(".mjs") || filePath.endsWith(".cjs"))
+        return ts.ScriptKind.JS;
+    return ts.ScriptKind.TS;
+}

package/dist/src/context/snippet-renderer.d.ts

@@ -0,0 +1,2 @@
+import type { ContextMode, ContextSnippet, SearchHit } from "../core/types.js";
+export declare function renderSnippet(hit: SearchHit, query: string, mode: Exclude<ContextMode, "auto">): ContextSnippet;

package/dist/src/context/snippet-renderer.js

@@ -0,0 +1,67 @@
+import { chooseExpansion } from "./expansion-policy.js";
+import { skeletonizeChunk } from "./skeletonizer.js";
+const FOCUS_WINDOW_LINES = 28;
+export function renderSnippet(hit, query, mode) {
+    const originalLineCount = lineCount(hit.chunk.content);
+    const decision = chooseExpansion(hit.chunk, query, mode);
+    const rendered = renderContent(hit, decision.expansionLevel, decision.focusLine);
+    const returnedLineCount = lineCount(rendered);
+    return {
+        filePath: hit.chunk.filePath,
+        startLine: renderedStartLine(hit, decision.focusLine),
+        endLine: renderedEndLine(hit, rendered, decision.focusLine),
+        content: rendered,
+        score: hit.score,
+        reason: hit.reason,
+        role: roleForHit(hit),
+        expansionLevel: decision.expansionLevel,
+        originalLineCount,
+        returnedLineCount,
+        elidedLineCount: Math.max(0, originalLineCount - returnedLineCount)
+    };
+}
+function renderContent(hit, expansionLevel, focusLine) {
+    if (expansionLevel === "full_body")
+        return hit.chunk.content;
+    if (expansionLevel === "skeleton")
+        return skeletonizeChunk(hit.chunk);
+    if (expansionLevel === "file_card")
+        return fileCard(hit);
+    if (focusLine !== undefined)
+        return focusedWindow(hit.chunk.content, focusLine);
+    return hit.chunk.content;
+}
+function focusedWindow(content, focusLine) {
+    const lines = content.split(/\r?\n/);
+    const half = Math.floor(FOCUS_WINDOW_LINES / 2);
+    const start = Math.max(0, focusLine - 1 - half);
+    const end = Math.min(lines.length, start + FOCUS_WINDOW_LINES);
+    const prefix = start > 0 ? ["..."] : [];
+    const suffix = end < lines.length ? ["..."] : [];
+    return [...prefix, ...lines.slice(start, end), ...suffix].join("\n");
+}
+function renderedStartLine(hit, focusLine) {
+    if (focusLine === undefined)
+        return hit.chunk.startLine;
+    return hit.chunk.startLine + Math.max(0, focusLine - 1 - Math.floor(FOCUS_WINDOW_LINES / 2));
+}
+function renderedEndLine(hit, content, focusLine) {
+    if (focusLine === undefined)
+        return hit.chunk.startLine + Math.max(0, lineCount(content) - 1);
+    return renderedStartLine(hit, focusLine) + Math.max(0, lineCount(content) - 1);
+}
+function fileCard(hit) {
+    return [
+        `${hit.chunk.kind}: ${hit.chunk.symbolName ?? hit.chunk.filePath}`,
+        `language: ${hit.chunk.language}`,
+        `lines: ${hit.chunk.startLine}-${hit.chunk.endLine}`
+    ].join("\n");
+}
+function roleForHit(hit) {
+    if (hit.chunk.symbolName)
+        return `${hit.chunk.kind}: ${hit.chunk.symbolName}`;
+    return `${hit.chunk.kind} evidence`;
+}
+function lineCount(content) {
+    return content.length === 0 ? 0 : content.split(/\r?\n/).length;
+}

package/dist/src/core/contracts.d.ts

@@ -0,0 +1,74 @@
+import type { CodeChunk, CodeFile, ContextPack, ContextRequest, DiffReview, EdgeKind, GraphEdge, ImpactAnalysis, IndexStatus, IndexRefreshOptions, OwnerCandidate, RelatedTests, ReuseCandidateReport, ReuseCandidateRequest, RepoIndex, SearchHit, SearchQuery, SymbolNode, TopologyMap, TopologyMapRequest, TraceFlow, VerifiedCodeSubgraph, VerifiedSubgraphRequest, ProjectIdentity, WatcherEventOptions, WatcherState } from "./types.js";
+export interface EmbeddingProvider {
+    readonly dimensions?: number;
+    embed(text: string): Promise<number[]>;
+    embedBatch?(texts: string[]): Promise<number[][]>;
+}
+export interface GraphStore {
+    close?(): void;
+    getProjectByRoot?(repoRoot: string): Promise<ProjectIdentity | undefined>;
+    listProjects?(): Promise<ProjectIdentity[]>;
+    getIndexGeneration?(repoRoot: string): Promise<number>;
+    recordFileEvents?(repoRoot: string, filePaths: string[], options?: WatcherEventOptions): Promise<WatcherState>;
+    getWatcherState?(repoRoot: string): Promise<WatcherState>;
+    markDirtyFilesIndexing?(repoRoot: string, filePaths: string[]): Promise<WatcherState>;
+    markDirtyFilesDeadLetter?(repoRoot: string, filePaths: string[], reason: string): Promise<WatcherState>;
+    clearDirtyFiles?(repoRoot: string, filePaths?: string[]): Promise<void>;
+    needsRebuild?(repoRoot: string, projectId: string): Promise<boolean>;
+    resetRepo(repoRoot: string): Promise<void>;
+    upsertIndex(index: RepoIndex): Promise<void>;
+    getFiles(repoRoot: string): Promise<CodeFile[]>;
+    getChunks(repoRoot: string): Promise<CodeChunk[]>;
+    getSkippedFiles(repoRoot: string): Promise<Array<{
+        filePath: string;
+        reason: string;
+    }>>;
+    getSymbols(repoRoot: string): Promise<SymbolNode[]>;
+    getEdges(repoRoot: string, kind?: EdgeKind): Promise<GraphEdge[]>;
+    findSymbol(repoRoot: string, name: string): Promise<SymbolNode[]>;
+    explainFile(repoRoot: string, filePath: string): Promise<{
+        file?: CodeFile;
+        chunks: CodeChunk[];
+        symbols: SymbolNode[];
+    }>;
+    searchText(query: SearchQuery): Promise<SearchHit[]>;
+    findOwner(repoRoot: string, query: string, limit?: number): Promise<OwnerCandidate[]>;
+    impactAnalysis(repoRoot: string, target: string): Promise<ImpactAnalysis>;
+    relatedTests(repoRoot: string, target: string): Promise<RelatedTests>;
+    traceFlow(repoRoot: string, entry: string, maxSteps?: number): Promise<TraceFlow>;
+    reviewDiff(repoRoot: string, diff?: string, changedFiles?: string[]): Promise<DiffReview>;
+}
+export interface SemanticStore {
+    needsRebuild?(repoRoot: string, projectId: string): Promise<boolean>;
+    resetRepo(repoRoot: string): Promise<void>;
+    deleteFile?(repoRoot: string, projectId: string, filePath: string): Promise<void>;
+    upsertChunks(chunks: CodeChunk[], provider: EmbeddingProvider, generation?: number): Promise<void>;
+    search(query: SearchQuery, provider: EmbeddingProvider): Promise<SearchHit[]>;
+}
+export interface Indexer {
+    indexRepo(repoRoot: string, projectId: string, project?: ProjectIdentity, options?: IndexRefreshOptions): Promise<RepoIndex>;
+}
+export interface ContextEngine {
+    indexRepo(repoRoot: string, options?: IndexRefreshOptions): Promise<RepoIndex>;
+    refreshIndex(repoRoot: string | undefined, options?: IndexRefreshOptions): Promise<RepoIndex>;
+    indexStatus(repoRoot: string | undefined): Promise<IndexStatus>;
+    recordFileEvents(repoRoot: string | undefined, filePaths: string[], options?: WatcherEventOptions): Promise<WatcherState>;
+    markDirtyFilesIndexing(repoRoot: string | undefined, filePaths: string[]): Promise<WatcherState>;
+    markDirtyFilesDeadLetter(repoRoot: string | undefined, filePaths: string[], reason: string): Promise<WatcherState>;
+    searchCode(query: SearchQuery): Promise<SearchHit[]>;
+    getContext(request: ContextRequest): Promise<ContextPack>;
+    verifiedSubgraph(request: VerifiedSubgraphRequest): Promise<VerifiedCodeSubgraph>;
+    topologyMap(request: TopologyMapRequest): Promise<TopologyMap>;
+    findSymbol(repoRoot: string | undefined, name: string): Promise<SymbolNode[]>;
+    explainFile(repoRoot: string | undefined, filePath: string): Promise<{
+        file?: CodeFile;
+        chunks: CodeChunk[];
+        symbols: SymbolNode[];
+    }>;
+    findOwner(repoRoot: string | undefined, query: string, limit?: number): Promise<OwnerCandidate[]>;
+    findReuseCandidates(request: ReuseCandidateRequest): Promise<ReuseCandidateReport>;
+    impactAnalysis(repoRoot: string | undefined, target: string): Promise<ImpactAnalysis>;
+    relatedTests(repoRoot: string | undefined, target: string): Promise<RelatedTests>;
+    traceFlow(repoRoot: string | undefined, entry: string, maxSteps?: number): Promise<TraceFlow>;
+    reviewDiff(repoRoot: string | undefined, diff?: string, changedFiles?: string[]): Promise<DiffReview>;
+}

package/dist/src/core/contracts.js

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

package/dist/src/core/engine.d.ts

@@ -0,0 +1,64 @@
+import type { ContextEngine, EmbeddingProvider, GraphStore, SemanticStore } from "./contracts.js";
+import type { ContextPack, ContextRequest, DiffReview, GraphEdge, ImpactAnalysis, IndexRefreshOptions, IndexStatus, OwnerCandidate, RelatedTests, ReuseCandidateReport, ReuseCandidateRequest, RepoIndex, SearchHit, SearchQuery, SymbolNode, TopologyMap, TopologyMapRequest, TraceFlow, VerifiedCodeSubgraph, VerifiedSubgraphRequest, WatcherEventOptions, WatcherState } from "./types.js";
+import { type HybridSearchDiagnostics } from "../retrieval/hybrid-retriever.js";
+import type { CodeFile, CodeChunk } from "./types.js";
+export interface RagCodeEngineOptions {
+    graphStore?: GraphStore;
+    semanticStore?: SemanticStore;
+    embeddingProvider?: EmbeddingProvider;
+    workspaceRoots?: string[];
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}
+export declare class RagCodeEngine implements ContextEngine {
+    private readonly graphStore;
+    private readonly semanticStore;
+    private readonly embeddingProvider;
+    private readonly projectRegistry;
+    private readonly workspaceResolver;
+    private readonly contextBuilder;
+    private readonly indexedAtByRepo;
+    private readonly cwd;
+    private readonly workspaceRoots;
+    private readonly hydratedRoots;
+    private hydratedAllProjects;
+    constructor(options?: RagCodeEngineOptions);
+    close(): void;
+    indexRepo(repoRoot: string, options?: IndexRefreshOptions): Promise<RepoIndex>;
+    refreshIndex(repoRoot: string | undefined, options?: IndexRefreshOptions): Promise<RepoIndex>;
+    indexStatus(repoRoot: string | undefined): Promise<IndexStatus>;
+    recordFileEvents(repoRoot: string | undefined, filePaths: string[], options?: WatcherEventOptions): Promise<WatcherState>;
+    markDirtyFilesIndexing(repoRoot: string | undefined, filePaths: string[]): Promise<WatcherState>;
+    markDirtyFilesDeadLetter(repoRoot: string | undefined, filePaths: string[], reason: string): Promise<WatcherState>;
+    searchCode(query: SearchQuery): Promise<SearchHit[]>;
+    searchCodeWithDiagnostics(query: SearchQuery): Promise<{
+        hits: SearchHit[];
+        diagnostics: HybridSearchDiagnostics;
+    }>;
+    getContext(request: ContextRequest): Promise<ContextPack>;
+    verifiedSubgraph(request: VerifiedSubgraphRequest): Promise<VerifiedCodeSubgraph>;
+    topologyMap(request: TopologyMapRequest): Promise<TopologyMap>;
+    findSymbol(repoRoot: string | undefined, name: string): Promise<SymbolNode[]>;
+    graphSnapshot(repoRoot: string | undefined): Promise<{
+        symbols: SymbolNode[];
+        edges: GraphEdge[];
+    }>;
+    explainFile(repoRoot: string | undefined, filePath: string): Promise<{
+        file?: CodeFile;
+        chunks: CodeChunk[];
+        symbols: SymbolNode[];
+    }>;
+    findOwner(repoRoot: string | undefined, query: string, limit?: number): Promise<OwnerCandidate[]>;
+    findReuseCandidates(request: ReuseCandidateRequest): Promise<ReuseCandidateReport>;
+    impactAnalysis(repoRoot: string | undefined, target: string): Promise<ImpactAnalysis>;
+    relatedTests(repoRoot: string | undefined, target: string): Promise<RelatedTests>;
+    traceFlow(repoRoot: string | undefined, entry: string, maxSteps?: number): Promise<TraceFlow>;
+    reviewDiff(repoRoot: string | undefined, diff?: string, changedFiles?: string[]): Promise<DiffReview>;
+    private resolveWorkspace;
+    private hydrateForInput;
+    private hydrateProjectByRoot;
+    private hydrateAllPersistedProjects;
+    private rememberHydratedProject;
+    private searchWithFreshness;
+    private computeFreshness;
+}