brain-cache 0.4.2 → 3.0.0

package/dist/chunk-KMRPAVMM.js

@@ -0,0 +1,967 @@
+#!/usr/bin/env node
+import {
+  RETRIEVAL_STRATEGIES,
+  classifyRetrievalMode,
+  deduplicateChunks,
+  searchChunks
+} from "./chunk-DFFMV3RR.js";
+import {
+  assembleContext,
+  countChunkTokens,
+  formatChunk
+} from "./chunk-4IOR54GU.js";
+import {
+  openDatabase,
+  queryEdgesFrom,
+  readIndexState
+} from "./chunk-3HQRTLBH.js";
+import {
+  embedBatchWithRetry
+} from "./chunk-RKPICQU7.js";
+import {
+  isOllamaRunning
+} from "./chunk-HRJ3OT6Q.js";
+import {
+  readProfile
+} from "./chunk-DPH5X5HL.js";
+import {
+  COMPRESSION_HARD_LIMIT,
+  COMPRESSION_TOKEN_THRESHOLD,
+  CONFIG_PATH,
+  DEFAULT_TOKEN_BUDGET,
+  HIGH_RELEVANCE_SIMILARITY_THRESHOLD,
+  TOOL_CALL_OVERHEAD_TOKENS,
+  childLogger
+} from "./chunk-TXLCXXKY.js";
+
+// src/workflows/buildContext.ts
+import { readFile as readFile4 } from "fs/promises";
+import { resolve as resolve3 } from "path";
+
+// src/services/cohesion.ts
+import { dirname, relative, basename } from "path";
+var log = childLogger("cohesion");
+function groupChunksByFile(chunks) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const chunk of chunks) {
+    const group = groups.get(chunk.filePath);
+    if (group === void 0) {
+      groups.set(chunk.filePath, [chunk]);
+    } else {
+      group.push(chunk);
+    }
+  }
+  for (const [, group] of groups) {
+    group.sort((a, b) => a.startLine - b.startLine);
+  }
+  return groups;
+}
+async function enrichWithParentClass(chunks, chunksTable, opts) {
+  const existingIds = new Set(chunks.map((c) => c.id));
+  const result = [...chunks];
+  let { currentTokens } = opts;
+  const parentsToInsert = [];
+  for (const chunk of chunks) {
+    if (chunk.chunkType !== "method" || chunk.scope === null) {
+      continue;
+    }
+    const escapedScope = chunk.scope.replace(/'/g, "''");
+    const escapedFilePath = chunk.filePath.replace(/'/g, "''");
+    log.debug({ scope: chunk.scope, filePath: chunk.filePath }, "Looking for parent class");
+    const rows = await chunksTable.query().where(`name = '${escapedScope}' AND file_path = '${escapedFilePath}' AND chunk_type = 'class'`).toArray();
+    if (rows.length === 0) {
+      continue;
+    }
+    const row = rows[0];
+    if (existingIds.has(row.id)) {
+      continue;
+    }
+    const parentChunk = {
+      id: row.id,
+      filePath: row.file_path,
+      chunkType: row.chunk_type,
+      scope: row.scope,
+      name: row.name,
+      content: row.content,
+      startLine: row.start_line,
+      endLine: row.end_line,
+      similarity: 1
+    };
+    const tokenCost = countChunkTokens(formatChunk(parentChunk));
+    if (currentTokens + tokenCost > opts.maxTokens) {
+      log.debug({ parentId: row.id, tokenCost, currentTokens, maxTokens: opts.maxTokens }, "Skipping parent class \u2014 token budget exceeded");
+      continue;
+    }
+    existingIds.add(row.id);
+    currentTokens += tokenCost;
+    parentsToInsert.push({ parent: parentChunk, beforeId: chunk.id });
+  }
+  for (const { parent, beforeId } of parentsToInsert) {
+    const idx = result.findIndex((c) => c.id === beforeId);
+    if (idx !== -1) {
+      result.splice(idx, 0, parent);
+    }
+  }
+  return result;
+}
+function formatGroupedContext(groups) {
+  const sections = [];
+  for (const [filePath, chunks] of groups) {
+    const header = `// \u2500\u2500 ${filePath} \u2500\u2500`;
+    const body = chunks.map(formatChunk).join("\n\n");
+    sections.push(`${header}
+${body}`);
+  }
+  return sections.join("\n\n---\n\n");
+}
+function extractBehavioralSummary(content) {
+  const lines = content.split("\n");
+  const jsDocLines = [];
+  let inJsDoc = false;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("// [compressed]") || trimmed.startsWith("// Signature:") || trimmed.startsWith("// [body stripped]")) continue;
+    if (trimmed.startsWith("/**")) {
+      inJsDoc = true;
+      jsDocLines.push(line);
+      if (trimmed.endsWith("*/")) break;
+      continue;
+    }
+    if (inJsDoc) {
+      jsDocLines.push(line);
+      if (trimmed.endsWith("*/")) break;
+      continue;
+    }
+  }
+  if (jsDocLines.length === 0) return null;
+  const descLines = jsDocLines.map((l) => l.replace(/^\s*\/?\*+\s?/, "").replace(/\s*\*\/.*$/, "").trim()).filter((l) => l.length > 0 && !l.startsWith("@") && l !== "/");
+  return descLines[0] ?? null;
+}
+function groupChunksByModule(chunks, rootDir) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const chunk of chunks) {
+    const rel = relative(rootDir, chunk.filePath);
+    const moduleKey = dirname(rel) || ".";
+    const group = groups.get(moduleKey);
+    if (group === void 0) groups.set(moduleKey, [chunk]);
+    else group.push(chunk);
+  }
+  for (const [, group] of groups) {
+    group.sort((a, b) => a.startLine - b.startLine);
+  }
+  return groups;
+}
+function extractWiringAnnotations(chunks) {
+  const importPattern = /from\s+['"](\.[^'"]+)['"]/g;
+  const internalDeps = /* @__PURE__ */ new Set();
+  for (const chunk of chunks) {
+    for (const match of chunk.content.matchAll(importPattern)) {
+      const importPath = match[1];
+      const stem = importPath.replace(/\.js$/, "").split("/").pop();
+      if (stem && stem.length > 1) {
+        internalDeps.add(stem);
+      }
+    }
+  }
+  return [...internalDeps].sort();
+}
+function formatModuleNarratives(groups) {
+  const sections = [];
+  for (const [moduleKey, chunks] of groups) {
+    const lines = [`### module: ${moduleKey}`];
+    const byFile = /* @__PURE__ */ new Map();
+    for (const chunk of chunks) {
+      const file = chunk.filePath;
+      const group = byFile.get(file);
+      if (group === void 0) byFile.set(file, [chunk]);
+      else group.push(chunk);
+    }
+    for (const [filePath, fileChunks] of byFile) {
+      const fileName = basename(filePath);
+      const summary = extractBehavioralSummary(fileChunks[0].content);
+      if (summary) {
+        lines.push(`
+**${fileName}** -- ${summary}`);
+      } else {
+        lines.push(`
+**${fileName}**`);
+      }
+      const wiring = extractWiringAnnotations(fileChunks);
+      if (wiring.length > 0) {
+        lines.push(`  imports: ${wiring.join(", ")}`);
+      }
+    }
+    sections.push(lines.join("\n"));
+  }
+  return sections.join("\n\n");
+}
+
+// src/services/compression.ts
+function compressChunk(chunk) {
+  const tokens = countChunkTokens(chunk.content);
+  if (tokens <= COMPRESSION_TOKEN_THRESHOLD) return chunk;
+  const isHighRelevance = chunk.similarity >= HIGH_RELEVANCE_SIMILARITY_THRESHOLD;
+  if (tokens <= COMPRESSION_HARD_LIMIT && isHighRelevance) {
+    return chunk;
+  }
+  const lines = chunk.content.split("\n");
+  const jsDocLines = [];
+  let signatureLine = "";
+  let inJsDoc = false;
+  let jsDocDone = false;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!jsDocDone) {
+      if (trimmed.startsWith("/**")) {
+        inJsDoc = true;
+        jsDocLines.push(line);
+        if (trimmed.endsWith("*/")) {
+          inJsDoc = false;
+          jsDocDone = true;
+        }
+        continue;
+      }
+      if (inJsDoc) {
+        jsDocLines.push(line);
+        if (trimmed.endsWith("*/")) {
+          inJsDoc = false;
+          jsDocDone = true;
+        }
+        continue;
+      }
+    }
+    if (trimmed.length > 0 && signatureLine === "") {
+      signatureLine = line;
+      break;
+    }
+  }
+  if (signatureLine === "" && jsDocLines.length === 0) {
+    signatureLine = lines.find((l) => l.trim().length > 0) ?? "";
+  }
+  const manifestParts = [
+    `// [compressed] ${chunk.name ?? "unknown"} (lines ${chunk.startLine}-${chunk.endLine})`
+  ];
+  if (jsDocLines.length > 0) {
+    manifestParts.push(...jsDocLines);
+  }
+  manifestParts.push(`// Signature: ${signatureLine}`);
+  manifestParts.push("// [body stripped]");
+  return { ...chunk, content: manifestParts.join("\n") };
+}
+
+// src/services/configLoader.ts
+import { readFile } from "fs/promises";
+var log2 = childLogger("configLoader");
+async function loadUserConfig() {
+  try {
+    const raw = await readFile(CONFIG_PATH, "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    log2.debug({ configPath: CONFIG_PATH }, "Config file not found or invalid \u2014 using defaults");
+    return {};
+  }
+}
+function resolveStrategy(mode, userConfig, toolOverride) {
+  const base = RETRIEVAL_STRATEGIES[mode];
+  const userOverride = userConfig.retrieval?.[mode] ?? {};
+  return { ...base, ...userOverride, ...toolOverride };
+}
+
+// src/workflows/traceFlow.ts
+import { resolve } from "path";
+import { readFile as readFile2 } from "fs/promises";
+
+// src/services/flowTracer.ts
+var log3 = childLogger("flowTracer");
+async function resolveSymbolToChunkId(chunksTable, toSymbol, fromFile) {
+  const escaped = toSymbol.replace(/'/g, "''");
+  const rows = await chunksTable.query().where(`name = '${escaped}'`).toArray();
+  if (rows.length === 0) {
+    return null;
+  }
+  const sameFile = rows.find((r) => r.file_path === fromFile);
+  return (sameFile ?? rows[0]).id;
+}
+async function traceFlow(edgesTable, chunksTable, seedChunkId, opts) {
+  const maxHops = opts?.maxHops ?? 3;
+  const visited = /* @__PURE__ */ new Set();
+  const queue = [{ chunkId: seedChunkId, depth: 0 }];
+  const hops = [];
+  log3.debug({ seedChunkId, maxHops }, "Starting BFS flow trace");
+  while (queue.length > 0) {
+    const { chunkId, depth } = queue.shift();
+    if (visited.has(chunkId)) {
+      continue;
+    }
+    visited.add(chunkId);
+    const escapedId = chunkId.replace(/'/g, "''");
+    const chunkRows = await chunksTable.query().where(`id = '${escapedId}'`).toArray();
+    if (chunkRows.length === 0) {
+      log3.debug({ chunkId }, "Chunk not found \u2014 skipping hop");
+      continue;
+    }
+    const row = chunkRows[0];
+    const edges = await queryEdgesFrom(edgesTable, chunkId);
+    const callEdges = edges.filter((e) => e.edge_type === "call");
+    hops.push({
+      chunkId,
+      filePath: row.file_path,
+      name: row.name,
+      startLine: row.start_line,
+      endLine: row.end_line,
+      content: row.content,
+      hopDepth: depth,
+      callsFound: [...new Set(callEdges.map((e) => e.to_symbol))]
+    });
+    if (depth >= maxHops) {
+      continue;
+    }
+    for (const edge of callEdges) {
+      const nextChunkId = await resolveSymbolToChunkId(chunksTable, edge.to_symbol, edge.from_file);
+      if (nextChunkId !== null && !visited.has(nextChunkId)) {
+        queue.push({ chunkId: nextChunkId, depth: depth + 1 });
+      }
+    }
+  }
+  log3.debug({ seedChunkId, hopsFound: hops.length, maxDepthReached: hops.length > 0 ? Math.max(...hops.map((h) => h.hopDepth)) : 0 }, "BFS flow trace complete");
+  return hops;
+}
+
+// src/workflows/traceFlow.ts
+var BODY_STRIPPED_MARKER = "// [body stripped]";
+var TEST_FILE_PATTERNS = [".test.", ".spec.", "/__tests__/", "/tests/"];
+function isTestFile(filePath) {
+  return TEST_FILE_PATTERNS.some((p) => filePath.includes(p));
+}
+var STDLIB_SYMBOLS = /* @__PURE__ */ new Set([
+  // Array
+  "map",
+  "filter",
+  "reduce",
+  "forEach",
+  "find",
+  "findIndex",
+  "some",
+  "every",
+  "includes",
+  "push",
+  "pop",
+  "shift",
+  "unshift",
+  "splice",
+  "slice",
+  "concat",
+  "join",
+  "sort",
+  "reverse",
+  "flat",
+  "flatMap",
+  "fill",
+  "indexOf",
+  "lastIndexOf",
+  // Set/Map
+  "keys",
+  "values",
+  "entries",
+  "has",
+  "get",
+  "set",
+  "delete",
+  "add",
+  "clear",
+  // Promise
+  "resolve",
+  "reject",
+  "then",
+  "catch",
+  "finally",
+  "all",
+  "race",
+  "allSettled",
+  // Object
+  "toString",
+  "valueOf",
+  "hasOwnProperty",
+  "assign",
+  "freeze",
+  "create",
+  // String
+  "split",
+  "replace",
+  "replaceAll",
+  "match",
+  "matchAll",
+  "trim",
+  "trimStart",
+  "trimEnd",
+  "startsWith",
+  "endsWith",
+  "padStart",
+  "padEnd",
+  "repeat",
+  "charAt",
+  "charCodeAt",
+  "substring",
+  "toLowerCase",
+  "toUpperCase",
+  // Property-like
+  "length"
+]);
+var LOW_CONFIDENCE_THRESHOLD = 0.5;
+function isCLIQuery(query) {
+  const lower = query.toLowerCase();
+  return lower.includes(" cli ") || lower.startsWith("cli ") || lower.includes("command");
+}
+function isCLIFile(filePath) {
+  return filePath.includes("/cli/");
+}
+async function computeHopSavings(hops) {
+  if (hops.length === 0) {
+    return { tokensSent: 0, estimatedWithoutBraincache: 0, reductionPct: 0, filesInContext: 0 };
+  }
+  const tokensSent = hops.reduce((sum, h) => sum + countChunkTokens(h.content), 0);
+  const uniqueFiles = [...new Set(hops.map((h) => h.filePath))];
+  const filesInContext = uniqueFiles.length;
+  const filesWithUncompressedContent = new Set(
+    hops.filter((h) => !h.content.includes(BODY_STRIPPED_MARKER)).map((h) => h.filePath)
+  );
+  let fileContentTokens = 0;
+  for (const filePath of uniqueFiles) {
+    if (!filesWithUncompressedContent.has(filePath)) continue;
+    try {
+      const fileContent = await readFile2(filePath, "utf-8");
+      fileContentTokens += countChunkTokens(fileContent);
+    } catch {
+    }
+  }
+  const toolCalls = 1 + filesInContext;
+  const toolCallOverhead = toolCalls * TOOL_CALL_OVERHEAD_TOKENS;
+  const estimatedWithoutBraincache = fileContentTokens + toolCallOverhead;
+  const reductionPct = estimatedWithoutBraincache > 0 ? Math.max(0, Math.round((1 - tokensSent / estimatedWithoutBraincache) * 100)) : 0;
+  return { tokensSent, estimatedWithoutBraincache, reductionPct, filesInContext };
+}
+function extractSymbolCandidate(query) {
+  const tokens = query.match(/\b[a-zA-Z_][a-zA-Z0-9_]{2,}\b/g);
+  if (!tokens) return null;
+  const stopWords = /* @__PURE__ */ new Set([
+    "how",
+    "does",
+    "work",
+    "the",
+    "what",
+    "where",
+    "trace",
+    "flow",
+    "call",
+    "path",
+    "find",
+    "show",
+    "into",
+    "from",
+    "this",
+    "that",
+    "with",
+    "when",
+    "which",
+    "about",
+    "explain",
+    "describe"
+  ]);
+  const camel = tokens.filter((t) => /[a-z][A-Z]/.test(t));
+  if (camel.length > 0) return camel[camel.length - 1];
+  const nonStop = tokens.filter((t) => !stopWords.has(t.toLowerCase()));
+  return nonStop.length > 0 ? nonStop[nonStop.length - 1] : null;
+}
+async function runTraceFlow(entrypoint, opts) {
+  const profile = await readProfile();
+  if (profile === null) {
+    throw new Error("No profile found. Run 'brain-cache init' first.");
+  }
+  const running = await isOllamaRunning();
+  if (!running) {
+    throw new Error("Ollama is not running.");
+  }
+  const rootDir = resolve(opts?.path ?? ".");
+  const indexState = await readIndexState(rootDir);
+  if (indexState === null) {
+    throw new Error(`No index found at ${rootDir}. Run 'brain-cache index' first.`);
+  }
+  const db = await openDatabase(rootDir);
+  const tableNames = await db.tableNames();
+  if (!tableNames.includes("chunks")) {
+    throw new Error("No chunks table found. Run 'brain-cache index' first.");
+  }
+  const table = await db.openTable("chunks");
+  if (!tableNames.includes("edges")) {
+    throw new Error("No edges table found. Re-run 'brain-cache index' to build call edges.");
+  }
+  const edgesTable = await db.openTable("edges");
+  const userConfig = await loadUserConfig();
+  const toolOverride = {};
+  if (opts?.limit !== void 0) toolOverride.limit = opts.limit;
+  if (opts?.distanceThreshold !== void 0) toolOverride.distanceThreshold = opts.distanceThreshold;
+  const strategy = resolveStrategy("trace", userConfig, Object.keys(toolOverride).length > 0 ? toolOverride : void 0);
+  const candidate = extractSymbolCandidate(entrypoint);
+  let seedChunkId = null;
+  if (candidate !== null) {
+    seedChunkId = await resolveSymbolToChunkId(table, candidate, "");
+  }
+  if (seedChunkId !== null) {
+    const maxHops2 = opts?.maxHops ?? 3;
+    const flowHops2 = await traceFlow(edgesTable, table, seedChunkId, { maxHops: maxHops2 });
+    const productionHops2 = flowHops2.filter((hop) => !isTestFile(hop.filePath));
+    const hops2 = productionHops2.map((hop) => {
+      const asChunk = {
+        id: hop.chunkId,
+        filePath: hop.filePath,
+        chunkType: "function",
+        scope: null,
+        name: hop.name,
+        content: hop.content,
+        startLine: hop.startLine,
+        endLine: hop.endLine,
+        similarity: 1
+      };
+      const compressed = compressChunk(asChunk);
+      return {
+        filePath: hop.filePath,
+        name: hop.name,
+        startLine: hop.startLine,
+        content: compressed.content,
+        callsFound: hop.callsFound.filter((s) => !STDLIB_SYMBOLS.has(s)),
+        // TRACE-02
+        hopDepth: hop.hopDepth
+      };
+    });
+    const exactSavings = await computeHopSavings(hops2);
+    return {
+      hops: hops2,
+      metadata: {
+        seedChunkId,
+        totalHops: hops2.length,
+        localTasksPerformed: ["exact_name_lookup", "bfs_trace", "compress"],
+        ...exactSavings,
+        confidenceWarning: null
+      }
+    };
+  }
+  const { embeddings } = await embedBatchWithRetry(indexState.embeddingModel, [entrypoint]);
+  const seedResults = await searchChunks(table, embeddings[0], strategy, entrypoint);
+  const seeds = deduplicateChunks(seedResults);
+  if (seeds.length === 0) {
+    return {
+      hops: [],
+      metadata: {
+        seedChunkId: null,
+        totalHops: 0,
+        localTasksPerformed: ["embed_query", "seed_search"],
+        tokensSent: 0,
+        estimatedWithoutBraincache: 0,
+        reductionPct: 0,
+        filesInContext: 0
+      }
+    };
+  }
+  let selectedSeed = seeds[0];
+  if (isCLIQuery(entrypoint)) {
+    const cliSeed = seeds.find((s) => isCLIFile(s.filePath));
+    if (cliSeed) selectedSeed = cliSeed;
+  }
+  let confidenceWarning = null;
+  if (selectedSeed.similarity < LOW_CONFIDENCE_THRESHOLD) {
+    const seedName = selectedSeed.name ?? "unknown";
+    const seedFile = selectedSeed.filePath.split("/").pop() ?? selectedSeed.filePath;
+    confidenceWarning = `No confident match for "${entrypoint}" \u2014 tracing nearest match: ${seedName} (${seedFile}:${selectedSeed.startLine}, similarity: ${selectedSeed.similarity.toFixed(2)})`;
+  }
+  const maxHops = opts?.maxHops ?? 3;
+  const flowHops = await traceFlow(edgesTable, table, selectedSeed.id, { maxHops });
+  const productionHops = flowHops.filter((hop) => !isTestFile(hop.filePath));
+  const hops = productionHops.map((hop) => {
+    const asChunk = {
+      id: hop.chunkId,
+      filePath: hop.filePath,
+      chunkType: "function",
+      scope: null,
+      name: hop.name,
+      content: hop.content,
+      startLine: hop.startLine,
+      endLine: hop.endLine,
+      similarity: 1
+    };
+    const compressed = compressChunk(asChunk);
+    return {
+      filePath: hop.filePath,
+      name: hop.name,
+      startLine: hop.startLine,
+      content: compressed.content,
+      callsFound: hop.callsFound.filter((s) => !STDLIB_SYMBOLS.has(s)),
+      // TRACE-02
+      hopDepth: hop.hopDepth
+    };
+  });
+  const savings = await computeHopSavings(hops);
+  return {
+    hops,
+    metadata: {
+      seedChunkId: selectedSeed.id,
+      totalHops: hops.length,
+      localTasksPerformed: ["embed_query", "seed_search", "bfs_trace", "compress"],
+      ...savings,
+      confidenceWarning
+    }
+  };
+}
+
+// src/workflows/explainCodebase.ts
+import { readFile as readFile3 } from "fs/promises";
+import { resolve as resolve2, relative as relative2, dirname as dirname2 } from "path";
+function isExportedChunk(chunk) {
+  if (chunk.chunkType === "file") return true;
+  const lines = chunk.content.split("\n");
+  let inJsDoc = false;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("/**")) {
+      inJsDoc = true;
+      if (trimmed.endsWith("*/")) {
+        inJsDoc = false;
+      }
+      continue;
+    }
+    if (inJsDoc) {
+      if (trimmed.endsWith("*/")) inJsDoc = false;
+      continue;
+    }
+    if (trimmed.startsWith("// [compressed]") || trimmed.startsWith("// Signature:") || trimmed.startsWith("// [body stripped]")) continue;
+    if (trimmed.length === 0) continue;
+    return trimmed.startsWith("export ");
+  }
+  return false;
+}
+var FALLBACK_QUERY = "module structure and component responsibilities";
+var ARCHITECTURE_QUERIES = [
+  FALLBACK_QUERY,
+  "entry points, CLI commands, and main application flow",
+  "core services, business logic, and data processing",
+  "data models, types, schemas, and configuration"
+];
+function buildDirectoryTree(filePaths, rootDir) {
+  const relativePaths = [
+    ...new Set(filePaths.map((fp) => relative2(rootDir, fp)))
+  ].sort();
+  const byDir = /* @__PURE__ */ new Map();
+  for (const rel of relativePaths) {
+    const dir = dirname2(rel);
+    if (!byDir.has(dir)) byDir.set(dir, []);
+    byDir.get(dir).push(rel);
+  }
+  const lines = [];
+  const dirs = [...byDir.keys()].sort();
+  for (let di = 0; di < dirs.length; di++) {
+    const dir = dirs[di];
+    const files = byDir.get(dir);
+    const isLastDir = di === dirs.length - 1;
+    if (dir !== ".") {
+      lines.push(`${isLastDir ? "\u2514\u2500\u2500" : "\u251C\u2500\u2500"} ${dir}/`);
+    }
+    for (let fi = 0; fi < files.length; fi++) {
+      const isLastFile = fi === files.length - 1;
+      const fileName = files[fi].includes("/") ? files[fi].split("/").pop() : files[fi];
+      const indent = dir !== "." ? "    " : "";
+      const isLast = isLastFile && (isLastDir || dir === ".");
+      lines.push(`${indent}${isLast ? "\u2514\u2500\u2500" : "\u251C\u2500\u2500"} ${fileName}`);
+    }
+  }
+  return lines.join("\n");
+}
+async function runExplainCodebase(opts) {
+  const profile = await readProfile();
+  if (profile === null) {
+    throw new Error("No profile found. Run 'brain-cache init' first.");
+  }
+  const running = await isOllamaRunning();
+  if (!running) {
+    throw new Error("Ollama is not running.");
+  }
+  const rootDir = resolve2(opts?.path ?? ".");
+  const indexState = await readIndexState(rootDir);
+  if (indexState === null) {
+    throw new Error(
+      `No index found at ${rootDir}. Run 'brain-cache index' first.`
+    );
+  }
+  const db = await openDatabase(rootDir);
+  const tableNames = await db.tableNames();
+  if (!tableNames.includes("chunks")) {
+    throw new Error("No chunks table found. Run 'brain-cache index' first.");
+  }
+  const table = await db.openTable("chunks");
+  const userConfig = await loadUserConfig();
+  const toolOverride = {};
+  if (opts?.limit !== void 0) toolOverride.limit = opts.limit;
+  if (opts?.distanceThreshold !== void 0)
+    toolOverride.distanceThreshold = opts.distanceThreshold;
+  const strategy = resolveStrategy(
+    "explore",
+    userConfig,
+    Object.keys(toolOverride).length > 0 ? toolOverride : void 0
+  );
+  const maxTokens = opts?.maxTokens ?? DEFAULT_TOKEN_BUDGET * 2;
+  const customQuestion = opts?.question;
+  const queries = customQuestion ? [customQuestion] : ARCHITECTURE_QUERIES;
+  process.stderr.write(
+    `brain-cache: explaining codebase (budget=${maxTokens} tokens, queries=${queries.length})
+`
+  );
+  const { embeddings } = await embedBatchWithRetry(indexState.embeddingModel, queries);
+  const allResults = await Promise.all(
+    embeddings.map((vec) => searchChunks(table, vec, strategy))
+  );
+  const merged = allResults.flat();
+  const deduped = deduplicateChunks(merged);
+  let allFilePaths = [];
+  try {
+    const allRows = await table.query().toArray();
+    allFilePaths = [...new Set(allRows.map((r) => r.file_path))].sort();
+  } catch {
+    allFilePaths = [];
+  }
+  const sorted = [...deduped].sort((a, b) => {
+    const aIsTest = /\/(tests?|__tests__|spec)\//i.test(a.filePath) || /\.(test|spec)\./i.test(a.filePath);
+    const bIsTest = /\/(tests?|__tests__|spec)\//i.test(b.filePath) || /\.(test|spec)\./i.test(b.filePath);
+    if (aIsTest === bIsTest) return 0;
+    return aIsTest ? 1 : -1;
+  });
+  const exportedOnly = sorted.filter(isExportedChunk);
+  const assembled = assembleContext(exportedOnly, { maxTokens });
+  const enriched = await enrichWithParentClass(assembled.chunks, table, {
+    maxTokens,
+    currentTokens: assembled.tokenCount
+  });
+  const compressed = enriched.map((c) => {
+    const tokens = countChunkTokens(c.content);
+    return tokens > 500 ? compressChunk(c) : c;
+  });
+  const moduleGroups = groupChunksByModule(compressed, rootDir);
+  const codeContent = formatModuleNarratives(moduleGroups);
+  const treeFilePaths = allFilePaths.length > 0 ? allFilePaths : [...new Set(compressed.map((c) => c.filePath))];
+  const nonTestPaths = treeFilePaths.filter(
+    (fp) => !(/\/(tests?|__tests__|spec)\//i.test(fp) || /\.(test|spec)\./i.test(fp))
+  );
+  const directoryTree = buildDirectoryTree(nonTestPaths, rootDir);
+  const content = [
+    "## Directory Structure\n\n```\n" + directoryTree + "\n```",
+    codeContent
+  ].join("\n\n---\n\n");
+  const uniqueFiles = [...new Set(compressed.map((c) => c.filePath))];
+  let fileContentTokens = 0;
+  for (const filePath of uniqueFiles) {
+    try {
+      const fileContent = await readFile3(filePath, "utf-8");
+      fileContentTokens += countChunkTokens(fileContent);
+    } catch {
+    }
+  }
+  const toolCalls = 1 + uniqueFiles.length;
+  const estimatedWithoutBraincache = fileContentTokens + toolCalls * TOOL_CALL_OVERHEAD_TOKENS;
+  const tokensSent = assembled.tokenCount;
+  const reductionPct = estimatedWithoutBraincache > 0 ? Math.max(
+    0,
+    Math.round((1 - tokensSent / estimatedWithoutBraincache) * 100)
+  ) : 0;
+  return {
+    content,
+    chunks: compressed,
+    metadata: {
+      tokensSent,
+      estimatedWithoutBraincache,
+      reductionPct,
+      filesInContext: uniqueFiles.length,
+      localTasksPerformed: [
+        "embed_query",
+        "vector_search",
+        "dedup",
+        "parent_enrich",
+        "compress",
+        "cohesion_group",
+        "token_budget",
+        "directory_tree"
+      ],
+      cloudCallsMade: 0
+    }
+  };
+}
+
+// src/workflows/buildContext.ts
+function splitCamelCase(name) {
+  return name.replace(/([a-z])([A-Z])/g, "$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2").toLowerCase().split(/\s+/).filter((t) => t.length >= 2);
+}
+function extractQueryTokens(query) {
+  return query.toLowerCase().split(/[\s.,;:!?'"()\[\]{}/\\]+/).filter((t) => t.length >= 3);
+}
+function isPrimaryMatch(chunk, queryTokens) {
+  if (queryTokens.length === 0) return false;
+  const fileName = chunk.filePath.split("/").pop()?.toLowerCase() ?? "";
+  const fileNameStem = fileName.replace(/\.[^.]+$/, "");
+  const originalName = chunk.name ?? "";
+  const chunkName = originalName.toLowerCase();
+  if (chunkName.length > 0 && queryTokens.some((t) => t === chunkName)) return true;
+  const subTokens = originalName.length > 0 ? splitCamelCase(originalName) : [];
+  if (subTokens.length > 1 && subTokens.every((sub) => queryTokens.some((t) => t.includes(sub) || sub.includes(t)))) return true;
+  if (fileNameStem.length > 0 && queryTokens.some((t) => t === fileNameStem)) return true;
+  return false;
+}
+var TEST_FILE_PATTERNS2 = [".test.", ".spec.", "/__tests__/", "/tests/"];
+function isTestFile2(filePath) {
+  return TEST_FILE_PATTERNS2.some((p) => filePath.includes(p));
+}
+var CONFIG_FILE_PATTERNS = [
+  /vitest\.config\./,
+  /tsup\.config\./,
+  /tsconfig.*\.json$/,
+  /jest\.config\./,
+  /eslint\.config\./,
+  /\.eslintrc/
+];
+function isConfigFile(filePath) {
+  const fileName = filePath.split("/").pop() ?? "";
+  return CONFIG_FILE_PATTERNS.some((p) => p.test(fileName));
+}
+async function runBuildContext(query, opts) {
+  const profile = await readProfile();
+  if (profile === null) {
+    throw new Error("No profile found. Run 'brain-cache init' first.");
+  }
+  const running = await isOllamaRunning();
+  if (!running) {
+    throw new Error("Ollama is not running. Start it with 'ollama serve' or run 'brain-cache init'.");
+  }
+  const rootDir = resolve3(opts?.path ?? ".");
+  const indexState = await readIndexState(rootDir);
+  if (indexState === null) {
+    throw new Error(`No index found at ${rootDir}. Run 'brain-cache index' first.`);
+  }
+  const db = await openDatabase(rootDir);
+  const tableNames = await db.tableNames();
+  if (!tableNames.includes("chunks")) {
+    throw new Error("No chunks table found. Run 'brain-cache index' first.");
+  }
+  const table = await db.openTable("chunks");
+  const hasEdges = tableNames.includes("edges");
+  const mode = classifyRetrievalMode(query);
+  const maxTokens = opts?.maxTokens ?? DEFAULT_TOKEN_BUDGET;
+  process.stderr.write(
+    `brain-cache: building context (intent=${mode}, budget=${maxTokens} tokens)
+`
+  );
+  const userConfig = await loadUserConfig();
+  const strategy = resolveStrategy(
+    mode,
+    userConfig,
+    opts?.limit !== void 0 ? { limit: opts.limit } : void 0
+  );
+  let finalChunks;
+  let finalContent;
+  let finalTokenCount;
+  let localTasksPerformed;
+  if (mode === "trace" && hasEdges) {
+    const traceResult = await runTraceFlow(query, {
+      maxHops: 3,
+      path: opts?.path,
+      limit: strategy.limit,
+      distanceThreshold: strategy.distanceThreshold
+    });
+    const traceChunks = traceResult.hops.map((hop, i) => ({
+      id: `trace-hop-${i}`,
+      filePath: hop.filePath,
+      chunkType: "function",
+      scope: null,
+      name: hop.name,
+      content: hop.content,
+      startLine: hop.startLine,
+      endLine: 0,
+      similarity: 1 - hop.hopDepth * 0.1
+    }));
+    const assembled = assembleContext(traceChunks, { maxTokens });
+    const groups = groupChunksByFile(assembled.chunks);
+    finalContent = formatGroupedContext(groups);
+    finalChunks = assembled.chunks;
+    finalTokenCount = assembled.tokenCount;
+    localTasksPerformed = traceResult.metadata.localTasksPerformed;
+  } else if (mode === "explore") {
+    const exploreResult = await runExplainCodebase({
+      question: query,
+      maxTokens,
+      path: opts?.path,
+      limit: strategy.limit,
+      distanceThreshold: strategy.distanceThreshold
+    });
+    finalContent = exploreResult.content;
+    finalChunks = exploreResult.chunks;
+    finalTokenCount = exploreResult.metadata.tokensSent;
+    localTasksPerformed = exploreResult.metadata.localTasksPerformed;
+  } else {
+    if (mode === "trace" && !hasEdges) {
+      process.stderr.write(`brain-cache: No edges table found, falling back to explore mode
+`);
+    }
+    const { embeddings: vectors } = await embedBatchWithRetry(indexState.embeddingModel, [query]);
+    const queryVector = vectors[0];
+    const results = await searchChunks(table, queryVector, strategy, query);
+    const deduped = deduplicateChunks(results);
+    const assembled = assembleContext(deduped, { maxTokens });
+    const enriched = await enrichWithParentClass(assembled.chunks, table, { maxTokens, currentTokens: assembled.tokenCount });
+    const withoutPeripheral = enriched.filter((chunk) => !isTestFile2(chunk.filePath) && !isConfigFile(chunk.filePath));
+    const queryTokens = extractQueryTokens(query);
+    const compressed = withoutPeripheral.map(
+      (chunk) => isPrimaryMatch(chunk, queryTokens) ? chunk : compressChunk(chunk)
+    );
+    const groups = groupChunksByFile(compressed);
+    finalContent = formatGroupedContext(groups);
+    finalChunks = compressed;
+    finalTokenCount = assembled.tokenCount;
+    localTasksPerformed = ["embed_query", "vector_search", "dedup", "parent_enrich", "drop_peripheral", "compress", "cohesion_group", "token_budget"];
+  }
+  const BODY_STRIPPED_MARKER2 = "// [body stripped]";
+  const filesWithUncompressedContent = new Set(
+    finalChunks.filter((c) => !c.content.includes(BODY_STRIPPED_MARKER2)).map((c) => c.filePath)
+  );
+  const uniqueFiles = [...new Set(finalChunks.map((c) => c.filePath))];
+  const numFiles = uniqueFiles.length;
+  let fileContentTokens = 0;
+  for (const filePath of uniqueFiles) {
+    if (!filesWithUncompressedContent.has(filePath)) {
+      continue;
+    }
+    try {
+      const fileContent = await readFile4(filePath, "utf-8");
+      fileContentTokens += countChunkTokens(fileContent);
+    } catch {
+    }
+  }
+  const toolCalls = 1 + numFiles;
+  const toolCallOverhead = toolCalls * TOOL_CALL_OVERHEAD_TOKENS;
+  const estimatedWithoutBraincache = fileContentTokens + toolCallOverhead;
+  const reductionPct = estimatedWithoutBraincache > 0 ? Math.max(0, Math.round((1 - finalTokenCount / estimatedWithoutBraincache) * 100)) : 0;
+  const result = {
+    content: finalContent,
+    chunks: finalChunks,
+    metadata: {
+      tokensSent: finalTokenCount,
+      estimatedWithoutBraincache,
+      reductionPct,
+      filesInContext: numFiles,
+      localTasksPerformed,
+      cloudCallsMade: 0
+    }
+  };
+  process.stderr.write(
+    `brain-cache: context assembled (${finalTokenCount} tokens, ${reductionPct}% reduction, ${finalChunks.length} chunks)
+`
+  );
+  return result;
+}
+
+export {
+  runBuildContext
+};