Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

fix(doc-drift): resolve GitHub's suffixed anchors for repeated headings (#3256)

Bharat Kauravfc6308e738b0
diff --git a/packages/core/src/repowise/core/analysis/doc_drift/resolver.py b/packages/core/src/repowise/core/analysis/doc_drift/resolver.py
index 870545b15..d3b49c9ed 100644
--- a/packages/core/src/repowise/core/analysis/doc_drift/resolver.py
+++ b/packages/core/src/repowise/core/analysis/doc_drift/resolver.py
@@ -173,13 +173,19 @@ class RepoIndex:
from .extractor import prose_lines
found: set[str] = set()
+ # GitHub suffixes repeated headings: the second ``## Usage`` is
+ # ``#usage-1``, the third ``#usage-2``. Same bookkeeping as
+ # github-slugger, so a suffixed slug that collides with a literal
+ # heading (``## Usage 1`` already took ``usage-1``) skips to the next
+ # free number rather than registering a slug GitHub never renders.
+ occurrences: dict[str, int] = {}
previous = ""
for _lineno, line in prose_lines(self._doc_text.get(rel, "")):
m = _HEADING_RE.match(line)
if m:
- found.add(github_slug(m.group(1)))
+ found.add(_unique_slug(github_slug(m.group(1)), occurrences))
elif previous.strip() and _SETEXT_UNDERLINE_RE.match(line):
- found.add(github_slug(previous))
+ found.add(_unique_slug(github_slug(previous), occurrences))
for groups in _HTML_ANCHOR_RE.findall(line):
value = next((g for g in groups if g), "")
found.add(value.strip().lower())
@@ -191,6 +197,21 @@ class RepoIndex:
return frozen
+def _unique_slug(slug: str, occurrences: dict[str, int]) -> str:
+ """The anchor GitHub gives a heading slugged *slug*, given the earlier ones.
+
+ *occurrences* holds every slug already handed out in the document and is
+ updated in place. Mirrors github-slugger: on a clash, bump the base slug's
+ counter and try ``f"{slug}-{n}"`` until one is free.
+ """
+ result = slug
+ while result in occurrences:
+ occurrences[slug] += 1
+ result = f"{slug}-{occurrences[slug]}"
+ occurrences[result] = 0
+ return result
+
+
def _suffix(path: str) -> str:
"""The lowercased extension of *path*, or ``""`` when it has none."""
base = path.rsplit("/", 1)[-1]
diff --git a/tests/unit/doc_drift/test_resolver.py b/tests/unit/doc_drift/test_resolver.py
index fd1184a2f..0b877e14a 100644
--- a/tests/unit/doc_drift/test_resolver.py
+++ b/tests/unit/doc_drift/test_resolver.py
@@ -219,6 +219,27 @@ def test_each_whitespace_character_becomes_its_own_dash():
assert resolve(idx, _anchor_ref("sql-dbt")).verdict is DriftVerdict.MISSING
+def test_repeated_headings_get_githubs_numbered_anchors():
+ """GitHub names the second ``## Usage`` ``#usage-1`` and the third
+ ``#usage-2``; only one more suffix than there are repeats exists."""
+ idx = _anchor_index("## Usage\n\n## Usage\n\nUsage\n-----\n")
+ for fragment in ("usage", "usage-1", "usage-2"):
+ assert resolve(idx, _anchor_ref(fragment)).verdict is DriftVerdict.RESOLVED
+ res = resolve(idx, _anchor_ref("usage-3"))
+ assert res.verdict is DriftVerdict.MISSING
+ assert res.origin == "anchor_no_heading"
+
+
+def test_a_suffix_skips_a_slug_a_literal_heading_already_took():
+ """``## Usage 1`` claims ``usage-1``, so the repeated ``## Usage`` after it
+ becomes ``usage-2``, and a later repeat of ``## Usage 1`` becomes
+ ``usage-1-1``. This is github-slugger's bookkeeping, not a naive count."""
+ idx = _anchor_index("## Usage\n\n## Usage 1\n\n## Usage\n\n## Usage 1\n")
+ anchors = idx.doc_anchors("README.md")
+ assert {"usage", "usage-1", "usage-2", "usage-1-1"} <= anchors
+ assert "usage-3" not in anchors
+
+
def test_anchor_into_a_missing_document_is_uncheckable_not_missing():
"""The LINK row already reports the missing file; saying it twice would
double-count one defect."""