@@ -316,7 +316,14 @@ static const tool_def_t TOOLS[] = {
316316 "Index a repository into the knowledge graph. "
317317 "Special mode 'cross-repo-intelligence': skip extraction, only match Routes/Channels "
318318 "across projects to create CROSS_HTTP_CALLS/CROSS_ASYNC_CALLS/CROSS_CHANNEL edges. "
319- "Requires target_projects param. Ensure target projects have fresh indexes first." ,
319+ "Requires target_projects param. Ensure target projects have fresh indexes first. "
320+ "COVERAGE: the response reports files that were NOT fully indexed — 'skipped' (not "
321+ "indexed at all: oversized/read/parse failures) and 'parse_partial' (indexed, but "
322+ "constructs inside the listed line ranges could not be parsed and are absent from the "
323+ "graph). parse_partial files also carry {parse_incomplete:true, error_ranges} on their "
324+ "File node — query later via query_graph: MATCH (f:File) WHERE f.parse_incomplete = true "
325+ "RETURN f. Both signals are best-effort: absence of a flag is NOT a completeness "
326+ "guarantee; prefer grep inside flagged ranges." ,
320327 "{\"type\":\"object\",\"properties\":{\"repo_path\":{\"type\":\"string\",\"description\":"
321328 "\"Path to the repository\"},"
322329 "\"mode\":{\"type\":\"string\","
@@ -3299,36 +3306,100 @@ static void add_excluded_summary(yyjson_mut_doc *doc, yyjson_mut_val *root, char
32993306 * the JSON carries "count" + "truncated" so nothing is silently hidden. */
33003307enum { INDEX_SKIPPED_FILE_CAP = 50 };
33013308
3309+ /* True when a recorded per-file entry is the parse-partial coverage signal
3310+ * (#963) rather than a genuine skip. Kept out of skipped[]/skipped_count so
3311+ * the "skipped" contract (file NOT indexed) stays exact. */
3312+ static bool is_parse_partial (const cbm_file_error_t * e ) {
3313+ return e -> phase && strcmp (e -> phase , "parse_partial" ) == 0 ;
3314+ }
3315+
33023316/* Attach a summary of per-file skips (Stage 2 / Track B). Always emits a
33033317 * top-level "skipped_count" (0 on clean runs) so consumers can rely on it.
33043318 * When there are skips, also emits:
33053319 * "skipped": {"files":[{path,reason,phase}..(<=50)], "count":N, "truncated":bool}
33063320 * and, if a per-run logfile was written, "logfile": "<path>".
33073321 * The run status stays "indexed" — a skipped file is the expected handled
3308- * outcome, not a failure. errs[] is borrowed (copied into doc). */
3322+ * outcome, not a failure. errs[] is borrowed (copied into doc) and may contain
3323+ * parse_partial entries, which are filtered out here (reported separately by
3324+ * add_parse_partial_summary). */
33093325static void add_skipped_summary (yyjson_mut_doc * doc , yyjson_mut_val * root ,
33103326 const cbm_file_error_t * errs , int count , const char * logfile ) {
3311- yyjson_mut_obj_add_int (doc , root , "skipped_count" , count < 0 ? 0 : count );
3312- if (!errs || count <= 0 ) {
3327+ int skips = 0 ;
3328+ for (int i = 0 ; i < count ; i ++ ) {
3329+ if (!is_parse_partial (& errs [i ])) {
3330+ skips ++ ;
3331+ }
3332+ }
3333+ yyjson_mut_obj_add_int (doc , root , "skipped_count" , skips );
3334+ if (logfile && logfile [0 ]) {
3335+ yyjson_mut_obj_add_strcpy (doc , root , "logfile" , logfile );
3336+ }
3337+ if (!errs || skips <= 0 ) {
33133338 return ;
33143339 }
33153340 yyjson_mut_val * skipped = yyjson_mut_obj (doc );
33163341 yyjson_mut_val * files = yyjson_mut_arr (doc );
3317- int shown = count < INDEX_SKIPPED_FILE_CAP ? count : INDEX_SKIPPED_FILE_CAP ;
3318- for (int i = 0 ; i < shown ; i ++ ) {
3342+ int shown = 0 ;
3343+ for (int i = 0 ; i < count && shown < INDEX_SKIPPED_FILE_CAP ; i ++ ) {
3344+ if (is_parse_partial (& errs [i ])) {
3345+ continue ;
3346+ }
33193347 yyjson_mut_val * fe = yyjson_mut_obj (doc );
33203348 yyjson_mut_obj_add_strcpy (doc , fe , "path" , errs [i ].path ? errs [i ].path : "" );
33213349 yyjson_mut_obj_add_strcpy (doc , fe , "reason" , errs [i ].reason ? errs [i ].reason : "" );
33223350 yyjson_mut_obj_add_strcpy (doc , fe , "phase" , errs [i ].phase ? errs [i ].phase : "" );
33233351 yyjson_mut_arr_add_val (files , fe );
3352+ shown ++ ;
33243353 }
33253354 yyjson_mut_obj_add_val (doc , skipped , "files" , files );
3326- yyjson_mut_obj_add_int (doc , skipped , "count" , count );
3327- yyjson_mut_obj_add_bool (doc , skipped , "truncated" , count > INDEX_SKIPPED_FILE_CAP );
3355+ yyjson_mut_obj_add_int (doc , skipped , "count" , skips );
3356+ yyjson_mut_obj_add_bool (doc , skipped , "truncated" , skips > INDEX_SKIPPED_FILE_CAP );
33283357 yyjson_mut_obj_add_val (doc , root , "skipped" , skipped );
3329- if (logfile && logfile [0 ]) {
3330- yyjson_mut_obj_add_strcpy (doc , root , "logfile" , logfile );
3358+ }
3359+
3360+ /* Attach the best-effort parse-coverage summary (#963). Always emits a
3361+ * top-level "parse_partial_count" (0 on clean runs). When files were flagged:
3362+ * "parse_partial": {"files":[{path,error_ranges}..(<=50)], "count":N,
3363+ * "truncated":bool, "note":"..."}
3364+ * These files WERE indexed — constructs inside the listed 1-based line ranges
3365+ * are missing from the graph because tree-sitter could not parse them. The
3366+ * note spells out the best-effort framing: absence from this list is NOT a
3367+ * completeness guarantee. */
3368+ static void add_parse_partial_summary (yyjson_mut_doc * doc , yyjson_mut_val * root ,
3369+ const cbm_file_error_t * errs , int count ) {
3370+ int partials = 0 ;
3371+ for (int i = 0 ; i < count ; i ++ ) {
3372+ if (is_parse_partial (& errs [i ])) {
3373+ partials ++ ;
3374+ }
3375+ }
3376+ yyjson_mut_obj_add_int (doc , root , "parse_partial_count" , partials );
3377+ if (!errs || partials <= 0 ) {
3378+ return ;
33313379 }
3380+ yyjson_mut_val * pp = yyjson_mut_obj (doc );
3381+ yyjson_mut_val * files = yyjson_mut_arr (doc );
3382+ int shown = 0 ;
3383+ for (int i = 0 ; i < count && shown < INDEX_SKIPPED_FILE_CAP ; i ++ ) {
3384+ if (!is_parse_partial (& errs [i ])) {
3385+ continue ;
3386+ }
3387+ yyjson_mut_val * fe = yyjson_mut_obj (doc );
3388+ yyjson_mut_obj_add_strcpy (doc , fe , "path" , errs [i ].path ? errs [i ].path : "" );
3389+ yyjson_mut_obj_add_strcpy (doc , fe , "error_ranges" , errs [i ].reason ? errs [i ].reason : "" );
3390+ yyjson_mut_arr_add_val (files , fe );
3391+ shown ++ ;
3392+ }
3393+ yyjson_mut_obj_add_val (doc , pp , "files" , files );
3394+ yyjson_mut_obj_add_int (doc , pp , "count" , partials );
3395+ yyjson_mut_obj_add_bool (doc , pp , "truncated" , partials > INDEX_SKIPPED_FILE_CAP );
3396+ yyjson_mut_obj_add_str (doc , pp , "note" ,
3397+ "Best-effort signal, not a completeness guarantee: these files WERE "
3398+ "indexed, but constructs inside the listed line ranges (1-based) could "
3399+ "not be parsed and are missing from the graph. Prefer text search "
3400+ "(grep) for those regions. Files absent from this list are NOT "
3401+ "guaranteed to be fully indexed." );
3402+ yyjson_mut_obj_add_val (doc , root , "parse_partial" , pp );
33323403}
33333404
33343405/* Write the FULL (uncapped) skip list to a per-run logfile — ONLY when >=1 file
@@ -3360,8 +3431,15 @@ static bool write_skip_logfile(const char *project, const cbm_file_error_t *errs
33603431 cbm_log_warn ("index.logfile_open_fail" , "path" , path );
33613432 return false;
33623433 }
3363- (void )fprintf (f , "# codebase-memory-mcp index skip report\n" );
3364- (void )fprintf (f , "# project=%s skipped=%d\n" , project ? project : "" , count );
3434+ int partials = 0 ;
3435+ for (int i = 0 ; i < count ; i ++ ) {
3436+ if (is_parse_partial (& errs [i ])) {
3437+ partials ++ ;
3438+ }
3439+ }
3440+ (void )fprintf (f , "# codebase-memory-mcp index coverage report\n" );
3441+ (void )fprintf (f , "# project=%s skipped=%d parse_partial=%d\n" , project ? project : "" ,
3442+ count - partials , partials );
33653443 (void )fprintf (f , "# columns: phase\treason\tpath\n" );
33663444 for (int i = 0 ; i < count ; i ++ ) {
33673445 (void )fprintf (f , "%s\t%s\t%s\n" , errs [i ].phase ? errs [i ].phase : "" ,
@@ -3384,6 +3462,7 @@ static bool build_index_success_response(cbm_mcp_server_t *srv, yyjson_mut_doc *
33843462 const char * logfile ) {
33853463 add_excluded_summary (doc , root , excluded_dirs , excluded_count );
33863464 add_skipped_summary (doc , root , file_errors , file_error_count , logfile );
3465+ add_parse_partial_summary (doc , root , file_errors , file_error_count );
33873466
33883467 int exp_nodes = -1 ;
33893468 int exp_edges = -1 ;
0 commit comments