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
feat(docs): a section's text keeps its diagram's labels, not its syntax
Martin Vogelabf65583e313
diff --git a/internal/cbm/cbm.h b/internal/cbm/cbm.hindex 7d3bf15a0..f5b90a1f5 100644--- a/internal/cbm/cbm.h+++ b/internal/cbm/cbm.h@@ -1167,6 +1167,11 @@ void cbm_extract_channels(CBMExtractCtx *ctx);* or AsciiDoc block, or a diagram file -- with a DiagramElement definition per* element and the arrows between them. */void cbm_extract_diagrams(CBMExtractCtx *ctx);+/* Is a Markdown block a diagram fence, and the labels its parser reads from+ * it (space-joined; NULL for none): a Section's text keeps those labels in+ * place of the fence (extract_markdown_section_body). */+bool cbm_diagram_fence_is_diagram(const char *source, TSNode block);+const char *cbm_diagram_fence_labels(CBMExtractCtx *ctx, TSNode block);/* A diagram file (CBM_LANG_DIAGRAM): its format comes from its extension. */void cbm_extract_diagram_file(CBMExtractCtx *ctx);diff --git a/internal/cbm/diagram.c b/internal/cbm/diagram.cindex 228c3ca67..cdd3785f4 100644--- a/internal/cbm/diagram.c+++ b/internal/cbm/diagram.c@@ -2813,24 +2813,31 @@ static bool dg_kind(TSNode n, const char *k) {return !ts_node_is_null(n) && strcmp(ts_node_type(n), k) == 0;}-/* A fenced block of a Markdown file: a diagram when its info string says so. */-static void dg_markdown_fence(CBMExtractCtx *ctx, TSNode block, dg_ordinal_t *ords, int *nords) {+/* The diagram format a Markdown fenced block's info string names, NULL for+ * none; *content is the block's text. */+static const char *dg_fence_format(const char *source, TSNode block, TSNode *content) {TSNode info = {0};- TSNode content = {0};+ *content = (TSNode){0};uint32_t nc = ts_node_named_child_count(block);for (uint32_t i = 0; i < nc; i++) {TSNode c = ts_node_named_child(block, i);info = dg_kind(c, "info_string") ? c : info;- content = dg_kind(c, "code_fence_content") ? c : content;+ *content = dg_kind(c, "code_fence_content") ? c : *content;}- if (ts_node_is_null(info) || ts_node_is_null(content)) {- return;+ if (ts_node_is_null(info) || ts_node_is_null(*content)) {+ return NULL;}TSNode lang = ts_node_named_child(info, 0);TSNode word = dg_kind(lang, "language") ? lang : info;uint32_t wb = ts_node_start_byte(word);uint32_t we = ts_node_end_byte(word);- const char *format = dg_format_of(ctx->source + wb, we - wb);+ return dg_format_of(source + wb, we - wb);+}++/* A fenced block of a Markdown file: a diagram when its info string says so. */+static void dg_markdown_fence(CBMExtractCtx *ctx, TSNode block, dg_ordinal_t *ords, int *nords) {+ TSNode content;+ const char *format = dg_fence_format(ctx->source, block, &content);if (!format) {return;}@@ -3508,6 +3515,77 @@ void cbm_extract_diagram_file(CBMExtractCtx *ctx) {}}+/* ── What a Markdown section's text keeps of its diagram fences ───── */++bool cbm_diagram_fence_is_diagram(const char *source, TSNode block) {+ TSNode content;+ return dg_kind(block, "fenced_code_block") && dg_fence_format(source, block, &content);+}++/* The labels of one Markdown diagram fence, space-joined in source order: the+ * DiagramElement names and arrow texts its parser produces, without the+ * format's syntax. The parse runs into a scratch result, so the file's own+ * definitions are untouched. NULL when the fence says nothing. */+const char *cbm_diagram_fence_labels(CBMExtractCtx *ctx, TSNode block) {+ TSNode content;+ const char *format = dg_fence_format(ctx->source, block, &content);+ if (!format) {+ return NULL;+ }+ CBMFileResult scratch;+ memset(&scratch, 0, sizeof(scratch));+ CBMExtractCtx sc = *ctx;+ sc.result = &scratch;+ uint32_t cb = ts_node_start_byte(content);+ dg_source_t src = {+ .format = format,+ .parent_qn = "e1",+ .ordinal = SKIP_ONE,+ .text = ctx->source + cb,+ .len = ts_node_end_byte(content) - cb,+ .first_line = ts_node_start_point(content).row + SKIP_ONE,+ .start_line = ts_node_start_point(block).row + SKIP_ONE,+ .end_line = ts_node_end_point(block).row + SKIP_ONE,+ };+ dg_build(&sc, &src);+ size_t total = 0;+ for (int i = 0; i < scratch.defs.count; i++) {+ const CBMDefinition *d = &scratch.defs.items[i];+ if (d->name && d->label && strcmp(d->label, "DiagramElement") == 0) {+ total += strlen(d->name) + SKIP_ONE;+ }+ }+ for (int i = 0; i < scratch.diagram_arrows.count; i++) {+ const char *l = scratch.diagram_arrows.items[i].label;+ total += l ? strlen(l) + SKIP_ONE : 0;+ }+ char *out = total ? (char *)cbm_arena_alloc(ctx->arena, total + SKIP_ONE) : NULL;+ if (!out) {+ return NULL;+ }+ size_t w = 0;+ for (int i = 0; i < scratch.defs.count; i++) {+ const CBMDefinition *d = &scratch.defs.items[i];+ if (d->name && d->label && strcmp(d->label, "DiagramElement") == 0) {+ size_t l = strlen(d->name);+ memcpy(out + w, d->name, l);+ w += l;+ out[w++] = ' ';+ }+ }+ for (int i = 0; i < scratch.diagram_arrows.count; i++) {+ const char *l = scratch.diagram_arrows.items[i].label;+ if (l) {+ size_t n = strlen(l);+ memcpy(out + w, l, n);+ w += n;+ out[w++] = ' ';+ }+ }+ out[w] = '\0';+ return out;+}+void cbm_extract_diagrams(CBMExtractCtx *ctx) {if (!ctx || !ctx->result || !ctx->source) {return;diff --git a/internal/cbm/extract_defs.c b/internal/cbm/extract_defs.cindex 5917c0804..e046bca83 100644--- a/internal/cbm/extract_defs.c+++ b/internal/cbm/extract_defs.c@@ -6840,10 +6840,22 @@ static bool is_markdown_heading_kind(const char *kind) {* with nested subsections as further `section` children that own their own* text. Stopping at either a `section` or another heading therefore gives each* Section exactly its OWN body under both that shape and a flat one. The bytes- * between are contiguous in the source, so one slice beats concatenation. */-static const char *extract_markdown_section_body(CBMArena *a, TSNode heading, const char *source) {+ * between are contiguous in the source, so one slice beats concatenation.+ *+ * A top-level diagram fence (```mermaid, plantuml, dot, d2 ...) is the one+ * exception: the body keeps the labels its diagram parser reads, not the+ * format's syntax. Arrows and keywords (`-->`, `participant`, `classDiagram`)+ * name no code and crowd the prose out of the 500-byte cap, while the labels+ * are what name the code. Judged on held-out sections that embed diagrams,+ * labels gave more sections a correct code candidate (56 vs 42 of 147) at a+ * higher precision (0.54 vs 0.45) than the fence as written; dropping the+ * fence lost candidates (29). The diagram itself keeps its own nodes. */+static const char *extract_markdown_section_body(CBMExtractCtx *ctx, TSNode heading) {+ CBMArena *a = ctx->arena;+ const char *source = ctx->source;uint32_t start = ts_node_end_byte(heading);uint32_t end = start;+ int fences = 0;for (TSNode sib = ts_node_next_sibling(heading); !ts_node_is_null(sib);sib = ts_node_next_sibling(sib)) {const char *sk = ts_node_type(sib);@@ -6851,11 +6863,57 @@ static const char *extract_markdown_section_body(CBMArena *a, TSNode heading, cobreak;}end = ts_node_end_byte(sib);+ fences += cbm_diagram_fence_is_diagram(source, sib);}if (end <= start) {return NULL;}- return collapse_prose(a, source + start, (size_t)(end - start));+ if (fences == 0) {+ return collapse_prose(a, source + start, (size_t)(end - start));+ }+ /* The body with each diagram fence replaced by its labels. */+ const char **labels = (const char **)cbm_arena_alloc(a, (size_t)fences * sizeof(char *));+ if (!labels) {+ return NULL;+ }+ size_t total = 0;+ int k = 0;+ for (TSNode sib = ts_node_next_sibling(heading); !ts_node_is_null(sib) && k < fences;+ sib = ts_node_next_sibling(sib)) {+ if (cbm_diagram_fence_is_diagram(source, sib)) {+ labels[k] = cbm_diagram_fence_labels(ctx, sib);+ total += labels[k] ? strlen(labels[k]) + SKIP_ONE : 0;+ k++;+ }+ }+ char *buf = (char *)cbm_arena_alloc(a, (size_t)(end - start) + total + SKIP_ONE);+ if (!buf) {+ return NULL;+ }+ size_t w = 0;+ uint32_t prev = start;+ k = 0;+ for (TSNode sib = ts_node_next_sibling(heading); !ts_node_is_null(sib) && k < fences;+ sib = ts_node_next_sibling(sib)) {+ if (!cbm_diagram_fence_is_diagram(source, sib)) {+ continue;+ }+ uint32_t sb = ts_node_start_byte(sib);+ memcpy(buf + w, source + prev, sb - prev);+ w += sb - prev;+ if (labels[k]) {+ size_t n = strlen(labels[k]);+ memcpy(buf + w, labels[k], n);+ w += n;+ buf[w++] = ' ';+ }+ k++;+ prev = ts_node_end_byte(sib);+ }+ memcpy(buf + w, source + prev, end - prev);+ w += end - prev;+ buf[w] = '\0';+ return collapse_prose(a, buf, w);}/* Push a config-language definition that carries prose. push_simple_class_def@@ -7055,7 +7113,7 @@ static bool extract_config_class_def(CBMExtractCtx *ctx, TSNode node, const char// "Class"; that assertion is the inaccurate side and is flagged for review.label = "Section";// #518: index what the section SAYS, not just its title.- docstring = extract_markdown_section_body(a, node, ctx->source);+ docstring = extract_markdown_section_body(ctx, node);} else if (ctx->language == CBM_LANG_HCL && strcmp(kind, "block") == 0) {name = find_hcl_block_name(a, node, ctx->source);} else {diff --git a/tests/test_diagrams.c b/tests/test_diagrams.cindex 42e2115f0..574f27148 100644--- a/tests/test_diagrams.c+++ b/tests/test_diagrams.c@@ -136,6 +136,57 @@ TEST(diagrams_markdown_mermaid) {PASS();}+/* A Section's text keeps a diagram fence's labels, not the format's syntax;+ * prose around it stays in order, other fences stay as written. */+TEST(diagrams_section_text_keeps_labels) {+ CBMFileResult *r = dm_extract(DG_DOC, CBM_LANG_MARKDOWN, "docs/arch.md");+ ASSERT_NOT_NULL(r);+ const CBMDefinition *arch = dg_def(r, ".Arch");+ ASSERT_NOT_NULL(arch);+ ASSERT_STR_EQ(arch->label, "Section");+ const char *doc = arch->docstring;+ ASSERT_NOT_NULL(doc);+ const char *kept[] = {"Web app", "API", "DB", "Cache", "Backend", "calls",+ "retries", "User", "login", "token", NULL};+ for (int i = 0; kept[i]; i++) {+ if (!strstr(doc, kept[i])) {+ printf(" label %s missing from: %s\n", kept[i], doc);+ }+ ASSERT(strstr(doc, kept[i]) != NULL);+ }+ const char *dropped[] = {"```", "mermaid", "flowchart", "-->", "sequenceDiagram",+ "participant", "subgraph", NULL};+ for (int i = 0; dropped[i]; i++) {+ if (strstr(doc, dropped[i])) {+ printf(" syntax %s kept in: %s\n", dropped[i], doc);+ }+ ASSERT(strstr(doc, dropped[i]) == NULL);+ }+ ASSERT_STR_EQ(dg_def(r, ".Doc")->docstring, "Intro."); /* no fence: as before */+ cbm_free_result(r);++ r = dm_extract("# Mixed\n"+ "\n"+ "Before.\n"+ "\n"+ "```mermaid\n"+ "flowchart LR\n"+ " A[Login] --> B[Session]\n"+ "```\n"+ "\n"+ "```python\n"+ "x = 1\n"+ "```\n"+ "\n"+ "After.\n",+ CBM_LANG_MARKDOWN, "docs/mixed.md");+ ASSERT_NOT_NULL(r);+ ASSERT_STR_EQ(dg_def(r, ".Mixed")->docstring,+ "Before. Login Session ```python x = 1 ``` After.");+ cbm_free_result(r);+ PASS();+}+TEST(diagrams_mermaid_kinds) {CBMFileResult *r = dm_extract("erDiagram\n"" CUSTOMER ||--o{ ORDER : places\n"@@ -1046,6 +1097,7 @@ TEST(diagrams_incremental_equals_full) {SUITE(diagrams) {RUN_TEST(diagrams_markdown_mermaid);+ RUN_TEST(diagrams_section_text_keeps_labels);RUN_TEST(diagrams_mermaid_kinds);RUN_TEST(diagrams_other_fences);RUN_TEST(diagrams_plantuml);