ragcode-context-engine 0.1.0

package/dist/src/diagnostics/doctor.js

@@ -0,0 +1,193 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { loadRuntimeConfig, redactRuntimeConfig } from "../config/runtime-config.js";
+import { RagCodeEngine } from "../core/engine.js";
+import { createMcpServer } from "../mcp/server.js";
+import { listToolDefinitions } from "../mcp/tools.js";
+import { readWatcherLiveness } from "../watch/watcher-liveness.js";
+export async function runDoctor(options = {}) {
+    const cwd = path.resolve(options.cwd ?? process.cwd());
+    const env = options.env ?? process.env;
+    const runtime = readCheck(() => loadRuntimeConfig({ cwd, env, overrides: options.repoRoot ? { repoRoot: path.resolve(cwd, options.repoRoot) } : undefined }));
+    const sqlite = await importCheck("node:sqlite", "node:sqlite import ok");
+    const lancedb = await importCheck("@lancedb/lancedb", "@lancedb/lancedb import ok");
+    const mcpSdk = await importCheck("@modelcontextprotocol/sdk/server/mcp.js", "@modelcontextprotocol/sdk import ok");
+    const mcp = createMcpCheck();
+    const report = {
+        ok: true,
+        cwd,
+        node: checkNodeVersion(),
+        runtime: {
+            graph: runtime.ok
+                ? { ok: true, message: "graph runtime config ok", config: redactRuntimeConfig(runtime.value) }
+                : { ok: false, message: runtime.message },
+            semantic: runtime.ok
+                ? { ok: true, message: "semantic runtime config ok", config: redactRuntimeConfig(runtime.value) }
+                : { ok: false, message: runtime.message }
+        },
+        dependencies: {
+            sqlite,
+            lancedb,
+            mcpSdk
+        },
+        mcp
+    };
+    if (options.repoRoot) {
+        report.watcher = await buildWatcherCheck(path.resolve(cwd, options.repoRoot));
+        report.smoke = await runRepoSmoke({
+            cwd,
+            env,
+            repoRoot: options.repoRoot,
+            searchQuery: options.searchQuery ?? "export function class import"
+        });
+    }
+    report.ok = [
+        report.node,
+        report.runtime.graph,
+        report.runtime.semantic,
+        report.dependencies.sqlite,
+        report.dependencies.lancedb,
+        report.dependencies.mcpSdk,
+        report.mcp,
+        report.smoke
+    ].filter((check) => Boolean(check)).every((check) => check.ok);
+    return report;
+}
+// Watcher liveness is informational: a repo with no running watcher is a valid (if not-auto-fresh)
+// state, so this never flips report.ok to false. It surfaces the gap the lifecycle work closes —
+// "indexed but nothing keeps it fresh" — so `doctor <repo>` is where a user discovers they should
+// run `ragcode service install`.
+async function buildWatcherCheck(repoRoot) {
+    const liveness = await readWatcherLiveness(repoRoot);
+    const message = liveness.state === "running"
+        ? `Watcher running (pid ${liveness.lock?.pid}); heartbeat ${liveness.heartbeatAgeMs}ms ago.`
+        : liveness.state === "stale"
+            ? `Watcher process is alive but its heartbeat is stale (${liveness.heartbeatAgeMs}ms old); it may be hung.`
+            : liveness.state === "dead"
+                ? "A watcher lock/heartbeat exists but no live process backs it; it likely crashed. Re-run `ragcode service install` or `ragcode watch`."
+                : "No background watcher running. The index will not auto-refresh. Run `ragcode service install <repo>` to keep it fresh across reboots.";
+    return {
+        ok: true,
+        message,
+        state: liveness.state,
+        processAlive: liveness.processAlive,
+        heartbeatFresh: liveness.heartbeatFresh,
+        heartbeatAgeMs: liveness.heartbeatAgeMs,
+        pendingFiles: liveness.heartbeat?.pendingFiles,
+        indexingFiles: liveness.heartbeat?.indexingFiles
+    };
+}
+function checkNodeVersion() {
+    const major = Number(process.versions.node.split(".")[0]);
+    return {
+        ok: Number.isFinite(major) && major >= 24,
+        message: `Node ${process.version}; required >=24.0.0 for node:sqlite graph storage`
+    };
+}
+function readCheck(read) {
+    try {
+        return { ok: true, value: read() };
+    }
+    catch (error) {
+        return { ok: false, message: errorMessage(error) };
+    }
+}
+async function importCheck(specifier, okMessage) {
+    try {
+        await import(specifier);
+        return { ok: true, message: okMessage };
+    }
+    catch (error) {
+        return { ok: false, message: errorMessage(error) };
+    }
+}
+function createMcpCheck() {
+    const tools = listToolDefinitions();
+    try {
+        const server = createMcpServer(createNoopEngine());
+        return {
+            ok: !server.isConnected() && tools.length > 0,
+            message: `MCP server factory ok with ${tools.length} tool(s)`,
+            toolCount: tools.length,
+            tools: tools.map((tool) => tool.name)
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            message: errorMessage(error),
+            toolCount: tools.length,
+            tools: tools.map((tool) => tool.name)
+        };
+    }
+}
+async function runRepoSmoke(options) {
+    const repoRoot = path.resolve(options.cwd, options.repoRoot);
+    let engine;
+    try {
+        const stat = await fs.stat(repoRoot).catch((error) => {
+            throw new Error(`repoRoot is not readable: ${repoRoot}. ${errorMessage(error)}`);
+        });
+        if (!stat.isDirectory()) {
+            throw new Error(`repoRoot is not a directory: ${repoRoot}`);
+        }
+        engine = new RagCodeEngine({ cwd: options.cwd, env: options.env });
+        const index = await engine.indexRepo(repoRoot);
+        const status = await engine.indexStatus(repoRoot);
+        const hits = await engine.searchCode({ repoRoot, query: options.searchQuery, limit: 5 });
+        return {
+            ok: true,
+            message: "repo smoke indexed and searched successfully",
+            repoRoot,
+            indexed: {
+                projectId: index.projectId,
+                repoRoot: index.repoRoot,
+                indexedAtMs: index.indexedAtMs,
+                files: index.files.length,
+                chunks: index.chunks.length,
+                symbols: index.symbols.length,
+                edges: index.edges.length,
+                skippedFiles: index.skippedFiles.length
+            },
+            status: {
+                fileCount: status.fileCount,
+                chunkCount: status.chunkCount,
+                symbolCount: status.symbolCount,
+                edgeCount: status.edgeCount,
+                staleFileCount: status.staleFileCount,
+                pendingFileCount: status.pendingFileCount,
+                skippedFileCount: status.skippedFileCount
+            },
+            search: {
+                query: options.searchQuery,
+                hits: hits.map((hit) => ({
+                    filePath: hit.chunk.filePath,
+                    startLine: hit.chunk.startLine,
+                    endLine: hit.chunk.endLine,
+                    score: hit.score,
+                    source: hit.source,
+                    reason: hit.reason
+                }))
+            }
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            message: errorMessage(error),
+            repoRoot
+        };
+    }
+    finally {
+        engine?.close();
+    }
+}
+function createNoopEngine() {
+    const handler = async () => ({ ok: true });
+    return new Proxy({}, {
+        get: () => handler
+    });
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/src/diagnostics/embedding-test.d.ts

@@ -0,0 +1,24 @@
+import { type RuntimeConfig, type RuntimeConfigOverrides } from "../config/runtime-config.js";
+export type EmbeddingFailureKind = "missing_key" | "auth_failure" | "model_not_found" | "network_failure" | "dimensions_mismatch" | "unsupported_dimensions_request" | "unknown";
+export interface EmbeddingTestResult {
+    ok: boolean;
+    provider: RuntimeConfig["semantic"]["embeddingProvider"];
+    model?: string;
+    baseUrl?: string;
+    requestedDimensions?: number;
+    dimensions?: number;
+    latencyMs?: number;
+    failure?: {
+        kind: EmbeddingFailureKind;
+        message: string;
+    };
+}
+export interface EmbeddingTestOptions {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    overrides?: RuntimeConfigOverrides;
+    fetchImpl?: typeof fetch;
+    sampleText?: string;
+}
+export declare function runEmbeddingTest(options?: EmbeddingTestOptions): Promise<EmbeddingTestResult>;
+export declare function testEmbeddingForConfig(config: RuntimeConfig, options?: Pick<EmbeddingTestOptions, "fetchImpl" | "sampleText">): Promise<EmbeddingTestResult>;

package/dist/src/diagnostics/embedding-test.js

@@ -0,0 +1,83 @@
+import { performance } from "node:perf_hooks";
+import { loadRuntimeConfig } from "../config/runtime-config.js";
+import { DeterministicEmbeddingProvider } from "../semantic/deterministic-embedding.js";
+import { OpenAICompatibleEmbeddingProvider } from "../semantic/openai-compatible-embedding.js";
+export async function runEmbeddingTest(options = {}) {
+    const config = loadRuntimeConfig({ cwd: options.cwd, env: options.env, overrides: options.overrides });
+    return testEmbeddingForConfig(config, options);
+}
+// Runs one small embedding request against the effective provider and classifies failures.
+// Never includes the API key in the result; baseUrl/model are not secrets and stay visible
+// so doctor/configure output remains actionable.
+export async function testEmbeddingForConfig(config, options = {}) {
+    const semantic = config.semantic;
+    const base = {
+        ok: false,
+        provider: semantic.embeddingProvider,
+        model: semantic.embeddingModel,
+        baseUrl: semantic.embeddingProvider === "openai-compatible" ? semantic.embeddingBaseUrl : undefined,
+        requestedDimensions: semantic.embeddingDimensions
+    };
+    if (semantic.embeddingProvider === "openai-compatible" && !config.embeddingApiKey) {
+        return {
+            ...base,
+            failure: {
+                kind: "missing_key",
+                message: "No embedding API key configured. Set RAGCODE_EMBEDDING_API_KEY (or OPENAI_API_KEY), or run `ragcode configure`."
+            }
+        };
+    }
+    const provider = semantic.embeddingProvider === "deterministic"
+        ? new DeterministicEmbeddingProvider(semantic.embeddingDimensions ?? 64)
+        : new OpenAICompatibleEmbeddingProvider({
+            apiKey: config.embeddingApiKey ?? "",
+            model: semantic.embeddingModel ?? "text-embedding-3-small",
+            baseUrl: semantic.embeddingBaseUrl,
+            dimensions: semantic.embeddingDimensions,
+            requestDimensions: semantic.embeddingRequestDimensions,
+            fetch: options.fetchImpl
+        });
+    const startedAt = performance.now();
+    try {
+        const vector = await provider.embed(options.sampleText ?? "ragcode embedding connectivity test");
+        const latencyMs = Math.round(performance.now() - startedAt);
+        if (semantic.embeddingDimensions !== undefined && vector.length !== semantic.embeddingDimensions) {
+            return {
+                ...base,
+                dimensions: vector.length,
+                latencyMs,
+                failure: {
+                    kind: "dimensions_mismatch",
+                    message: `Provider returned ${vector.length} dimensions but ${semantic.embeddingDimensions} are configured. Align embeddingDimensions or enable embeddingRequestDimensions if the provider supports it.`
+                }
+            };
+        }
+        return { ...base, ok: true, dimensions: vector.length, latencyMs };
+    }
+    catch (error) {
+        return {
+            ...base,
+            latencyMs: Math.round(performance.now() - startedAt),
+            failure: classifyEmbeddingFailure(error)
+        };
+    }
+}
+function classifyEmbeddingFailure(error) {
+    const candidate = error;
+    const message = candidate?.message ?? String(error);
+    const lowered = message.toLowerCase();
+    const causeCode = candidate?.cause?.code ?? "";
+    if (candidate?.status === 401 || candidate?.status === 403 || /unauthorized|invalid api key|incorrect api key|forbidden/.test(lowered)) {
+        return { kind: "auth_failure", message: "Authentication failed. Check the embedding API key." };
+    }
+    if ((candidate?.status === 404 && /model/.test(lowered)) || /model.*(not found|does not exist)/.test(lowered)) {
+        return { kind: "model_not_found", message: `Embedding model rejected by the provider: ${message}` };
+    }
+    if (/dimensions?.*(unsupported|not supported|invalid)|unsupported.*dimensions?|does not support.*dimensions?/.test(lowered)) {
+        return { kind: "unsupported_dimensions_request", message: `Provider rejected the dimensions request: ${message}` };
+    }
+    if (/^(ECONNREFUSED|ENOTFOUND|ETIMEDOUT|ECONNRESET|EAI_AGAIN)$/.test(causeCode) || /fetch failed|network|econnrefused|enotfound|etimedout/.test(lowered)) {
+        return { kind: "network_failure", message: `Could not reach the embedding endpoint: ${message}` };
+    }
+    return { kind: "unknown", message };
+}

package/dist/src/graph/diff-files.d.ts

@@ -0,0 +1 @@
+export declare function extractChangedFiles(diff: string): string[];

package/dist/src/graph/diff-files.js

@@ -0,0 +1,14 @@
+import parseDiff from "parse-diff";
+import { normalizeUserPath } from "../utils/path.js";
+export function extractChangedFiles(diff) {
+    const files = new Set();
+    for (const file of parseDiff(diff)) {
+        if (file.deleted)
+            continue;
+        const target = file.to ?? file.from;
+        if (!target || target === "/dev/null")
+            continue;
+        files.add(normalizeUserPath(target));
+    }
+    return [...files].sort();
+}

package/dist/src/graph/impact-report.d.ts

@@ -0,0 +1,10 @@
+import type { GraphEdge, ImpactAnalysis, ImpactReference, SymbolNode } from "../core/types.js";
+export interface ImpactReportInput {
+    target: string;
+    matchedSymbols: SymbolNode[];
+    incomingEdges: GraphEdge[];
+    outgoingEdges: GraphEdge[];
+    symbols: SymbolNode[];
+}
+export declare function buildImpactAnalysis(input: ImpactReportInput): ImpactAnalysis;
+export declare function impactReference(edge: GraphEdge, symbolsById: Map<string, SymbolNode>): ImpactReference;

package/dist/src/graph/impact-report.js

@@ -0,0 +1,173 @@
+export function buildImpactAnalysis(input) {
+    const symbolsById = new Map(input.symbols.map((symbol) => [symbol.id, symbol]));
+    const minimalPackByFile = new Map();
+    const allEdges = [...input.incomingEdges, ...input.outgoingEdges];
+    for (const symbol of input.matchedSymbols) {
+        addPackItem(minimalPackByFile, symbol.filePath, "target", `Matched target symbol ${symbol.name}.`, [symbol]);
+    }
+    for (const edge of input.incomingEdges) {
+        const source = symbolsById.get(edge.sourceId);
+        const target = symbolsById.get(edge.targetId);
+        if (source)
+            addPackItem(minimalPackByFile, source.filePath, roleForIncoming(edge.kind), `Incoming ${edge.kind} reference to target.`, [source]);
+        if (target)
+            addPackItem(minimalPackByFile, target.filePath, "target", `Target side of incoming ${edge.kind} reference.`, [target]);
+        addMetadataFiles(minimalPackByFile, edge, roleForIncoming(edge.kind), `Incoming ${edge.kind} metadata reference.`);
+    }
+    for (const edge of input.outgoingEdges) {
+        const source = symbolsById.get(edge.sourceId);
+        const target = symbolsById.get(edge.targetId);
+        if (source)
+            addPackItem(minimalPackByFile, source.filePath, "target", `Source side of outgoing ${edge.kind} reference.`, [source]);
+        if (target)
+            addPackItem(minimalPackByFile, target.filePath, roleForOutgoing(edge.kind), `Outgoing ${edge.kind} reference from target.`, [target]);
+        addMetadataFiles(minimalPackByFile, edge, roleForOutgoing(edge.kind), `Outgoing ${edge.kind} metadata reference.`);
+    }
+    const minimalPack = [...minimalPackByFile.values()].sort((a, b) => rolePriority(a.role) - rolePriority(b.role) || a.filePath.localeCompare(b.filePath));
+    const references = uniqueReferences(allEdges.map((edge) => impactReference(edge, symbolsById)));
+    const impactedFiles = minimalPack.map((item) => item.filePath);
+    const riskLevel = riskFor(minimalPack.length, references.length);
+    return {
+        target: input.target,
+        minimalPack,
+        references,
+        nextQueries: nextQueriesFor(input.target, references),
+        matchedSymbols: input.matchedSymbols,
+        impactedFiles,
+        incomingEdges: input.incomingEdges,
+        outgoingEdges: input.outgoingEdges,
+        riskLevel
+    };
+}
+export function impactReference(edge, symbolsById) {
+    const source = symbolsById.get(edge.sourceId);
+    const target = symbolsById.get(edge.targetId);
+    return {
+        edge: edge.kind,
+        sourceFile: source?.filePath ?? stringMetadata(edge, "sourceFile"),
+        targetFile: target?.filePath ?? stringMetadata(edge, "targetFile"),
+        sourceSymbol: source?.name,
+        targetSymbol: target?.name,
+        targetName: stringMetadata(edge, "targetName"),
+        reason: reasonForEdge(edge.kind),
+        confidence: confidenceForEdge(edge)
+    };
+}
+function addMetadataFiles(items, edge, role, reason) {
+    const sourceFile = stringMetadata(edge, "sourceFile");
+    const targetFile = stringMetadata(edge, "targetFile");
+    if (sourceFile)
+        addPackItem(items, sourceFile, role === "test" ? "target" : role, reason, []);
+    if (targetFile)
+        addPackItem(items, targetFile, role, reason, []);
+}
+function addPackItem(items, filePath, role, reason, symbols) {
+    const existing = items.get(filePath);
+    if (!existing) {
+        items.set(filePath, {
+            filePath,
+            role,
+            reason,
+            symbols: symbols.map(symbolSummary)
+        });
+        return;
+    }
+    if (rolePriority(role) < rolePriority(existing.role))
+        existing.role = role;
+    if (existing.reason.length > reason.length)
+        existing.reason = reason;
+    const byName = new Map(existing.symbols.map((symbol) => [`${symbol.kind}:${symbol.name}:${symbol.startLine}`, symbol]));
+    for (const symbol of symbols.map(symbolSummary))
+        byName.set(`${symbol.kind}:${symbol.name}:${symbol.startLine}`, symbol);
+    existing.symbols = [...byName.values()];
+}
+function symbolSummary(symbol) {
+    return {
+        name: symbol.name,
+        kind: symbol.kind,
+        startLine: symbol.startLine,
+        endLine: symbol.endLine
+    };
+}
+function roleForIncoming(kind) {
+    if (kind === "calls_api" || kind === "routes_to")
+        return "route";
+    if (kind === "tested_by")
+        return "test";
+    if (kind === "uses_middleware")
+        return "middleware";
+    return "caller";
+}
+function roleForOutgoing(kind) {
+    if (kind === "tested_by")
+        return "test";
+    if (kind === "uses_middleware")
+        return "middleware";
+    if (kind === "reads_from" || kind === "writes_to")
+        return "resource_owner";
+    if (kind === "handles_event")
+        return "event_owner";
+    if (kind === "calls_api" || kind === "routes_to")
+        return "route";
+    return "callee";
+}
+function rolePriority(role) {
+    if (role === "target")
+        return 0;
+    if (role === "test")
+        return 1;
+    if (role === "caller" || role === "callee" || role === "route")
+        return 2;
+    return 3;
+}
+function reasonForEdge(kind) {
+    if (kind === "tested_by")
+        return "Test coverage edge from indexed graph.";
+    if (kind === "routes_to")
+        return "Route-to-service edge from indexed topology.";
+    if (kind === "calls_api")
+        return "Client-to-API edge from indexed topology.";
+    if (kind === "uses_middleware")
+        return "Middleware usage edge from indexed topology.";
+    if (kind === "reads_from")
+        return "Resource read edge from indexed topology.";
+    if (kind === "writes_to")
+        return "Resource write edge from indexed topology.";
+    if (kind === "handles_event")
+        return "Event handler edge from indexed topology.";
+    return `Graph ${kind} edge from indexed structure.`;
+}
+function confidenceForEdge(edge) {
+    if (edge.kind === "tested_by")
+        return "high";
+    if (edge.metadata?.resolution === "resolved" || edge.metadata?.resolution === "resolved_lsp")
+        return "high";
+    if (edge.metadata?.resolution === "framework_static" || edge.metadata?.resolution === "resource_static" || edge.metadata?.resolution === "event_static")
+        return "high";
+    if (edge.metadata?.targetName)
+        return "medium";
+    return "low";
+}
+function nextQueriesFor(target, references) {
+    const queries = [`get_context ${target}`, `trace_flow ${target}`];
+    if (references.some((reference) => reference.edge === "tested_by"))
+        queries.push(`related_tests ${target}`);
+    if (references.some((reference) => reference.edge === "reads_from" || reference.edge === "writes_to"))
+        queries.push(`topology_map ${target} data flow`);
+    return [...new Set(queries)];
+}
+function riskFor(fileCount, referenceCount) {
+    const score = fileCount + referenceCount;
+    return score > 12 ? "high" : score > 4 ? "medium" : "low";
+}
+function uniqueReferences(references) {
+    const byKey = new Map();
+    for (const reference of references) {
+        byKey.set([reference.edge, reference.sourceFile, reference.targetFile, reference.targetName].join("::"), reference);
+    }
+    return [...byKey.values()];
+}
+function stringMetadata(edge, key) {
+    const value = edge.metadata?.[key];
+    return typeof value === "string" ? value : undefined;
+}

package/dist/src/graph/in-memory-graph-store.d.ts

@@ -0,0 +1,36 @@
+import type { GraphStore } from "../core/contracts.js";
+import type { CodeChunk, CodeFile, DiffReview, EdgeKind, GraphEdge, ImpactAnalysis, OwnerCandidate, RelatedTests, RepoIndex, SearchHit, SearchQuery, SymbolNode, TraceFlow, WatcherEventOptions, WatcherState } from "../core/types.js";
+export declare class InMemoryGraphStore implements GraphStore {
+    private readonly repos;
+    resetRepo(repoRoot: string): Promise<void>;
+    upsertIndex(index: RepoIndex): Promise<void>;
+    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>;
+    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>;
+    private ensureRepo;
+    private clearDirtyRows;
+    private deleteFileRows;
+}