Skip to content

fix(decision-records): respect code spans, validate link anchors - #5

Merged
trungfinity merged 1 commit into
mainfrom
fix/decision-records-link-check
Jul 3, 2026
Merged

trungfinity merged 1 commit into
mainfrom
fix/decision-records-link-check

Conversation

@trungfinity

Copy link
Copy Markdown
Contributor

Problem

check_links had two gaps:

  1. False positives on code spans. It regex-scanned raw text, so a link written inside a code span or fenced block — syntax being displayed, not a live link (per CommonMark, code spans contain no links) — was flagged as broken. Hit in practice by an AGENTS.md line showing the link format as an example: [term](../../glossary.md#term).
  2. Anchors never validated. The fragment was discarded (target.split("#", 1)[0]), so glossary.md#egres-proxy passed as long as glossary.md existed, and pure #fragment intra-doc links were skipped entirely. Repos adopting glossary-term and section-heading linking get zero protection on the half of the link most likely to rot (promotion moves records between directory depths).

Fix

  • strip_code() blanks fenced blocks and inline code spans before the link scan (line structure preserved).
  • heading_anchors() computes GitHub-style slugs for a file's headings — lowercase, punctuation dropped, spaces→hyphens, -N suffixes for duplicate headings, markdown links/backticks in heading text reduced to display text (covers em-dash cases like #appendix--harnesses-evaluated-research-notes-non-binding).
  • Every #fragment on a markdown target is validated against the target's slugs; pure #fragment links resolve against the containing file. Failures report as broken anchor, distinct from broken link.

Testing

  • 5 new tests: slug computation (em-dash, quotes, &, duplicates, fenced pseudo-headings), code-span and fenced-block links not checked, cross-file anchor validation (pass + fail), intra-doc anchor validation (pass + fail).
  • Full suite: 62 passed.
  • Field-tested against skymavis/lanh-ai's docs tree (~70 glossary/section anchor links across 6 accepted records + 3 drafts): all validate; the previously false-positive AGENTS.md pattern no longer flags.

check_links scanned raw text, so a link written inside a code span or
fenced block (syntax on display, not a live link) was flagged as
broken; and it discarded fragments entirely, so a typo'd or stale
anchor passed silently.

- strip fenced blocks and inline code spans before scanning for links
- validate every #fragment against the target file's headings using
  GitHub-style slugs (punctuation dropped, spaces to hyphens, -N
  suffixes for duplicates); pure #fragment links now resolve against
  the containing file instead of being skipped
- report anchor failures as 'broken anchor' distinct from
  'broken link'
@trungfinity
trungfinity merged commit a454f10 into main Jul 3, 2026
5 checks passed
@trungfinity
trungfinity deleted the fix/decision-records-link-check branch July 3, 2026 01:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant