Skip to content

Commit 9129898

Browse files
blineclaude
andcommitted
fix(markdown): qualify a repeated heading's Section by its parent headings (DeusData#2586)
A Section's qualified name is the file's module plus the heading text, so two `## Implementation` headings under `# Service A` and `# Service B` had one qualified name. The graph kept one node (the last), and doclink_md sent the references under both headings to the File node, since neither heading owned the shared node. A heading whose name repeats in the file now takes the names of the headings above it into its qualified name (`docs.repeated.Service-A.Implementation`). tree-sitter-markdown nests each heading's `section` in the section of the heading above it, so the chain is read from the tree. A heading whose name is unique in the file keeps its name alone, so no other Section is renamed. Headings that repeat under the same parents still share a name and keep the existing File fallback (doc_links_md_repeated_headings is unchanged). A heading text may hold dots, so a qualified name can equal another heading's name: `# Service-A.Implementation` against the qualified `## Implementation` under `# Service A`. All of a file's final names are therefore settled together, once per file on its first heading, in the scratch arena. A unique heading keeps its name, or else the first qualified one does, and every other qualified name in the collision takes the first free `~2`, `~3`, .... Names collide only when they come from different headings: the comparison is on the list of heading names, not on the dotted text. Diagrams find their Section through the definition list, so a diagram under a repeated heading now hangs off that heading's own Section. Tests (tests/test_doc_links_md.c): the document from the issue, with a Mermaid diagram under the second heading. Without the fix it fails on the defect: one `Implementation` Section where there are two. The same document plus `# Service-A.Implementation` requires five Sections, the unique heading keeping its name. Without the collision handling it fails with four. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Scott Beck <296871+bline@users.noreply.github.com>
1 parent 0ca6e7d commit 9129898

3 files changed

Lines changed: 394 additions & 4 deletions

File tree

