Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
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.pyindex 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_linesfound: 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.pyindex 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 woulddouble-count one defect."""