♻️ refactor(test): consolidate repository checks

2026-07-20 09:08:36 +08:00
parent 10ce779b1b
commit ff07c79818
24 changed files with 426 additions and 4596 deletions
@@ -0,0 +1,191 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Iterator, Optional, Sequence
+
+
+EXCLUDED_DIRECTORIES = {".git", "build", "dist", "node_modules", "tmp"}
+FENCE_PATTERN = re.compile(r"^\s*(`{3,}|~{3,})")
+INLINE_CODE_PATTERN = re.compile(r"`[^`]*`")
+INLINE_LINK_PATTERN = re.compile(r"!?\[[^]]*\]\(([^)]*)\)")
+REFERENCE_LINK_PATTERN = re.compile(
+    r"^\s*\[[^]]+\]:\s*(?:<([^>]+)>|([^\s]+))"
+)
+
+
+@dataclass(frozen=True)
+class MarkdownLink:
+    line: int
+    target: str
+
+
+@dataclass(frozen=True)
+class BrokenLink:
+    source: Path
+    line: int
+    target: str
+    resolved_target: Path
+
+
+@dataclass
+class LinkCheckResult:
+    markdown_files: int = 0
+    total_links: int = 0
+    valid_links: int = 0
+    skipped_links: int = 0
+    broken_links: list[BrokenLink] = field(default_factory=list)
+
+
+def extract_links(text: str) -> Iterator[MarkdownLink]:
+    fence_character: Optional[str] = None
+
+    for line_number, raw_line in enumerate(text.splitlines(), start=1):
+        fence_match = FENCE_PATTERN.match(raw_line)
+        if fence_match:
+            marker_character = fence_match.group(1)[0]
+            if fence_character is None:
+                fence_character = marker_character
+            elif marker_character == fence_character:
+                fence_character = None
+            continue
+        if fence_character is not None:
+            continue
+
+        line = INLINE_CODE_PATTERN.sub("", raw_line)
+        for match in INLINE_LINK_PATTERN.finditer(line):
+            yield MarkdownLink(line_number, match.group(1).strip())
+
+        reference_match = REFERENCE_LINK_PATTERN.match(line)
+        if reference_match:
+            target = reference_match.group(1) or reference_match.group(2)
+            yield MarkdownLink(line_number, target.strip())
+
+
+def iter_markdown_files(root: Path) -> Iterator[Path]:
+    for path in sorted(root.rglob("*.md")):
+        relative_path = path.relative_to(root)
+        if path.name.endswith(".template.md"):
+            continue
+        if any(part in EXCLUDED_DIRECTORIES for part in relative_path.parts[:-1]):
+            continue
+        if path.is_file():
+            yield path
+
+
+def _local_target(target: str) -> Optional[str]:
+    target = target.strip()
+    if target.startswith("<") and target.endswith(">"):
+        target = target[1:-1].strip()
+
+    target = target.split("#", 1)[0]
+    if not target:
+        return None
+
+    lower_target = target.lower()
+    if lower_target.startswith(("http://", "https://", "mailto:")):
+        return None
+    if target.startswith("/en/docs/"):
+        return None
+    return target
+
+
+def _resolve_target(root: Path, source: Path, target: str) -> Path:
+    if target.startswith("/"):
+        return (root / target.lstrip("/")).resolve()
+    return (source.parent / target).resolve()
+
+
+def check_repository(root: Path) -> LinkCheckResult:
+    root = root.resolve()
+    markdown_files = list(iter_markdown_files(root))
+    result = LinkCheckResult(markdown_files=len(markdown_files))
+
+    for source in markdown_files:
+        text = source.read_text(encoding="utf-8")
+        for link in extract_links(text):
+            result.total_links += 1
+            local_target = _local_target(link.target)
+            if local_target is None:
+                result.skipped_links += 1
+                continue
+
+            resolved_target = _resolve_target(root, source, local_target)
+            if resolved_target.exists():
+                result.valid_links += 1
+                continue
+
+            result.broken_links.append(
+                BrokenLink(source, link.line, link.target, resolved_target)
+            )
+
+    return result
+
+
+def _display_path(path: Path, root: Path) -> str:
+    try:
+        return path.relative_to(root).as_posix()
+    except ValueError:
+        return str(path)
+
+
+def print_report(result: LinkCheckResult, root: Path) -> None:
+    root = root.resolve()
+    print(f"Playbook root: {root}")
+    print(f"Markdown files: {result.markdown_files}")
+
+    for broken in result.broken_links:
+        source = _display_path(broken.source, root)
+        target = _display_path(broken.resolved_target, root)
+        print(f"BROKEN: {source}:{broken.line}")
+        print(f"  Link: {broken.target}")
+        print(f"  Target: {target}")
+
+    print(f"Total links: {result.total_links}")
+    print(f"Valid links: {result.valid_links}")
+    print(f"Skipped links: {result.skipped_links}")
+    print(f"Broken links: {len(result.broken_links)}")
+
+
+def parse_args(argv: Optional[Sequence[str]] = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Check local links in Markdown files.")
+    parser.add_argument(
+        "--root",
+        type=Path,
+        default=Path(__file__).resolve().parents[2],
+        help="repository root to scan (default: inferred from this script)",
+    )
+    return parser.parse_args(argv)
+
+
+def _configure_output() -> None:
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is not None:
+            reconfigure(errors="backslashreplace")
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    _configure_output()
+    args = parse_args(argv)
+    root = args.root.resolve()
+    if not root.is_dir():
+        print(f"ERROR: root directory does not exist: {root}")
+        return 2
+
+    result = check_repository(root)
+    print_report(result, root)
+    if result.broken_links:
+        print("Document link check failed.")
+        return 1
+
+    print("All document links passed.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())