@@ -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+
21812243static 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). */
23062288static 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+
44304444static 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 }
0 commit comments