Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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");
+});