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
fix(doc-links): report a path::member reference to a missing member (#2587)
Scott Beck9a180d06263c
diff --git a/src/pipeline/doc_links_md.c b/src/pipeline/doc_links_md.cindex 9e76d41a4..14d6db513 100644--- a/src/pipeline/doc_links_md.c+++ b/src/pipeline/doc_links_md.c@@ -17,9 +17,12 @@** Unresolved:* missing the path is not in the graph, but its directory is: the- * document names something that is not there (doc rot)+ * document names something that is not there (doc rot); or a+ * code file's member that the file does not define* ambiguous a file name alone that is not next to the document but exists- * elsewhere in the repository: the document does not say which+ * elsewhere in the repository: the document does not say which;+ * or a member name the file defines more than once, with no+ * owner to pick one* Not a reference to this repository at all (LOCAL: no edge, no row): a link* back into the same document; a path that is neither indexed nor of a type* the indexer reads (an image, an archive, an extensionless page); a path@@ -478,12 +481,24 @@ static void mdr_file_defs(const mdr_index_t *x, const char *path, int *lo, int **hi = e;}+/* How a member lookup ended: found, or why not. */+typedef enum {+ MDR_MEMBER_FOUND = 0,+ MDR_MEMBER_MISSING, /* no definition of that name in the file */+ MDR_MEMBER_AMBIGUOUS, /* several, and the owner does not pick one */+} mdr_member_t;+/* The code definition of file `path` that the range or the member names, or* NULL. Read from the index's definitions by file, never from DEFINES edges:* an incremental run's graph holds the edges of the files it re-extracts- * only, while every node is there. */+ * only, while every node is there. *member_result (when not NULL) says how a+ * member lookup ended. */static const cbm_gbuf_node_t *mdr_segment(const mdr_index_t *x, const char *path, uint32_t first,- uint32_t last, const char *member) {+ uint32_t last, const char *member,+ mdr_member_t *member_result) {+ if (member_result) {+ *member_result = MDR_MEMBER_FOUND;+ }int lo = 0;int hi = 0;mdr_file_defs(x, path, &lo, &hi);@@ -516,6 +531,9 @@ static const cbm_gbuf_node_t *mdr_segment(const mdr_index_t *x, const char *pathsize_t owner_len;mdr_member_names(member, &name, &name_len, &owner, &owner_len);if (!name) {+ if (member_result) {+ *member_result = MDR_MEMBER_MISSING;+ }return NULL;}const cbm_gbuf_node_t *hit = NULL;@@ -537,7 +555,13 @@ static const cbm_gbuf_node_t *mdr_segment(const mdr_index_t *x, const char *pathif (owned_hits == SKIP_ONE) {return owned;}- return owned_hits == 0 && hits == SKIP_ONE ? hit : NULL;+ if (owned_hits == 0 && hits == SKIP_ONE) {+ return hit;+ }+ if (member_result) {+ *member_result = hits == 0 ? MDR_MEMBER_MISSING : MDR_MEMBER_AMBIGUOUS;+ }+ return NULL;}/* Is `path` of a file type the indexer reads? */@@ -1151,9 +1175,21 @@ static void mdr_resolve_path(const mdr_index_t *x, const cbm_gbuf_t *graph, consout->kind = CBM_DOCLINK_LOCAL; /* a link into the same document */return;}- const cbm_gbuf_node_t *seg = (r->first > 0 || r->member)- ? mdr_segment(x, t, r->first, r->last, r->member)- : NULL;+ mdr_member_t member_result = MDR_MEMBER_FOUND;+ const cbm_gbuf_node_t *seg =+ (r->first > 0 || r->member)+ ? mdr_segment(x, t, r->first, r->last, r->member, &member_result)+ : NULL;+ /* A named member that a code file does not define is no coarser+ * link to the file: it is a stale or unclear reference. A+ * document's own headings are not definitions, so members of+ * other files keep the file edge. */+ if (!seg && r->member && member_result != MDR_MEMBER_FOUND && mdr_code_file(t)) {+ out->kind = CBM_DOCLINK_UNRESOLVED;+ out->reason = member_result == MDR_MEMBER_AMBIGUOUS ? CBM_DOCLINK_REASON_AMBIGUOUS+ : CBM_DOCLINK_REASON_MISSING;+ return;+ }mdr_edge(out, seg ? seg : file, r->first, r->last);return;}@@ -1388,7 +1424,8 @@ static void mdr_resolve(const void *index, void *state, int run_file, const CBMDconst cbm_gbuf_node_t *cbm_doclink_md_segment(const void *md_index, const char *path,uint32_t first, uint32_t last, const char *member) {- return md_index ? mdr_segment((const mdr_index_t *)md_index, path, first, last, member) : NULL;+ return md_index ? mdr_segment((const mdr_index_t *)md_index, path, first, last, member, NULL)+ : NULL;}/* ── A region of a file's text (the field test's H8 bind_range) ─────── */diff --git a/tests/test_doc_links_md.c b/tests/test_doc_links_md.cindex 21e74f37e..11049e032 100644--- a/tests/test_doc_links_md.c+++ b/tests/test_doc_links_md.c@@ -388,6 +388,73 @@ TEST(doc_links_md_resolve) {PASS();}+/* #2587: a `path::member` reference whose member the code file does not+ * define was an exact edge to the file, so a renamed or deleted definition+ * looked like a valid, coarser link. It is a missing reference; a member the+ * file defines more than once, with no owner to pick one, is ambiguous. */+TEST(doc_links_md_member_not_defined_issue2587) {+ char tmp[256];+ snprintf(tmp, sizeof(tmp), "/tmp/cbm_dlmd_XXXXXX");+ ASSERT_NOT_NULL(cbm_mkdtemp(tmp));+ th_write_file(TH_PATH(tmp, "docs/members.md"),+ "# Members\n"+ "\n"+ "See `src/util/rounding.py::clamp` and "+ "`src/util/rounding.py::no_such_function`.\n"+ "Areas: `src/shapes.py::Square::area`, `src/shapes.py::area`.\n"+ "Notes: `docs/other.md::Intro`.\n");+ th_write_file(TH_PATH(tmp, "docs/other.md"), "# Intro\n\nText.\n");+ th_write_file(TH_PATH(tmp, "src/util/rounding.py"), "def clamp(x, lo, hi):\n"+ " return max(lo, min(hi, x))\n");+ th_write_file(TH_PATH(tmp, "src/shapes.py"), "class Circle:\n"+ " def area(self):\n"+ " return 3\n"+ "\n"+ "\n"+ "class Square:\n"+ " def area(self):\n"+ " return 4\n");+ char db[512];+ snprintf(db, sizeof(db), "%s/md.db", tmp);+ ASSERT_EQ(dm_index(tmp, db, NULL), 0);+ char props[512];+ char reason[64];++ /* a member the file defines, alone or through its owner */+ ASSERT_EQ(md_edge(db, "Members", "rounding.clamp", props, sizeof(props)), 1);+ ASSERT_EQ(md_edge(db, "Members", "Square.area", props, sizeof(props)), 1);+ ASSERT_EQ(md_edge(db, "Members", "Circle.area", props, sizeof(props)), 0);++ /* a member the file does not define: no edge to the file, a missing row */+ ASSERT_EQ(dm_count(db, "SELECT COUNT(*) FROM edges e JOIN nodes s ON s.id = e.source_id "+ "JOIN nodes t ON t.id = e.target_id WHERE e.type = 'MENTIONS' "+ "AND s.qualified_name LIKE '%.Members' AND t.label = 'File' "+ "AND t.file_path = 'src/util/rounding.py'"),+ 0);+ dm_row(db, "docs/members.md", "src/util/rounding.py::no_such_function", reason, sizeof(reason),+ NULL, 0);+ ASSERT_STR_EQ(reason, "missing");++ /* defined twice and no owner written: ambiguous, not the file */+ dm_row(db, "docs/members.md", "src/shapes.py::area", reason, sizeof(reason), NULL, 0);+ ASSERT_STR_EQ(reason, "ambiguous");+ ASSERT_EQ(dm_count(db, "SELECT COUNT(*) FROM edges e JOIN nodes s ON s.id = e.source_id "+ "JOIN nodes t ON t.id = e.target_id WHERE e.type = 'MENTIONS' "+ "AND s.qualified_name LIKE '%.Members' AND t.label = 'File' "+ "AND t.file_path = 'src/shapes.py'"),+ 0);++ /* a document's headings are no definitions: the file edge stays */+ ASSERT_EQ(dm_count(db, "SELECT COUNT(*) FROM edges e JOIN nodes s ON s.id = e.source_id "+ "JOIN nodes t ON t.id = e.target_id WHERE e.type = 'MENTIONS' "+ "AND s.qualified_name LIKE '%.Members' AND t.label = 'File' "+ "AND t.file_path = 'docs/other.md'"),+ 1);++ th_cleanup(tmp);+ PASS();+}+/* ── incremental == full ─────────────────────────────────────────── */TEST(doc_links_md_incremental) {@@ -865,6 +932,7 @@ SUITE(doc_links_md) {RUN_TEST(doc_links_md_repeated_headings);RUN_TEST(doc_links_md_classify_span);RUN_TEST(doc_links_md_resolve);+ RUN_TEST(doc_links_md_member_not_defined_issue2587);RUN_TEST(doc_links_md_incremental);RUN_TEST(doc_links_md_adr);RUN_TEST(doc_links_md_adr_label_choice);