@kage-core/kage-graph-mcp 1.1.29 → 1.1.31

package/README.md

@@ -36,8 +36,11 @@ Restart your agent once after setup so MCP tools reload.
 
 - repo-local memory for decisions, runbooks, bug fixes, gotchas, conventions,
   and code explanations
-- a code graph for files, symbols, imports, calls, routes, tests, and packages,
-  including generic call/test signals and mixed-language framework routes
+- a code graph for files, symbols, imports, confidence-scored calls, routes,
+  tests, and packages, including generic call/test signals and mixed-language
+  framework routes
+- conservative cleanup candidates for unreferenced files, unused exports, and
+  internal-looking unused symbols
 - memory-code links so project knowledge points at the code it affects
 - decision intelligence for why-memory coverage, stale/weak packets, and
   important files that still lack linked repo knowledge

package/dist/index.js

@@ -221,7 +221,7 @@ function listTools() {
         },
         {
             name: "kage_cleanup_candidates",
-            description: "Find conservative cleanup candidates from Kage's code graph. Reports unreferenced source files with confidence and reasons; never auto-deletes.",
+            description: "Find conservative cleanup candidates from Kage's code graph. Reports unreferenced source files, unused exports, and internal-looking unused symbols with confidence and reasons; never auto-deletes.",
             inputSchema: {
                 type: "object",
                 properties: {

package/dist/kernel.js

@@ -1656,7 +1656,9 @@ function hydrateCodeGraphArtifact(projectDir, artifact, structural) {
             ...index.imports,
             ...(artifact.extra_imports ?? []),
         ].sort((a, b) => a.from_path.localeCompare(b.from_path) || a.line - b.line || a.specifier.localeCompare(b.specifier)),
-        calls: artifact.calls ?? [],
+        calls: (artifact.calls ?? [])
+            .map((call) => normalizeCallEdge(call, { confidence: 0.7, resolution: "generic_static_name" }))
+            .filter((call) => Boolean(call)),
         routes: artifact.routes ?? [],
         tests: artifact.tests ?? [],
         packages: artifact.packages ?? [],
@@ -2755,6 +2757,27 @@ function symbolAtLine(symbols, path, line) {
         .filter((symbol) => symbol.path === path && symbol.line <= line && (symbol.end_line ?? symbol.line) >= line)
         .sort((a, b) => (b.line - a.line) || ((a.end_line ?? a.line) - (b.end_line ?? b.line)))[0] ?? null;
 }
+function normalizeCallConfidence(value, fallback) {
+    const numeric = Number(value);
+    if (!Number.isFinite(numeric))
+        return fallback;
+    return Number(Math.max(0, Math.min(1, numeric)).toFixed(2));
+}
+function normalizeCallResolution(value, fallback) {
+    return value === "typescript_ast_name" || value === "generic_static_name" || value === "external_index" ? value : fallback;
+}
+function normalizeCallEdge(call, fallback) {
+    if (!isRecord(call) || typeof call.to_symbol !== "string")
+        return null;
+    return {
+        from_symbol: typeof call.from_symbol === "string" ? call.from_symbol : null,
+        to_symbol: call.to_symbol,
+        path: String(call.path ?? ""),
+        line: Math.max(1, Number(call.line ?? 1)),
+        confidence: normalizeCallConfidence(call.confidence, fallback.confidence),
+        resolution: normalizeCallResolution(call.resolution, fallback.resolution),
+    };
+}
 function extractCalls(path, text, symbols, symbolByName) {
     const sourceFile = sourceFileFor(path, text);
     const calls = [];
@@ -2782,7 +2805,14 @@ function extractCalls(path, text, symbols, symbolByName) {
                 break;
             if (target.path === path && target.line === line)
                 continue;
-            calls.push({ from_symbol: caller?.id ?? null, to_symbol: target.id, path, line });
+            calls.push({
+                from_symbol: caller?.id ?? null,
+                to_symbol: target.id,
+                path,
+                line,
+                confidence: target.path === path ? 0.9 : 0.75,
+                resolution: "typescript_ast_name",
+            });
         }
         ts.forEachChild(node, visit);
     };
@@ -2824,7 +2854,14 @@ function extractGenericCalls(path, text, symbols, symbolByName) {
             for (const target of targets.slice(0, 3)) {
                 if (calls.length >= MAX_CODE_GRAPH_CALLS_PER_FILE)
                     break;
-                calls.push({ from_symbol: caller?.id ?? null, to_symbol: target.id, path, line });
+                calls.push({
+                    from_symbol: caller?.id ?? null,
+                    to_symbol: target.id,
+                    path,
+                    line,
+                    confidence: target.path === path ? 0.7 : 0.55,
+                    resolution: "generic_static_name",
+                });
             }
         }
     }
@@ -3173,9 +3210,8 @@ function parseKageExternalIndex(projectDir, parser, path) {
         : [];
     const calls = Array.isArray(raw.calls)
         ? raw.calls.flatMap((item) => {
-            if (!isRecord(item) || typeof item.to_symbol !== "string")
-                return [];
-            return [{ from_symbol: typeof item.from_symbol === "string" ? item.from_symbol : null, to_symbol: item.to_symbol, path: String(item.path ?? ""), line: Math.max(1, Number(item.line ?? 1)) }];
+            const call = normalizeCallEdge(item, { confidence: 0.85, resolution: "external_index" });
+            return call ? [call] : [];
         })
         : [];
     return { symbols, imports, calls };
@@ -3230,7 +3266,7 @@ function parseScipJsonObject(projectDir, raw) {
                     symbols.push(symbol);
             }
             else {
-                calls.push({ from_symbol: null, to_symbol: name, path: rel, line });
+                calls.push({ from_symbol: null, to_symbol: name, path: rel, line, confidence: 0.85, resolution: "external_index" });
             }
         }
     }
@@ -4995,7 +5031,7 @@ function queryCodeGraph(projectDir, query, limit = 10, graph) {
         ...imports.map(({ item }, index) => `${index + 1}. ${item.from_path}:${item.line} ${item.kind} ${item.specifier}${item.to_path ? ` -> ${item.to_path}` : ""}`),
         calls.length ? "" : "",
         calls.length ? "## Calls" : "",
-        ...calls.map((call, index) => `${index + 1}. ${call.from_symbol ? symbolNameById.get(call.from_symbol) ?? call.from_symbol : call.path} calls ${symbolNameById.get(call.to_symbol) ?? call.to_symbol} at ${call.path}:${call.line}`),
+        ...calls.map((call, index) => `${index + 1}. ${call.from_symbol ? symbolNameById.get(call.from_symbol) ?? call.from_symbol : call.path} calls ${symbolNameById.get(call.to_symbol) ?? call.to_symbol} at ${call.path}:${call.line} (${call.resolution}, confidence ${call.confidence.toFixed(2)})`),
     ];
     return {
         query,
@@ -5501,6 +5537,26 @@ function hasRuntimePathReference(projectDir, graph, target) {
     }
     return false;
 }
+function cleanupSymbolKind(symbol) {
+    return ["function", "method", "class", "constant"].includes(symbol.kind);
+}
+function symbolCleanupCandidate(symbol, kind, reasons, score, coveredByTests, git) {
+    return {
+        path: symbol.path,
+        kind,
+        symbol_id: symbol.id,
+        symbol_name: symbol.name,
+        line: symbol.line,
+        confidence: cleanupConfidence(score),
+        score,
+        reasons,
+        inbound_imports: 0,
+        source_inbound_imports: 0,
+        outbound_imports: 0,
+        covered_by_tests: coveredByTests,
+        last_commit_at: git?.last_commit_at ?? null,
+    };
+}
 function kageCleanupCandidates(projectDir) {
     const graph = readCurrentCodeGraph(projectDir) ?? buildCodeGraph(projectDir);
     const fileByPath = new Map(graph.files.map((file) => [file.path, file]));
@@ -5525,6 +5581,7 @@ function kageCleanupCandidates(projectDir) {
         warnings.push("Git history is unavailable, so cleanup confidence does not use recency.");
     const candidates = [];
     const skippedRuntimeReferences = [];
+    const wholeFileCandidates = new Set();
     for (const file of graph.files) {
         if (file.kind !== "source")
             continue;
@@ -5577,6 +5634,60 @@ function kageCleanupCandidates(projectDir) {
             covered_by_tests: coveredByTests,
             last_commit_at: git?.last_commit_at ?? null,
         });
+        wholeFileCandidates.add(file.path);
+    }
+    const calledSymbols = new Set(graph.calls.map((call) => call.to_symbol));
+    const routeHandlers = new Set(graph.routes.map((route) => route.handler_symbol).filter((value) => Boolean(value)));
+    const coveredSymbolNames = new Set(graph.tests.map((test) => test.covers_symbol?.toLowerCase()).filter((value) => Boolean(value)));
+    const symbolsByPath = new Map();
+    for (const symbol of graph.symbols.filter(cleanupSymbolKind)) {
+        const list = symbolsByPath.get(symbol.path) ?? [];
+        list.push(symbol);
+        symbolsByPath.set(symbol.path, list);
+    }
+    const importedNamesByPath = new Map();
+    for (const edge of graph.imports) {
+        if (!edge.to_path || !edge.imported.length)
+            continue;
+        const names = importedNamesByPath.get(edge.to_path) ?? new Set();
+        for (const name of edge.imported)
+            names.add(name);
+        importedNamesByPath.set(edge.to_path, names);
+    }
+    for (const file of graph.files) {
+        if (file.kind !== "source" || wholeFileCandidates.has(file.path))
+            continue;
+        if (isEntrypointLike(file.path) || routeFiles.has(file.path))
+            continue;
+        const fileSymbols = symbolsByPath.get(file.path) ?? [];
+        if (!fileSymbols.length)
+            continue;
+        const git = hasGit ? gitFileSignal(projectDir, file.path, graphPaths) : null;
+        const coveredByTests = hasTestCoverage(file.path, graph);
+        const importedNames = importedNamesByPath.get(file.path) ?? new Set();
+        const exportedSymbols = fileSymbols.filter((symbol) => symbol.export);
+        const hasMatchedNamedExport = exportedSymbols.some((symbol) => importedNames.has(symbol.name));
+        for (const symbol of fileSymbols) {
+            const symbolReferenced = calledSymbols.has(symbol.id) || routeHandlers.has(symbol.id) || coveredSymbolNames.has(symbol.name.toLowerCase());
+            if (symbolReferenced)
+                continue;
+            if (symbol.export) {
+                if (!hasMatchedNamedExport || importedNames.has(symbol.name))
+                    continue;
+                candidates.push(symbolCleanupCandidate(symbol, "unused_export", [
+                    `export "${symbol.name}" is not imported by current named import edges`,
+                    "symbol is not a known call target, route handler, or covered test target",
+                    "file has at least one other exported symbol imported by name",
+                ], 0.62, coveredByTests, git));
+            }
+            else if (/^_[A-Za-z0-9_]+/.test(symbol.name)) {
+                candidates.push(symbolCleanupCandidate(symbol, "unused_internal_symbol", [
+                    `internal-looking symbol "${symbol.name}" has no known call edge`,
+                    "symbol is not a route handler or covered test target",
+                    "candidate is review input only; dynamic references may exist",
+                ], 0.5, coveredByTests, git));
+            }
+        }
     }
     candidates.sort((a, b) => b.score - a.score || a.path.localeCompare(b.path));
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kage-core/kage-graph-mcp",
-  "version": "1.1.29",
+  "version": "1.1.31",
   "description": "Local-first repo memory, code graph, and recall MCP server for coding agents",
   "main": "dist/index.js",
   "files": [

package/viewer/app.js

@@ -698,19 +698,21 @@
       seen.add(entity.id);
       entities.push(entity);
     };
-    var addEdge = function (from, to, relation, fact, source) {
+    var addEdge = function (from, to, relation, fact, source, options) {
       if (!from || !to) return;
+      options = options || {};
       edges.push({
         id: relation + ":" + from + ":" + to + ":" + edges.length,
         from: from,
         to: to,
         relation: relation,
         fact: fact,
-        confidence: 1,
+        confidence: options.confidence == null ? 1 : Number(options.confidence),
         evidence: [],
         commit: graph.repo_state && graph.repo_state.head,
         source: source || "code_graph",
-        graph_kind: "code"
+        graph_kind: "code",
+        resolution: options.resolution
       });
     };
 
@@ -764,7 +766,11 @@
     });
 
     (graph.calls || []).forEach(function (call) {
-      addEdge(call.from_symbol || "file:" + call.path, call.to_symbol, "calls", call.path + ":" + call.line + " calls target symbol.", "calls");
+      var confidence = call.confidence == null ? 0.7 : Number(call.confidence);
+      addEdge(call.from_symbol || "file:" + call.path, call.to_symbol, "calls", call.path + ":" + call.line + " calls target symbol.", "calls", {
+        confidence: confidence,
+        resolution: call.resolution
+      });
     });
 
     (graph.routes || []).forEach(function (route) {