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(md): a code name never binds a JVM package folder

Martin Vogel190ac6bb3011
diff --git a/src/pipeline/doc_links_md.c b/src/pipeline/doc_links_md.c
index bb396d5cb..4eaee1ce8 100644
--- a/src/pipeline/doc_links_md.c
+++ b/src/pipeline/doc_links_md.c
@@ -770,6 +770,32 @@ static bool mdr_c_family_file(const char *path) {
return mdr_ext_in(path, exts);
}
+/* Is `dir` a JVM package folder: is the first code definition at or below it
+ * in a Java/Kotlin/Scala/Groovy file? A dotted name in documentation that
+ * matches such a folder is far more often a configuration key, an OSGi or JMX
+ * id or a Maven coordinate than the package (`snapshot.mode` of
+ * io/debezium/snapshot/mode), so a code name never binds one; a Python
+ * package is what its dotted name says and keeps binding. */
+static bool mdr_jvm_folder(const mdr_index_t *x, const char *dir) {
+ char prefix[MDR_PATH_CAP];
+ int n = snprintf(prefix, sizeof(prefix), "%s/", dir);
+ if (n < 0 || (size_t)n >= sizeof(prefix)) {
+ return false;
+ }
+ int a = 0;
+ int b = x->ndefs;
+ while (a < b) {
+ int mid = a + ((b - a) / PAIR_LEN);
+ if (strcmp(x->defs[mid].file, prefix) < 0) {
+ a = mid + SKIP_ONE;
+ } else {
+ b = mid;
+ }
+ }
+ return a < x->ndefs && strncmp(x->defs[a].file, prefix, (size_t)n) == 0 &&
+ mdr_jvm_file(x->defs[a].file);
+}
+
/* A repository can carry several copies of one project (snapshots side by
* side, a vendored copy). A definition of another copy never answers the
* document: below the directory where the document's path and the file's part,
@@ -1009,9 +1035,12 @@ static void mdr_resolve_name(const mdr_index_t *x, const cbm_gbuf_t *graph, cons
if (!exact && !mdr_chain_match(m->chain, cl, &q, nq, false, false, &left)) {
continue;
}
- bool refused = mfile && ((std_root && mdr_c_family_file(mfile)) ||
- (jvm_root && mdr_jvm_file(mfile) && !mdr_rooted(m->chain, left)) ||
- mdr_other_copy(x, doc, mfile));
+ bool refused =
+ mfile && ((std_root && mdr_c_family_file(mfile)) ||
+ (jvm_root && mdr_jvm_file(mfile) && !mdr_rooted(m->chain, left)) ||
+ mdr_other_copy(x, doc, mfile) ||
+ (!m->file && m->node->label && strcmp(m->node->label, "Folder") == 0 &&
+ mdr_jvm_folder(x, mfile)));
if (!doc_test && mdr_test_path(m->file ? m->file : m->node->file_path)) {
test_hits++;
continue;
diff --git a/tests/test_doc_links_md.c b/tests/test_doc_links_md.c
index f9793e1a0..2b66e63bd 100644
--- a/tests/test_doc_links_md.c
+++ b/tests/test_doc_links_md.c
@@ -820,6 +820,15 @@ TEST(doc_links_md_name_scope_rules) {
"# Debug\n\nCall `Debug.log`.\n");
th_write_file(TH_PATH(tmp, "v2/docs/design.md"), "# Design\n\nThe `Store.Reader` reads.\n");
th_write_file(TH_PATH(tmp, "v1/docs/notes.md"), "# Notes\n\nThe `Store.Reader` reads.\n");
+ /* a configuration key that spells a Java package's tail; a Python package */
+ th_write_file(TH_PATH(tmp, "core/src/main/java/io/acme/snapshot/mode/SnapshotMode.java"),
+ "package io.acme.snapshot.mode;\npublic enum SnapshotMode { INITIAL }\n");
+ th_write_file(TH_PATH(tmp, "pyapp/__init__.py"), "");
+ th_write_file(TH_PATH(tmp, "pyapp/sub/__init__.py"), "from .core import run\n");
+ th_write_file(TH_PATH(tmp, "pyapp/sub/core.py"), "def run():\n return 1\n");
+ th_write_file(TH_PATH(tmp, "docs/config.md"),
+ "# Config\n\nSet `snapshot.mode` to `initial`.\n\n"
+ "# Py\n\nThe `pyapp.sub` package runs it.\n");
char db[512];
snprintf(db, sizeof(db), "%s/md.db", tmp);
ASSERT_EQ(dm_index(tmp, db, NULL), 0);
@@ -832,6 +841,8 @@ TEST(doc_links_md_name_scope_rules) {
ASSERT_EQ(md_edge(db, "guide.Debug", "Debug.log", props, sizeof(props)), 1);
ASSERT_EQ(md_edge(db, "design.Design", "Store.Reader", props, sizeof(props)), 0);
ASSERT_EQ(md_edge(db, "notes.Notes", "Store.Reader", props, sizeof(props)), 1);
+ ASSERT_EQ(md_edge(db, "config.Config", "snapshot.mode", props, sizeof(props)), 0);
+ ASSERT_EQ(md_edge(db, "config.Py", "sub.__init__.py.__file__", props, sizeof(props)), 1);
th_cleanup(tmp);
PASS();
}