Skip to content

Local code intelligence for developers and AI agents. Connect code, docs and infrastructure in a persistent graph, with CBM Lens, MCP tools, agent integrations and change-aware test selection.

chore(pipeline): merge upstream document coverage changes

Pcristin40179b39f36a
diff --cc src/pipeline/pass_parallel.c
index f3d1836eb,950d74573..592889df3
--- a/src/pipeline/pass_parallel.c
+++ b/src/pipeline/pass_parallel.c
@@@ -4281,12 -4250,13 +4299,18 @@@ static void resolve_worker(int worker_i
atomic_fetch_add_explicit(&rc->time_ns_semantic, extract_now_ns() - _ph_t0,
memory_order_relaxed);
+ /* ── MENTIONS (doc-comment references) ─────────────────── */
+ if (rc->pctx && rc->pctx->doc_links) {
+ cbm_doclinks_resolve_file(rc->pctx->doc_links, file_idx, result, rc->main_gbuf,
+ ws->local_edge_buf);
+ }
+
resolve_file_cleanup:
+ /* Capture the resolved file and side evidence before releasing either,
+ * including files loaded from the spill store. */
+ resolve_capture_coverage(rc, rel, result, evidence);
+ cbm_free(CBM_MEM_CLASS_RESOLVE, evidence);
+
cbm_registry_reach_cache_end();
cbm_registry_import_map_cache_end();
cbm_registry_resolve_cache_end();
diff --cc src/pipeline/pipeline.c
index 1c7b7c776,2d66a6c7e..0747a8bea
--- a/src/pipeline/pipeline.c
+++ b/src/pipeline/pipeline.c
@@@ -19,8 -19,8 +19,9 @@@ enum { CBM_DIR_PERMS = 0755, PL_RING =
#include "pipeline/pipeline.h"
#include "pipeline/artifact.h"
#include "pipeline/pipeline_internal.h"
+ #include "pipeline/doc_links.h"
#include "pipeline/lsp_surface.h"
+#include "pipeline/lsp_resolve.h"
#include "pipeline/pass_lsp_cross.h"
#include "pipeline/pass_ensemble_routing.h"
#include "pipeline/worker_pool.h"
@@@ -273,13 -267,18 +274,25 @@@ struct cbm_pipeline
cbm_lsp_surface_row_t *surface_rows;
int surface_row_count;
+ /* Per-file unresolved invocation diagnostics, published as coverage rows. */
+ cbm_coverage_row_t *unresolved_rows;
+ int unresolved_count;
+ int unresolved_capacity;
+ atomic_bool unresolved_capture_failed;
+ cbm_mutex_t unresolved_mutex; /* one append per file, after parallel resolution */
+
+ /* This run's doc_link_unresolved rows (doc_links.h), handed over by the
+ * resolve phase; doc_links_ran stays false until a doc-link phase did. */
+ cbm_doc_link_row_t *doc_link_rows;
+ int doc_link_row_count;
+ bool doc_links_failed;
+ bool doc_links_ran;
+ /* Doc -> code candidates from pass_semantic_edges, published with the
+ * generation (heap rows, cbm_store_doc_candidates_free in
+ * cbm_pipeline_free). NULL when the pass found none or did not run. */
+ cbm_doc_candidate_t *doc_candidates;
+ int doc_candidate_count;
+
/* Deterministic test-only seam at the final publication boundary. Kept
* per pipeline so concurrent test/process activity cannot cross-trigger. */
void (*before_publish_hook)(cbm_pipeline_t *, const char *, void *);
@@@ -925,392 -920,23 +938,409 @@@ void cbm_pipeline_set_lsp_surfaces(cbm_
p->surface_row_count = count;
}
+static void *unresolved_json_alloc(void *ctx, size_t size) {
+ (void)ctx;
+ return cbm_alloc(CBM_MEM_CLASS_RESOLVE, size);
+}
+
+static void *unresolved_json_realloc(void *ctx, void *ptr, size_t old_size, size_t size) {
+ (void)ctx;
+ (void)old_size;
+ return cbm_realloc(CBM_MEM_CLASS_RESOLVE, ptr, size);
+}
+
+static void unresolved_json_free(void *ctx, void *ptr) {
+ (void)ctx;
+ cbm_free(CBM_MEM_CLASS_RESOLVE, ptr);
+}
+
+enum {
+ UNRESOLVED_KEY_OVERHEAD = 128,
+ UNRESOLVED_INITIAL_ROWS = 64,
+ UNRESOLVED_ROW_GROWTH = 2,
+ UNRESOLVED_MAX_SITES = 1000,
+ UNRESOLVED_MAX_JSON_BYTES = 128 * 1024,
+ UNRESOLVED_SITE_OVERHEAD = 256,
+ UNRESOLVED_TRUNCATION_RESERVE = 32,
+ UNRESOLVED_JSON_ARRAY_BYTES = 2,
+ UNRESOLVED_JSON_RAW_CHAR_BYTES = 1,
+ UNRESOLVED_JSON_ESCAPE_BYTES = 2,
+ UNRESOLVED_JSON_CONTROL_ESCAPE_BYTES = 6,
+ UNRESOLVED_JSON_CONTROL_BOUNDARY = 0x20,
+ UNRESOLVED_JSON_OVERSIZE = UNRESOLVED_MAX_JSON_BYTES + 1,
+ UNRESOLVED_NO_CARRIER = -1,
+ UNRESOLVED_AMBIGUOUS_CARRIER = -2
+};
+
+static char *unresolved_site_key(const char *caller, const char *leaf, uint32_t start, uint32_t end,
+ CBMSourceOrigin origin) {
+ size_t cn = strlen(caller);
+ size_t ln = strlen(leaf);
+ size_t cap = cn + ln + UNRESOLVED_KEY_OVERHEAD;
+ char *key = cbm_alloc(CBM_MEM_CLASS_RESOLVE, cap);
+ if (key) {
+ (void)snprintf(key, cap, "%zu:%s|%zu:%s|%u:%u:%u", cn, caller, ln, leaf, start, end,
+ (unsigned)origin);
+ }
+ return key;
+}
+
+typedef struct {
+ int call_index;
+} unresolved_carrier_t;
+
+typedef struct {
+ yyjson_mut_doc *doc;
+ yyjson_mut_val *sites;
+ CBMHashTable *carriers;
+ CBMHashTable *seen;
+ const CBMFileResult *result;
+ const CBMCallEvidence *evidence;
+ const CBMResolvedCall *selected[UNRESOLVED_MAX_SITES];
+ int selected_count;
+ size_t json_bytes;
+ bool truncated;
+} unresolved_capture_t;
+
+static void unresolved_carrier_free(const char *key, void *value, void *ctx) {
+ (void)ctx;
+ cbm_free(CBM_MEM_CLASS_RESOLVE, (void *)key);
+ cbm_free(CBM_MEM_CLASS_RESOLVE, value);
+}
+
+static void unresolved_key_free(const char *key, void *value, void *ctx) {
+ (void)value;
+ (void)ctx;
+ cbm_free(CBM_MEM_CLASS_RESOLVE, (void *)key);
+}
+
+static void unresolved_capture_free(unresolved_capture_t *capture) {
+ if (capture->carriers) {
+ cbm_ht_foreach(capture->carriers, unresolved_carrier_free, NULL);
+ cbm_ht_free(capture->carriers);
+ }
+ if (capture->seen) {
+ cbm_ht_foreach(capture->seen, unresolved_key_free, NULL);
+ cbm_ht_free(capture->seen);
+ }
+ if (capture->doc) {
+ yyjson_mut_doc_free(capture->doc);
+ }
+}
+
+static bool unresolved_call_is_missing(const CBMResolvedCall *rc) {
+ return rc->kind == CBM_RESOLVED_INVOCATION && rc->strategy &&
+ strcmp(rc->strategy, "lsp_unresolved") == 0 && rc->caller_qn && rc->callee_qn;
+}
+
+static bool unresolved_has_missing_calls(const CBMFileResult *result) {
+ for (int i = 0; i < result->resolved_calls.count; i++) {
+ if (unresolved_call_is_missing(&result->resolved_calls.items[i])) {
+ return true;
+ }
+ }
+ return false;
+}
+
+static size_t unresolved_json_char_bytes(unsigned char ch) {
+ if (ch < UNRESOLVED_JSON_CONTROL_BOUNDARY) {
+ return UNRESOLVED_JSON_CONTROL_ESCAPE_BYTES;
+ }
+ if (ch == '"' || ch == '\\') {
+ return UNRESOLVED_JSON_ESCAPE_BYTES;
+ }
+ return UNRESOLVED_JSON_RAW_CHAR_BYTES;
+}
+
+/* Stop at the budget even for one enormous string. Reserve six bytes for each
+ * escaped control character; quotes and backslashes use two bytes in JSON. */
+static size_t unresolved_string_json_bytes(const char *text) {
+ size_t bytes = 0;
+ for (const unsigned char *p = (const unsigned char *)text; p && *p; p++) {
+ size_t width = unresolved_json_char_bytes(*p);
+ if (bytes > UNRESOLVED_MAX_JSON_BYTES - width) {
+ return UNRESOLVED_JSON_OVERSIZE;
+ }
+ bytes += width;
+ }
+ return bytes;
+}
+
+static size_t unresolved_site_json_bytes(const CBMResolvedCall *rc, const char *caller,
+ const char *leaf, const char *candidate) {
+ const char *fields[] = {caller, leaf, rc->reason ? rc->reason : "unresolved", candidate};
+ size_t bytes = UNRESOLVED_SITE_OVERHEAD;
+ for (size_t i = 0; i < sizeof(fields) / sizeof(fields[0]); i++) {
+ size_t field_bytes = unresolved_string_json_bytes(fields[i]);
+ if (field_bytes > UNRESOLVED_MAX_JSON_BYTES - bytes) {
+ return UNRESOLVED_JSON_OVERSIZE;
+ }
+ bytes += field_bytes;
+ }
+ return bytes;
+}
+
+/* Hash only the bounded diagnostic subset. Hashing every extracted call
+ * would retain unbounded side state. */
+static bool unresolved_select_diagnostics(unresolved_capture_t *capture) {
+ size_t selected_bytes = UNRESOLVED_JSON_ARRAY_BYTES + UNRESOLVED_TRUNCATION_RESERVE;
+ const CBMFileResult *result = capture->result;
+ for (int i = 0; i < result->resolved_calls.count; i++) {
+ const CBMResolvedCall *rc = &result->resolved_calls.items[i];
+ if (!unresolved_call_is_missing(rc)) {
+ continue;
+ }
+ const char *leaf = cbm_lsp_bare_segment(rc->callee_qn);
+ size_t site_bytes = unresolved_site_json_bytes(rc, rc->caller_qn, leaf, NULL);
+ if (capture->selected_count == UNRESOLVED_MAX_SITES ||
+ site_bytes > UNRESOLVED_MAX_JSON_BYTES - selected_bytes) {
+ capture->truncated = true;
+ break;
+ }
+ selected_bytes += site_bytes;
+ capture->selected[capture->selected_count++] = rc;
+ char *key = unresolved_site_key("", leaf, rc->site_start_byte, rc->site_end_byte,
+ rc->source_origin);
+ if (!key) {
+ return false;
+ }
+ if (cbm_ht_has(capture->carriers, key)) {
+ cbm_free(CBM_MEM_CLASS_RESOLVE, key);
+ continue;
+ }
+ unresolved_carrier_t *carrier = cbm_alloc(CBM_MEM_CLASS_RESOLVE, sizeof(*carrier));
+ if (!carrier) {
+ cbm_free(CBM_MEM_CLASS_RESOLVE, key);
+ return false;
+ }
+ carrier->call_index = UNRESOLVED_NO_CARRIER;
+ cbm_ht_set(capture->carriers, key, carrier);
+ if (!cbm_ht_has(capture->carriers, key)) {
+ cbm_free(CBM_MEM_CLASS_RESOLVE, key);
+ cbm_free(CBM_MEM_CLASS_RESOLVE, carrier);
+ return false;
+ }
+ }
+ return true;
+}
+
+static bool unresolved_build_carriers(unresolved_capture_t *capture) {
+ if (!unresolved_select_diagnostics(capture)) {
+ return false;
+ }
+ const CBMFileResult *result = capture->result;
+ /* Caller names in the TS LSP walk can denote an outer factory. Join on
+ * span, leaf and origin; the extractor owns the enclosing function name. */
+ for (int i = 0; i < result->calls.count && capture->selected_count > 0; i++) {
+ const CBMCall *call = &result->calls.items[i];
+ if (!call->callee_name || call->site_end_byte <= call->site_start_byte) {
+ continue;
+ }
+ const char *leaf = cbm_lsp_bare_segment(call->callee_name);
+ if (unresolved_string_json_bytes(leaf) > UNRESOLVED_MAX_JSON_BYTES) {
+ continue; /* No bounded diagnostic key can match this leaf. */
+ }
+ char *key = unresolved_site_key("", leaf, call->site_start_byte, call->site_end_byte,
+ call->source_origin);
+ if (!key) {
+ return false;
+ }
+ unresolved_carrier_t *carrier = cbm_ht_get(capture->carriers, key);
+ cbm_free(CBM_MEM_CLASS_RESOLVE, key);
+ if (carrier) {
+ /* An ambiguous occurrence must never erase a diagnostic. */
+ carrier->call_index =
+ carrier->call_index == UNRESOLVED_NO_CARRIER ? i : UNRESOLVED_AMBIGUOUS_CARRIER;
+ }
+ }
+ return true;
+}
+
+static bool unresolved_append_site(unresolved_capture_t *capture, const CBMResolvedCall *rc,
+ const CBMCall *call, const CBMCallEvidence *evidence,
+ const char *caller, const char *leaf) {
+ const char *candidate = evidence ? evidence->candidate_qn : NULL;
+ size_t site_bytes = unresolved_site_json_bytes(rc, caller, leaf, candidate);
+ if (site_bytes > UNRESOLVED_MAX_JSON_BYTES - capture->json_bytes) {
+ capture->truncated = true;
+ return true;
+ }
+ yyjson_mut_doc *doc = capture->doc;
+ yyjson_mut_val *site = yyjson_mut_obj(doc);
+ bool ok =
+ site && yyjson_mut_obj_add_strcpy(doc, site, "caller", caller) &&
+ yyjson_mut_obj_add_strcpy(doc, site, "leaf", leaf) &&
+ yyjson_mut_obj_add_uint(doc, site, "start_byte", rc->site_start_byte) &&
+ yyjson_mut_obj_add_uint(doc, site, "end_byte", rc->site_end_byte) &&
+ yyjson_mut_obj_add_uint(doc, site, "source_origin", rc->source_origin) &&
+ yyjson_mut_obj_add_strcpy(doc, site, "reason", rc->reason ? rc->reason : "unresolved");
+ if (ok && call && call->start_line > 0) {
+ ok = yyjson_mut_obj_add_int(doc, site, "line", call->start_line);
+ }
+ if (ok && candidate) {
+ ok = yyjson_mut_obj_add_strcpy(doc, site, "candidate", candidate);
+ }
+ capture->json_bytes += site_bytes;
+ return ok && yyjson_mut_arr_add_val(capture->sites, site);
+}
+
+static bool unresolved_collect_site(unresolved_capture_t *capture, const CBMResolvedCall *rc) {
+ const char *leaf = cbm_lsp_bare_segment(rc->callee_qn);
+ char *lookup =
+ unresolved_site_key("", leaf, rc->site_start_byte, rc->site_end_byte, rc->source_origin);
+ if (!lookup) {
+ return false;
+ }
+ const unresolved_carrier_t *carrier = cbm_ht_get(capture->carriers, lookup);
+ int call_index = carrier ? carrier->call_index : UNRESOLVED_NO_CARRIER;
+ const CBMCall *call = call_index >= 0 ? &capture->result->calls.items[call_index] : NULL;
+ const CBMCallEvidence *evidence =
+ call_index >= 0 && capture->evidence ? &capture->evidence[call_index] : NULL;
+ cbm_free(CBM_MEM_CLASS_RESOLVE, lookup);
+ /* Suppress only this exact occurrence's real CALLS edge, including dedup.
+ * HTTP/ASYNC/CONFIGURES/SPAWNS and a candidate alone never suppress it. */
+ if (evidence && evidence->calls_emitted) {
+ return true;
+ }
+ const char *caller = call && call->enclosing_func_qn ? call->enclosing_func_qn : rc->caller_qn;
+ /* Bound both the retained dedup key and copied JSON strings. */
+ size_t site_bytes =
+ unresolved_site_json_bytes(rc, caller, leaf, evidence ? evidence->candidate_qn : NULL);
+ if (site_bytes > UNRESOLVED_MAX_JSON_BYTES - capture->json_bytes) {
+ capture->truncated = true;
+ return true;
+ }
+ char *key = unresolved_site_key(caller, leaf, rc->site_start_byte, rc->site_end_byte,
+ rc->source_origin);
+ if (!key) {
+ return false;
+ }
+ if (cbm_ht_has(capture->seen, key)) {
+ cbm_free(CBM_MEM_CLASS_RESOLVE, key);
+ return true;
+ }
+ cbm_ht_set(capture->seen, key, key);
+ if (!cbm_ht_has(capture->seen, key)) {
+ cbm_free(CBM_MEM_CLASS_RESOLVE, key);
+ return false;
+ }
+ return unresolved_append_site(capture, rc, call, evidence, caller, leaf);
+}
+
+static bool unresolved_collect_sites(unresolved_capture_t *capture) {
+ for (int i = 0; i < capture->selected_count; i++) {
+ if (!unresolved_collect_site(capture, capture->selected[i])) {
+ return false;
+ }
+ }
+ if (capture->truncated) {
+ yyjson_mut_val *marker = yyjson_mut_obj(capture->doc);
+ return marker && yyjson_mut_obj_add_bool(capture->doc, marker, "truncated", true) &&
+ yyjson_mut_arr_add_val(capture->sites, marker);
+ }
+ return true;
+}
+
+/* Caller holds unresolved_mutex. Ownership transfers only on success. */
+static bool unresolved_append_row(cbm_pipeline_t *p, const char *path, const char *detail) {
+ if (!detail || !path || p->unresolved_capture_failed) {
+ return false;
+ }
+ if (p->unresolved_count == p->unresolved_capacity) {
+ int capacity = p->unresolved_capacity ? p->unresolved_capacity * UNRESOLVED_ROW_GROWTH
+ : UNRESOLVED_INITIAL_ROWS;
+ cbm_coverage_row_t *rows = cbm_realloc(CBM_MEM_CLASS_RESOLVE, p->unresolved_rows,
+ (size_t)capacity * sizeof(*rows));
+ if (!rows) {
+ return false;
+ }
+ p->unresolved_rows = rows;
+ p->unresolved_capacity = capacity;
+ }
+ p->unresolved_rows[p->unresolved_count++] =
+ (cbm_coverage_row_t){.rel_path = path, .kind = "unresolved_calls", .detail = detail};
+ return true;
+}
+
+void cbm_pipeline_record_unresolved_calls(cbm_pipeline_t *p, const char *rel_path,
+ const CBMFileResult *result,
+ const CBMCallEvidence *evidence) {
+ if (!p || !rel_path || !result || p->unresolved_capture_failed) {
+ return;
+ }
+ if (!unresolved_has_missing_calls(result)) {
+ return;
+ }
+ yyjson_alc allocator = {.malloc = unresolved_json_alloc,
+ .realloc = unresolved_json_realloc,
+ .free = unresolved_json_free};
+ unresolved_capture_t capture = {.doc = yyjson_mut_doc_new(&allocator),
+ .carriers = cbm_ht_create_in(CBM_MEM_CLASS_RESOLVE, 0),
+ .seen = cbm_ht_create_in(CBM_MEM_CLASS_RESOLVE, 0),
+ .result = result,
+ .evidence = evidence,
+ .json_bytes = UNRESOLVED_JSON_ARRAY_BYTES +
+ UNRESOLVED_TRUNCATION_RESERVE};
+ capture.sites = capture.doc ? yyjson_mut_arr(capture.doc) : NULL;
+ bool ok = capture.doc && capture.carriers && capture.seen && capture.sites;
+ if (capture.doc) {
+ yyjson_mut_doc_set_root(capture.doc, capture.sites);
+ }
+ ok = ok && unresolved_build_carriers(&capture) && unresolved_collect_sites(&capture);
+ if (ok && yyjson_mut_arr_size(capture.sites) > 0) {
+ char *detail = yyjson_mut_write_opts(capture.doc, 0, &allocator, NULL, NULL);
+ char *path = cbm_mem_strdup(CBM_MEM_CLASS_RESOLVE, rel_path);
+ /* The estimate reserves overhead and escaping. Enforce the serialized
+ * limit as well, before any detail is transferred to persistence. */
+ ok = detail && strlen(detail) <= UNRESOLVED_MAX_JSON_BYTES;
+ if (ok) {
+ cbm_mutex_lock(&p->unresolved_mutex);
+ ok = unresolved_append_row(p, path, detail);
+ cbm_mutex_unlock(&p->unresolved_mutex);
+ }
+ if (!ok) {
+ cbm_free(CBM_MEM_CLASS_RESOLVE, detail);
+ cbm_free(CBM_MEM_CLASS_RESOLVE, path);
+ }
+ }
+ if (!ok) {
+ p->unresolved_capture_failed = true;
+ }
+ unresolved_capture_free(&capture);
+}
+
+void cbm_pipeline_mark_unresolved_capture_failed(cbm_pipeline_t *p) {
+ if (p)
+ p->unresolved_capture_failed = true;
+}
+
+void cbm_pipeline_get_unresolved_calls(cbm_pipeline_t *p, cbm_coverage_row_t **rows, int *count,
+ bool *complete) {
+ if (rows)
+ *rows = p ? p->unresolved_rows : NULL;
+ if (count)
+ *count = p ? p->unresolved_count : 0;
+ if (complete)
+ *complete = p && !p->unresolved_capture_failed;
+}
+
+ void cbm_pipeline_set_doc_candidates(cbm_pipeline_t *p, cbm_doc_candidate_t *rows, int count) {
+ if (!p) {
+ cbm_store_doc_candidates_free(rows, count);
+ return;
+ }
+ cbm_store_doc_candidates_free(p->doc_candidates, p->doc_candidate_count);
+ p->doc_candidates = rows;
+ p->doc_candidate_count = rows ? count : 0;
+ }
+
+ const cbm_doc_candidate_t *cbm_pipeline_doc_candidates(const cbm_pipeline_t *p, int *count) {
+ if (count) {
+ *count = p ? p->doc_candidate_count : 0;
+ }
+ return p ? p->doc_candidates : NULL;
+ }
+
static void pipeline_release_test_config(cbm_pipeline_t *p) {
if (!p) {
return;
@@@ -1354,12 -1016,10 +1420,17 @@@ void cbm_pipeline_free(cbm_pipeline_t *
cbm_store_free_lsp_surfaces(p->surface_rows, p->surface_row_count);
p->surface_rows = NULL;
p->surface_row_count = 0;
+ for (int i = 0; i < p->unresolved_count; i++) {
+ cbm_free(CBM_MEM_CLASS_RESOLVE, (char *)p->unresolved_rows[i].rel_path);
+ cbm_free(CBM_MEM_CLASS_RESOLVE, (char *)p->unresolved_rows[i].detail);
+ }
+ cbm_free(CBM_MEM_CLASS_RESOLVE, p->unresolved_rows);
+ cbm_mutex_destroy(&p->unresolved_mutex);
++
+ pipeline_reset_doc_links(p);
+ cbm_store_doc_candidates_free(p->doc_candidates, p->doc_candidate_count);
+ p->doc_candidates = NULL;
+ p->doc_candidate_count = 0;
cbm_git_context_free(&p->git_ctx);
/* gbuf, store, registry freed during/after run */
/* Defensive owner cleanup; normal runs release after publication. */
diff --cc src/pipeline/pipeline_incremental.c
index a6451f4b8,330d36d89..33e1bba55
--- a/src/pipeline/pipeline_incremental.c
+++ b/src/pipeline/pipeline_incremental.c
@@@ -31,8 -33,8 +33,9 @@@ enum { INCR_RING_BUF = 4, INCR_RING_MAS
#include "foundation/compat_thread.h"
#include "foundation/platform.h"
#include "foundation/sha256.h"
+#include "result_spill.h"
+ #include <ctype.h>
#include <errno.h>
#include <stdlib.h>
#include <string.h>
@@@ -2946,8 -3306,15 +3343,12 @@@ int cbm_pipeline_run_incremental(cbm_pi
cbm_coverage_meta_t meta = {0};
int meta_rc = cbm_store_coverage_meta_get(store, project, &meta);
const char *mode_name = incr_mode_name(cbm_pipeline_get_mode(p));
- bool metadata_current = meta_rc == CBM_STORE_OK &&
- meta.coverage_version == CBM_SEMANTIC_INDEX_VERSION &&
- meta.hash_records_complete && meta.index_mode &&
- strcmp(meta.index_mode, mode_name) == 0;
+ bool metadata_current = incremental_metadata_current(meta_rc, &meta, mode_name);
- bool exact = metadata_current &&
+ /* A generation whose doc-link layer is missing or failed is not
+ * current even with identical inputs: index_status tells the user to
+ * re-run, and the re-run has to rebuild. */
+ bool doc_links_current = metadata_current && incr_doc_links_current(store, project);
+ bool exact = doc_links_current &&
cbm_pipeline_semantic_manifests_equal(stored, stored_count, baseline_manifest,
baseline_count);
cbm_store_coverage_meta_clear(&meta);
diff --cc src/pipeline/pipeline_internal.h
index fafcc2a02,7ecddbb4e..9c4b67c95
--- a/src/pipeline/pipeline_internal.h
+++ b/src/pipeline/pipeline_internal.h
@@@ -1245,16 -1261,26 +1261,31 @@@ int cbm_pipeline_build_fresh_semantic_m
/* Compatibility contract persisted in coverage metadata. Increment when a
* graph/manifest semantic change makes prior exact-input indexes unsafe.
- * 4 (upstream): C-family node identities changed. A preprocessor macro's QN
- * ends in "#macro"; unscoped C/C++/Objective-C enumerators are
- * `<scope>.<NAME>` (the enum name is no longer a segment); typedef names,
- * anonymous-enum constants and macro-prefixed functions are nodes; a
- * bodyless `struct X` is no node.
- * 5: unresolved-call evidence capture and candidate indexing.
- * 6: integrate the C-family identities into version-5 indexes. Those indexes
- * still hold old QNs for unchanged files and must rebuild in full once.
+ * 4: C-family node identities changed. A preprocessor macro's QN ends in
+ * "#macro"; unscoped C/C++/Objective-C enumerators are `<scope>.<NAME>`
+ * (the enum name is no longer a segment); typedef names, anonymous-enum
+ * constants and macro-prefixed functions are nodes; a bodyless
+ * `struct X` is no node. An index written before this holds the old
+ * QNs for every unchanged file, so it is rebuilt in full once.
+ * 5: doc-comment references became MENTIONS edges and doc_link_unresolved
+ * rows, and C# LSP surfaces carry the doc-link scope ("dl"); an index
+ * built before has neither, so it rebuilds once on upgrade.
+ * 6: documents became link sources: Markdown, reStructuredText and AsciiDoc
+ * sections and PDF pages hold MENTIONS edges into the code, ADR records
+ * are nodes, and AsciiDoc files, PDFs and a Sphinx project's extra
+ * source suffixes are indexed. An index built before has none of this
+ * for its unchanged documents, so it rebuilds once on upgrade.
+ * 7: SEMANTICALLY_RELATED changed: TF-IDF compares vocabulary, string
+ * properties are read with their escapes, admission is best-first and
+ * every edge carries "p"; doc_link_candidates holds doc section -> code
+ * candidates. An index built before has the old pairs and no
- * candidates, so it rebuilds once on upgrade. */
-enum { CBM_SEMANTIC_INDEX_VERSION = 7 };
++ * candidates, so it rebuilds once on upgrade.
++ * 8: combine these changes with unresolved-call evidence capture and its
++ * candidate index. This branch's earlier versions 5 and 6 did not have
++ * the document-link and TF-IDF layers; upstream version 7 did not have
++ * unresolved-call capture. Both require a full rebuild on upgrade.
+ * The unresolved-call coverage threshold remains independent. */
- enum { CBM_SEMANTIC_INDEX_VERSION = 6 };
++enum { CBM_SEMANTIC_INDEX_VERSION = 8 };
typedef struct {
cbm_gbuf_t *gbuf;
@@@ -1339,19 -1382,22 +1387,35 @@@ void cbm_pipeline_discard_stage(const c
* Takes ownership; dump_and_persist_hashes writes them into the staging
* store and cbm_pipeline_free releases them. Passing NULL/0 clears. */
void cbm_pipeline_set_lsp_surfaces(cbm_pipeline_t *p, cbm_lsp_surface_row_t *rows, int count);
+/* One entry per call, owned by the current file's resolve pass. Candidate
+ * strings are borrowed from the graph and copied by coverage capture. */
+typedef struct {
+ const char *candidate_qn;
+ bool calls_emitted;
+} CBMCallEvidence;
+void cbm_pipeline_record_unresolved_calls(cbm_pipeline_t *p, const char *rel_path,
+ const CBMFileResult *result,
+ const CBMCallEvidence *evidence);
+void cbm_pipeline_mark_unresolved_capture_failed(cbm_pipeline_t *p);
+void cbm_pipeline_get_unresolved_calls(cbm_pipeline_t *p, cbm_coverage_row_t **rows, int *count,
+ bool *complete);
+
+ /* The run's doc_link_unresolved rows and failure flag (doc_links.h), taken
+ * over by the pipeline (set replaces and frees earlier rows; NULL p frees).
+ * A full run publishes them from dump_and_persist_hashes; an incremental
+ * route takes them back for its carry-forward merge. `ran` stays false until
+ * a doc-link phase hands rows over, so a route that never resolved can tell. */
+ void cbm_pipeline_set_doc_link_rows(cbm_pipeline_t *p, cbm_doc_link_row_t *rows, int count,
+ bool failed);
+ void cbm_pipeline_take_doc_link_rows(cbm_pipeline_t *p, cbm_doc_link_row_t **rows, int *count,
+ bool *failed, bool *ran);
+
+ /* Hand the run's doc -> code candidates (pass_semantic_edges) to the
+ * pipeline. Takes ownership (rows and strings in CBM_MEM_CLASS_STORE, released
+ * with cbm_store_doc_candidates_free); a NULL p frees them. NULL/0 clears. */
+ void cbm_pipeline_set_doc_candidates(cbm_pipeline_t *p, cbm_doc_candidate_t *rows, int count);
+ const cbm_doc_candidate_t *cbm_pipeline_doc_candidates(const cbm_pipeline_t *p, int *count);
+
/* Pipeline accessors for incremental use */
const char *cbm_pipeline_repo_path(const cbm_pipeline_t *p);
const cbm_test_declarations_t *cbm_pipeline_test_declarations(const cbm_pipeline_t *p);