|
| 1 | +#!/usr/bin/env python3 |
| 2 | +"""Deterministic internal-link checker for the DSGAI scanner docs. |
| 3 | +
|
| 4 | +Verifies that relative markdown links point at files that exist, and that |
| 5 | +in-file `#anchor` fragments match a heading in the target document. External |
| 6 | +(http/https/mailto) links are intentionally not fetched — that is flaky in CI |
| 7 | +and a separate concern. Exit 1 if any internal link is broken. |
| 8 | +
|
| 9 | +Usage: python check_md_links.py <dir-or-file> [more...] |
| 10 | +""" |
| 11 | +import re, sys, unicodedata |
| 12 | +from pathlib import Path |
| 13 | + |
| 14 | +LINK_RE = re.compile(r'(?<!\!)\[[^\]]*\]\(([^)]+)\)') |
| 15 | +HEADING_RE = re.compile(r'^(#{1,6})\s+(.*?)\s*#*\s*$') |
| 16 | + |
| 17 | + |
| 18 | +def slug(text: str) -> str: |
| 19 | + """GitHub-style heading -> anchor slug.""" |
| 20 | + text = unicodedata.normalize('NFKD', text) |
| 21 | + # strip markdown inline formatting and links |
| 22 | + text = re.sub(r'`([^`]*)`', r'\1', text) |
| 23 | + text = re.sub(r'\[([^\]]*)\]\([^)]*\)', r'\1', text) |
| 24 | + text = re.sub(r'[*_~]', '', text) |
| 25 | + text = text.lower() |
| 26 | + text = re.sub(r'[^\w\s-]', '', text) |
| 27 | + text = text.strip().replace(' ', '-') |
| 28 | + return text |
| 29 | + |
| 30 | + |
| 31 | +def anchors_of(path: Path) -> set: |
| 32 | + out = set() |
| 33 | + if not path.exists(): |
| 34 | + return out |
| 35 | + for line in path.read_text(encoding='utf-8', errors='replace').splitlines(): |
| 36 | + m = HEADING_RE.match(line) |
| 37 | + if m: |
| 38 | + out.add(slug(m.group(2))) |
| 39 | + return out |
| 40 | + |
| 41 | + |
| 42 | +def collect_md(targets): |
| 43 | + files = [] |
| 44 | + for t in targets: |
| 45 | + p = Path(t) |
| 46 | + if p.is_dir(): |
| 47 | + files += sorted(p.rglob('*.md')) |
| 48 | + elif p.suffix == '.md': |
| 49 | + files.append(p) |
| 50 | + return files |
| 51 | + |
| 52 | + |
| 53 | +def main(): |
| 54 | + targets = sys.argv[1:] or ['.'] |
| 55 | + files = collect_md(targets) |
| 56 | + anchor_cache = {} |
| 57 | + broken = [] |
| 58 | + for f in files: |
| 59 | + text = f.read_text(encoding='utf-8', errors='replace') |
| 60 | + for m in LINK_RE.finditer(text): |
| 61 | + target = m.group(1).strip() |
| 62 | + if target.startswith('<') and target.endswith('>'): |
| 63 | + target = target[1:-1] |
| 64 | + # skip external and pure-anchor-to-external schemes |
| 65 | + if re.match(r'^[a-z]+://', target) or target.startswith('mailto:'): |
| 66 | + continue |
| 67 | + path_part, _, frag = target.partition('#') |
| 68 | + if path_part == '': |
| 69 | + # same-file anchor |
| 70 | + dest = f |
| 71 | + else: |
| 72 | + dest = (f.parent / path_part).resolve() |
| 73 | + if not dest.exists(): |
| 74 | + broken.append(f"{f}: missing file -> {target}") |
| 75 | + continue |
| 76 | + if frag: |
| 77 | + if dest not in anchor_cache: |
| 78 | + anchor_cache[dest] = anchors_of(dest) |
| 79 | + if slug(frag) not in anchor_cache[dest]: |
| 80 | + broken.append(f"{f}: missing anchor -> {target}") |
| 81 | + if broken: |
| 82 | + print("Broken internal links:") |
| 83 | + for b in broken: |
| 84 | + print(" " + b) |
| 85 | + return 1 |
| 86 | + print(f"OK: {len(files)} markdown files, all internal links resolve.") |
| 87 | + return 0 |
| 88 | + |
| 89 | + |
| 90 | +if __name__ == '__main__': |
| 91 | + sys.exit(main()) |
0 commit comments