156 lines
4.8 KiB
Python
156 lines
4.8 KiB
Python
"""检查仓库内 Markdown 文件的链接和标题锚点。"""
|
|
|
|
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())
|