@plumpslabs/kuma 2.2.7 → 2.3.0

package/dist/chunk-IMO4QAFJ.js

@@ -0,0 +1,752 @@
+import {
+  getDb,
+  saveDb
+} from "./chunk-6NEMSUKP.js";
+import {
+  getProjectRoot
+} from "./chunk-IXMWW5WA.js";
+
+// src/engine/kumaSelfHeal.ts
+import { execSync } from "child_process";
+import fs from "fs";
+import path from "path";
+import crypto from "crypto";
+function contentFingerprint(filePath) {
+  try {
+    const fullPath = path.join(getProjectRoot(), filePath);
+    if (!fs.existsSync(fullPath)) return null;
+    const stat = fs.statSync(fullPath);
+    if (!stat.isFile()) return null;
+    const fd = fs.openSync(fullPath, "r");
+    try {
+      const size = stat.size;
+      const readSize = Math.min(1024, size);
+      const head = Buffer.alloc(readSize);
+      fs.readSync(fd, head, 0, readSize, 0);
+      let tail = Buffer.alloc(0);
+      if (size > 2048) {
+        tail = Buffer.alloc(1024);
+        fs.readSync(fd, tail, 0, 1024, size - 1024);
+      }
+      const hash = crypto.createHash("md5");
+      hash.update(head);
+      hash.update(tail);
+      hash.update(String(size));
+      return hash.digest("hex");
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    return null;
+  }
+}
+function findByFingerprint(fingerprint, oldName) {
+  try {
+    const root = getProjectRoot();
+    const ext = path.extname(oldName);
+    const result = execSync(
+      `find . -name "*${ext}" -type f -not -path "./node_modules/*" -not -path "./.git/*" -not -path "./dist/*" -not -path "./build/*" 2>/dev/null | head -200`,
+      { cwd: root, encoding: "utf-8", maxBuffer: 1024 * 1024, timeout: 1e4 }
+    ).trim();
+    if (!result) return null;
+    const files = result.split("\n").filter(Boolean);
+    for (const file of files) {
+      const relativePath = file.startsWith("./") ? file.slice(2) : file;
+      const fp = contentFingerprint(relativePath);
+      if (fp === fingerprint) {
+        return relativePath;
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+async function detectStaleNodes() {
+  const stale = [];
+  try {
+    const db = await getDb();
+    const root = getProjectRoot();
+    const stmt = db.prepare(`
+      SELECT id, type, name, file_path FROM nodes
+      WHERE file_path IS NOT NULL
+        AND length(file_path) > 0
+      ORDER BY updated_at DESC LIMIT 500
+    `);
+    while (stmt.step()) {
+      const row = stmt.getAsObject();
+      const filePath = row.file_path;
+      if (filePath.startsWith("search::") || filePath.startsWith("api_route::")) continue;
+      const fullPath = path.join(root, filePath);
+      if (!fs.existsSync(fullPath)) {
+        const newPath = findRenamedPath(filePath);
+        if (newPath) {
+          stale.push({
+            nodeId: row.id,
+            type: row.type,
+            name: row.name,
+            oldPath: filePath,
+            newPath,
+            issue: "path-changed"
+          });
+        } else {
+          const oldFingerprint = contentFingerprint(filePath);
+          const contentMatch = oldFingerprint ? findByFingerprint(oldFingerprint, path.basename(filePath)) : null;
+          stale.push({
+            nodeId: row.id,
+            type: row.type,
+            name: row.name,
+            oldPath: filePath,
+            newPath: contentMatch,
+            issue: contentMatch ? "path-changed" : "file-missing"
+          });
+        }
+      }
+    }
+    stmt.free();
+  } catch (err) {
+    console.error(`[KumaSelfHeal] Failed to detect stale nodes: ${err}`);
+  }
+  return stale;
+}
+function findRenamedPath(oldPath) {
+  try {
+    const root = getProjectRoot();
+    const output = execSync(
+      `git log --follow --diff-filter=R --name-only --format="" -1 -- "${oldPath}"`,
+      { cwd: root, encoding: "utf-8", maxBuffer: 1024 * 1024, timeout: 5e3 }
+    ).trim();
+    if (output) {
+      const lines = output.split("\n").filter(Boolean);
+      return lines[lines.length - 1] || null;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+async function cascadeStaleEdges(nodeIds) {
+  try {
+    const db = await getDb();
+    let count = 0;
+    for (const nodeId2 of nodeIds) {
+      db.run(
+        `UPDATE edges SET weight = MAX(weight * 0.1, 0.01), metadata = json_set(COALESCE(NULLIF(metadata,''), '{}'), '$.stale', 1)
+         WHERE (source_id = ? OR target_id = ?) AND weight > 0`,
+        [nodeId2, nodeId2]
+      );
+      count += db.getRowsModified();
+    }
+    saveDb();
+    return count;
+  } catch (err) {
+    console.error(`[KumaSelfHeal] Failed to cascade stale edges: ${err}`);
+    return 0;
+  }
+}
+async function healStaleNode(entry) {
+  try {
+    const db = await getDb();
+    if (entry.newPath) {
+      db.run(
+        `UPDATE nodes SET file_path = ?, updated_at = strftime('%s','now') WHERE id = ?`,
+        [entry.newPath, entry.nodeId]
+      );
+      db.run(
+        `UPDATE edges SET metadata = json_set(COALESCE(NULLIF(metadata,''), '{}'), '$.healed', 1) WHERE source_id = ? OR target_id = ?`,
+        [entry.nodeId, entry.nodeId]
+      );
+      db.run(
+        `UPDATE edges SET metadata = json_set(COALESCE(NULLIF(metadata,''), '{}'), '$.healed', 1, '$.newPath', ?)
+        WHERE json_extract(metadata, '$.filePath') = ?`,
+        [entry.newPath, entry.oldPath]
+      );
+      saveDb();
+      return true;
+    }
+    db.run(
+      `UPDATE nodes SET metadata = json_set(COALESCE(NULLIF(metadata,''), '{}'), '$.stale', 1) WHERE id = ?`,
+      [entry.nodeId]
+    );
+    saveDb();
+    return false;
+  } catch (err) {
+    console.error(`[KumaSelfHeal] Failed to heal node ${entry.nodeId}: ${err}`);
+    return false;
+  }
+}
+async function autoHeal() {
+  const stale = await detectStaleNodes();
+  let healed = 0;
+  let missing = 0;
+  for (const entry of stale) {
+    const success = await healStaleNode(entry);
+    if (success) healed++;
+    else missing++;
+  }
+  const staleNodeIds = stale.filter((e) => !e.newPath).map((e) => e.nodeId);
+  const cascadedEdges = await cascadeStaleEdges(staleNodeIds);
+  return { healed, missing, total: stale.length, cascadedEdges };
+}
+async function healOnQuery(filePaths) {
+  if (filePaths.length === 0) return { healed: 0 };
+  try {
+    const stalePaths = filePaths.filter((fp) => {
+      if (!fp || fp.startsWith("search::") || fp.startsWith("api_route::")) return false;
+      const fullPath = path.join(getProjectRoot(), fp);
+      return !fs.existsSync(fullPath);
+    });
+    if (stalePaths.length === 0) return { healed: 0 };
+    let healed = 0;
+    for (const oldPath of stalePaths) {
+      const newPath = findRenamedPath(oldPath);
+      if (newPath) {
+        const db = await getDb();
+        db.run(
+          `UPDATE nodes SET file_path = ?, updated_at = strftime('%s','now') WHERE file_path = ?`,
+          [newPath, oldPath]
+        );
+        saveDb();
+        healed++;
+      }
+    }
+    return { healed };
+  } catch {
+    return { healed: 0 };
+  }
+}
+function formatHealReport(result) {
+  if (result.total === 0) {
+    return "\u2705 **Self-Heal Check** \u2014 No stale entries found. Knowledge Graph is fresh.";
+  }
+  const lines = [
+    `\u{1FA7A} **Self-Heal Report**`,
+    `\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501`,
+    "",
+    `\u{1F4CA} ${result.total} stale entr${result.total > 1 ? "ies" : "y"} found`,
+    `\u2705 ${result.healed} healed (file renamed \u2192 path updated)`,
+    `\u274C ${result.missing} missing (file deleted \u2014 marked as stale)`,
+    result.cascadedEdges > 0 ? `\u{1F517} ${result.cascadedEdges} cascade edges updated` : "",
+    ""
+  ].filter(Boolean);
+  if (result.healed > 0) {
+    lines.push("\u{1F4A1} Healed entries had their file paths updated via git rename detection or content hash matching.");
+  }
+  if (result.missing > 0) {
+    lines.push("\u26A0\uFE0F Missing entries were marked as stale. The Knowledge Graph will deprioritize them.");
+    lines.push("\u{1F4A1} Run incremental healing after making changes to keep the graph fresh.");
+  }
+  return lines.join("\n");
+}
+
+// src/engine/kumaGraph.ts
+function nodeId(type, name) {
+  return `${type}::${name}`;
+}
+async function upsertNode(node) {
+  try {
+    const db = await getDb();
+    const id = node.id || nodeId(node.type, node.name);
+    const metadata = JSON.stringify(node.metadata ?? {});
+    db.run(`
+      INSERT INTO nodes (id, type, name, file_path, metadata, updated_at)
+      VALUES (?, ?, ?, ?, ?, strftime('%s','now'))
+      ON CONFLICT(id) DO UPDATE SET
+        type = excluded.type,
+        name = excluded.name,
+        file_path = COALESCE(excluded.file_path, nodes.file_path),
+        metadata = excluded.metadata,
+        updated_at = strftime('%s','now')
+    `, [id, node.type, node.name, node.filePath || null, metadata]);
+    try {
+      db.run(`INSERT INTO nodes_fts (rowid, name, metadata) VALUES (last_insert_rowid(), ?, ?)`, [node.name, metadata]);
+    } catch {
+    }
+    saveDb(db);
+  } catch (err) {
+    console.error(`[KumaGraph] Failed to upsert node: ${err}`);
+  }
+}
+async function addEdge(edge) {
+  try {
+    const db = await getDb();
+    const weight = edge.weight ?? 1;
+    const metadata = JSON.stringify(edge.metadata ?? {});
+    db.run(`
+      INSERT INTO edges (source_id, target_id, type, weight, metadata)
+      VALUES (?, ?, ?, ?, ?)
+      ON CONFLICT(source_id, target_id, type) DO UPDATE SET
+        weight = edges.weight + 1,
+        metadata = excluded.metadata
+    `, [edge.sourceId, edge.targetId, edge.type, weight, metadata]);
+    saveDb(db);
+  } catch (err) {
+    console.error(`[KumaGraph] Failed to add edge: ${err}`);
+  }
+}
+async function recordFunctionCall(caller, callee, filePath) {
+  const callerId = nodeId("function", caller);
+  const calleeId = nodeId("function", callee);
+  await upsertNode({ id: callerId, type: "function", name: caller, filePath });
+  await upsertNode({ id: calleeId, type: "function", name: callee });
+  await addEdge({ sourceId: callerId, targetId: calleeId, type: "calls" });
+}
+async function recordFileDefinition(filePath, symbol, symbolType = "function") {
+  const fileId = nodeId("file", filePath);
+  const symbolId = nodeId(symbolType, symbol);
+  await upsertNode({ id: fileId, type: "file", name: filePath });
+  await upsertNode({ id: symbolId, type: symbolType, name: symbol, filePath });
+  await addEdge({ sourceId: fileId, targetId: symbolId, type: "defines", metadata: { filePath } });
+}
+async function recordImport(fromFile, toFile) {
+  const fromId = nodeId("file", fromFile);
+  const toId = nodeId("file", toFile);
+  await upsertNode({ id: fromId, type: "file", name: fromFile });
+  await upsertNode({ id: toId, type: "file", name: toFile });
+  await addEdge({ sourceId: fromId, targetId: toId, type: "imports" });
+}
+async function recordTestRelation(testFile, functionName) {
+  const testId = nodeId("test", testFile);
+  const funcId = nodeId("function", functionName);
+  await upsertNode({ id: testId, type: "test", name: testFile });
+  await upsertNode({ id: funcId, type: "function", name: functionName });
+  await addEdge({ sourceId: testId, targetId: funcId, type: "tests" });
+}
+async function recordApiRoute(route, handler) {
+  const routeId = nodeId("api_route", route);
+  const handlerId = nodeId("function", handler);
+  await upsertNode({ id: routeId, type: "api_route", name: route });
+  await upsertNode({ id: handlerId, type: "function", name: handler });
+  await addEdge({ sourceId: routeId, targetId: handlerId, type: "routes" });
+}
+async function queryGraph(params) {
+  try {
+    const db = await getDb();
+    const { type = "nodes", query, limit = 20 } = params;
+    if (query && !query.includes("::")) {
+      try {
+        await healOnQuery([query]);
+      } catch {
+      }
+    }
+    if (type === "nodes") {
+      const stmt = db.prepare(`
+        SELECT id, type, name, file_path, metadata FROM nodes
+        WHERE name LIKE ? OR type = ?
+        ORDER BY updated_at DESC
+        LIMIT ?
+      `);
+      stmt.bind([`%${query}%`, query, limit]);
+      const results = [];
+      while (stmt.step()) {
+        const row = stmt.getAsObject();
+        results.push(row);
+      }
+      stmt.free();
+      if (results.length === 0) {
+        return `\u{1F50D} **Graph Query** \u2014 No nodes found for "${query}".
+
+Try a different search term or check if the graph has been built by using tools like smart_grep or lsp_query.`;
+      }
+      const lines = [
+        `\u{1F50D} **Graph Nodes** \u2014 ${results.length} result(s) for "${query}"`,
+        ""
+      ];
+      for (const r of results) {
+        const typeEmoji = r.type === "function" ? "\u{1F527}" : r.type === "file" ? "\u{1F4C4}" : r.type === "test" ? "\u{1F9EA}" : r.type === "api_route" ? "\u{1F310}" : r.type === "db_table" ? "\u{1F5C4}\uFE0F" : r.type === "class" ? "\u{1F3D7}\uFE0F" : "\u{1F4CC}";
+        lines.push(`${typeEmoji} **${r.name}** (${r.type})`);
+        if (r.file_path) lines.push(`   \u{1F4CD} ${r.file_path}`);
+      }
+      lines.push("", "\u{1F4A1} Use kuma_context({ action: 'research', scope: '<name>' }) to research a scope.");
+      return lines.join("\n");
+    } else if (type === "edges") {
+      const stmt = db.prepare(`
+        SELECT e.type, e.weight,
+          CASE WHEN e.source_id = ? THEN e.target_id ELSE e.source_id END AS connected_node,
+          n.type AS connected_type, n.name AS connected_name, n.file_path AS connected_path
+        FROM edges e
+        LEFT JOIN nodes n ON n.id = (CASE WHEN e.source_id = ? THEN e.target_id ELSE e.source_id END)
+        WHERE e.source_id = ? OR e.target_id = ?
+        ORDER BY e.weight DESC
+        LIMIT ?
+      `);
+      stmt.bind([query, query, query, query, limit]);
+      const results = [];
+      while (stmt.step()) {
+        const row = stmt.getAsObject();
+        results.push(row);
+      }
+      stmt.free();
+      if (results.length === 0) {
+        return `\u{1F50D} **Graph Edges** \u2014 No connections found for node "${query}".
+
+Try kuma_graph_query({ type: 'nodes', query: '<search>' }) to find node IDs first.`;
+      }
+      const lines = [
+        `\u{1F517} **Graph Edges** \u2014 ${results.length} connection(s) for "${query}"`,
+        ""
+      ];
+      for (const r of results) {
+        const edgeEmoji = r.type === "calls" ? "\u27A1\uFE0F" : r.type === "imports" ? "\u{1F4E5}" : r.type === "defines" ? "\u{1F4DD}" : r.type === "tests" ? "\u{1F9EA}" : r.type === "routes" ? "\u{1F310}" : "\u{1F517}";
+        const typeLabel = r.connected_type ? ` (${r.connected_type})` : "";
+        lines.push(`${edgeEmoji} **${r.connected_node}**${typeLabel} \u2014 ${r.type} (weight: ${r.weight})`);
+        if (r.connected_path) lines.push(`   \u{1F4CD} ${r.connected_path}`);
+      }
+      return lines.join("\n");
+    } else if (type === "paths") {
+      const parts = query.split("\u2192").map((s) => s.trim());
+      if (parts.length !== 2) {
+        return `\u26A0\uFE0F For path queries, use format: "sourceNodeID \u2192 targetNodeID"
+Example: kuma_graph_query({ type: 'paths', query: 'function::login \u2192 function::validatePassword' })`;
+      }
+      const [sourceId, targetId] = parts;
+      const visited = /* @__PURE__ */ new Set();
+      const maxDepth = 10;
+      const queue = [{ nodeId: sourceId, path: [sourceId] }];
+      visited.add(sourceId);
+      let foundPath = null;
+      while (queue.length > 0 && !foundPath && queue[0].path.length <= maxDepth) {
+        const current = queue.shift();
+        const stmt = db.prepare(`
+          SELECT CASE WHEN source_id = ? THEN target_id ELSE source_id END AS neighbor
+          FROM edges WHERE (source_id = ? OR target_id = ?)
+        `);
+        stmt.bind([current.nodeId, current.nodeId, current.nodeId]);
+        while (stmt.step()) {
+          const row = stmt.getAsObject();
+          const neighbor = row.neighbor;
+          if (neighbor === targetId) {
+            foundPath = [...current.path, neighbor];
+            break;
+          }
+          if (!visited.has(neighbor)) {
+            visited.add(neighbor);
+            queue.push({ nodeId: neighbor, path: [...current.path, neighbor] });
+          }
+        }
+        stmt.free();
+      }
+      if (!foundPath) {
+        return `\u{1F50D} **Path Query** \u2014 No path found between "${sourceId}" and "${targetId}".
+
+The two nodes may not be connected in the knowledge graph yet. Use more tools to build the graph.`;
+      }
+      const names = [];
+      for (const nodeId2 of foundPath) {
+        const stmt2 = db.prepare("SELECT name, type FROM nodes WHERE id = ?");
+        stmt2.bind([nodeId2]);
+        if (stmt2.step()) {
+          const row = stmt2.getAsObject();
+          names.push(`${row.name} (${row.type})`);
+        } else {
+          names.push(nodeId2);
+        }
+        stmt2.free();
+      }
+      return [
+        `\u{1F6E4}\uFE0F **Graph Path** \u2014 ${names.length} node(s)`,
+        "",
+        ...names.map((n, i) => `  ${i > 0 ? "\u2192" : " "} ${n}`),
+        "",
+        "\u{1F4A1} This path was discovered by traversing the knowledge graph built from AI tool calls."
+      ].join("\n");
+    }
+    return `\u26A0\uFE0F Unknown query type "${type}". Use "nodes", "edges", or "paths".`;
+  } catch (err) {
+    return `Error querying graph: ${err}`;
+  }
+}
+async function buildFromSessionMemory() {
+  try {
+    const { sessionMemory } = await import("./sessionMemory-52ECPXZ6.js");
+    const toolCalls = sessionMemory.getToolCallHistory(50);
+    let edgeCount = 0;
+    for (const call of toolCalls) {
+      const params = call.params;
+      if (call.toolName === "kuma_research" || call.toolName === "research") {
+        const scope = params.scope;
+        if (scope) {
+          await upsertNode({
+            id: `research::${scope}`,
+            type: "variable",
+            name: `research:${scope}`,
+            metadata: { confidence: params.confidence || 0 }
+          });
+          edgeCount++;
+        }
+      }
+      const filePath = params.filePath || params.files?.[0];
+      if (filePath) {
+        await upsertNode({
+          id: nodeId("file", filePath),
+          type: "file",
+          name: filePath
+        });
+        edgeCount++;
+      }
+    }
+    return edgeCount;
+  } catch {
+    return 0;
+  }
+}
+async function searchGraph(query, limit = 20) {
+  try {
+    const db = await getDb();
+    try {
+      const stmt2 = db.prepare(`
+        SELECT n.id, n.type, n.name, n.file_path
+        FROM nodes_fts f
+        JOIN nodes n ON n.rowid = f.rowid
+        WHERE nodes_fts MATCH ?
+        LIMIT ?
+      `);
+      stmt2.bind([query, limit]);
+      const results2 = [];
+      while (stmt2.step()) {
+        results2.push(stmt2.getAsObject());
+      }
+      stmt2.free();
+      if (results2.length > 0) {
+        const lines2 = [
+          `\u{1F50D} **Graph Search** \u2014 ${results2.length} result(s) for "${query}"`,
+          ""
+        ];
+        for (const r of results2) {
+          lines2.push(`  \u2022 **${r.name}** (${r.type})${r.file_path ? ` \u2014 ${r.file_path}` : ""}`);
+        }
+        return lines2.join("\n");
+      }
+    } catch {
+    }
+    const stmt = db.prepare(`
+      SELECT id, type, name, file_path FROM nodes
+      WHERE name LIKE ? OR file_path LIKE ?
+      ORDER BY updated_at DESC
+      LIMIT ?
+    `);
+    stmt.bind([`%${query}%`, `%${query}%`, limit]);
+    const results = [];
+    while (stmt.step()) {
+      results.push(stmt.getAsObject());
+    }
+    stmt.free();
+    if (results.length === 0) {
+      return `\u{1F50D} **Graph Search** \u2014 No results for "${query}". Try a different search term.`;
+    }
+    const lines = [
+      `\u{1F50D} **Graph Search** \u2014 ${results.length} result(s) for "${query}"`,
+      ""
+    ];
+    for (const r of results) {
+      lines.push(`  \u2022 **${r.name}** (${r.type})${r.file_path ? ` \u2014 ${r.file_path}` : ""}`);
+    }
+    return lines.join("\n");
+  } catch (err) {
+    return `Error searching graph: ${err}`;
+  }
+}
+async function getGraphStats() {
+  try {
+    const db = await getDb();
+    const nodeCount = db.exec("SELECT COUNT(*) as c FROM nodes")[0]?.values[0][0] ?? 0;
+    const edgeCount = db.exec("SELECT COUNT(*) as c FROM edges")[0]?.values[0][0] ?? 0;
+    const typeCounts = [];
+    try {
+      const stmt = db.prepare("SELECT type, COUNT(*) as cnt FROM nodes GROUP BY type ORDER BY cnt DESC");
+      while (stmt.step()) {
+        typeCounts.push(stmt.getAsObject());
+      }
+      stmt.free();
+    } catch {
+    }
+    const lines = [
+      `\u{1F4CA} **Knowledge Graph Stats**`,
+      `\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501`,
+      "",
+      `\u{1F4CA} **${nodeCount} nodes** | **${edgeCount} edges**`,
+      ""
+    ];
+    if (typeCounts.length > 0) {
+      lines.push("**Node Types:**");
+      for (const t of typeCounts) {
+        const emoji = t.type === "function" ? "\u{1F527}" : t.type === "file" ? "\u{1F4C4}" : t.type === "test" ? "\u{1F9EA}" : t.type === "api_route" ? "\u{1F310}" : t.type === "db_table" ? "\u{1F5C4}\uFE0F" : t.type === "class" ? "\u{1F3D7}\uFE0F" : "\u{1F4CC}";
+        lines.push(`  ${emoji} ${t.type}: ${t.cnt}`);
+      }
+    }
+    lines.push(
+      "",
+      "\u{1F4A1} Nodes are built from research and code changes:",
+      "  \u2022 kuma_context research \u2192 research nodes",
+      "  \u2022 File modifications \u2192 file change edges",
+      "  \u2022 Graph queries \u2192 connection edges"
+    );
+    return lines.join("\n");
+  } catch (err) {
+    return `Error getting graph stats: ${err}`;
+  }
+}
+async function analyzeImpact(target) {
+  try {
+    const db = await getDb();
+    const nodeStmt = db.prepare(`
+      SELECT id, name, type, file_path FROM nodes
+      WHERE name LIKE ? OR file_path = ? OR id = ?
+      LIMIT 1
+    `);
+    nodeStmt.bind([`%${target}%`, target, target]);
+    let nodeId2 = "";
+    let nodeName = "";
+    if (nodeStmt.step()) {
+      const row = nodeStmt.getAsObject();
+      nodeId2 = row.id;
+      nodeName = row.name;
+    }
+    nodeStmt.free();
+    if (!nodeId2) {
+      return { symbol: target, references: 0, files: 0, testFiles: 0, entryPoints: [], risk: "low" };
+    }
+    const refStmt = db.prepare(`
+      SELECT COUNT(*) as cnt, COUNT(DISTINCT CASE WHEN e.source_id != ? THEN e.source_id ELSE e.target_id END) as file_count
+      FROM edges e WHERE e.source_id = ? OR e.target_id = ?
+    `);
+    refStmt.bind([nodeId2, nodeId2, nodeId2]);
+    let references = 0;
+    let files = 0;
+    if (refStmt.step()) {
+      const row = refStmt.getAsObject();
+      references = row.cnt || 0;
+      files = row.file_count || 0;
+    }
+    refStmt.free();
+    let testFiles = 0;
+    try {
+      const testStmt = db.prepare(
+        `SELECT COUNT(*) as cnt FROM edges e JOIN nodes n ON n.id = e.source_id WHERE (e.source_id = ? OR e.target_id = ?) AND n.type = 'test'`
+      );
+      testStmt.bind([nodeId2, nodeId2]);
+      if (testStmt.step()) {
+        testFiles = testStmt.getAsObject().cnt || 0;
+      }
+      testStmt.free();
+    } catch {
+    }
+    const entryStmt = db.prepare(
+      `SELECT n.name, COUNT(*) as cnt FROM edges e JOIN nodes n ON n.id = e.target_id WHERE e.target_id = ? GROUP BY n.name ORDER BY cnt DESC LIMIT 5`
+    );
+    entryStmt.bind([nodeId2]);
+    const entryRows = [];
+    while (entryStmt.step()) {
+      entryRows.push(entryStmt.getAsObject());
+    }
+    entryStmt.free();
+    const entryPoints = [];
+    for (const row of entryRows) {
+      entryPoints.push(`${row.name} (${row.cnt} refs)`);
+    }
+    const risk = references > 20 ? "high" : references > 5 ? "medium" : "low";
+    return { symbol: nodeName, references, files, testFiles, entryPoints, risk };
+  } catch (err) {
+    console.error(`[KumaGraph] Impact analysis failed: ${err}`);
+    return { symbol: target, references: 0, files: 0, testFiles: 0, entryPoints: [], risk: "low" };
+  }
+}
+function formatImpact(result) {
+  const icon = result.risk === "high" ? "\u{1F534}" : result.risk === "medium" ? "\u{1F7E1}" : "\u{1F7E2}";
+  const lines = [
+    `${icon} **Impact Analysis** \u2014 ${result.symbol}`,
+    `\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501`,
+    "",
+    `\u{1F4CA} ${result.references} reference(s) across ${result.files} file(s)`,
+    `\u{1F9EA} ${result.testFiles} test file(s)`,
+    result.entryPoints.length > 0 ? `
+\u{1F3AF} Entry Points:
+  ${result.entryPoints.join("\n  ")}` : "",
+    "",
+    `\u26A0\uFE0F Risk Level: **${result.risk.toUpperCase()}**`,
+    result.risk === "high" ? "\u{1F4A1} High impact \u2014 review thoroughly before changing." : ""
+  ].filter(Boolean);
+  return lines.join("\n");
+}
+async function traceFlow(entryPoint, maxDepth = 10) {
+  const steps = [];
+  try {
+    const db = await getDb();
+    const nodeStmt = db.prepare("SELECT id FROM nodes WHERE name LIKE ? OR id = ? LIMIT 1");
+    nodeStmt.bind([`%${entryPoint}%`, entryPoint]);
+    let nodeId2 = "";
+    if (nodeStmt.step()) {
+      nodeId2 = nodeStmt.getAsObject().id;
+    }
+    nodeStmt.free();
+    if (!nodeId2) return steps;
+    const visited = /* @__PURE__ */ new Set();
+    const queue = [{ id: nodeId2, depth: 0 }];
+    visited.add(nodeId2);
+    while (queue.length > 0) {
+      const current = queue.shift();
+      if (current.depth >= maxDepth) continue;
+      const edgeStmt = db.prepare(`
+        SELECT e.type, n.id, n.name FROM edges e
+        JOIN nodes n ON n.id = e.target_id
+        WHERE e.source_id = ? AND e.type IN ('calls','routes','imports')
+        ORDER BY e.weight DESC LIMIT 10
+      `);
+      edgeStmt.bind([current.id]);
+      while (edgeStmt.step()) {
+        const row = edgeStmt.getAsObject();
+        const targetId = row.id;
+        const targetName = row.name;
+        const edgeType = row.type;
+        if (!visited.has(targetId)) {
+          visited.add(targetId);
+          steps.push({ from: current.id, to: targetName, edgeType });
+          queue.push({ id: targetId, depth: current.depth + 1 });
+        }
+      }
+      edgeStmt.free();
+    }
+    return steps;
+  } catch (err) {
+    console.error(`[KumaGraph] Flow trace failed: ${err}`);
+    return steps;
+  }
+}
+function formatFlow(entryPoint, steps) {
+  if (steps.length === 0) {
+    return `\u{1F50D} No flow found for "${entryPoint}". Research the scope first with kuma_context({ action: 'research' }).`;
+  }
+  const lines = [
+    `\u{1F6E4}\uFE0F **Flow: ${entryPoint}**`,
+    `\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501`,
+    ""
+  ];
+  const edgeEmojis = { calls: "\u27A1\uFE0F", routes: "\u{1F310}", imports: "\u{1F4E5}" };
+  for (const step of steps) {
+    const emoji = edgeEmojis[step.edgeType] || "\u{1F517}";
+    lines.push(`  ${emoji} ${step.to} (${step.edgeType})`);
+  }
+  lines.push("", `\u{1F4A1} ${steps.length} step(s) traversed.`);
+  return lines.join("\n");
+}
+
+export {
+  detectStaleNodes,
+  autoHeal,
+  formatHealReport,
+  upsertNode,
+  addEdge,
+  recordFunctionCall,
+  recordFileDefinition,
+  recordImport,
+  recordTestRelation,
+  recordApiRoute,
+  queryGraph,
+  buildFromSessionMemory,
+  searchGraph,
+  getGraphStats,
+  analyzeImpact,
+  formatImpact,
+  traceFlow,
+  formatFlow
+};