‎internal/cbm/cbm.h‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1021,6 +1021,9 @@ typedef struct {
10211021
* POD section index. */
10221022
void *doc_memo;
10231023
void *doc_pod_index;
1024+
/* Markdown: the sorted names of the file's headings (extract_defs.c),
1025+
* NULL until the first heading; allocated in `scratch`. */
1026+
void *md_headings;
10241027
const cbm_test_declarations_t *test_declarations; /* borrowed for this call only */
10251028
bool test_declarations_raw_source;
10261029
struct CBMTestDefinitionMatch *test_definition_matches; /* traversal scratch */

‎internal/cbm/extract_defs.c‎

Lines changed: 239 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7030,13 +7030,15 @@ static const char *extract_markdown_section_body(CBMExtractCtx *ctx, TSNode head
70307030

70317031
/* Push a config-language definition that carries prose. push_simple_class_def
70327032
* delegates here with no docstring. */
7033-
static void push_simple_class_def_doc(CBMExtractCtx *ctx, TSNode node, char *name,
7034-
const char *label, const char *docstring) {
7033+
/* Push a definition whose qualified name ends with `qn_name` (already QN-safe)
7034+
* rather than with its name. */
7035+
static void push_class_def_qn(CBMExtractCtx *ctx, TSNode node, char *name, const char *qn_name,
7036+
const char *label, const char *docstring) {
70357037
CBMArena *a = ctx->arena;
70367038
CBMDefinition def;
70377039
memset(&def, 0, sizeof(def));
70387040
def.name = name;
7039-
def.qualified_name = cbm_fqn_compute(a, ctx->project, ctx->rel_path, qn_safe_segment(a, name));
7041+
def.qualified_name = cbm_fqn_compute(a, ctx->project, ctx->rel_path, qn_name);
70407042
def.label = label;
70417043
def.file_path = ctx->rel_path;
70427044
def.start_line = ts_node_start_point(node).row + TS_LINE_OFFSET;
@@ -7046,6 +7048,11 @@ static void push_simple_class_def_doc(CBMExtractCtx *ctx, TSNode node, char *nam
70467048
cbm_defs_push(&ctx->result->defs, a, def);
70477049
}
70487050

7051+
static void push_simple_class_def_doc(CBMExtractCtx *ctx, TSNode node, char *name,
7052+
const char *label, const char *docstring) {
7053+
push_class_def_qn(ctx, node, name, qn_safe_segment(ctx->arena, name), label, docstring);
7054+
}
7055+
70497056
static void push_simple_class_def(CBMExtractCtx *ctx, TSNode node, char *name, const char *label) {
70507057
push_simple_class_def_doc(ctx, node, name, label, NULL);
70517058
}
@@ -7145,6 +7152,231 @@ static char *extract_markdown_heading_name(CBMArena *a, TSNode node, const char
71457152
return trim_heading_name(name);
71467153
}
71477154

7155+
/* #2586: a heading name that repeats in a file (`## Implementation` under two
7156+
* parents) gave its Sections one qualified name, so the graph kept one node
7157+
* and the references under them fell back to the File. A repeated heading's
7158+
* qualified name therefore takes the names of the headings above it as well
7159+
* (`Service-A.Implementation`). A heading whose name is unique in the file
7160+
* keeps its name alone, always. A heading text may itself hold dots, so a
7161+
* qualified name can equal another heading's final name (`# Service-A.
7162+
* Implementation`): the qualified one then takes `~2`, `~3`, ... until no
7163+
* other heading of the file has that name. Headings that repeat under the
7164+
* same parents too still share a name, as before. All final names are
7165+
* settled once per file, on the first heading. */
7166+
typedef struct {
7167+
uint32_t start; /* the heading node's first byte */
7168+
TSNode node; /* valid while the file's tree is */
7169+
const char *seg; /* the heading's own QN-safe name */
7170+
const char *key; /* repeated only: the chain's segments, '\n'-joined */
7171+
const char *qn_name; /* the final QN segment */
7172+
bool repeated;
7173+
} md_heading_t;
7174+
7175+
typedef struct {
7176+
md_heading_t *v; /* in document order */
7177+
int count;
7178+
} md_headings_t;
7179+
7180+
/* The QN-safe name of a heading node, or NULL. */
7181+
static const char *md_heading_segment(CBMExtractCtx *ctx, CBMArena *a, TSNode node) {
7182+
const char *kind = ts_node_type(node);
7183+
if (!is_markdown_heading_kind(kind)) {
7184+
return NULL;
7185+
}
7186+
char *name = extract_markdown_heading_name(a, node, kind, ctx->source);
7187+
return name ? qn_safe_segment(a, name) : NULL;
7188+
}
7189+
7190+
/* Visit every heading of the file: count them (v NULL), or fill v. */
7191+
static int md_collect_headings(CBMExtractCtx *ctx, CBMArena *a, md_heading_t *v, int cap) {
7192+
int n = 0;
7193+
if (ts_node_is_null(ctx->root)) {
7194+
return 0;
7195+
}
7196+
TSTreeCursor cur = ts_tree_cursor_new(ctx->root);
7197+
for (;;) {
7198+
TSNode node = ts_tree_cursor_current_node(&cur);
7199+
if (is_markdown_heading_kind(ts_node_type(node))) {
7200+
if (!v) {
7201+
n++;
7202+
} else if (n < cap) {
7203+
const char *seg = md_heading_segment(ctx, a, node);
7204+
if (seg) {
7205+
v[n++] = (md_heading_t){.start = ts_node_start_byte(node),
7206+
.node = node,
7207+
.seg = seg,
7208+
.qn_name = seg};
7209+
}
7210+
}
7211+
} else if (ts_tree_cursor_goto_first_child(&cur)) {
7212+
continue;
7213+
}
7214+
while (!ts_tree_cursor_goto_next_sibling(&cur)) {
7215+
if (!ts_tree_cursor_goto_parent(&cur)) {
7216+
ts_tree_cursor_delete(&cur);
7217+
return n;
7218+
}
7219+
}
7220+
}
7221+
}
7222+
7223+
static int md_by_seg(const void *x, const void *y) {
7224+
return strcmp((*(const md_heading_t *const *)x)->seg, (*(const md_heading_t *const *)y)->seg);
7225+
}
7226+
7227+
static int md_by_name(const void *x, const void *y) {
7228+
const md_heading_t *p = *(const md_heading_t *const *)x;
7229+
const md_heading_t *q = *(const md_heading_t *const *)y;
7230+
int c = strcmp(p->qn_name, q->qn_name);
7231+
return c ? c : (p->start > q->start) - (p->start < q->start);
7232+
}
7233+
7234+
/* A repeated heading's chain: the names of the headings above it and its own,
7235+
* dot-joined (its QN segment) and '\n'-joined (its identity: a QN-safe name
7236+
* holds no whitespace). tree-sitter-markdown nests each heading's `section` in
7237+
* the section of the heading above it. False on allocation failure. */
7238+
static bool md_heading_chain(CBMExtractCtx *ctx, CBMArena *a, md_heading_t *h) {
7239+
const char *dotted = h->seg;
7240+
const char *key = h->seg;
7241+
TSNode sec = ts_node_parent(h->node);
7242+
while (!ts_node_is_null(sec) && strcmp(ts_node_type(sec), "section") == 0) {
7243+
TSNode up = ts_node_parent(sec);
7244+
if (ts_node_is_null(up) || strcmp(ts_node_type(up), "section") != 0) {
7245+
break;
7246+
}
7247+
const char *above = ts_node_named_child_count(up) > 0
7248+
? md_heading_segment(ctx, a, ts_node_named_child(up, 0))
7249+
: NULL;
7250+
if (above) {
7251+
dotted = cbm_arena_sprintf(a, "%s.%s", above, dotted);
7252+
key = cbm_arena_sprintf(a, "%s\n%s", above, key);
7253+
if (!dotted || !key) {
7254+
return false;
7255+
}
7256+
}
7257+
sec = up;
7258+
}
7259+
h->qn_name = dotted;
7260+
h->key = key;
7261+
return true;
7262+
}
7263+
7264+
static bool md_name_taken(const md_headings_t *hs, const char *name) {
7265+
for (int i = 0; i < hs->count; i++) {
7266+
if (strcmp(hs->v[i].qn_name, name) == 0) {
7267+
return true;
7268+
}
7269+
}
7270+
return false;
7271+
}
7272+
7273+
/* Within a run of headings that share a final name: a unique heading keeps
7274+
* it, or else the first chain does; every other chain takes the first free
7275+
* `~N`. Headings with one chain (the same headings) move together. */
7276+
static bool md_split_run(CBMArena *a, md_headings_t *hs, md_heading_t **run, int n) {
7277+
const char *keep = run[0]->key; /* NULL: a unique heading keeps the name */
7278+
for (int i = 0; i < n; i++) {
7279+
if (!run[i]->repeated) {
7280+
keep = NULL;
7281+
}
7282+
}
7283+
const char *base = run[0]->qn_name;
7284+
for (int i = 0; i < n; i++) {
7285+
md_heading_t *h = run[i];
7286+
if (!h->repeated || (keep && strcmp(h->key, keep) == 0) || strcmp(h->qn_name, base) != 0) {
7287+
continue; /* the name's keeper, or a chain already moved */
7288+
}
7289+
const char *name = NULL;
7290+
for (int k = PAIR_LEN; !name || md_name_taken(hs, name); k++) {
7291+
name = cbm_arena_sprintf(a, "%s~%d", base, k);
7292+
if (!name) {
7293+
return false;
7294+
}
7295+
}
7296+
for (int j = i; j < n; j++) {
7297+
if (run[j]->repeated && strcmp(run[j]->key, h->key) == 0) {
7298+
run[j]->qn_name = name;
7299+
}
7300+
}
7301+
}
7302+
return true;
7303+
}
7304+
7305+
static bool md_settle_names(CBMExtractCtx *ctx, CBMArena *a, md_headings_t *hs) {
7306+
int n = hs->count;
7307+
md_heading_t **by = (md_heading_t **)cbm_arena_alloc(a, (size_t)n * sizeof(*by));
7308+
if (!by) {
7309+
return false;
7310+
}
7311+
for (int i = 0; i < n; i++) {
7312+
by[i] = &hs->v[i];
7313+
hs->v[i].qn_name = hs->v[i].seg;
7314+
}
7315+
qsort(by, (size_t)n, sizeof(*by), md_by_seg);
7316+
for (int i = 1; i < n; i++) {
7317+
if (strcmp(by[i]->seg, by[i - SKIP_ONE]->seg) == 0) {
7318+
by[i]->repeated = by[i - SKIP_ONE]->repeated = true;
7319+
}
7320+
}
7321+
for (int i = 0; i < n; i++) {
7322+
if (hs->v[i].repeated && !md_heading_chain(ctx, a, &hs->v[i])) {
7323+
return false;
7324+
}
7325+
}
7326+
qsort(by, (size_t)n, sizeof(*by), md_by_name);
7327+
for (int i = 0; i < n;) {
7328+
int j = i + SKIP_ONE;
7329+
while (j < n && strcmp(by[j]->qn_name, by[i]->qn_name) == 0) {
7330+
j++;
7331+
}
7332+
if (j - i > SKIP_ONE && !md_split_run(a, hs, by + i, j - i)) {
7333+
return false;
7334+
}
7335+
i = j;
7336+
}
7337+
return true;
7338+
}
7339+
7340+
static const md_headings_t *md_headings(CBMExtractCtx *ctx) {
7341+
if (ctx->md_headings) {
7342+
return (const md_headings_t *)ctx->md_headings;
7343+
}
7344+
CBMArena *a = doc_scratch(ctx);
7345+
md_headings_t *hs = (md_headings_t *)cbm_arena_alloc(a, sizeof(*hs));
7346+
if (!hs) {
7347+
return NULL;
7348+
}
7349+
int cap = md_collect_headings(ctx, a, NULL, 0);
7350+
hs->v = cap > 0 ? (md_heading_t *)cbm_arena_alloc(a, (size_t)cap * sizeof(md_heading_t)) : NULL;
7351+
hs->count = hs->v ? md_collect_headings(ctx, a, hs->v, cap) : 0;
7352+
if (hs->count > SKIP_ONE && !md_settle_names(ctx, a, hs)) {
7353+
hs->count = 0; /* every heading keeps its own name, as before */
7354+
}
7355+
ctx->md_headings = hs;
7356+
return hs;
7357+
}
7358+
7359+
/* The QN segment of a heading: its own name unless the file's names say
7360+
* otherwise. */
7361+
static const char *md_heading_qn_name(CBMExtractCtx *ctx, TSNode heading, const char *seg) {
7362+
const md_headings_t *hs = md_headings(ctx);
7363+
uint32_t start = ts_node_start_byte(heading);
7364+
int lo = 0;
7365+
int hi = hs ? hs->count : 0;
7366+
while (lo < hi) {
7367+
int mid = lo + ((hi - lo) / PAIR_LEN);
7368+
if (hs->v[mid].start < start) {
7369+
lo = mid + SKIP_ONE;
7370+
} else {
7371+
hi = mid;
7372+
}
7373+
}
7374+
if (hs && lo < hs->count && hs->v[lo].start == start && strcmp(hs->v[lo].seg, seg) == 0) {
7375+
return hs->v[lo].qn_name;
7376+
}
7377+
return seg;
7378+
}
7379+
71487380
// INI: extract section name from section node.
71497381
static char *find_ini_section_name(CBMArena *a, TSNode node, const char *source) {
71507382
uint32_t nc = ts_node_child_count(node);
@@ -7245,7 +7477,10 @@ static bool extract_config_class_def(CBMExtractCtx *ctx, TSNode node, const char
72457477
return false;
72467478
}
72477479

7248-
if (name && name[0]) {
7480+
if (name && name[0] && ctx->language == CBM_LANG_MARKDOWN) {
7481+
const char *seg = qn_safe_segment(a, name);
7482+
push_class_def_qn(ctx, node, name, md_heading_qn_name(ctx, node, seg), label, docstring);
7483+
} else if (name && name[0]) {
72497484
push_simple_class_def_doc(ctx, node, name, label, docstring);
72507485
}
72517486
return true;

0 commit comments

Comments
 (0)