link_check.py

Go to the documentation of this file.

#!/usr/bin/env python
"""Repo-wide stale-link checker for Markdown docs (OC_Chat maintenance tool).
 
Scans every ``.md`` file under the repo, extracts ``[](...)`` links and backtick
path code-spans, resolves each against the filesystem, and reports DEAD file
references. The output is filtered so the noise (illustrative example paths,
forward-refs to not-yet-authored TARGET files, generated views, preserved
receipts, frozen golden fixtures) is separated from genuine broken navigation.
 
The high-signal section ("A") is: markdown ``[](...)`` nav-links in *active*
docs whose target no longer exists but whose basename exists *elsewhere* (i.e.
the target moved) — with the new location. Those are the actionable stale links.
 
Usage:  python tools/link_check.py
 
Origin: written 2026-07-04 to sweep for stale links after the Plan-142 archival
(the archival moved 17 plan files to plans/completed/ and left dead references
in lint config, specs, and cross-links). Caught 3 partial-scope misses that
several scoped greps had missed; kept as a reusable check.
 
TODO(oct-migration): this checker is generic, not OC_Chat-specific. Migrate it
into the `oct` linter as a repo-wide ``stale_links`` check when the monorepo
lands, respecting the exempt buckets below (receipts / old / archive /
completed / generated views / golden fixtures). Kept here meanwhile.
"""
import os, re
 
REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))  # tools/ -> repo root
SCAN_ROOTS = ["oc_chat", "tools"]
 
 
def _n(p):
    return p.replace("/", os.sep)
 
 
# A dead link in one of these is EXPECTED (preserved receipt / superseded snapshot /
# generated view / frozen test oracle) — never reported as actionable.
EXEMPT = [_n(s) for s in [
    "historical-archive-DO-NOT-DELETE", "/old/", "/reviews/", "/reports/reports/",
    "DESIGN_DECISIONS_2026-06-08", "report-phase2", "/completed/",
    "/golden/",  # frozen render-oracle fixtures — must byte-match; fix the source, not these
]]
# Active-ish design/research/portable docs, heavy with ILLUSTRATIVE example paths;
# demoted to CONTEXT so the actionable "A" section stays clean.
CONTEXT = [_n(s) for s in [
    "/docs/Ollama/", "/LLM-API-support/", "/best-practices/", "/benchmarks/",
    "/architecture/memory/", "/architecture/roadmap-render/", "/architecture/agent_runtime/",
    "/architecture/security/", "/version-semantics/", "/process/", "/option_c_specs/",
    "/docs/research/", "/docs/audits/",   # dated research/audit snapshots -> archived versions
]]
 
 
def _generated(fp):
    return fp == os.path.join(REPO, "CHANGELOG.md") or \
        fp.startswith(os.path.join(REPO, "oc_chat", "roadmap") + os.sep)
 
 
def bucket(fp):
    if any(s in fp for s in EXEMPT) or _generated(fp):
        return "EXEMPT"
    if any(s in fp for s in CONTEXT):
        return "CONTEXT"
    return "CORE"
 
 
_md_link = re.compile(r'\‍[[^\‍]]*\‍]\‍(([^)\s]+)')
_code_span = re.compile(r'`([^`\n]+)`')
 
 
def _clean(t):
    t = t.strip().strip("<>").strip().split("#", 1)[0]
    return re.sub(r'(:\d+(-\d+)?)+$', '', t).strip()
 
 
def _is_md_ref(t):
    if not t or any(c in t for c in " \t~*{}<>|"):
        return False
    if "://" in t or t.startswith(("http", "mailto:")):
        return False
    return "/" in t and t.lower().endswith(".md")
 
 
def _resolve(target, d):
    return any(os.path.exists(os.path.normpath(os.path.join(b, target))) for b in (REPO, d))
 
 
def _walk_md():
    for root in SCAN_ROOTS:
        for dp, _, fs in os.walk(os.path.join(REPO, root)):
            if ".git" in dp:
                continue
            for f in fs:
                if f.endswith(".md"):
                    yield os.path.join(dp, f)
    for f in os.listdir(REPO):
        if f.endswith(".md"):
            yield os.path.join(REPO, f)
 
 
def main():
    files = list(_walk_md())
    index = {}
    for fp in files:
        index.setdefault(os.path.basename(fp).lower(), []).append(os.path.relpath(fp, REPO))
 
    dead, checked = [], 0
    for fp in files:
        d = os.path.dirname(fp)
        text = open(fp, encoding="utf-8", errors="replace").read()
        src = {}
        for m in _code_span.finditer(text):
            src[m.group(1)] = "code-span"
        for m in _md_link.finditer(text):
            src[m.group(1)] = "LINK"
        for raw, s in src.items():
            t = _clean(raw)
            if not _is_md_ref(t):
                continue
            checked += 1
            if not _resolve(t, d):
                dead.append((os.path.relpath(fp, REPO), t, bucket(fp), s))
 
    def cands(t):
        base = t.rstrip("/").split("/")[-1].lower()
        return [c for c in index.get(base, []) if c.replace("\\", "/") != t]
 
    core = sorted(set((d[0], d[1], d[3]) for d in dead if d[2] == "CORE"))
    nav_moved = [(fp, t, cands(t)) for fp, t, s in core if s == "LINK" and cands(t)]
    print(f"scanned {len(files)} .md files; checked {checked} .md nav-links")
    print(f"\nA. GENUINE BROKEN NAV LINKS (markdown [](...) links in active docs, target moved): {len(nav_moved)}")
    for fp, t, c in nav_moved:
        print(f"  {fp}\n      [](link): {t}\n      now at:  {', '.join(c[:2])}")
    if not nav_moved:
        print("  (none)")
    print("\n(CONTEXT / EXEMPT / never-existed buckets suppressed -- tweak the script to surface them.)")
 
 
if __name__ == "__main__":
    main()