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: document families ship as edges only after a held-out audit
Martin Vogel7209ae12397c
diff --git a/internal/cbm/doclink.h b/internal/cbm/doclink.hindex d6b24219b..03addc973 100644--- a/internal/cbm/doclink.h+++ b/internal/cbm/doclink.h@@ -55,7 +55,12 @@* edge. false: the tier is below the audit's bar; its references* still resolve, but a resolved one stays a doc_link_unresolved* row with reason below_bar_tier (an unresolved one keeps its own- * reason). Nothing else about the family changes.+ * reason). Nothing else about the family changes. A document+ * family ships once a held-out audit passed it: below the bar+ * (pdf_qn; Markdown and AsciiDoc code spans naming paths, AsciiDoc+ * code names, reST code paths, supersedes) or not yet audited for+ * want of held-out occurrences (reST object, include,+ * literalinclude, kernel_doc; AsciiDoc attribute) means false.* edge the type of the edge a resolved reference becomes: MENTIONS* (documentation names code), SUPERSEDES (an ADR states that it* supersedes another). The edge's source is always the@@ -64,40 +69,40 @@** The enum below and the family table (doclink.c) are both generated from this* list, so a value cannot exist without its name and its gate. */-#define CBM_DOCLINK_FAMILY_LIST(X) \- /* csharp */ \- X(CBM_DOCLINK_CS_SEE, CBM_LANG_CSHARP, "see", false, true, "MENTIONS") \- X(CBM_DOCLINK_CS_SEEALSO, CBM_LANG_CSHARP, "seealso", false, true, "MENTIONS") \- X(CBM_DOCLINK_CS_EXCEPTION, CBM_LANG_CSHARP, "exception", false, true, "MENTIONS") \- X(CBM_DOCLINK_CS_INHERITDOC, CBM_LANG_CSHARP, "inheritdoc", false, true, "MENTIONS") \- /* markdown (doclink_md.c): what a document's text names explicitly */ \- X(CBM_DOCLINK_MD_LINK, CBM_LANG_MARKDOWN, "link", false, true, "MENTIONS") \- X(CBM_DOCLINK_MD_PATH, CBM_LANG_MARKDOWN, "path", false, true, "MENTIONS") \- X(CBM_DOCLINK_MD_CODE_PATH, CBM_LANG_MARKDOWN, "code_path", false, true, "MENTIONS") \- X(CBM_DOCLINK_MD_CODE_NAME, CBM_LANG_MARKDOWN, "code_name", false, true, "MENTIONS") \- /* an ADR's own "supersedes" / "replaces" statement (doc_adr.c): ADR -> ADR */ \- X(CBM_DOCLINK_MD_SUPERSEDES, CBM_LANG_MARKDOWN, "supersedes", false, true, "SUPERSEDES") \- /* pdf (doc_pdf.c): structural mentions in a page's text; pdf_name (bare */ \- /* names) only decides which line fragments a cross-line join replaces */ \- X(CBM_DOCLINK_PDF_PATH, CBM_LANG_PDF, "pdf_path", false, true, "MENTIONS") \- X(CBM_DOCLINK_PDF_FILE, CBM_LANG_PDF, "pdf_file", false, true, "MENTIONS") \- X(CBM_DOCLINK_PDF_QN, CBM_LANG_PDF, "pdf_qn", false, false, "MENTIONS") \- X(CBM_DOCLINK_PDF_NAME, CBM_LANG_PDF, "pdf_name", false, false, "MENTIONS") \- /* restructuredtext (doclink_rst.c): Sphinx domain markup, directives, inline literals */ \- X(CBM_DOCLINK_RST_ROLE, CBM_LANG_RST, "role", false, true, "MENTIONS") \- X(CBM_DOCLINK_RST_OBJECT, CBM_LANG_RST, "object", false, true, "MENTIONS") \- X(CBM_DOCLINK_RST_AUTODOC, CBM_LANG_RST, "autodoc", false, true, "MENTIONS") \- X(CBM_DOCLINK_RST_INCLUDE, CBM_LANG_RST, "include", false, true, "MENTIONS") \- X(CBM_DOCLINK_RST_LITERALINCLUDE, CBM_LANG_RST, "literalinclude", false, true, "MENTIONS") \- X(CBM_DOCLINK_RST_KERNEL_DOC, CBM_LANG_RST, "kernel_doc", false, true, "MENTIONS") \- X(CBM_DOCLINK_RST_CODE_PATH, CBM_LANG_RST, "code_path", false, true, "MENTIONS") \- X(CBM_DOCLINK_RST_CODE_NAME, CBM_LANG_RST, "code_name", false, true, "MENTIONS") \- /* asciidoc (doc_adoc.c): includes, Antora API attributes, monospace spans */ \- X(CBM_DOCLINK_ADOC_INCLUDE, CBM_LANG_ASCIIDOC, "include", false, true, "MENTIONS") \- X(CBM_DOCLINK_ADOC_ATTRIBUTE, CBM_LANG_ASCIIDOC, "attribute", false, true, "MENTIONS") \- X(CBM_DOCLINK_ADOC_CODE_PATH, CBM_LANG_ASCIIDOC, "code_path", false, true, "MENTIONS") \- X(CBM_DOCLINK_ADOC_CODE_NAME, CBM_LANG_ASCIIDOC, "code_name", false, true, "MENTIONS") \- /* any language (CBM_LANG_COUNT): a URL is never an edge */ \+#define CBM_DOCLINK_FAMILY_LIST(X) \+ /* csharp */ \+ X(CBM_DOCLINK_CS_SEE, CBM_LANG_CSHARP, "see", false, true, "MENTIONS") \+ X(CBM_DOCLINK_CS_SEEALSO, CBM_LANG_CSHARP, "seealso", false, true, "MENTIONS") \+ X(CBM_DOCLINK_CS_EXCEPTION, CBM_LANG_CSHARP, "exception", false, true, "MENTIONS") \+ X(CBM_DOCLINK_CS_INHERITDOC, CBM_LANG_CSHARP, "inheritdoc", false, true, "MENTIONS") \+ /* markdown (doclink_md.c): what a document's text names explicitly */ \+ X(CBM_DOCLINK_MD_LINK, CBM_LANG_MARKDOWN, "link", false, true, "MENTIONS") \+ X(CBM_DOCLINK_MD_PATH, CBM_LANG_MARKDOWN, "path", false, true, "MENTIONS") \+ X(CBM_DOCLINK_MD_CODE_PATH, CBM_LANG_MARKDOWN, "code_path", false, false, "MENTIONS") \+ X(CBM_DOCLINK_MD_CODE_NAME, CBM_LANG_MARKDOWN, "code_name", false, true, "MENTIONS") \+ /* an ADR's own "supersedes" / "replaces" statement (doc_adr.c): ADR -> ADR */ \+ X(CBM_DOCLINK_MD_SUPERSEDES, CBM_LANG_MARKDOWN, "supersedes", false, false, "SUPERSEDES") \+ /* pdf (doc_pdf.c): structural mentions in a page's text; pdf_name (bare */ \+ /* names) only decides which line fragments a cross-line join replaces */ \+ X(CBM_DOCLINK_PDF_PATH, CBM_LANG_PDF, "pdf_path", false, true, "MENTIONS") \+ X(CBM_DOCLINK_PDF_FILE, CBM_LANG_PDF, "pdf_file", false, true, "MENTIONS") \+ X(CBM_DOCLINK_PDF_QN, CBM_LANG_PDF, "pdf_qn", false, false, "MENTIONS") \+ X(CBM_DOCLINK_PDF_NAME, CBM_LANG_PDF, "pdf_name", false, false, "MENTIONS") \+ /* restructuredtext (doclink_rst.c): Sphinx domain markup, directives, inline literals */ \+ X(CBM_DOCLINK_RST_ROLE, CBM_LANG_RST, "role", false, true, "MENTIONS") \+ X(CBM_DOCLINK_RST_OBJECT, CBM_LANG_RST, "object", false, false, "MENTIONS") \+ X(CBM_DOCLINK_RST_AUTODOC, CBM_LANG_RST, "autodoc", false, true, "MENTIONS") \+ X(CBM_DOCLINK_RST_INCLUDE, CBM_LANG_RST, "include", false, false, "MENTIONS") \+ X(CBM_DOCLINK_RST_LITERALINCLUDE, CBM_LANG_RST, "literalinclude", false, false, "MENTIONS") \+ X(CBM_DOCLINK_RST_KERNEL_DOC, CBM_LANG_RST, "kernel_doc", false, false, "MENTIONS") \+ X(CBM_DOCLINK_RST_CODE_PATH, CBM_LANG_RST, "code_path", false, false, "MENTIONS") \+ X(CBM_DOCLINK_RST_CODE_NAME, CBM_LANG_RST, "code_name", false, true, "MENTIONS") \+ /* asciidoc (doc_adoc.c): includes, Antora API attributes, monospace spans */ \+ X(CBM_DOCLINK_ADOC_INCLUDE, CBM_LANG_ASCIIDOC, "include", false, true, "MENTIONS") \+ X(CBM_DOCLINK_ADOC_ATTRIBUTE, CBM_LANG_ASCIIDOC, "attribute", false, false, "MENTIONS") \+ X(CBM_DOCLINK_ADOC_CODE_PATH, CBM_LANG_ASCIIDOC, "code_path", false, false, "MENTIONS") \+ X(CBM_DOCLINK_ADOC_CODE_NAME, CBM_LANG_ASCIIDOC, "code_name", false, false, "MENTIONS") \+ /* any language (CBM_LANG_COUNT): a URL is never an edge */ \X(CBM_DOCLINK_HREF, CBM_LANG_COUNT, "href", true, false, "MENTIONS")typedef enum {diff --git a/tests/test_doc_links_adoc.c b/tests/test_doc_links_adoc.cindex 97cd5999e..bf3200e3c 100644--- a/tests/test_doc_links_adoc.c+++ b/tests/test_doc_links_adoc.c@@ -280,8 +280,10 @@ TEST(adoc_links_incremental) {}SUITE(doc_links_adoc) {+ dm_ship_held_families();RUN_TEST(adoc_scan_structure);RUN_TEST(adoc_antora_scope_blob);RUN_TEST(adoc_links_pipeline);RUN_TEST(adoc_links_incremental);+ cbm_doclink_test_reset_ships();}diff --git a/tests/test_doc_links_md.c b/tests/test_doc_links_md.cindex 0a63f735e..378324eda 100644--- a/tests/test_doc_links_md.c+++ b/tests/test_doc_links_md.c@@ -573,11 +573,42 @@ TEST(doc_links_md_adr) {PASS();}+/* The production gate (doclink.h): families held back by the held-out audit+ * write rows, not edges; the families that passed still write edges. */+TEST(doc_links_md_ship_gate) {+ for (size_t i = 0; i < sizeof(DM_HELD_FAMILIES) / sizeof(DM_HELD_FAMILIES[0]); i++) {+ ASSERT_FALSE(cbm_doclink_syntax_ships(DM_HELD_FAMILIES[i]));+ }+ ASSERT_TRUE(cbm_doclink_syntax_ships(CBM_DOCLINK_MD_LINK));+ ASSERT_TRUE(cbm_doclink_syntax_ships(CBM_DOCLINK_RST_ROLE));+ ASSERT_TRUE(cbm_doclink_syntax_ships(CBM_DOCLINK_ADOC_INCLUDE));+ char tmp[256];+ snprintf(tmp, sizeof(tmp), "/tmp/cbm_dlmdgate_XXXXXX");+ ASSERT_NOT_NULL(cbm_mkdtemp(tmp));+ md_write_fixture(tmp);+ char db[512];+ snprintf(db, sizeof(db), "%s/md.db", tmp);+ ASSERT_EQ(dm_index(tmp, db, NULL), 0);+ char props[512];+ ASSERT_EQ(md_edge(db, "Guide", "config.go.__file__", props, sizeof(props)), 1);+ ASSERT_EQ(md_edge(db, "Paths", "APIRouter.add", props, sizeof(props)), 0);+ ASSERT_TRUE(dm_count(db, "SELECT COUNT(*) FROM doc_link_unresolved WHERE "+ "reason = 'below_bar_tier' AND syntax = 'code_path'") > 0);+ ASSERT_EQ(dm_count(db, "SELECT COUNT(*) FROM edges WHERE type = 'MENTIONS' AND "+ "properties LIKE '%\"syntax\":\"code_path\"%'"),+ 0);+ th_cleanup(tmp);+ PASS();+}+SUITE(doc_links_md) {+ dm_ship_held_families();RUN_TEST(doc_links_md_extract_tokens);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_incremental);RUN_TEST(doc_links_md_adr);+ cbm_doclink_test_reset_ships();+ RUN_TEST(doc_links_md_ship_gate);}diff --git a/tests/test_doc_links_rst.c b/tests/test_doc_links_rst.cindex 98afb9a95..2ec9b2428 100644--- a/tests/test_doc_links_rst.c+++ b/tests/test_doc_links_rst.c@@ -446,9 +446,11 @@ TEST(rst_links_incremental) {}SUITE(doc_links_rst) {+ dm_ship_held_families();RUN_TEST(rst_scan_structure);RUN_TEST(rst_python_scope_blob);RUN_TEST(rst_links_pipeline);RUN_TEST(rst_adr_record);RUN_TEST(rst_links_incremental);+ cbm_doclink_test_reset_ships();}diff --git a/tests/test_doc_mentions_helpers.h b/tests/test_doc_mentions_helpers.hindex 66fbcd52c..fc02b177f 100644--- a/tests/test_doc_mentions_helpers.h+++ b/tests/test_doc_mentions_helpers.h@@ -411,4 +411,21 @@ static inline int dm_reason_lines(const char *db, const char *block) {return n;}+/* The document families held back from shipping (doclink.h: below the held-out+ * audit's bar, or not yet audited). Their resolution is tested with them on,+ * so it is the resolution an audit would ship; doc_links_md_ship_gate tests+ * the production gate itself. */+static const int DM_HELD_FAMILIES[] = {+ CBM_DOCLINK_MD_CODE_PATH, CBM_DOCLINK_MD_SUPERSEDES, CBM_DOCLINK_RST_OBJECT,+ CBM_DOCLINK_RST_INCLUDE, CBM_DOCLINK_RST_LITERALINCLUDE, CBM_DOCLINK_RST_KERNEL_DOC,+ CBM_DOCLINK_RST_CODE_PATH, CBM_DOCLINK_ADOC_ATTRIBUTE, CBM_DOCLINK_ADOC_CODE_PATH,+ CBM_DOCLINK_ADOC_CODE_NAME,+};++static inline void dm_ship_held_families(void) {+ for (size_t i = 0; i < sizeof(DM_HELD_FAMILIES) / sizeof(DM_HELD_FAMILIES[0]); i++) {+ cbm_doclink_test_set_ships(DM_HELD_FAMILIES[i], true);+ }+}+#endif /* TEST_DOC_MENTIONS_HELPERS_H */