py_link_check.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_chat/scripts/py_link_check.py
 
# OCT-LINT: disable=tests_exist reason="Calibrated at authoring via the plan-151 T0 RED/GREEN fixture run; a unit-test module is tracked post-migration"
"""
Relative-link checker for NON-``.md`` link targets (the class ``tools/link_check.py`` is blind to).
 
Purpose
-------
``tools/link_check.py`` only validates markdown links whose target ends in ``.md``
(``_is_md_ref``), so it is BLIND to dead relative links pointing at ``.py`` (or any
other non-``.md``) files — exactly the class a code move breaks (e.g. the many
``.py``-target links in ``CONTRACTS.md`` / ``TOOL_CONTRACT.md``). This companion
sweep resolves every relative, non-URL, non-anchor markdown link whose target is a
file with a non-``.md`` extension and reports the ones that do not exist on disk.
Usage: ``python oc_chat/scripts/py_link_check.py [--root DIR] [--json]``. ``--root``
defaults to the repository root inferred from this file's location, so the script
scans the tree it travels with (post-move it is invoked from the monorepo root as
``python oc_chat/oc_chat/scripts/py_link_check.py``). Exit ``0`` when no broken
non-``.md`` relative file links are found; ``1`` otherwise. The §2.2 gate is
baseline-relative: fail only on NEW entries vs the recorded pre-move baseline.
 
Responsibilities
----------------
- Enumerate ``*.md`` files under a scan root (skipping VCS internals).
- Extract inline-link targets and normalise them (strip titles, fragments,
  queries, ``:NN`` line locators, percent-encoding).
- Resolve each non-``.md`` relative file target and report the unresolved ones.
 
Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
    L2 - CLI lifecycle (scan start / result)
    L3 - per-root resolution details
    L4 - per-file / per-link tracing
 
Contracts
---------
- Imports ONLY ``oc_diagnostics`` (structured logging) — never ``oc_chat`` — so it
  is immune to the ``sys.path[0] = scripts/`` ``import oc_chat`` editable-install
  shadowing trap (plan 151 §2.3); the scan logic is driven entirely by the ``--root``
  filesystem path, not by imports, so it runs identically pre- and post-move.
- Read-only: never writes to the scanned tree.
- Deterministic: results are sorted; identical tree -> identical output.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
"""
from __future__ import annotations
 
import argparse
import json
import re
import sys
from dataclasses import dataclass
from pathlib import Path
from urllib.parse import unquote
 
from oc_diagnostics import _dbg
 
 
_dbg("OC_CHAT.MAIN", "module", "loaded", 4)
 
# Markdown inline link body: the target portion of ``[text](target)``.
_LINK_RE = re.compile(r"\‍]\‍(([^)]+)\‍)")
# Targets we never resolve as on-disk relative file paths.
_SKIP_PREFIXES = ("http://", "https://", "mailto:", "ftp://", "tel:", "#", "//")
# A trailing source locator appended to a code ref: ``:123``, ``:123-456``,
# ``:123:4`` (line:col), or ``:123:4-125`` (editor line:col-line spans).
_LINE_LOCATOR_RE = re.compile(r"(?::\d+)+(?:-\d+(?::\d+)?)?$")
 
 
@dataclass(frozen=True)
class BrokenLink:
    """One unresolved non-``.md`` relative link."""
 
    source: str
    target: str
    resolved: str
 
 
def _iter_markdown_files(root: Path):
    """Yield every ``*.md`` file under *root*, skipping VCS internals."""
 
    for path in sorted(root.rglob("*.md")):
        if ".git" in path.parts:
            continue
        yield path
 
 
def _clean_target(raw: str) -> str | None:
    """Normalise a link body to a bare relative file path, or ``None`` to skip.
 
    Strips ``<...>`` wrappers, an optional ``"title"`` suffix, ``#anchor`` /
    ``?query`` fragments, a trailing ``:NN`` source-line locator, and percent
    encoding. Returns ``None`` for URLs, pure anchors, absolute paths, extension-less
    targets (directory/section references), and ``.md`` targets (owned by
    ``tools/link_check.py``).
    """
 
    func = "_clean_target"
    target = raw.strip()
    if target.startswith("<") and target.endswith(">"):
        target = target[1:-1].strip()
    for quote in ('"', "'"):
        idx = target.find(f" {quote}")
        if idx != -1:
            target = target[:idx].strip()
    if not target or target.startswith(_SKIP_PREFIXES) or "://" in target:
        return None
    target = target.split("#", 1)[0].split("?", 1)[0]
    if not target:
        return None
    target = _LINE_LOCATOR_RE.sub("", unquote(target))
    if not target or target.startswith("/") or re.match(r"^[A-Za-z]:[\\/]", target):
        return None
    last = target.replace("\\", "/").rstrip("/").rsplit("/", 1)[-1]
    if "." not in last or last.lower().endswith(".md"):
        return None
    _dbg("OC_CHAT.MAIN", func, f"candidate target {target}", 4)
    return target
 
 
def find_broken_links(root: Path) -> list[BrokenLink]:
    """Return every broken non-``.md`` relative file link under *root*, sorted."""
 
    func = "find_broken_links"
    root = root.resolve()
    broken: list[BrokenLink] = []
    for md_path in _iter_markdown_files(root):
        try:
            text = md_path.read_text(encoding="utf-8", errors="replace")
        except OSError:
            continue
        for match in _LINK_RE.finditer(text):
            target = _clean_target(match.group(1))
            if target is None:
                continue
            resolved = (md_path.parent / target).resolve()
            if not resolved.exists():
                broken.append(
                    BrokenLink(
                        source=md_path.relative_to(root).as_posix(),
                        target=target,
                        resolved=str(resolved),
                    )
                )
    _dbg("OC_CHAT.MAIN", func, f"{len(broken)} broken under {root}", 2)
    return sorted(broken, key=lambda item: (item.source, item.target))
 
 
def _build_parser() -> argparse.ArgumentParser:
    """Construct the CLI argument parser."""
 
    parser = argparse.ArgumentParser(
        prog="python oc_chat/scripts/py_link_check.py",
        description="Report broken relative links whose target is a non-.md file.",
    )
    default_root = Path(__file__).resolve().parent.parent.parent
    parser.add_argument(
        "--root",
        default=str(default_root),
        help="Scan root (default: repo root inferred from this file's location).",
    )
    parser.add_argument("--json", action="store_true", help="Emit machine-readable JSON.")
    return parser
 
 
def main(argv: list[str] | None = None) -> int:
    """CLI entry point: scan ``--root`` and report broken non-``.md`` file links."""
 
    func = "main"
    args = _build_parser().parse_args(argv)
    root = Path(args.root)
    if not root.is_dir():
        print(f"py_link_check: --root is not a directory: {root}", file=sys.stderr)
        return 2
    broken = find_broken_links(root)
    if args.json:
        print(
            json.dumps(
                {
                    "root": str(root.resolve()),
                    "broken_count": len(broken),
                    "broken": [
                        {"source": item.source, "target": item.target, "resolved": item.resolved}
                        for item in broken
                    ],
                },
                indent=2,
                sort_keys=True,
            )
        )
    else:
        print(f"py_link_check: scanned {root.resolve()}")
        print(f"broken non-.md relative file links: {len(broken)}")
        for item in broken:
            print(f"  {item.source} -> {item.target}")
    _dbg("OC_CHAT.MAIN", func, f"exit {1 if broken else 0}", 2)
    return 1 if broken else 0
 
 
if __name__ == "__main__":
    sys.exit(main())