Skip to content

Commit 545971c

Browse files
committed
feat(mcp): fold coverage into index_status; coverage note on get_code_snippet
Per review: no dedicated coverage tool. - index_status now carries the coverage report (parse_partial + skipped lists from the separate index_coverage table, plus the best-effort coverage_note); get_index_coverage is removed. Tool description updated so agents learn the coverage semantics from index_status; index_repository and the response note now point there - the read hook resolves coverage through index_status (same envelope fields, unchanged note wording); verified end-to-end against a real index (flagged file -> note with exact ranges, clean file -> silence) - get_code_snippet responses from a parse_partial file now carry a correlated coverage_note ("line range(s) X could not be parsed ... the source above is ground truth") — the result names its file, so the warning is precisely anchored. Entirely-skipped files cannot appear here (no nodes), so no uncorrelated noise is possible; clean files carry no note (asserted both ways in the e2e test) Refs DeusData#963 Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
1 parent c97f682 commit 545971c

3 files changed

Lines changed: 136 additions & 106 deletions

File tree

‎src/cli/hook_augment.c‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -231,7 +231,8 @@ static char *ha_format_context(const char *envelope, const char *token, bool *is
231231
* knows the knowledge graph may under-report this file. Best-effort and
232232
* non-blocking like everything else here — no entry, no output. */
233233

234-
/* Parse a get_index_coverage envelope and return a note when `rel` is listed.
234+
/* Parse an index_status envelope (which carries the coverage report) and
235+
* return a note when `rel` is listed.
235236
* *is_error is set for MCP errors (project not indexed) → caller climbs. */
236237
static char *ha_coverage_context(const char *envelope, const char *rel, bool *is_error) {
237238
*is_error = false;
@@ -349,7 +350,7 @@ static char *ha_resolve_coverage(cbm_mcp_server_t *srv, const char *file_path) {
349350
yyjson_mut_doc_free(adoc);
350351
free(project);
351352
if (args) {
352-
char *res = cbm_mcp_handle_tool(srv, "get_index_coverage", args);
353+
char *res = cbm_mcp_handle_tool(srv, "index_status", args);
353354
free(args);
354355
if (res) {
355356
bool is_error = false;

‎src/mcp/mcp.c‎

Lines changed: 112 additions & 99 deletions
Original file line numberDiff line numberDiff line change
@@ -320,7 +320,7 @@ static const tool_def_t TOOLS[] = {
320320
"COVERAGE: the response reports files that were NOT fully indexed — 'skipped' (not "
321321
"indexed at all: oversized/read/parse failures) and 'parse_partial' (indexed, but "
322322
"constructs inside the listed line ranges could not be parsed and MAY be missing from "
323-
"the graph). Query the persisted signal any time via the get_index_coverage tool or "
323+
"the graph). Query the persisted signal any time via index_status or "
324324
"structurally via query_graph(graph=\"missed\"). Both signals are best-effort: absence "
325325
"of a flag is NOT a completeness guarantee; prefer grep inside flagged ranges.",
326326
"{\"type\":\"object\",\"properties\":{\"repo_path\":{\"type\":\"string\",\"description\":"
@@ -437,7 +437,10 @@ static const tool_def_t TOOLS[] = {
437437
{"get_code_snippet", "Get code snippet",
438438
"Read source code for a function/class/symbol. IMPORTANT: First call search_graph to find the "
439439
"exact qualified_name, then pass it here. This is a read tool, not a search tool. Accepts "
440-
"full qualified_name (exact match) or short function name (returns suggestions if ambiguous).",
440+
"full qualified_name (exact match) or short function name (returns suggestions if ambiguous). "
441+
"If the response carries a 'coverage_note', the file was only partially indexed — constructs "
442+
"in the noted line ranges may be missing from the graph (best-effort signal); prefer grep "
443+
"there and treat the returned source as ground truth.",
441444
"{\"type\":\"object\",\"properties\":{\"qualified_name\":{\"type\":\"string\",\"description\":"
442445
"\"Full qualified_name from search_graph, or short function name\"},\"project\":{"
443446
"\"type\":\"string\"},\"include_neighbors\":{"
@@ -495,18 +498,15 @@ static const tool_def_t TOOLS[] = {
495498
"{\"type\":\"object\",\"properties\":{\"project\":{\"type\":\"string\"}},\"required\":["
496499
"\"project\"]}"},
497500

498-
{"index_status", "Index status", "Get the indexing status of a project",
499-
"{\"type\":\"object\",\"properties\":{\"project\":{\"type\":\"string\"}},\"required\":["
500-
"\"project\"]}"},
501-
502-
{"get_index_coverage", "Index coverage",
503-
"Report which files the indexer could NOT fully cover (best-effort signal, #963): "
504-
"'parse_partial' files WERE indexed but contain line ranges tree-sitter could not parse — "
505-
"constructs there MAY be missing from the graph (some are still recovered); 'skipped' files "
506-
"were not indexed at all (oversized/read/parse failure). Use this before trusting graph "
507-
"completeness on a file: if a file is listed, ALSO grep it (especially the flagged ranges). "
508-
"IMPORTANT: absence from this list is NOT a completeness guarantee — the signal only marks "
509-
"what the indexer can detect. For structural queries over the misses use "
501+
{"index_status", "Index status",
502+
"Get the indexing status of a project: node/edge counts, root path, git context, and the "
503+
"indexing-COVERAGE report — which files the indexer could NOT fully cover (best-effort "
504+
"signal): 'parse_partial' files WERE indexed but contain line ranges tree-sitter could not "
505+
"parse — constructs there MAY be missing from the graph (some are still recovered); "
506+
"'skipped' files were not indexed at all (oversized/read/parse failure). Use this before "
507+
"trusting graph completeness on a file: if a file is listed, ALSO grep it (especially the "
508+
"flagged ranges). IMPORTANT: absence from these lists is NOT a completeness guarantee — the "
509+
"signal only marks what the indexer can detect. For structural queries over the misses use "
510510
"query_graph(graph=\"missed\").",
511511
"{\"type\":\"object\",\"properties\":{\"project\":{\"type\":\"string\"}},\"required\":["
512512
"\"project\"]}"},
@@ -2178,6 +2178,68 @@ static char *handle_query_graph(cbm_mcp_server_t *srv, const char *args) {
21782178
return res;
21792179
}
21802180

2181+
/* Indexing-coverage report (#963), attached to index_status: the best-effort
2182+
* signal from the separate index_coverage table (coverage is metadata ABOUT
2183+
* the graph, stored outside it). Full per-project list, capped generously. */
2184+
enum { COVERAGE_FILE_CAP = 500 };
2185+
2186+
static void add_coverage_report(yyjson_mut_doc *doc, yyjson_mut_val *root, cbm_store_t *store,
2187+
const char *project) {
2188+
cbm_coverage_row_t *rows = NULL;
2189+
int count = 0;
2190+
(void)cbm_store_coverage_get(store, project, &rows, &count);
2191+
2192+
yyjson_mut_val *pp_files = yyjson_mut_arr(doc);
2193+
yyjson_mut_val *sk_files = yyjson_mut_arr(doc);
2194+
int pp_n = 0;
2195+
int sk_n = 0;
2196+
for (int i = 0; i < count; i++) {
2197+
bool partial = rows[i].kind && strcmp(rows[i].kind, "parse_partial") == 0;
2198+
if (partial) {
2199+
if (pp_n < COVERAGE_FILE_CAP) {
2200+
yyjson_mut_val *fe = yyjson_mut_obj(doc);
2201+
yyjson_mut_obj_add_strcpy(doc, fe, "path", rows[i].rel_path);
2202+
yyjson_mut_obj_add_strcpy(doc, fe, "error_ranges",
2203+
rows[i].detail ? rows[i].detail : "");
2204+
yyjson_mut_arr_add_val(pp_files, fe);
2205+
}
2206+
pp_n++;
2207+
} else {
2208+
if (sk_n < COVERAGE_FILE_CAP) {
2209+
yyjson_mut_val *fe = yyjson_mut_obj(doc);
2210+
yyjson_mut_obj_add_strcpy(doc, fe, "path", rows[i].rel_path);
2211+
yyjson_mut_obj_add_strcpy(doc, fe, "reason", rows[i].detail ? rows[i].detail : "");
2212+
yyjson_mut_obj_add_strcpy(doc, fe, "phase", rows[i].kind ? rows[i].kind : "");
2213+
yyjson_mut_arr_add_val(sk_files, fe);
2214+
}
2215+
sk_n++;
2216+
}
2217+
}
2218+
cbm_store_free_coverage(rows, count);
2219+
2220+
yyjson_mut_val *pp = yyjson_mut_obj(doc);
2221+
yyjson_mut_obj_add_val(doc, pp, "files", pp_files);
2222+
yyjson_mut_obj_add_int(doc, pp, "count", pp_n);
2223+
yyjson_mut_obj_add_bool(doc, pp, "truncated", pp_n > COVERAGE_FILE_CAP);
2224+
yyjson_mut_obj_add_val(doc, root, "parse_partial", pp);
2225+
2226+
yyjson_mut_val *sk = yyjson_mut_obj(doc);
2227+
yyjson_mut_obj_add_val(doc, sk, "files", sk_files);
2228+
yyjson_mut_obj_add_int(doc, sk, "count", sk_n);
2229+
yyjson_mut_obj_add_bool(doc, sk, "truncated", sk_n > COVERAGE_FILE_CAP);
2230+
yyjson_mut_obj_add_val(doc, root, "skipped", sk);
2231+
2232+
if (pp_n > 0 || sk_n > 0) {
2233+
yyjson_mut_obj_add_str(
2234+
doc, root, "coverage_note",
2235+
"Best-effort signal, not a completeness guarantee: parse_partial files WERE indexed, "
2236+
"but constructs inside the listed line ranges (1-based) MAY be missing from the graph "
2237+
"(tree-sitter error recovery still salvages some). skipped files were not indexed at "
2238+
"all. Prefer text search (grep) for flagged files/ranges. Files absent from this list "
2239+
"are NOT guaranteed to be fully indexed.");
2240+
}
2241+
}
2242+
21812243
static char *handle_index_status(cbm_mcp_server_t *srv, const char *args) {
21822244
char *project = get_project_arg(args);
21832245
cbm_store_t *store = resolve_store(srv, project);
@@ -2203,6 +2265,7 @@ static char *handle_index_status(cbm_mcp_server_t *srv, const char *args) {
22032265
safe_str_free(&proj_info.indexed_at);
22042266
safe_str_free(&proj_info.root_path);
22052267
}
2268+
add_coverage_report(doc, root, store, project);
22062269
if (nodes == 0) {
22072270
yyjson_mut_obj_add_str(
22082271
doc, root, "hint",
@@ -2221,87 +2284,6 @@ static char *handle_index_status(cbm_mcp_server_t *srv, const char *args) {
22212284
return result;
22222285
}
22232286

2224-
/* get_index_coverage (#963): report the best-effort indexing-coverage signal
2225-
* from the separate index_coverage table (coverage is metadata ABOUT the
2226-
* graph, stored outside it). Full per-project list, capped generously. */
2227-
enum { COVERAGE_FILE_CAP = 500 };
2228-
2229-
static char *handle_get_index_coverage(cbm_mcp_server_t *srv, const char *args) {
2230-
char *project = get_project_arg(args);
2231-
cbm_store_t *store = resolve_store(srv, project);
2232-
REQUIRE_STORE(store, project);
2233-
2234-
yyjson_mut_doc *doc = yyjson_mut_doc_new(NULL);
2235-
yyjson_mut_val *root = yyjson_mut_obj(doc);
2236-
yyjson_mut_doc_set_root(doc, root);
2237-
2238-
if (project) {
2239-
yyjson_mut_obj_add_str(doc, root, "project", project);
2240-
cbm_coverage_row_t *rows = NULL;
2241-
int count = 0;
2242-
(void)cbm_store_coverage_get(store, project, &rows, &count);
2243-
2244-
yyjson_mut_val *pp_files = yyjson_mut_arr(doc);
2245-
yyjson_mut_val *sk_files = yyjson_mut_arr(doc);
2246-
int pp_n = 0;
2247-
int sk_n = 0;
2248-
for (int i = 0; i < count; i++) {
2249-
bool partial = rows[i].kind && strcmp(rows[i].kind, "parse_partial") == 0;
2250-
if (partial) {
2251-
if (pp_n < COVERAGE_FILE_CAP) {
2252-
yyjson_mut_val *fe = yyjson_mut_obj(doc);
2253-
yyjson_mut_obj_add_strcpy(doc, fe, "path", rows[i].rel_path);
2254-
yyjson_mut_obj_add_strcpy(doc, fe, "error_ranges",
2255-
rows[i].detail ? rows[i].detail : "");
2256-
yyjson_mut_arr_add_val(pp_files, fe);
2257-
}
2258-
pp_n++;
2259-
} else {
2260-
if (sk_n < COVERAGE_FILE_CAP) {
2261-
yyjson_mut_val *fe = yyjson_mut_obj(doc);
2262-
yyjson_mut_obj_add_strcpy(doc, fe, "path", rows[i].rel_path);
2263-
yyjson_mut_obj_add_strcpy(doc, fe, "reason",
2264-
rows[i].detail ? rows[i].detail : "");
2265-
yyjson_mut_obj_add_strcpy(doc, fe, "phase", rows[i].kind ? rows[i].kind : "");
2266-
yyjson_mut_arr_add_val(sk_files, fe);
2267-
}
2268-
sk_n++;
2269-
}
2270-
}
2271-
cbm_store_free_coverage(rows, count);
2272-
2273-
yyjson_mut_val *pp = yyjson_mut_obj(doc);
2274-
yyjson_mut_obj_add_val(doc, pp, "files", pp_files);
2275-
yyjson_mut_obj_add_int(doc, pp, "count", pp_n);
2276-
yyjson_mut_obj_add_bool(doc, pp, "truncated", pp_n > COVERAGE_FILE_CAP);
2277-
yyjson_mut_obj_add_val(doc, root, "parse_partial", pp);
2278-
2279-
yyjson_mut_val *sk = yyjson_mut_obj(doc);
2280-
yyjson_mut_obj_add_val(doc, sk, "files", sk_files);
2281-
yyjson_mut_obj_add_int(doc, sk, "count", sk_n);
2282-
yyjson_mut_obj_add_bool(doc, sk, "truncated", sk_n > COVERAGE_FILE_CAP);
2283-
yyjson_mut_obj_add_val(doc, root, "skipped", sk);
2284-
2285-
yyjson_mut_obj_add_str(
2286-
doc, root, "note",
2287-
"Best-effort signal, not a completeness guarantee: parse_partial files WERE indexed, "
2288-
"but constructs inside the listed line ranges (1-based) MAY be missing from the graph "
2289-
"(tree-sitter error recovery still salvages some). skipped files were not indexed at "
2290-
"all. Prefer text search (grep) for flagged files/ranges. Files absent from this list "
2291-
"are NOT guaranteed to be fully indexed.");
2292-
} else {
2293-
yyjson_mut_obj_add_str(doc, root, "status", "no_project");
2294-
}
2295-
2296-
char *json = yy_doc_to_str(doc);
2297-
yyjson_mut_doc_free(doc);
2298-
free(project);
2299-
2300-
char *result = cbm_mcp_text_result(json, false);
2301-
free(json);
2302-
return result;
2303-
}
2304-
23052287
/* delete_project: just erase the .db file (and WAL/SHM). */
23062288
static char *handle_delete_project(cbm_mcp_server_t *srv, const char *args) {
23072289
char *name = get_project_arg(args);
@@ -3520,7 +3502,7 @@ static void add_parse_partial_summary(yyjson_mut_doc *doc, yyjson_mut_val *root,
35203502
"not be parsed and MAY be missing from the graph (tree-sitter error "
35213503
"recovery still salvages some). Prefer text search (grep) for those "
35223504
"regions. Files absent from this list are NOT guaranteed to be fully "
3523-
"indexed. Query the persisted signal via get_index_coverage.");
3505+
"indexed. Query the persisted signal via index_status.");
35243506
yyjson_mut_obj_add_val(doc, root, "parse_partial", pp);
35253507
}
35263508

@@ -4427,6 +4409,38 @@ static void add_string_array(yyjson_mut_doc *doc, yyjson_mut_val *obj, const cha
44274409
yyjson_mut_obj_add_val(doc, obj, key, arr);
44284410
}
44294411

4412+
/* get_code_snippet coverage note (#963): if the resolved node's file is
4413+
* flagged parse_partial, warn that the graph may under-report this file.
4414+
* Correlated by construction — the result names its file. (An entirely-
4415+
* skipped file cannot appear here: it has no nodes to resolve a snippet
4416+
* from.) */
4417+
static void add_snippet_coverage_note(yyjson_mut_doc *doc, yyjson_mut_val *root_obj,
4418+
cbm_store_t *store, const cbm_node_t *node) {
4419+
if (!node->file_path || !node->file_path[0] || !node->project) {
4420+
return;
4421+
}
4422+
cbm_coverage_row_t *rows = NULL;
4423+
int count = 0;
4424+
if (cbm_store_coverage_get(store, node->project, &rows, &count) != CBM_STORE_OK) {
4425+
return;
4426+
}
4427+
for (int i = 0; i < count; i++) {
4428+
if (rows[i].rel_path && strcmp(rows[i].rel_path, node->file_path) == 0 && rows[i].kind &&
4429+
strcmp(rows[i].kind, "parse_partial") == 0) {
4430+
char note[CBM_SZ_1K];
4431+
snprintf(note, sizeof(note),
4432+
"This file was only PARTIALLY indexed — line range(s) %s could not be "
4433+
"parsed, so constructs there may be missing from the graph (callers/callees "
4434+
"and search results can under-report this file). The source above is ground "
4435+
"truth. (best-effort signal)",
4436+
rows[i].detail && rows[i].detail[0] ? rows[i].detail : "?");
4437+
yyjson_mut_obj_add_strcpy(doc, root_obj, "coverage_note", note);
4438+
break;
4439+
}
4440+
}
4441+
cbm_store_free_coverage(rows, count);
4442+
}
4443+
44304444
static char *build_snippet_response(cbm_mcp_server_t *srv, cbm_node_t *node,
44314445
const char *match_method, bool include_neighbors,
44324446
cbm_node_t *alternatives, int alt_count) {
@@ -4484,6 +4498,8 @@ static char *build_snippet_response(cbm_mcp_server_t *srv, cbm_node_t *node,
44844498
yyjson_mut_obj_add_int(doc, root_obj, "callers", in_deg);
44854499
yyjson_mut_obj_add_int(doc, root_obj, "callees", out_deg);
44864500

4501+
add_snippet_coverage_note(doc, root_obj, store, node);
4502+
44874503
char **nb_callers = NULL;
44884504
int nb_caller_count = 0;
44894505
char **nb_callees = NULL;
@@ -5978,9 +5994,6 @@ char *cbm_mcp_handle_tool(cbm_mcp_server_t *srv, const char *tool_name, const ch
59785994
if (strcmp(tool_name, "query_graph") == 0) {
59795995
return handle_query_graph(srv, args_json);
59805996
}
5981-
if (strcmp(tool_name, "get_index_coverage") == 0) {
5982-
return handle_get_index_coverage(srv, args_json);
5983-
}
59845997
if (strcmp(tool_name, "index_status") == 0) {
59855998
return handle_index_status(srv, args_json);
59865999
}

‎tests/test_index_resilience.c‎

Lines changed: 21 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -364,7 +364,7 @@ TEST(index_parse_partial_reported) {
364364
free(logtext);
365365

366366
/* The signal is persisted in the SEPARATE index_coverage table (never
367-
* mixed into the graph tables) and queryable via get_index_coverage,
367+
* mixed into the graph tables) and reported by index_status,
368368
* exactly as the index_repository tool description advertises. */
369369
cbm_coverage_row_t *rows = NULL;
370370
int cov_count = 0;
@@ -384,12 +384,28 @@ TEST(index_parse_partial_reported) {
384384

385385
char qargs[900];
386386
snprintf(qargs, sizeof(qargs), "{\"project\":\"%s\"}", lp.project);
387-
char *qresp = cbm_mcp_handle_tool(lp.srv, "get_index_coverage", qargs);
387+
char *qresp = cbm_mcp_handle_tool(lp.srv, "index_status", qargs);
388388
ASSERT_NOT_NULL(qresp);
389389
ASSERT_NOT_NULL(strstr(qresp, "split.c"));
390390
ASSERT_NOT_NULL(strstr(qresp, "parse_partial"));
391391
free(qresp);
392392

393+
/* get_code_snippet on a symbol from the flagged file carries the
394+
* correlated coverage note (the result names its file, so the warning is
395+
* precisely anchored); the note never fires for clean files. */
396+
snprintf(qargs, sizeof(qargs), "{\"project\":\"%s\",\"qualified_name\":\"ok_before\"}",
397+
lp.project);
398+
char *sresp = cbm_mcp_handle_tool(lp.srv, "get_code_snippet", qargs);
399+
ASSERT_NOT_NULL(sresp);
400+
ASSERT_NOT_NULL(strstr(sresp, "coverage_note"));
401+
ASSERT_NOT_NULL(strstr(sresp, "PARTIALLY indexed"));
402+
free(sresp);
403+
snprintf(qargs, sizeof(qargs), "{\"project\":\"%s\",\"qualified_name\":\"alpha\"}", lp.project);
404+
char *cresp2 = cbm_mcp_handle_tool(lp.srv, "get_code_snippet", qargs);
405+
ASSERT_NOT_NULL(cresp2);
406+
ASSERT_NULL(strstr(cresp2, "coverage_note")); /* good.py: no note */
407+
free(cresp2);
408+
393409
/* The missed GRAPH: the same signal is queryable as a file-structure
394410
* graph via query_graph(graph="missed") — exactly the query the tool
395411
* description advertises — and it lives under the shadow project, so the
@@ -424,7 +440,7 @@ TEST(index_parse_partial_reported) {
424440
/* INV(parse-partial-clears-on-fix, #963): the persisted coverage signal must
425441
* stay FRESH — after the broken file is fixed and the project re-indexed
426442
* (incremental route: the DB already exists), its parse_partial row is gone
427-
* and get_index_coverage reports it no longer. A stale flag on a fixed file
443+
* and index_status reports it no longer. A stale flag on a fixed file
428444
* would make the whole signal untrustworthy. */
429445
TEST(index_parse_partial_clears_on_fix) {
430446
RProj lp;
@@ -464,7 +480,7 @@ TEST(index_parse_partial_clears_on_fix) {
464480
/* Flagged after the first (full) index. */
465481
char qargs[900];
466482
snprintf(qargs, sizeof(qargs), "{\"project\":\"%s\"}", lp.project);
467-
char *cov1 = cbm_mcp_handle_tool(lp.srv, "get_index_coverage", qargs);
483+
char *cov1 = cbm_mcp_handle_tool(lp.srv, "index_status", qargs);
468484
ASSERT_NOT_NULL(cov1);
469485
ASSERT_NOT_NULL(strstr(cov1, "flaky.c"));
470486
free(cov1);
@@ -485,7 +501,7 @@ TEST(index_parse_partial_clears_on_fix) {
485501
ASSERT_NOT_NULL(resp2);
486502
free(resp2);
487503

488-
char *cov2 = cbm_mcp_handle_tool(lp.srv, "get_index_coverage", qargs);
504+
char *cov2 = cbm_mcp_handle_tool(lp.srv, "index_status", qargs);
489505
ASSERT_NOT_NULL(cov2);
490506
ASSERT_NULL(strstr(cov2, "flaky.c"));
491507
free(cov2);

0 commit comments

Comments
 (0)