devlensio 0.2.0

package/dist/summarizer/checkpoint.js

@@ -0,0 +1,110 @@
+// Purely a read/write utility — no LLM calls, no complex logic.
+//
+// createCheckpoint()  — called at start of fresh summarization run
+// loadCheckpoint()    — called on resume
+// saveCheckpoint()    — called after every level/group completes
+// deleteCheckpoint()  — called on cancel or completion
+// getResumePoint()    — returns { phase, levelIndex } — where to continue from
+import fs from "fs";
+import { getCheckpointPath } from "../storage/fileStorage.js";
+// ─── Load / Save / Delete ─────────────────────────────────────────────────────
+export function loadCheckpoint(graphId, commitHash) {
+    const file = getCheckpointPath(graphId, commitHash);
+    if (!fs.existsSync(file))
+        return undefined;
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf-8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function saveCheckpoint(checkpoint) {
+    const file = getCheckpointPath(checkpoint.graphId, checkpoint.commitHash);
+    checkpoint.updatedAt = new Date().toISOString();
+    // Atomic write — never corrupts on crash mid-write
+    const tmp = `${file}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(checkpoint, null, 2), "utf-8");
+    fs.renameSync(tmp, file);
+}
+export function deleteCheckpoint(graphId, commitHash) {
+    const file = getCheckpointPath(graphId, commitHash);
+    if (fs.existsSync(file))
+        fs.unlinkSync(file);
+}
+// ─── Create ───────────────────────────────────────────────────────────────────
+//
+// Called once at the start of a fresh summarization run.
+// nodeOrder is now string[][] — each inner array is one parallel level.
+// On resume we load this file and never redo the topo sort.
+export function createCheckpoint(graphId, commitHash, nodeOrder, cycleGroups, fileNodes) {
+    const now = new Date().toISOString();
+    const totalRegularNodes = nodeOrder.reduce((sum, level) => sum + level.length, 0);
+    const totalCycleNodes = cycleGroups.reduce((sum, g) => sum + g.size, 0);
+    const totalNodes = totalRegularNodes + totalCycleNodes + fileNodes.length;
+    const checkpoint = {
+        graphId,
+        commitHash,
+        status: "running",
+        createdAt: now,
+        updatedAt: now,
+        nodeOrder,
+        cycleGroups,
+        fileNodes,
+        // -1 = not started for all three phases
+        lastCompletedLevel: -1,
+        lastCompletedCycleGroup: -1,
+        lastCompletedFileNode: -1,
+        totalNodes,
+        completedNodes: 0,
+    };
+    saveCheckpoint(checkpoint);
+    return checkpoint;
+}
+export function getResumePoint(checkpoint) {
+    // Phase 1 — regular nodes (level by level)
+    if (checkpoint.lastCompletedLevel < checkpoint.nodeOrder.length - 1) {
+        return {
+            phase: "nodes",
+            index: checkpoint.lastCompletedLevel + 1,
+        };
+    }
+    // Phase 2 — cycle groups
+    if (checkpoint.lastCompletedCycleGroup < checkpoint.cycleGroups.length - 1) {
+        return {
+            phase: "cycles",
+            index: checkpoint.lastCompletedCycleGroup + 1,
+        };
+    }
+    // Phase 3 — file nodes
+    if (checkpoint.lastCompletedFileNode < checkpoint.fileNodes.length - 1) {
+        return {
+            phase: "files",
+            index: checkpoint.lastCompletedFileNode + 1,
+        };
+    }
+    return { phase: "done", index: -1 };
+}
+// ─── Progress update helpers ──────────────────────────────────────────────────
+//
+// Called by the batch loop after each level/group/file completes.
+// Marks an entire level as completed — levels are atomic.
+export function markLevelCompleted(checkpoint, levelIndex) {
+    checkpoint.lastCompletedLevel = levelIndex;
+    checkpoint.completedNodes += checkpoint.nodeOrder[levelIndex].length;
+}
+export function markCycleGroupCompleted(checkpoint, groupIndex) {
+    checkpoint.lastCompletedCycleGroup = groupIndex;
+    checkpoint.completedNodes += checkpoint.cycleGroups[groupIndex].size;
+}
+export function markFileNodeCompleted(checkpoint, index) {
+    checkpoint.lastCompletedFileNode = index;
+    checkpoint.completedNodes++;
+}
+// Marks a batch of file nodes as completed.
+// batchEnd = index of the LAST node in the batch (inclusive).
+// count    = how many nodes were actually in the batch (may be < batchSize at end).
+export function markFileNodeBatchCompleted(checkpoint, batchEnd, count) {
+    checkpoint.lastCompletedFileNode = batchEnd;
+    checkpoint.completedNodes += count;
+}

package/dist/summarizer/index.d.ts

@@ -0,0 +1,2 @@
+import { type SummarizationInput } from "./types.js";
+export declare function runSummarization(input: SummarizationInput): Promise<void>;

package/dist/summarizer/index.js

@@ -0,0 +1,281 @@
+// ─── Summarization Architecture ───────────────────────────────────────────────
+//
+// Triggered after Phase 1 (analysis) completes for a job.
+//
+// SMART REUSE
+//   Before summarizing, we check if the commit was already summarized (skip entirely),
+//   or if a previous summarized commit exists — nodes whose codeHash hasn't changed
+//   get their summaries copied for free without any LLM call.
+//
+// JOB-SCOPED INDEXES
+//   edgeIndex, routeIndex, systemPrompt, and allNodesMap are built ONCE per job
+//   before the batch loop starts. A job is tied to a single commit — nodes, edges,
+//   and routes never change mid-job even if the user edits code. Building indexes
+//   once and reusing them across all batches avoids O(n×e) redundant work.
+//
+// THREE PHASES (in order)
+//   Phase 1 — nodeOrder[][]   topo-sorted levels, each level runs in parallel
+//   Phase 2 — cycleGroups[]   nodes with circular deps, grouped or individual
+//   Phase 3 — fileNodes[]     FILE nodes last — use child summaries as context
+//
+// PAUSE / CANCEL
+//   Signals are checked between levels/groups — never mid-level.
+//   Levels complete atomically so resume always starts at a clean boundary.
+//   Checkpoint is saved after every level/group — O(1) resume via lastCompletedLevel.
+//
+// MAPREDUCE
+//   Nodes whose rawCode exceeds MAPREDUCE_TOKEN_THRESHOLD are split into chunks,
+//   each chunk summarized in parallel (map), then reduced into one final summary.
+import { storage } from "../storage/index.js";
+import { resolveConfig } from "../config/index.js";
+import { FILE_BATCH_SIZE } from "./types.js";
+import { buildTopologicalOrder } from "./topological.js";
+import { createCheckpoint, loadCheckpoint, saveCheckpoint, deleteCheckpoint, getResumePoint, markLevelCompleted, markCycleGroupCompleted, markFileNodeBatchCompleted, } from "./checkpoint.js";
+import { buildEdgeIndex, buildRouteIndex, buildSystemPrompt, buildPrompt, buildCycleGroupPrompt, } from "./prompts.js";
+import { createLLMClient } from "./providers/index.js";
+import { exceedsThreshold, mapreduceSummarize } from "./mapreduce.js";
+import { withRetry } from "./retry.js";
+import { MAX_GROUP_SUMMARY_SIZE } from "./types.js";
+// ─── runSummarization ─────────────────────────────────────────────────────────
+//
+// Main entry point — called by runner.ts after Phase 1 completes.
+// Handles fresh runs and resumes from checkpoint transparently.
+//
+// Flow:
+//   1. Load commit data (nodes, edges, fingerprint, routes)
+//   2. Check if already summarized → skip
+//   3. Copy summaries from previous commit where codeHash matches → free reuse
+//   4. Build indexes once (edges, routes, system prompt, allNodes map)
+//   5. Build or load checkpoint
+//   6. Run three phases: nodeOrder levels → cycleGroups → fileNodes
+//   7. Save summaries to storage after every level/group
+//   8. Check pause/cancel signals between levels
+export async function runSummarization(input) {
+    const { job, queue, graphId, commitHash, repoPath, routes, callbacks } = input;
+    // ── Step 1: Load commit data ───────────────────────────────────────────────
+    const result = storage.getGraph(graphId, commitHash);
+    if (!result) {
+        callbacks.onError(`Commit data not found: ${graphId}/${commitHash}`);
+        return;
+    }
+    // ── Step 2: Skip if already summarized ────────────────────────────────────
+    if (storage.isCommitSummarized(graphId, commitHash)) {
+        callbacks.onComplete();
+        console.log("Already Summarized!");
+        return;
+    }
+    // ── Step 3: Copy summaries from previous commit where codeHash matches ────
+    // Nodes whose code hasn't changed don't need re-summarization.
+    // We identify them by codeHash — if it matches, copy the summary directly.
+    // Skipped when forceSummarize=true so every node gets a fresh LLM call.
+    if (input.previousCommitHash && !job.forceSummarize) {
+        const prevResult = storage.getGraph(graphId, input.previousCommitHash);
+        if (prevResult) {
+            const prevById = new Map(prevResult.allNodes.map(n => [n.id, n]));
+            let duplicateNodes = 0;
+            for (const node of result.allNodes) {
+                const prev = prevById.get(node.id);
+                if (prev &&
+                    prev.technicalSummary &&
+                    node.codeHash &&
+                    node.codeHash === prev.codeHash) {
+                    node.technicalSummary = prev.technicalSummary;
+                    node.businessSummary = prev.businessSummary;
+                    node.security = prev.security;
+                    node.summaryModel = prev.summaryModel;
+                    node.summarizedAt = prev.summarizedAt;
+                    duplicateNodes++;
+                }
+            }
+            const toSummarize = result.allNodes.filter(n => !n.technicalSummary).length;
+            console.log(`${duplicateNodes} copied, ${toSummarize} to summarize`);
+            console.log(duplicateNodes, "Nodes' Summaries were copied from previous Hash", input.previousCommitHash);
+        }
+    }
+    // ── Step 4: Build job-scoped indexes — built once, reused every batch ─────
+    const config = await resolveConfig();
+    const client = createLLMClient(config.summarization);
+    const allNodesMap = new Map(result.allNodes.map(n => [n.id, n]));
+    const edgeIndex = buildEdgeIndex(result.allEdges);
+    const routeIndex = buildRouteIndex(routes);
+    const systemPrompt = buildSystemPrompt(result.fingerprint);
+    // Validate LLM connection before starting — fail fast
+    try {
+        await client.validateConnection();
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : "LLM connection failed";
+        callbacks.onError(msg);
+        return;
+    }
+    // ── Step 5: Build or load checkpoint ──────────────────────────────────────
+    let checkpoint = loadCheckpoint(graphId, commitHash);
+    const isResume = !!checkpoint;
+    if (!checkpoint) {
+        // Fresh run — build topo order and create checkpoint
+        const { nodeOrder, cycleGroups, fileNodes } = buildTopologicalOrder(result.allNodes, result.allEdges);
+        checkpoint = createCheckpoint(graphId, commitHash, nodeOrder, cycleGroups, fileNodes);
+    }
+    // On resume: nodes from already-completed levels may have summaries in memory
+    // (merged into the commit file by saveGraph on restart) but saveBatch will never
+    // be called for skipped levels — so those summaries would sit in memory and never
+    // be re-persisted after the fresh saveGraph overwrote the file.
+    // Fix: flush all already-summarized nodes to disk in one pass before the loop starts.
+    if (isResume) {
+        const alreadySummarized = result.allNodes.filter(n => n.technicalSummary);
+        if (alreadySummarized.length > 0) {
+            const updates = new Map(alreadySummarized.map(n => [n.id, {
+                    technicalSummary: n.technicalSummary,
+                    businessSummary: n.businessSummary ?? "",
+                    security: n.security ?? { severity: "none", summary: "" },
+                    summaryModel: n.summaryModel ?? "",
+                    summarizedAt: n.summarizedAt ?? new Date().toISOString(),
+                }]));
+            storage.saveNodeSummaries(graphId, commitHash, updates);
+            console.log(`♻️  Re-persisted ${alreadySummarized.length} summaries from pre-crash levels`);
+        }
+    }
+    // Notify caller of total work
+    callbacks.onStarted(checkpoint.totalNodes);
+    // ── Helper: summarize one node ────────────────────────────────────────────
+    async function summarizeNode(node) {
+        // Skip if already summarized (copied from previous commit)
+        if (node.technicalSummary) {
+            console.log("Summary already exists, skipping for node", node.id);
+            return;
+        }
+        console.log(` Starting summarization for node "${node.id}"`);
+        const output = await withRetry(() => exceedsThreshold(node)
+            ? mapreduceSummarize(node, client, systemPrompt)
+            : client.summarize({
+                messages: buildPrompt({ node, allNodes: allNodesMap, edgeIndex, routeIndex, systemPrompt }),
+                temperature: 0,
+            }), undefined, node.id);
+        // Write summary back onto node in memory
+        node.technicalSummary = output.technicalSummary;
+        node.businessSummary = output.businessSummary;
+        node.security = output.security;
+        node.summaryModel = client.model;
+        node.summarizedAt = new Date().toISOString();
+    }
+    // ── Helper: save a batch of node updates to disk ──────────────────────────
+    function saveBatch(nodes) {
+        const updates = new Map(nodes.map(n => [n.id, {
+                technicalSummary: n.technicalSummary,
+                businessSummary: n.businessSummary ?? "",
+                security: n.security ?? { severity: "none", summary: "" },
+                summaryModel: n.summaryModel ?? client.model,
+                summarizedAt: n.summarizedAt ?? new Date().toISOString(),
+            }]));
+        storage.saveNodeSummaries(graphId, commitHash, updates);
+    }
+    // ── Helper: check pause/cancel signals ────────────────────────────────────
+    function shouldPause() { return queue.getJob(job.jobId)?.pauseRequested ?? false; }
+    function shouldCancel() { return queue.getJob(job.jobId)?.cancelRequested ?? false; }
+    // ── Derive start indexes for all three phases ─────────────────────────────
+    // If resumePoint is past a phase entirely, start index = length (skips loop).
+    const resumePoint = getResumePoint(checkpoint);
+    const levelStart = resumePoint.phase === "nodes" ? resumePoint.index :
+        resumePoint.phase === "done" ? checkpoint.nodeOrder.length :
+            /* cycles or files — nodes already done */ checkpoint.nodeOrder.length;
+    const cycleStart = resumePoint.phase === "cycles" ? resumePoint.index :
+        resumePoint.phase === "files" || resumePoint.phase === "done" ? checkpoint.cycleGroups.length :
+            /* nodes phase — cycles not started yet */ 0;
+    const fileStart = resumePoint.phase === "files" ? resumePoint.index :
+        resumePoint.phase === "done" ? checkpoint.fileNodes.length :
+            /* nodes or cycles phase — files not started yet */ 0;
+    // ── Step 6: Phase 1 — nodeOrder levels ────────────────────────────────────
+    // Each level is independent — all nodes in a level run in parallel.
+    // Levels complete atomically — checkpoint saves after each full level.
+    for (let lvl = levelStart; lvl < checkpoint.nodeOrder.length; lvl++) {
+        const level = checkpoint.nodeOrder[lvl];
+        const nodes = level.map(id => allNodesMap.get(id)).filter(Boolean);
+        const newInLevel = nodes.filter(n => !n.technicalSummary).length;
+        console.log(`🔍 Level ${lvl}: ${nodes.length} nodes, ${newInLevel} new to summarize (skipped ${nodes.length - newInLevel})`);
+        // All nodes in this level summarized in parallel
+        await Promise.all(nodes.map(summarizeNode));
+        saveBatch(nodes);
+        markLevelCompleted(checkpoint, lvl);
+        saveCheckpoint(checkpoint);
+        callbacks.onProgress(checkpoint.completedNodes, checkpoint.totalNodes, `level ${lvl}`);
+        if (shouldCancel()) {
+            deleteCheckpoint(graphId, commitHash);
+            callbacks.onCancel(true);
+            return;
+        }
+        if (shouldPause()) {
+            checkpoint.status = "paused";
+            saveCheckpoint(checkpoint);
+            callbacks.onPause();
+            return;
+        }
+    }
+    // ── Step 7: Phase 2 — cycleGroups ─────────────────────────────────────────
+    for (let gi = cycleStart; gi < checkpoint.cycleGroups.length; gi++) {
+        const group = checkpoint.cycleGroups[gi];
+        const nodes = group.nodeIds.map(id => allNodesMap.get(id)).filter(Boolean);
+        if (group.size <= MAX_GROUP_SUMMARY_SIZE) {
+            // Small cycle — one grouped LLM call
+            console.log(` Starting grouped LLM summary for cycle group ${gi} (${group.nodeIds.length} nodes)`);
+            const messages = buildCycleGroupPrompt(group.nodeIds, { allNodes: allNodesMap, edgeIndex, routeIndex, systemPrompt });
+            const output = await client.summarize({ messages, temperature: 0 });
+            // For grouped calls the LLM returns one summary — apply to all nodes in group
+            for (const node of nodes) {
+                node.technicalSummary = output.technicalSummary;
+                node.businessSummary = output.businessSummary;
+                node.security = output.security;
+                node.summaryModel = client.model;
+                node.summarizedAt = new Date().toISOString();
+            }
+        }
+        else {
+            // Large cycle — summarize individually
+            await Promise.all(nodes.map(summarizeNode));
+        }
+        saveBatch(nodes);
+        markCycleGroupCompleted(checkpoint, gi);
+        saveCheckpoint(checkpoint);
+        callbacks.onProgress(checkpoint.completedNodes, checkpoint.totalNodes, `cycle group ${gi}`);
+        if (shouldCancel()) {
+            deleteCheckpoint(graphId, commitHash);
+            callbacks.onCancel(true);
+            return;
+        }
+        if (shouldPause()) {
+            checkpoint.status = "paused";
+            saveCheckpoint(checkpoint);
+            callbacks.onPause();
+            return;
+        }
+    }
+    // ── Step 8: Phase 3 — fileNodes ───────────────────────────────────────────
+    // FILE nodes summarized last — they use child summaries as context.
+    for (let fi = fileStart; fi < checkpoint.fileNodes.length; fi += FILE_BATCH_SIZE) {
+        const batchEnd = Math.min(fi + FILE_BATCH_SIZE - 1, checkpoint.fileNodes.length - 1);
+        const batchIds = checkpoint.fileNodes.slice(fi, batchEnd + 1);
+        const batchNodes = batchIds.map(id => allNodesMap.get(id)).filter(Boolean);
+        //Debug-Log
+        const newInBatch = batchNodes.filter(n => !n.technicalSummary).length;
+        console.log(`🔍 File batch ${fi}-${batchEnd}: ${batchNodes.length} nodes, ${newInBatch} new to summarize (skipped ${batchNodes.length - newInBatch})`);
+        await Promise.all(batchNodes.map(summarizeNode));
+        saveBatch(batchNodes);
+        markFileNodeBatchCompleted(checkpoint, batchEnd, batchNodes.length);
+        saveCheckpoint(checkpoint);
+        callbacks.onProgress(checkpoint.completedNodes, checkpoint.totalNodes, `file batch ${fi}-${batchEnd}`);
+        if (shouldCancel()) {
+            deleteCheckpoint(graphId, commitHash);
+            callbacks.onCancel(true);
+            return;
+        }
+        if (shouldPause()) {
+            checkpoint.status = "paused";
+            saveCheckpoint(checkpoint);
+            callbacks.onPause();
+            return;
+        }
+    }
+    // ── Done ──────────────────────────────────────────────────────────────────
+    storage.markCommitSummarized(graphId, commitHash);
+    deleteCheckpoint(graphId, commitHash);
+    callbacks.onComplete();
+}

package/dist/summarizer/mapreduce.d.ts

@@ -0,0 +1,4 @@
+import type { CodeNode } from "../types.js";
+import type { LLMClient, NodeSummaryOutput } from "./providers/types.js";
+export declare function exceedsThreshold(node: CodeNode): boolean;
+export declare function mapreduceSummarize(node: CodeNode, client: LLMClient, systemPrompt: string): Promise<NodeSummaryOutput>;

package/dist/summarizer/mapreduce.js

@@ -0,0 +1,87 @@
+import { MAPREDUCE_TOKEN_THRESHOLD } from "./types.js";
+// ─── Token Estimation ─────────────────────────────────────────────────────────
+//
+// 1 token ≈ 4 characters — standard rule of thumb, accurate enough for
+// threshold checks. Avoids adding a full tokenizer dependency.
+function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+export function exceedsThreshold(node) {
+    if (!node.rawCode)
+        return false;
+    return estimateTokens(node.rawCode) > MAPREDUCE_TOKEN_THRESHOLD;
+}
+// ─── Chunking ─────────────────────────────────────────────────────────────────
+//
+// Splits rawCode into chunks by line — never cuts mid-line.
+// Each chunk targets MAPREDUCE_TOKEN_THRESHOLD tokens.
+// Overlap of 10 lines between chunks preserves context at boundaries.
+const CHUNK_OVERLAP_LINES = 10;
+function chunkCode(rawCode) {
+    const lines = rawCode.split("\n");
+    const chunks = [];
+    const targetLines = Math.floor(MAPREDUCE_TOKEN_THRESHOLD * 4 / 50); // ~50 chars avg per line
+    let start = 0;
+    while (start < lines.length) {
+        const end = Math.min(start + targetLines, lines.length);
+        const chunk = lines.slice(start, end).join("\n");
+        chunks.push(chunk);
+        if (end === lines.length)
+            break;
+        start = end - CHUNK_OVERLAP_LINES; // overlap for context continuity
+    }
+    return chunks;
+}
+// ─── Map Phase ────────────────────────────────────────────────────────────────
+//
+// Summarizes each chunk individually.
+// Chunk summaries are purely technical — no business/security analysis yet.
+// That happens in the reduce phase where the full picture is available.
+function buildChunkMessages(chunk, chunkIndex, totalChunks, nodeName, systemPrompt) {
+    return [
+        { role: "system", content: systemPrompt },
+        {
+            role: "user", content: `You are summarizing chunk ${chunkIndex + 1} of ${totalChunks} from a large code node named "${nodeName}".\n` +
+                `Provide a concise technical summary of what this chunk does. No business or security analysis yet.\n\n` +
+                `\`\`\`\n${chunk}\n\`\`\``
+        },
+    ];
+}
+// ─── Reduce Phase ─────────────────────────────────────────────────────────────
+//
+// Takes all chunk summaries and produces the final NodeSummaryOutput.
+// Uses the same XML format as single-node summarization — consistent parsing.
+function buildReduceMessages(chunkSummaries, nodeName, systemPrompt) {
+    const summaryList = chunkSummaries
+        .map((s, i) => `Chunk ${i + 1}:\n${s}`)
+        .join("\n\n");
+    return [
+        { role: "system", content: systemPrompt },
+        {
+            role: "user", content: `The following are chunk summaries of a large code node named "${nodeName}".\n` +
+                `Based on these summaries, produce the final complete summary in the required XML format.\n\n` +
+                `${summaryList}`
+        },
+    ];
+}
+// ─── Public API ───────────────────────────────────────────────────────────────
+// Summarizes a node that exceeds the token threshold via map-reduce.
+// Called from the batch loop instead of buildPrompt when exceedsThreshold() is true.
+export async function mapreduceSummarize(node, client, systemPrompt) {
+    const rawCode = node.rawCode ?? "";
+    const chunks = chunkCode(rawCode);
+    // ── Map phase — summarize each chunk in parallel ──────────────
+    const chunkResults = await Promise.all(chunks.map((chunk, i) => {
+        const messages = buildChunkMessages(chunk, i, chunks.length, node.name, systemPrompt);
+        return client.summarize({ messages, temperature: 0 });
+    }));
+    const chunkSummaries = chunkResults.map(r => r.technicalSummary);
+    const totalTokensUsed = chunkResults.reduce((sum, r) => sum + r.tokensUsed, 0);
+    // ── Reduce phase — combine chunk summaries into final output ──
+    const reduceMessages = buildReduceMessages(chunkSummaries, node.name, systemPrompt);
+    const finalResult = await client.summarize({ messages: reduceMessages, temperature: 0 });
+    return {
+        ...finalResult,
+        tokensUsed: totalTokensUsed + finalResult.tokensUsed,
+    };
+}

