Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
fix(deep): treat empty meaning replies as failures, not permanent pending (#172) (#177)
Frankie-Xubd6bf6b2dfc8
diff --git a/src/ai/crux.ts b/src/ai/crux.tsindex e0443abd..125ea50d 100644--- a/src/ai/crux.ts+++ b/src/ai/crux.ts@@ -114,6 +114,66 @@ function parseResults(obj: { symbols?: unknown } | undefined): NodeCrux[] {}));}+/**+ * Some OpenAI-compatible gateways ignore forced `tool_choice` and put the tool+ * payload in `content` instead (plain `{symbols:…}`, fenced JSON, or an emulated+ * `[{name, parameters}]` array). Without this recovery the meaning pass sees an+ * empty `toolCalls` list, leaves every node `pending`, and `graft check` loops+ * on "run --deep" forever (#172; same trigger as #129 for the crux path).+ */+function argsFromResponse(res: { text: string; toolCalls: { name: string; args: unknown }[] }): {+ symbols?: unknown;+} | undefined {+ const call = res.toolCalls.find((c) => c.name === RECORD_TOOL) ?? res.toolCalls[0];+ if (call?.args && typeof call.args === "object" && !Array.isArray(call.args)) {+ return call.args as { symbols?: unknown };+ }+ return recoverArgsFromContent(res.text);+}++function recoverArgsFromContent(text: string): { symbols?: unknown } | undefined {+ const raw = text?.trim();+ if (!raw) return undefined;+ const stripped = raw.replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/i, "").trim();++ const asSymbols = (value: unknown): { symbols?: unknown } | undefined => {+ if (!value || typeof value !== "object") return undefined;+ if (Array.isArray(value)) {+ for (const item of value) {+ if (!item || typeof item !== "object") continue;+ const rec = item as Record<string, unknown>;+ const name = typeof rec.name === "string" ? rec.name : "";+ // Accept the crux tool, or a generic emit_json wrapper some gateways use.+ if (name && name !== RECORD_TOOL && name !== "emit_json") continue;+ const params = rec.parameters ?? rec.arguments ?? rec.args;+ const hit = asSymbols(params);+ if (hit) return hit;+ }+ return undefined;+ }+ const obj = value as Record<string, unknown>;+ if (Array.isArray(obj.symbols)) return obj as { symbols?: unknown };+ return undefined;+ };++ try {+ const hit = asSymbols(JSON.parse(stripped));+ if (hit) return hit;+ } catch {+ /* try bracket slice below */+ }+ const start = stripped.indexOf("{");+ const end = stripped.lastIndexOf("}");+ if (start >= 0 && end > start) {+ try {+ return asSymbols(JSON.parse(stripped.slice(start, end + 1)));+ } catch {+ return undefined;+ }+ }+ return undefined;+}+/** Crux summarizer backed by any {@link ChatModel} via forced tool calling. */export class ChatCruxSummarizer implements CruxSummarizer {constructor(private model: ChatModel) {}@@ -136,6 +196,6 @@ export class ChatCruxSummarizer implements CruxSummarizer {{ role: "user", content: userContent(input) },],});- return parseResults(res.toolCalls[0]?.args as { symbols?: unknown } | undefined);+ return parseResults(argsFromResponse(res));}}diff --git a/src/graph/check.ts b/src/graph/check.tsindex d33a9437..f2cf273a 100644--- a/src/graph/check.ts+++ b/src/graph/check.ts@@ -36,6 +36,9 @@ export interface GraphCheckResult {stale: string[];/** Nodes never summarized (reported for context; not counted as drift). */pending: number;+ /** Ids of pending nodes (capped when formatting) — so a stuck meaning pass+ * names the files instead of only saying "run --deep" (#172). */+ pendingIds: string[];/** Committed nodes in total — the denominator that turns `pending` into a* coverage figure. A deep build that lost most of its LLM calls (#127) is only* distinguishable from a deliberate Tier-1 build by the SHARE that is missing. */@@ -65,6 +68,7 @@ export async function checkGraph(changed: [],stale: [],pending: 0,+ pendingIds: [],nodes: 0,};@@ -107,13 +111,18 @@ export async function checkGraph(if (now === undefined) result.removed.push(id);else if (now !== node.body_hash) result.changed.push(id);if (node.summary_state === "stale") result.stale.push(id);- if (node.summary_state === "pending") result.pending++;+ if (node.summary_state === "pending") {+ result.pending++;+ result.pendingIds.push(id);+ }}for (const id of current.keys()) {if (!committedById.has(id)) result.added.push(id);}- for (const arr of [result.added, result.removed, result.changed, result.stale]) arr.sort();+ for (const arr of [result.added, result.removed, result.changed, result.stale, result.pendingIds]) {+ arr.sort();+ }result.ok =result.added.length === 0 &&@@ -132,9 +141,7 @@ export function formatGraphCheckReport(r: GraphCheckResult): string {// A share, not a bare count: "1203 not yet summarized" reads the same whether// the repo was never deep-built or a deep build failed most of its calls.const pct = r.nodes > 0 ? Math.round(((r.nodes - r.pending) / r.nodes) * 100) : 0;- const note = r.pending- ? ` (meaning tier ${pct}% complete — ${r.pending} of ${r.nodes} node(s) not yet summarized; run \`graft build --deep\`)`- : "";+ const note = r.pending ? ` (${formatPendingNote(r, pct)})` : "";return `graph check: OK — the wiring graph is in sync with the code.${note}`;}@@ -161,3 +168,22 @@ export function formatGraphCheckReport(r: GraphCheckResult): string {if (r.stale.length) lines.push("Run `graft build --deep` to refresh stale summaries.");return lines.join("\n");}++/** Cap how many pending ids the OK-note lists so a large Tier-1 graph stays readable. */+const PENDING_SAMPLE = 8;++function formatPendingNote(r: GraphCheckResult, pct: number): string {+ const ids = r.pendingIds ?? [];+ const sample = ids.slice(0, PENDING_SAMPLE);+ const more = ids.length > PENDING_SAMPLE ? `, … +${ids.length - PENDING_SAMPLE} more` : "";+ const named = sample.length ? `: ${sample.join(", ")}${more}` : "";+ // Tier-1-only builds are supposed to leave everything pending — "run --deep"+ // is the right next step. A deep build that still left them pending used to+ // dead-end here (#172): re-running the same command never cleared empty/failed+ // meaning replies, so name the nodes and point at the last build's errors.+ return (+ `meaning tier ${pct}% complete — ${r.pending} of ${r.nodes} node(s) pending${named}. ` ++ `Run \`graft build --deep\` to summarize them; if a deep build already left these pending, ` ++ `that meaning pass failed — see that build's errors (re-running alone will not clear them)`+ );+}diff --git a/src/graph/enrich.ts b/src/graph/enrich.tsindex 75598e19..bbbd180e 100644--- a/src/graph/enrich.ts+++ b/src/graph/enrich.ts@@ -169,25 +169,39 @@ export async function enrichGraph(});const { results, error } = await collectFileCrux(summarizer, path, source, refs);- if (error) {- stats.errors.push(`${path}: ${error}`);- gate.record(error);- } else {- gate.succeeded();+ let fileError = error;+ if (fileError) {+ stats.errors.push(`${path}: ${fileError}`);+ gate.record(fileError);}+ let applied = 0;for (const node of fileNodes) {const r = results.size > 0 ? results.get(node.id) : undefined;- if (!r) {- // whole-file call failed, or the model skipped this symbol: keep what it had.+ // Empty / whitespace-only summaries are not success: caching them as+ // `ready` made the next `--deep` a permanent cache hit (#172).+ if (!r || !r.summary.trim()) {+ // whole-file call failed, the model skipped this symbol, or it returned+ // an empty summary: keep what it had and leave it retryable.if (node.summary_state === "stale") stats.stale++;else stats.pending++;continue;}- node.summary = r.summary || null;+ node.summary = r.summary;node.crux = buildCrux(r, node, source, lineCount);node.summary_state = "ready";stats.computed++;+ applied++;+ }++ if (!fileError && refs.length > 0 && applied === 0) {+ // collectFileCrux already labels a total miss; this catches "got entries+ // but every summary was blank" so the CLI's #127 degraded-exit path fires.+ fileError = "model returned no usable symbol summaries";+ stats.errors.push(`${path}: ${fileError}`);+ gate.record(fileError);+ } else if (!fileError) {+ gate.succeeded();}// Report on completion so the counter climbs monotonically under concurrency.@@ -250,6 +264,13 @@ async function collectFileCrux(break;}}+ // A total miss used to return `{ results: ∅ }` with no error — enrich left+ // every node `pending`, the CLI exited 0, and `graft check` told the user to+ // re-run `--deep` forever (#172). Surface it as a failure like a thrown error.+ if (!error && refs.length > 0 && results.size === 0) {+ error =+ "model returned no symbol summaries (empty tool response — the provider may ignore forced tool_choice)";+ }return { results, error };}diff --git a/test/graph-enrich-pending.test.ts b/test/graph-enrich-pending.test.tsnew file mode 100644index 00000000..6e92f1e0--- /dev/null+++ b/test/graph-enrich-pending.test.ts@@ -0,0 +1,161 @@+/**+ * #172: `graft build --deep` can finish with every node still `pending` when the+ * meaning pass gets an empty reply (no tool call / no symbols) — and re-running+ * does not clear it, while `graft check` only says "run --deep".+ *+ * The #127 gate already catches thrown provider errors; this covers the silent+ * empty-success path that left CI stuck on an unresolvable check note.+ */+import { test } from "node:test";+import assert from "node:assert/strict";+import { enrichGraph } from "../src/graph/enrich.js";+import { ChatCruxSummarizer } from "../src/ai/crux.js";+import { formatGraphCheckReport, type GraphCheckResult } from "../src/graph/check.js";+import type { CruxSummarizer, FileCruxInput, NodeCrux } from "../src/ai/crux.js";+import type { ChatModel, ChatRequest, ChatResponse } from "../src/ai/llm/types.js";+import type { NodeV1 } from "../src/graph/types.js";++/** Returns no symbols — the silent failure mode behind #172. */+class EmptyCrux implements CruxSummarizer {+ calls = 0;+ async describeFile(_input: FileCruxInput): Promise<NodeCrux[]> {+ this.calls++;+ return [];+ }+}++/** Returns entries whose summaries are empty strings. */+class BlankSummaryCrux implements CruxSummarizer {+ async describeFile(input: FileCruxInput): Promise<NodeCrux[]> {+ return input.nodes.map((n) => ({ id: n.id, summary: " ", crux_start: 0, crux_end: 0 }));+ }+}++function node(path: string, name: string, kind: NodeV1["kind"] = "function"): NodeV1 {+ return {+ id: kind === "file" ? path : `${path}#${name}`,+ name,+ kind,+ path,+ span: "L1-L3",+ signature: kind === "file" ? null : `${name}()`,+ exported: true,+ origin: "ast",+ body_hash: `h-${name}`,+ summary_state: "pending",+ summary: null,+ crux: null,+ };+}++function calcFixture(): { nodes: NodeV1[]; sources: Map<string, string> } {+ const path = "src/calc.py";+ return {+ nodes: [+ node(path, "calc.py", "file"),+ node(path, "add"),+ node(path, "mul"),+ node(path, "total"),+ ],+ sources: new Map([[path, "def add(a, b):\n return a + b\n"]]),+ };+}++test("#172: an empty meaning reply is a failed file, not a silent all-pending success", async () => {+ const { nodes, sources } = calcFixture();+ const summarizer = new EmptyCrux();++ const stats = await enrichGraph(nodes, new Map(), sources, { summarizer, concurrency: 1 });++ assert.equal(stats.computed, 0);+ assert.equal(stats.pending, 4);+ assert.equal(stats.failedFiles, 1, "empty reply must count as a failed file so the CLI can exit non-zero");+ assert.ok(stats.errors.length > 0, "empty reply must leave a readable error");+ assert.match(stats.errors[0] ?? "", /no symbol|empty/i);+ // collectFileCrux retries once when the model omits every id+ assert.equal(summarizer.calls, 2);+ for (const n of nodes) assert.equal(n.summary_state, "pending");+});++test("#172: empty summaries must not be cached as ready — a re-run still retries them", async () => {+ const { nodes, sources } = calcFixture();++ const first = await enrichGraph(nodes, new Map(), sources, {+ summarizer: new BlankSummaryCrux(),+ concurrency: 1,+ });+ assert.equal(first.computed, 0, "blank summaries are not a successful compute");+ assert.equal(first.pending, 4);+ for (const n of nodes) {+ assert.equal(n.summary_state, "pending", "blank summary must not flip the node to ready");+ assert.equal(n.summary, null);+ }++ // Prior graph still has pending+null; a working summarizer on the next --deep must retry.+ const prior = new Map(nodes.map((n) => [n.id, structuredClone(n)]));+ const { nodes: again } = calcFixture();+ let calls = 0;+ const working: CruxSummarizer = {+ async describeFile(input) {+ calls++;+ return input.nodes.map((n) => ({+ id: n.id,+ summary: `purpose of ${n.id}`,+ crux_start: 0,+ crux_end: 0,+ }));+ },+ };+ const second = await enrichGraph(again, prior, sources, { summarizer: working, concurrency: 1 });+ assert.equal(calls, 1, "pending nodes from a blank pass must be retried");+ assert.equal(second.computed, 4);+ assert.equal(second.pending, 0);+ assert.equal(second.cached, 0);+});++test("#172: check names pending nodes and does not pretend re-running --deep always clears them", () => {+ const r: GraphCheckResult = {+ ok: true,+ missing: false,+ added: [],+ removed: [],+ changed: [],+ stale: [],+ pending: 4,+ pendingIds: ["src/calc.py", "src/calc.py#add", "src/calc.py#mul", "src/calc.py#total"],+ nodes: 4,+ };+ const report = formatGraphCheckReport(r);+ assert.match(report, /src\/calc\.py#add/);+ assert.match(report, /pending/);+ // Must not be the old dead-end that only says "run graft build --deep".+ assert.match(report, /already|failed|errors|meaning pass/i);+});++test("#172: ChatCruxSummarizer recovers symbols when the gateway puts the tool payload in content", async () => {+ class ContentOnlyModel implements ChatModel {+ readonly label = "fake:content-tool";+ async create(_req: ChatRequest): Promise<ChatResponse> {+ const payload = {+ symbols: [{ id: "src/calc.py#add", summary: "adds two numbers", crux_start: 0, crux_end: 0 }],+ };+ // DeepSeek-style: ignore tool_choice, emulate the call in content (#129 trigger).+ return {+ text: JSON.stringify([{ name: "record_symbols", parameters: payload }]),+ toolCalls: [],+ usage: { input: 0, output: 0, cacheRead: 0, cacheCreate: 0 },+ stopReason: "stop",+ assistant: { role: "assistant", content: "" },+ };+ }+ }++ const out = await new ChatCruxSummarizer(new ContentOnlyModel()).describeFile({+ path: "src/calc.py",+ source: "def add(a, b):\n return a + b\n",+ nodes: [{ id: "src/calc.py#add", kind: "function", signature: null, startLine: 1, endLine: 2 }],+ });+ assert.equal(out.length, 1);+ assert.equal(out[0].id, "src/calc.py#add");+ assert.equal(out[0].summary, "adds two numbers");+});