ploop/scripts/check_docs.py
2026-08-31 15:27:34 +08:00

156 lines
4.8 KiB
Python

"""Check repository-local Markdown file links and heading anchors."""
from __future__ import annotations
import argparse
from collections.abc import Iterable
from dataclasses import dataclass
from pathlib import Path
import re
import unicodedata
from urllib.parse import unquote
HEADING_PATTERN = re.compile(r"^(#{1,6})\s+(.+?)\s*#*\s*$", re.MULTILINE)
LINK_PATTERN = re.compile(
r"(?<!!)\[[^\]]+\]\(([^)\s]+)(?:\s+[\"'][^)]*[\"'])?\)"
)
EXTERNAL_PREFIXES = ("http://", "https://", "mailto:", "tel:", "data:")
@dataclass(frozen=True)
class CheckResult:
checked: int
markdown_files: int
errors: tuple[str, ...]
def main() -> int:
arguments = _parser().parse_args()
root = arguments.root.resolve()
excluded_paths = tuple(_resolve_excluded_path(root, path) for path in arguments.exclude)
result = check_markdown(root, excluded_paths)
print(
f"checked={result.checked} markdown_files={result.markdown_files} "
f"errors={len(result.errors)}"
)
for error in result.errors:
print(error)
return 1 if result.errors else 0
def check_markdown(root: Path, excluded_paths: tuple[Path, ...] = ()) -> CheckResult:
markdown_files = tuple(_markdown_files(root, excluded_paths))
repository_root = root.parent if root.is_file() else root
anchors_by_file: dict[Path, set[str]] = {}
errors: list[str] = []
checked = 0
for source in markdown_files:
for destination in _destinations(source):
if _is_external(destination):
continue
checked += 1
path_part, _, anchor = destination.partition("#")
target = source if not path_part else (source.parent / path_part).resolve()
source_name = _display_path(source, repository_root)
if not target.is_file():
errors.append(f"{source_name} -> {destination}: missing file")
continue
if anchor and anchor not in anchors_by_file.setdefault(target, _anchors(target)):
errors.append(f"{source_name} -> {destination}: missing anchor")
return CheckResult(
checked=checked,
markdown_files=len(markdown_files),
errors=tuple(errors),
)
def _parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(
description="Validate relative Markdown file links and heading anchors."
)
parser.add_argument("root", type=Path, nargs="?", default=Path("."))
parser.add_argument(
"--exclude",
type=Path,
action="append",
default=[],
help="Path relative to ROOT that the repository scan must skip; repeatable.",
)
return parser
def _markdown_files(root: Path, excluded_paths: tuple[Path, ...]) -> Iterable[Path]:
if root.is_file():
if root.suffix != ".md":
raise ValueError(f"expected a Markdown file or directory, got: {root}")
return (root,)
return tuple(
path
for path in sorted(root.rglob("*.md"))
if not any(_is_within(path, excluded_path) for excluded_path in excluded_paths)
)
def _resolve_excluded_path(root: Path, excluded_path: Path) -> Path:
return excluded_path.resolve() if excluded_path.is_absolute() else (root / excluded_path).resolve()
def _is_within(path: Path, parent: Path) -> bool:
try:
path.resolve().relative_to(parent)
except ValueError:
return False
return True
def _destinations(source: Path) -> Iterable[str]:
body = source.read_text(encoding="utf-8")
return (
unquote(match.group(1).strip("<>"))
for match in LINK_PATTERN.finditer(body)
)
def _is_external(destination: str) -> bool:
return destination.startswith(EXTERNAL_PREFIXES) or destination.startswith("/")
def _anchors(path: Path) -> set[str]:
seen: dict[str, int] = {}
anchors: set[str] = set()
for match in HEADING_PATTERN.finditer(path.read_text(encoding="utf-8")):
base = _slug(match.group(2))
duplicate_number = seen.get(base, 0)
seen[base] = duplicate_number + 1
anchors.add(base if duplicate_number == 0 else f"{base}-{duplicate_number}")
return anchors
def _slug(text: str) -> str:
without_links = re.sub(r"\[([^\]]*)\]\([^)]*\)", r"\1", text)
without_formatting = re.sub(r"[`*_~]", "", without_links).strip().lower()
pieces: list[str] = []
for character in without_formatting:
if character.isspace():
pieces.append("-")
elif character in {"-", "_"} or unicodedata.category(character)[0] in {"L", "N"}:
pieces.append(character)
return re.sub(r"-+", "-", "".join(pieces)).strip("-")
def _display_path(path: Path, root: Path) -> str:
try:
return str(path.relative_to(root))
except ValueError:
return str(path)
if __name__ == "__main__":
raise SystemExit(main())