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
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.cindex 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.hindex 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.cindex 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 *pchar **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 *pgoto 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 *pif (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.cindex 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`,  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`,  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.cindex 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"