fix(markdown): qualify a repeated heading's Section by its parent headings (#2586)

[bline]

What does this PR do?

Fixes #2586. A Markdown Section's qualified name is the file's module plus
the heading text. So ## Implementation under # Service A and under
# Service B shared one qualified name. The graph kept one node (the
last), and the references under both headings went to the File node.

This changes Section qualified names, so please check the naming. A
heading whose name repeats in the file now has the names of the headings
above it in its qualified name:

heading	before	after
# Service A	…docs.repeated.Service-A	unchanged
## Implementation (under A)	…docs.repeated.Implementation (shared)	…docs.repeated.Service-A.Implementation
## Implementation (under B)	…docs.repeated.Implementation (shared)	…docs.repeated.Service-B.Implementation
## Notes (unique)	…docs.repeated.Notes	unchanged

Choices I made, any of which I'm happy to change:

• Only repeated names are qualified. A heading whose name is unique in
  its file keeps its current qualified name, so existing queries and
  stored names for those Sections still work. The cost is that adding a
  second ## Implementation renames the first. Qualifying every nested
  heading would avoid that, but it would rename most Sections in every
  indexed repository.
• The whole chain of headings above, not just the nearest. The name is
  then fixed by the document's structure alone, with no ordinal that shifts
  when a section is inserted above.
• A qualified name that equals another heading's name gets a suffix. A
  heading text may contain dots, so # Service-A.Implementation would get
  the same name as the qualified ## Implementation under # Service A.
  All final names in a file are settled together: a heading whose name is
  unique keeps it, and a qualified name that collides takes the first free
  ~2, ~3, …. (When only qualified names collide, the first in the file
  keeps the name.) Names match only when their headings do. The comparison
  is on the list of headings, not on the dotted text. The suffix appears
  only in that collision.
• Headings that repeat under the same parents (two ## Fixes under one
  # Changes) still share a name and keep the existing File fallback in
  doclink_md.c. doc_links_md_repeated_headings pins that and is
  unchanged.
• name stays the heading text. Only qualified_name changes.

How. The parent headings come from the tree: tree-sitter-markdown nests
each heading's section inside the section of the heading above it. The
file's heading names are collected and sorted once per file, when the first
heading is seen. They are allocated in the scratch arena and held in a new
CBMExtractCtx.md_headings slot, like doc_memo. Diagrams find their
Section through the definition list, so a diagram under a repeated heading
now hangs off that heading's own Section.

This is Markdown only. reST and AsciiDoc sections are built elsewhere, and I
haven't checked whether they share the problem.

Evidence

doc_links_md_repeated_headings_by_parent_issue2586 in
tests/test_doc_links_md.c indexes the document from the issue, with a
Mermaid diagram under the second Implementation.
doc_links_md_repeated_heading_name_collision_issue2586 adds
# Service-A.Implementation to that document and requires five Sections,
with the unique heading keeping its name. Without the source change the first
test fails on the defect itself:

FAIL tests/test_doc_links_md.c:245: dm_count(... name = 'Implementation' ...) == 1, expected 2

With it, scripts/test.sh --suites doc_links_md,doc_links_rst,doc_links_adoc,doc_mentions,diagrams
reports 115 passed, 0 failed.

Checklist

• Every commit is signed off (git commit -s) — required, CI rejects
  unsigned commits (DCO, see CONTRIBUTING.md)
• Tests pass locally: scripts/test.sh (the canonical leg), 9384 passed, 0 failed, 10 skipped,
  189 suites, Linux x86-64, gcc
• Lint passes: scripts/lint.sh --ci in test-infrastructure lint container
  (cppcheck + clang-format-20 + memory-core), "All linters passed"
• New behavior is covered by a test (reproduce-first for bug fixes)

Written with an AI agent (Claude); I reviewed the change and certify it via
the DCO sign-off.

🤖 Generated with Claude Code

[github-actions]

Thanks for opening this — it has been seen, and it is queued.

This note is automated, but it is not a brush-off: it exists so you know where your PR stands instead of having to guess from silence.

Current review status: working through a backlog. 0.9.1-rc.1 is out, so the release freeze that held reviews is over — but it left a large queue of open pull requests behind it, and we are reading through them oldest-first. The background is in discussion #1144.

What that means for this PR, concretely:

• It will not be closed for inactivity. No stale bot touches pull requests here.
• It may still sit a while before a human reads it. That is on us, not on you.
• Older PRs are read first, so a recent one is not being skipped — it is behind a queue.

Things that will genuinely speed it up whenever review does happen:

• Keep it rebased on main — the tree is moving quickly right now, and a conflicting branch cannot be reviewed as the diff you intended.
• Get CI green, or say which failures you believe are pre-existing.
• Keep the change to one claim. Bundled features and refactors get split before they get merged, which costs you a round trip.
• Every commit needs a sign-off (git commit -s) — CI enforces DCO.

If this fixes a bug, a reproduction we can run is worth more than a description of the symptom.

Thanks for contributing, and sorry in advance for the wait.