package/dist/summarizer/prompts.d.ts

@@ -0,0 +1,22 @@
+import type { CodeNode, CodeEdge, RouteNode, BackendRouteNode, ProjectFingerprint } from "../types.js";
+import type { LLMMessage } from "./providers/types.js";
+export interface EdgeIndex {
+    outgoing: Map<string, Map<string, string[]>>;
+    incoming: Map<string, Map<string, string[]>>;
+}
+export interface RouteIndex {
+    byFilePath: Map<string, RouteNode | BackendRouteNode>;
+}
+export declare function buildEdgeIndex(edges: CodeEdge[]): EdgeIndex;
+export declare function buildRouteIndex(routes: RouteNode[] | BackendRouteNode[]): RouteIndex;
+export interface PromptContext {
+    node: CodeNode;
+    allNodes: Map<string, CodeNode>;
+    edgeIndex: EdgeIndex;
+    routeIndex: RouteIndex;
+    systemPrompt: string;
+}
+export declare function buildSystemPrompt(fingerprint: ProjectFingerprint): string;
+export declare const EDGE_LABELS: Record<string, string>;
+export declare function buildPrompt(ctx: PromptContext): LLMMessage[];
+export declare function buildCycleGroupPrompt(nodeIds: string[], ctx: Omit<PromptContext, "node">): LLMMessage[];