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.
C aiderastclaude-codecode-analysiscode-intelligencecodexcursorcypherdeveloper-toolsgemini-cligraph-visualizationkilocodeknowledge-graphmcpmcp-servermodel-context-protocolopencodesqlitetree-sitterwindsurf
doc-links(cs): a name is looked up once per region; a second candidate decides (S5)
Martin Vogelcc2c9663d2b3
diff --git a/src/pipeline/doc_links.c b/src/pipeline/doc_links.cindex 7c1af2bb6..fd2b32a32 100644--- a/src/pipeline/doc_links.c+++ b/src/pipeline/doc_links.c@@ -429,6 +429,7 @@ void cbm_doclinks_resolve_file(cbm_doclinks_t *dl, int file_idx, const CBMFileRe* file-level doc resolves */const cbm_gbuf_node_t *file_node = NULL;bool file_node_looked_up = false;+ void *state = (R && index && R->file_begin) ? R->file_begin(index, file_idx) : NULL;for (int i = 0; i < n; i++) {const CBMDocLink *link = &result->doc_links.items[i];cbm_doclink_outcome_t out = {.kind = CBM_DOCLINK_UNRESOLVED,@@ -438,7 +439,7 @@ void cbm_doclinks_resolve_file(cbm_doclinks_t *dl, int file_idx, const CBMFileRe} else if (!R || !index) {continue; /* no resolver for this language: nothing to say */} else {- R->resolve(index, file_idx, link, graph, &out);+ R->resolve(index, state, file_idx, link, graph, &out);}if (out.kind == CBM_DOCLINK_LOCAL) {atomic_fetch_add_explicit(&dl->local_refs, 1, memory_order_relaxed);@@ -495,6 +496,9 @@ void cbm_doclinks_resolve_file(cbm_doclinks_t *dl, int file_idx, const CBMFileRe}atomic_fetch_add_explicit(&dl->reasons[reason], 1, memory_order_relaxed);}+ if (state && R->file_end) {+ R->file_end(state);+ }if (nm > 0) {emit_mentions(dl, fi->rel_path, mentions, nm, edge_out);}diff --git a/src/pipeline/doc_links.h b/src/pipeline/doc_links.hindex 9a6452a77..2f08f5c22 100644--- a/src/pipeline/doc_links.h+++ b/src/pipeline/doc_links.h@@ -189,9 +189,16 @@ typedef struct {/* The language's project-wide index; NULL on allocation failure. */void *(*build)(const cbm_doclink_build_in_t *in);void (*destroy)(void *index);+ /* Optional working state for the references of one file, which one thread+ * resolves: made before its first reference, handed to every resolve call+ * of the file, released after its last. A NULL state (no hook, or memory+ * ran out) changes the cost of resolving, never an outcome. */+ void *(*file_begin)(const void *index, int run_file);+ void (*file_end)(void *state);/* Resolve one reference of run file `run_file` (its own scope is in the- * index). Thread-safe: the index is read-only after build. */- void (*resolve)(const void *index, int run_file, const CBMDocLink *link,+ * index). Thread-safe: the index is read-only after build; `state` is the+ * file's own (file_begin) or NULL. */+ void (*resolve)(const void *index, void *state, int run_file, const CBMDocLink *link,const cbm_gbuf_t *graph, cbm_doclink_outcome_t *out);/* Incremental runs; both optional.* scope_input true for a file that is no source of the language and hasdiff --git a/src/pipeline/doc_links_cs.c b/src/pipeline/doc_links_cs.cindex 92ab111e6..a32b13451 100644--- a/src/pipeline/doc_links_cs.c+++ b/src/pipeline/doc_links_cs.c@@ -2867,6 +2867,8 @@ typedef struct {cs_why_t why; /* of an ambiguous one */} cs_res_t;+typedef struct cs_memo cs_memo_t;+typedef struct {const cs_index_t *ix;int file;@@ -2885,6 +2887,9 @@ typedef struct {/* Set when a namespace this context does not see was passed over (NULL:* nobody asks). */bool *passed_over;+ /* What the using directives of a scope level gave a query, remembered+ * for the pass the caller runs (lookup); NULL: nothing is remembered. */+ cs_memo_t *memo;} cs_ctx_t;static cs_res_t res_edge(const cbm_gbuf_node_t *n, bool exact) {@@ -4437,6 +4442,13 @@ static void add_alias_target(const cs_ctx_t *c, const cs_using_t *u, cs_found_t}}+/* True once a level has two candidates: the lookup is ambiguous whatever the+ * directives after them bring, so they are not asked (S5). Which candidate+ * came first, and whether there was one, never depends on the ones skipped. */+static bool found_decided(const cs_found_t *fd) {+ return fd->n > SKIP_ONE;+}+static void level_aliases(const cs_ctx_t *c, const cs_using_t *us, int n,const cs_using_index_t *index, const cs_query_t *q, cs_found_t *fd) {/* an alias names a type or a namespace: no candidate for `Name{T}` */@@ -4444,7 +4456,7 @@ static void level_aliases(const cs_ctx_t *c, const cs_using_t *us, int n,return;}if (!index || !index->ready) {- for (int i = 0; i < n; i++) {+ for (int i = 0; i < n && !found_decided(fd); i++) {cs_work(SKIP_ONE);if (us[i].kind == 'a' && strcmp(us[i].alias, q->name) == 0) {add_alias_target(c, &us[i], fd);@@ -4463,7 +4475,7 @@ static void level_aliases(const cs_ctx_t *c, const cs_using_t *us, int n,hi = mid;}}- for (size_t i = lo; i < index->naliases; i++) {+ for (size_t i = lo; i < index->naliases && !found_decided(fd); i++) {cs_work(SKIP_ONE);if (strcmp(index->aliases[i].name, q->name)) {break;@@ -4599,7 +4611,7 @@ static void level_usings(const cs_ctx_t *c, const cs_using_t *us, int n,/* A common name in a large repository must not make a small scope walk* more postings than it has directives. The baseline scan stays cheap. */if (!indexed || hi - lo >= (size_t)n) {- for (int i = 0; i < n; i++) {+ for (int i = 0; i < n && !found_decided(fd); i++) {level_using(c, &us[i], q, a_type_name, fd);}return;@@ -4618,7 +4630,7 @@ static void level_usings(const cs_ctx_t *c, const cs_using_t *us, int n,if (ids.n > 1) {qsort(ids.ids, ids.n, sizeof(int), candidate_id_cmp);}- for (size_t i = 0; i < ids.n; i++) {+ for (size_t i = 0; i < ids.n && !found_decided(fd); i++) {cs_work(SKIP_ONE);/* Own and twin postings may select the SAME directive twice.* Distinct directive IDs must still be resolved separately. */@@ -4631,12 +4643,91 @@ static void level_usings(const cs_ctx_t *c, const cs_using_t *us, int n,cbm_free(CBM_MEM_CLASS_OTHER, ids.ids);}if (!complete) {- for (int i = 0; i < n; i++) {+ for (int i = 0; i < n && !found_decided(fd); i++) {level_using(c, &us[i], q, a_type_name, fd);}}}+/* The using step of a lookup -- what the directives of one region, and at+ * the global namespace the unit's, give one query -- remembered for one pass+ * over a file's references (or one pass of the build): a name looked up+ * again in the same region costs one probe, not the directives (S5). The key+ * holds everything the step reads: the file, the region and unit asked, the+ * context's visibility (product code, unit, assembly) and the query. A memo+ * that ran out of memory stops remembering; the lookups stay exact. */+struct cs_memo {+ CBMHashTable *steps; /* key -> cs_found_t in `arena` */+ CBMArena arena;+ bool off;+};++enum { CS_MEMO_KEY = CS_NAME_BUF + CBM_SZ_128 };++static void memo_init(cs_memo_t *m) {+ memset(m, 0, sizeof(*m));+ cbm_arena_init(&m->arena);+ m->steps = cbm_ht_create(CBM_SZ_256);+ m->off = m->steps == NULL;+}++static void memo_destroy(cs_memo_t *m) {+ cbm_ht_free(m->steps);+ cbm_arena_destroy(&m->arena);+ memset(m, 0, sizeof(*m));+}++/* The key of one using step; false when it does not fit (not remembered). */+static bool memo_key(char *buf, size_t cap, const cs_ctx_t *c, int region, int unit,+ const cs_query_t *q) {+ int n = snprintf(buf, cap, "%d|%d|%d|%d|%d|%d|%d|%d%d%d%c|%s", c->file, region, unit, c->unit,+ c->group, (int)c->prod, q->arity, (int)q->types_only, (int)q->statics,+ (int)q->ctors, q->kind ? q->kind : '-', q->name);+ return n > 0 && (size_t)n < cap;+}++static bool memo_get(const cs_memo_t *m, const char *key, cs_found_t *out) {+ cs_work(SKIP_ONE);+ const cs_found_t *hit = (const cs_found_t *)cbm_ht_get(m->steps, key);+ if (hit) {+ *out = *hit;+ }+ return hit != NULL;+}++static void memo_put(cs_memo_t *m, const char *key, const cs_found_t *step) {+ char *k = cbm_arena_strdup(&m->arena, key);+ cs_found_t *v = (cs_found_t *)cbm_arena_alloc(&m->arena, sizeof(*v));+ if (!k || !v) {+ m->off = true;+ return;+ }+ *v = *step;+ cbm_ht_set(m->steps, k, v);+ m->off = cbm_ht_get(m->steps, k) != v; /* an insert that did not take */+}++/* What the directives of this scope level give the query: the region's own+ * (`us`, when asked) and, at the global namespace, the unit's. Asked once per+ * key when the context has a memo. */+static void using_step(const cs_ctx_t *c, int region, const cs_using_t *us, int nus,+ const cs_using_index_t *usi, const cs_unit_t *unit, const cs_query_t *q,+ cs_found_t *step) {+ char key[CS_MEMO_KEY];+ bool keyed = c->memo && !c->memo->off &&+ memo_key(key, sizeof(key), c, region, unit ? c->unit : CS_NONE, q);+ if (keyed && memo_get(c->memo, key, step)) {+ return;+ }+ level_usings(c, us, nus, usi, q, step);+ if (unit && !found_decided(step)) {+ level_usings(c, unit->usings, unit->nusings, &unit->using_index, q, step);+ }+ if (keyed) {+ memo_put(c->memo, key, step);+ }+}+/* True when the lookup is settled by what the last level added. A level that* had only invisible candidates does not bind: the lookup goes on, and* remembers. */@@ -4714,9 +4805,16 @@ static void lookup(const cs_ctx_t *c, const cs_query_t *q, cs_found_t *fd, boolfd->exact = true;return;}- level_usings(c, us, nus, usi, q, fd);- if (unit) {- level_usings(c, unit->usings, unit->nusings, &unit->using_index, q, fd);+ if (nus > 0 || unit) {+ /* Nothing is found yet (settled), and a step only adds: the step+ * is asked on its own and its candidates are the level's. */+ cs_found_t step = {0};+ using_step(c, asked ? reg : CS_NONE, us, nus, usi, unit, q, &step);+ fd->first = step.first;+ fd->n = step.n;+ fd->invisible = step.invisible;+ fd->why = step.why;+ fd->joined = fd->joined || step.joined;}if (settled(fd, &invisible)) {*statics = fd->first.kind == 'M';@@ -5515,6 +5613,10 @@ static bool resolve_usings(cs_index_t *ix) {return false;}}+ /* A lookup asks only regions above the directive's own, whose directives+ * are resolved already: what it remembers of them stays true. */+ cs_memo_t memo;+ memo_init(&memo);for (int fi = 0; fi < ix->nfiles; fi++) {cs_file_t *f = &ix->files[fi];/* Regions are in ancestor order. Publish an outer region's index@@ -5528,10 +5630,12 @@ static bool resolve_usings(cs_index_t *ix) {c.prod = false; /* a directive names whatever the compiler bound */c.glob = r == 0;c.skip_region = r;+ c.memo = &memo;resolve_using(&f->usings[i], &c);}const cs_using_t *us = reg->u_hi > reg->u_lo ? f->usings + reg->u_lo : NULL;if (!build_using_index(ix, us, reg->u_hi - reg->u_lo, ®->using_index)) {+ memo_destroy(&memo);return false;}}@@ -5543,6 +5647,7 @@ static bool resolve_usings(cs_index_t *ix) {}}}+ memo_destroy(&memo);return true;}@@ -5570,6 +5675,8 @@ static bool resolve_bases(cs_index_t *ix) {int *listed =(int *)cbm_calloc(CBM_MEM_CLASS_OTHER, ((size_t)ix->nents + SKIP_ONE) * sizeof(int));bool ok = listed != NULL;+ cs_memo_t memo; /* every directive is resolved: what a lookup remembers stays true */+ memo_init(&memo);for (int ei = 0; ok && ei < ix->nents; ei++) {cs_entity_t *e = &ix->ents[ei];int written = 0;@@ -5587,6 +5694,7 @@ static bool resolve_bases(cs_index_t *ix) {/* a base list is written outside the type it belongs to */ctx_at(&c, ix, e->decls[d].file, t->region, t->outer);c.prod = false; /* a declared base is whatever the compiler bound */+ c.memo = &memo;for (const char *p = t->bases; p && *p;) {const char *bar = strchr(p, '|');size_t n = bar ? (size_t)(bar - p) : strlen(p);@@ -5601,6 +5709,7 @@ static bool resolve_bases(cs_index_t *ix) {}}}+ memo_destroy(&memo);cbm_free(CBM_MEM_CLASS_OTHER, listed);ix->oom = ix->oom || !ok;return ok;@@ -6054,7 +6163,26 @@ static bool names_quarantined(const cs_index_t *ix, const cs_file_t *f, const csreturn false;}-static void cs_resolve(const void *index, int run_file, const CBMDocLink *link,+/* The working state of one file's references: the memo of their lookups. */+static void *cs_file_begin(const void *index, int run_file) {+ (void)index;+ (void)run_file;+ cs_memo_t *m = (cs_memo_t *)cbm_alloc(CBM_MEM_CLASS_OTHER, sizeof(*m));+ if (m) {+ memo_init(m);+ }+ return m;+}++static void cs_file_end(void *state) {+ cs_memo_t *m = (cs_memo_t *)state;+ if (m) {+ memo_destroy(m);+ cbm_free(CBM_MEM_CLASS_OTHER, m);+ }+}++static void cs_resolve(const void *index, void *state, int run_file, const CBMDocLink *link,const cbm_gbuf_t *graph, cbm_doclink_outcome_t *out) {const cs_index_t *ix = (const cs_index_t *)index;(void)graph; /* every node was looked up when the index was built */@@ -6091,6 +6219,7 @@ static void cs_resolve(const void *index, int run_file, const CBMDocLink *link,cs_ctx_t c;ctx_init(&c, ix, file, link->def_line, file_doc);c.glob = r.glob;+ c.memo = (cs_memo_t *)state;cs_res_t res = resolve_ref(&c, &r);if (res.st == CS_LOCAL) {out->kind = CBM_DOCLINK_LOCAL;@@ -6260,6 +6389,8 @@ const cbm_doclink_resolver_t cbm_doclink_cs_resolver = {.scope_tag = CBM_DOCLINK_CS_SCOPE_TAG,.build = cs_build,.destroy = cs_destroy,+ .file_begin = cs_file_begin,+ .file_end = cs_file_end,.resolve = cs_resolve,.scope_delta = cs_scope_delta,};diff --git a/tests/test_doc_mentions.c b/tests/test_doc_mentions.cindex aec90228f..99c4090eb 100644--- a/tests/test_doc_mentions.c+++ b/tests/test_doc_mentions.c@@ -8729,6 +8729,138 @@ TEST(doc_mentions_cs_import_lookup_cost) {PASS();}+/* S5: `Shared` is declared in k namespaces nobody imports; one file has k+ * usings of other namespaces and r documented classes that each name it, so+ * every one of its r lookups would walk the k directives. The resolver's+ * lookup work, and the number of `missing` rows for `Shared` (r when all are+ * resolved; -1 when the repository cannot be indexed). */+static uint64_t dm_repeated_name_work(int k, int r, int *rows) {+ enum { CAP = 256 * 1024 };+ char *src = malloc(CAP);+ char tmp[256] = "/tmp/cbm_dm_repeated_XXXXXX";+ *rows = -1;+ if (!src || !cbm_mkdtemp(tmp)) {+ free(src);+ return 0;+ }+ size_t w = 0;+ for (int i = 0; i < k; i++) {+ w += (size_t)snprintf(src + w, CAP - w,+ "namespace P%d { public class Shared { } }\n"+ "namespace In.U%d { public class Other%d { } }\n",+ i, i, i);+ }+ th_write_file(TH_PATH(tmp, "src/Far.cs"), src);+ w = 0;+ for (int i = 0; i < k; i++) {+ w += (size_t)snprintf(src + w, CAP - w, "using In.U%d;\n", i);+ }+ w += (size_t)snprintf(src + w, CAP - w, "namespace N0\n{\n");+ for (int j = 0; j < r; j++) {+ w += (size_t)snprintf(src + w, CAP - w,+ "/// <summary><see cref=\"Shared\"/></summary>\n"+ "public class L%d { }\n",+ j);+ }+ snprintf(src + w, CAP - w, "}\n");+ th_write_file(TH_PATH(tmp, "src/Uses.cs"), src);+ free(src);+ char db[512];+ snprintf(db, sizeof(db), "%s/repeated.db", tmp);+ cbm_doclink_cs_test_work_reset();+ uint64_t work = dm_index(tmp, db, NULL) == 0 ? cbm_doclink_cs_test_work() : 0;+ *rows = dm_count(db, "SELECT COUNT(*) FROM doc_link_unresolved "+ "WHERE raw = 'Shared' AND reason = 'missing'");+ dm_unlink_db(db);+ th_rmtree(tmp);+ return work;+}++/* A name looked up again in the same region costs once: with k and r both+ * four times as large the work grows with the input (about 4 x), not with+ * r x k (16 x). */+TEST(doc_mentions_cs_lookup_repeated_name_work) {+ int rows[2] = {0};+ uint64_t small = dm_repeated_name_work(60, 40, &rows[0]);+ uint64_t large = dm_repeated_name_work(240, 160, &rows[1]);+ double ratio = small ? (double)large / (double)small : 0.0;+ printf(" repeated name, k 60 -> 240 and r 40 -> 160: %llu -> %llu steps, %.2f times the "+ "work, want at most 6\n",+ (unsigned long long)small, (unsigned long long)large, ratio);+ ASSERT_EQ(rows[0], 40);+ ASSERT_EQ(rows[1], 160);+ ASSERT_GT(small, 0);+ ASSERT_LTE(large, 6 * small);+ PASS();+}++/* S5: k namespaces all declare `Shared` and one file imports all of them;+ * `refs` documented classes name it (0 or 1). The resolver's lookup work and+ * the reason of the row (empty when there is none). */+static uint64_t dm_ambiguous_name_work(int k, int refs, char *reason, size_t cap) {+ enum { SRC_CAP = 64 * 1024 };+ char *src = malloc(SRC_CAP);+ char tmp[256] = "/tmp/cbm_dm_ambiguous_XXXXXX";+ reason[0] = '\0';+ if (!src || !cbm_mkdtemp(tmp)) {+ free(src);+ return 0;+ }+ size_t w = 0;+ for (int i = 0; i < k; i++) {+ w += (size_t)snprintf(src + w, SRC_CAP - w, "namespace P%d { public class Shared { } }\n",+ i);+ }+ th_write_file(TH_PATH(tmp, "src/Far.cs"), src);+ w = 0;+ for (int i = 0; i < k; i++) {+ w += (size_t)snprintf(src + w, SRC_CAP - w, "using P%d;\n", i);+ }+ w += (size_t)snprintf(src + w, SRC_CAP - w, "namespace N0\n{\n");+ for (int j = 0; j < refs; j++) {+ w += (size_t)snprintf(src + w, SRC_CAP - w,+ "/// <summary><see cref=\"Shared\"/></summary>\n"+ "public class L%d { }\n",+ j);+ }+ snprintf(src + w, SRC_CAP - w, "public class Last { }\n}\n");+ th_write_file(TH_PATH(tmp, "src/Uses.cs"), src);+ free(src);+ char db[512];+ snprintf(db, sizeof(db), "%s/ambiguous.db", tmp);+ cbm_doclink_cs_test_work_reset();+ uint64_t work = dm_index(tmp, db, NULL) == 0 ? cbm_doclink_cs_test_work() : 0;+ dm_row(db, "src/Uses.cs", "Shared", reason, cap, NULL, 0);+ dm_unlink_db(db);+ th_rmtree(tmp);+ return work;+}++/* One lookup stops at its second candidate: the name is ambiguous whatever+ * the directives after it bring. The work of one ambiguous reference (the+ * run with it less the run without it) does not grow with the k imports that+ * all declare the name. */+TEST(doc_mentions_cs_lookup_ambiguous_stops) {+ static const int ks[2] = {50, 200};+ uint64_t one[2] = {0};+ bool ambiguous = true;+ for (int i = 0; i < 2; i++) {+ char reason[64];+ char none[64];+ uint64_t with = dm_ambiguous_name_work(ks[i], 1, reason, sizeof(reason));+ uint64_t without = dm_ambiguous_name_work(ks[i], 0, none, sizeof(none));+ one[i] = with > without ? with - without : 0;+ ambiguous = ambiguous && strcmp(reason, "ambiguous") == 0 && !none[0];+ }+ printf(" one ambiguous reference, k 50 -> 200 imports that declare it: %llu -> %llu steps, "+ "want at most 1.5 times\n",+ (unsigned long long)one[0], (unsigned long long)one[1]);+ ASSERT_TRUE(ambiguous);+ ASSERT_GT(one[0], 0);+ ASSERT_LTE(2 * one[1], 3 * one[0]);+ PASS();+}+/* Parent/global imports are ready for a child's directives. The child's own* directives stay excluded while those targets are resolved. */TEST(doc_mentions_cs_import_stage_aliases) {@@ -10009,6 +10141,8 @@ SUITE(doc_mentions) {RUN_TEST(doc_mentions_cs_text_forms);RUN_TEST(doc_mentions_cs_lookup_cost);RUN_TEST(doc_mentions_cs_import_lookup_cost);+ RUN_TEST(doc_mentions_cs_lookup_repeated_name_work);+ RUN_TEST(doc_mentions_cs_lookup_ambiguous_stops);RUN_TEST(doc_mentions_cs_import_stage_aliases);RUN_TEST(doc_mentions_cs_import_static_parts);RUN_TEST(doc_mentions_cs_import_candidate_allocation);