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.

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.h
index 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.c
index 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.c
index 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.c
index 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.h
index 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 */