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.

incremental(doc-links): documents bound by lines re-resolve on a body edit

Martin Vogelc2c87f6202d9
diff --git a/src/pipeline/doc_links.c b/src/pipeline/doc_links.c
index f3b8f228d..71159220d 100644
--- a/src/pipeline/doc_links.c
+++ b/src/pipeline/doc_links.c
@@ -92,6 +92,10 @@ static const cbm_doclink_resolver_t *resolver_of_scope(const char *scope) {
/* ── Incremental scope rules ─────────────────────────────────────── */
+bool cbm_doclinks_binds_lines(CBMLanguage lang) {
+ return lang == CBM_LANG_MARKDOWN || lang == CBM_LANG_RST;
+}
+
bool cbm_doclinks_is_scope_input(const char *rel_path) {
for (int i = 0; rel_path && i < DOCLINK_RESOLVER_COUNT; i++) {
if (DOCLINK_RESOLVERS[i]->scope_input && DOCLINK_RESOLVERS[i]->scope_input(rel_path)) {
diff --git a/src/pipeline/doc_links.h b/src/pipeline/doc_links.h
index 8ad2384d4..ec1416f27 100644
--- a/src/pipeline/doc_links.h
+++ b/src/pipeline/doc_links.h
@@ -277,6 +277,12 @@ bool cbm_doclink_cs_test_scope_parses(const char *scope);
void cbm_doclink_cs_test_unit_memo(bool on);
#endif
+/* True for a document language whose references may bind the LINES of a file
+ * (Markdown `file#L3-L9`, reST :lines:): a body edit of that file keeps its
+ * names but can move what those lines hold, so an incremental run
+ * re-resolves such documents with the edited file. */
+bool cbm_doclinks_binds_lines(CBMLanguage lang);
+
/* True when `rel_path` is a scope input of some language (scope_input). */
bool cbm_doclinks_is_scope_input(const char *rel_path);
diff --git a/src/pipeline/pipeline_incremental.c b/src/pipeline/pipeline_incremental.c
index 03ccf415b..bc3beb7e6 100644
--- a/src/pipeline/pipeline_incremental.c
+++ b/src/pipeline/pipeline_incremental.c
@@ -2363,6 +2363,12 @@ static int closure_try_plan(cbm_pipeline_t *p, cbm_store_t *store, const char *p
char **changed_paths = NULL;
char **dependents = NULL;
int dependent_count = 0;
+ /* body-edited files (surface unchanged) and the documents bound to their
+ * lines, which re-resolve with them */
+ const char **body_targets = NULL;
+ int body_target_count = 0;
+ char **line_docs = NULL;
+ int line_doc_count = 0;
cbm_lsp_surface_row_t *probe_rows = NULL;
int probe_count = 0;
cbm_file_info_t *probe_files = NULL;
@@ -2529,13 +2535,15 @@ static int closure_try_plan(cbm_pipeline_t *p, cbm_store_t *store, const char *p
/* Early cutoff per changed file; surface-changed files seed the
* dependent query. Deleted files always seed it. */
int n_surface_changed = 0;
+ /* dep_targets, then the body-edited files (body_targets) in the same block */
const char **dep_targets =
- (const char **)calloc((size_t)(n_changed + n_deleted), sizeof(char *));
+ (const char **)calloc((size_t)(n_changed + n_deleted + n_changed), sizeof(char *));
if (!dep_targets) {
cbm_ht_free(rows_by_path);
decline = "alloc";
goto done;
}
+ body_targets = dep_targets + n_changed + n_deleted;
int dep_target_count = 0;
for (int i = 0; i < n_changed; i++) {
const cbm_lsp_surface_row_t *stored_row = cbm_ht_get(rows_by_path, changed_paths[i]);
@@ -2553,7 +2561,10 @@ static int closure_try_plan(cbm_pipeline_t *p, cbm_store_t *store, const char *p
goto done;
}
if (strcmp(stored_row->surface_sha, fresh_row->surface_sha) == 0) {
- continue; /* body edit: the file re-resolves, nobody else does */
+ /* body edit: the file re-resolves, and of the others only the
+ * documents bound to its lines (below) */
+ body_targets[body_target_count++] = changed_paths[i];
+ continue;
}
bool added = false;
const char *why = NULL;
@@ -2583,14 +2594,23 @@ static int closure_try_plan(cbm_pipeline_t *p, cbm_store_t *store, const char *p
}
cbm_ht_free(rows_by_path);
- if (dep_target_count > 0 &&
- cbm_store_get_dependent_files(store, project, dep_targets, dep_target_count, &dependents,
- &dependent_count) != CBM_STORE_OK) {
- free(dep_targets);
+ /* A body edit keeps a file's names but moves its lines: a document that
+ * bound a reference by lines (`file#L3-L9`, :lines:) would keep a stale
+ * target, so the documents with edges into a body-edited file re-resolve
+ * too (added to the closure below). */
+ bool dep_failed =
+ (dep_target_count > 0 &&
+ cbm_store_get_dependent_files(store, project, dep_targets, dep_target_count, &dependents,
+ &dependent_count) != CBM_STORE_OK) ||
+ (body_target_count > 0 &&
+ cbm_store_get_dependent_files(store, project, body_targets, body_target_count, &line_docs,
+ &line_doc_count) != CBM_STORE_OK);
+ free(dep_targets); /* body_targets with it */
+ body_targets = NULL;
+ if (dep_failed) {
decline = "dependent_query_failed";
goto done;
}
- free(dep_targets);
if (gone_scope_changed) {
decline = "doc_scope_changed";
goto done;
@@ -2618,6 +2638,16 @@ static int closure_try_plan(cbm_pipeline_t *p, cbm_store_t *store, const char *p
if (decline) {
goto done;
}
+ /* the documents bound to a body-edited file's lines; code files stay out:
+ * their references bind names, which a body edit keeps */
+ for (int i = 0; i < line_doc_count; i++) {
+ const cbm_file_info_t *info = cbm_ht_get(files_by_path, line_docs[i]);
+ if (info && cbm_doclinks_binds_lines(info->language) &&
+ !cbm_ht_get(closure_set, line_docs[i])) {
+ cbm_ht_set(closure_set, line_docs[i], line_docs[i]);
+ n_row_dependents++;
+ }
+ }
/* Files whose unresolved doc-link references name something a changed or
* deleted file no longer declares re-resolve too. */
doc_row_name_dependents(plan->doc_rows, plan->doc_row_count, removed_names, row_deps);
@@ -2665,6 +2695,7 @@ done:
free(probe_files);
cbm_store_free_lsp_surfaces(probe_rows, probe_count);
cbm_store_free_dependent_files(dependents, dependent_count);
+ cbm_store_free_dependent_files(line_docs, line_doc_count);
free(changed_paths);
cbm_ht_free(fresh_by_path);
cbm_ht_free(files_by_path);
diff --git a/tests/test_doc_links_md.c b/tests/test_doc_links_md.c
index 4ec817f8a..0a63f735e 100644
--- a/tests/test_doc_links_md.c
+++ b/tests/test_doc_links_md.c
@@ -24,34 +24,34 @@
/* ── the fixture ─────────────────────────────────────────────────── */
/* docs/guide.md, line by line (the line numbers are asserted below). */
-static const char
- MD_GUIDE[] = "Intro names `pkg/config.go` before any heading.\n" /* 1 */
- "\n" /* 2 */
- "# Guide\n" /* 3 */
- "\n" /* 4 */
- "See [the config](../pkg/config.go) and [routing][r].\n" /* 5 */
- "\n" /* 6 */
- "[r]: ../app/routing.py\n" /* 7 */
- "\n" /* 8 */
- "## Paths\n" /* 9 */
- "\n" /* 10 */
- "Range `app/routing.py#L4-L5`, span `app/routing.py:1-9`, bare "
- "app/applications.py.\n" /* 11 */
- "Dir `app/middleware/`, route `/docs`, ![x](img/a.png) and "
- "https://example.org/a/b.py.\n" /* 12 */
- "\n" /* 13 */
- "## Names\n" /* 14 */
- "\n" /* 15 */
- "Use `app.routing.APIRouter.add`, `app.middleware`, `pkg.Config.Name`, "
- "`self.Name`.\n" /* 16 */
- "Also `os.path.join`, `app.Nope`, `test_routing.only_in_tests`, `main.py`, "
- "`../app/gone.py`.\n" /* 17 */
- "\n" /* 18 */
- "```\n" /* 19 */
- "`app/fenced.py` inside a fence\n" /* 20 */
- "```\n" /* 21 */
- "<!-- `app/commented.py` in a comment -->\n" /* 22 */
- "<code>app/html.py</code> in HTML, `cfg.Name` through an instance.\n"; /* 23 */
+static const char MD_GUIDE[] =
+ "Intro names `pkg/config.go` before any heading.\n" /* 1 */
+ "\n" /* 2 */
+ "# Guide\n" /* 3 */
+ "\n" /* 4 */
+ "See [the config](../pkg/config.go) and [routing][r].\n" /* 5 */
+ "\n" /* 6 */
+ "[r]: ../app/routing.py\n" /* 7 */
+ "\n" /* 8 */
+ "## Paths\n" /* 9 */
+ "\n" /* 10 */
+ "Range `app/routing.py#L4-L5`, span `app/routing.py:1-9`, bare "
+ "app/applications.py.\n" /* 11 */
+ "Dir `app/middleware/`, route `/docs`, ![x](img/a.png) and "
+ "https://example.org/a/b.py.\n" /* 12 */
+ "\n" /* 13 */
+ "## Names\n" /* 14 */
+ "\n" /* 15 */
+ "Use `app.routing.APIRouter.add`, `app.middleware`, `pkg.Config.Name`, "
+ "`self.Name`.\n" /* 16 */
+ "Also `os.path.join`, `app.Nope`, `test_routing.only_in_tests`, `main.py`, "
+ "`../app/gone.py`.\n" /* 17 */
+ "\n" /* 18 */
+ "```\n" /* 19 */
+ "`app/fenced.py` inside a fence\n" /* 20 */
+ "```\n" /* 21 */
+ "<!-- `app/commented.py` in a comment -->\n" /* 22 */
+ "<code>app/html.py</code> in HTML, `cfg.Name` through an instance.\n"; /* 23 */
static void md_write_fixture(const char *tmp) {
th_write_file(TH_PATH(tmp, "docs/guide.md"), MD_GUIDE);
@@ -400,6 +400,20 @@ TEST(doc_links_md_incremental) {
snprintf(guide, sizeof(guide), "%s\nSee also [helpers](../app/routing.py#L8-L9).\n", MD_GUIDE);
th_write_file(TH_PATH(repo, "docs/guide.md"), guide);
ASSERT_EQ(dm_step(repo, db, full_db, "document edit", CBM_INCREMENTAL_ROUTE_CLOSURE_REPAIR), 0);
+ /* a body edit that moves lines: the document bound by lines (#L8-L9, the
+ * helper until now) re-resolves, though no name changed */
+ th_write_file(TH_PATH(repo, "app/routing.py"), "# moved\n"
+ "# down\n"
+ "class APIRouter:\n"
+ " prefix = ''\n"
+ "\n"
+ " def add(self, p):\n"
+ " return p + p\n"
+ "\n"
+ "\n"
+ "def helper():\n"
+ " return 2\n");
+ ASSERT_EQ(dm_step(repo, db, full_db, "lines moved", CBM_INCREMENTAL_ROUTE_CLOSURE_REPAIR), 0);
/* the name a row calls missing is added: the run goes FULL and the row
* becomes an edge, exactly as a full index has it */
th_write_file(TH_PATH(repo, "app/nope.py"), "def Nope():\n"
@@ -433,24 +447,23 @@ static void md_write_adrs(const char *tmp, const char *first_status) {
"Superseded by [ADR-0002](0002-use-y.md).\n",
first_status);
th_write_file(TH_PATH(tmp, "docs/adr/0001-use-x.md"), first);
- th_write_file(TH_PATH(tmp, "docs/adr/0002-use-y.md"),
- "# 2. Use Y instead\n"
- "\n"
- "Date: 12 May 2024\n"
- "\n"
- "## Status\n"
- "\n"
- "Accepted\n"
- "\n"
- "Supersedes [ADR-0001](0001-use-x.md).\n"
- "\n"
- "## Context\n"
- "\n"
- "X was slow.\n"
- "\n"
- "## Decision\n"
- "\n"
- "We use Y.\n");
+ th_write_file(TH_PATH(tmp, "docs/adr/0002-use-y.md"), "# 2. Use Y instead\n"
+ "\n"
+ "Date: 12 May 2024\n"
+ "\n"
+ "## Status\n"
+ "\n"
+ "Accepted\n"
+ "\n"
+ "Supersedes [ADR-0001](0001-use-x.md).\n"
+ "\n"
+ "## Context\n"
+ "\n"
+ "X was slow.\n"
+ "\n"
+ "## Decision\n"
+ "\n"
+ "We use Y.\n");
th_write_file(TH_PATH(tmp, "docs/adr/0003-cache.md"),
"# Cache reads\n"
"\n"
diff --git a/tests/test_doc_links_rst.c b/tests/test_doc_links_rst.c
index 160dd5581..98afb9a95 100644
--- a/tests/test_doc_links_rst.c
+++ b/tests/test_doc_links_rst.c
@@ -413,6 +413,20 @@ TEST(rst_links_incremental) {
snprintf(full_db, sizeof(full_db), "%s/full.db", tmp);
rst_write_repo(repo, INIT_PY);
ASSERT_EQ(dm_index(repo, db, NULL), 0);
+ ASSERT_TRUE(rst_edge(db, "docs.api.Code", "pkg.base.Model.save", "\"target_lines\":[2,3]"));
+ /* a body edit moves the lines a literalinclude names: the document
+ * re-resolves with the code file (its names did not change) */
+ th_write_file(TH_PATH(repo, "pkg/base.py"), "# moved\n"
+ "# down\n"
+ "class Model:\n"
+ " def save(self):\n"
+ " return None\n"
+ "\n"
+ "\n"
+ "def top():\n"
+ " return 1\n");
+ ASSERT_EQ(dm_step(repo, db, full_db, "lines moved", CBM_INCREMENTAL_ROUTE_CLOSURE_REPAIR), 0);
+ ASSERT_FALSE(rst_edge(db, "docs.api.Code", "pkg.base.Model.save", "\"target_lines\":[2,3]"));
/* the document changes alone: it re-resolves through the stored re-exports */
th_write_file(TH_PATH(repo, "docs/api.rst"), "Models\n"
"======\n"