| from __future__ import annotations |
| |
| |
|
|
| """ |
| supersede_check.py — v2 supersede/contradicts chain validator. |
| |
| Rohit G00 v2 范式：每个 wiki 页可以 supersede 旧页 / contradicts 兄弟页。 |
| 这个脚本验证： |
| 1. supersedes 目标存在 |
| 2. 目标 stage == archived |
| 3. 没有环 |
| 4. 没有"被 supersede 但未归档"的孤儿 |
| 5. contradicts 对称性（A contradicts B 要求 B 也填 contradicts A） |
| |
| Usage: |
| python3 scripts/supersede_check.py |
| python3 scripts/supersede_check.py --json |
| """ |
|
|
| import argparse |
| import json |
| import re |
| import sys |
| from pathlib import Path |
|
|
|
|
| ROOT = Path(__file__).resolve().parents[1] |
| WIKI_ROOT = ROOT / "docs" / "wiki" |
|
|
| FRONTMATTER_RE = re.compile(r"^---\n(.*?)\n---", re.DOTALL) |
|
|
|
|
| def parse_frontmatter(text: str) -> dict[str, str]: |
| m = FRONTMATTER_RE.match(text) |
| if not m: |
| return {} |
| out: dict[str, str] = {} |
| for line in m.group(1).splitlines(): |
| if ":" in line: |
| key, _, value = line.partition(":") |
| out[key.strip()] = value.strip() |
| return out |
|
|
|
|
| def parse_list_field(value: str) -> list[str]: |
| """Parse a YAML-ish list: [./a.md, ./b.md] -> [./a.md, ./b.md]""" |
| if not value or value in ("[]", ""): |
| return [] |
| return re.findall(r"\./[^\s,\]]+", value) |
|
|
|
|
| def main() -> int: |
| parser = argparse.ArgumentParser(description="v2 supersede / contradicts chain validator") |
| parser.add_argument("--wiki-root", type=Path, default=WIKI_ROOT) |
| parser.add_argument("--json", action="store_true", help="emit JSON report") |
| args = parser.parse_args() |
|
|
| if not args.wiki_root.exists(): |
| print(f"supersede_check: {args.wiki_root} does not exist") |
| return 1 |
|
|
| md_files = sorted(args.wiki_root.rglob("*.md")) |
| pages: dict[str, dict[str, str]] = {} |
| for path in md_files: |
| text = path.read_text(encoding="utf-8") |
| fm = parse_frontmatter(text) |
| if not fm: |
| continue |
| rel = path.relative_to(args.wiki_root).as_posix() |
| pages[rel] = fm |
|
|
| errors: list[str] = [] |
| orphans: list[str] = [] |
|
|
| |
| for rel, fm in pages.items(): |
| supersedes = parse_list_field(fm.get("supersedes", "")) |
| for target in supersedes: |
| target_norm = target.lstrip("./") |
| if target_norm not in pages: |
| errors.append(f"supersedes target missing: {rel} -> {target}") |
| continue |
| target_stage = pages[target_norm].get("stage", "") |
| if target_stage != "archived": |
| errors.append( |
| f"supersedes target not archived: {rel} -> {target} " |
| f"(stage={target_stage!r}, expected 'archived')" |
| ) |
|
|
| |
| |
| adj: dict[str, set[str]] = {} |
| for rel, fm in pages.items(): |
| supersedes = parse_list_field(fm.get("supersedes", "")) |
| adj[rel] = {t.lstrip("./") for t in supersedes if t.lstrip("./") in pages} |
|
|
| |
| WHITE, GRAY, BLACK = 0, 1, 2 |
| color = {node: WHITE for node in adj} |
| cycles: list[list[str]] = [] |
|
|
| def dfs(node: str, path: list[str]) -> None: |
| color[node] = GRAY |
| path.append(node) |
| for nxt in adj.get(node, set()): |
| if color[nxt] == GRAY: |
| |
| if nxt in path: |
| cycle = path[path.index(nxt):] + [nxt] |
| cycles.append(cycle) |
| elif color[nxt] == WHITE: |
| dfs(nxt, path) |
| path.pop() |
| color[node] = BLACK |
|
|
| for node in list(adj.keys()): |
| if color[node] == WHITE: |
| dfs(node, []) |
|
|
| for cycle in cycles: |
| errors.append(f"supersedes cycle detected: {' -> '.join(cycle)}") |
|
|
| |
| all_superseded_targets: set[str] = set() |
| for fm in pages.values(): |
| supersedes = parse_list_field(fm.get("supersedes", "")) |
| for t in supersedes: |
| all_superseded_targets.add(t.lstrip("./")) |
|
|
| for rel in all_superseded_targets: |
| if rel in pages and pages[rel].get("stage", "") != "archived": |
| orphans.append(f"{rel} (stage={pages[rel].get('stage', '')!r})") |
|
|
| |
| for rel, fm in pages.items(): |
| contradicts = parse_list_field(fm.get("contradicts", "")) |
| for target in contradicts: |
| target_norm = target.lstrip("./") |
| if target_norm not in pages: |
| continue |
| target_contradicts = parse_list_field(pages[target_norm].get("contradicts", "")) |
| if rel not in [t.lstrip("./") for t in target_contradicts]: |
| errors.append( |
| f"contradicts asymmetric: {rel} -> {target} " |
| f"(target {target_norm} does not contradict back)" |
| ) |
|
|
| |
| report = { |
| "wiki_root": str(args.wiki_root), |
| "page_count": len(pages), |
| "supersedes_total": sum(len(parse_list_field(fm.get("supersedes", ""))) for fm in pages.values()), |
| "contradicts_total": sum(len(parse_list_field(fm.get("contradicts", ""))) for fm in pages.values()), |
| "orphans": orphans, |
| "errors": errors, |
| "cycles": cycles, |
| } |
|
|
| if args.json: |
| print(json.dumps(report, indent=2, ensure_ascii=False)) |
| else: |
| print("supersede_check:") |
| print(f"- pages: {report['page_count']}") |
| print(f"- supersedes total: {report['supersedes_total']}") |
| print(f"- contradicts total: {report['contradicts_total']}") |
| if orphans: |
| print(f"- orphans (superseded but not archived): {len(orphans)}") |
| for o in orphans: |
| print(f" - {o}") |
| if errors: |
| print(f"- errors: {len(errors)}") |
| for e in errors: |
| print(f" - {e}") |
| return 1 |
| if cycles: |
| print(f"- cycles: {len(cycles)}") |
| return 1 |
| print("- OK") |
|
|
| return 0 if not errors and not cycles else 1 |
|
|
|
|
| if __name__ == "__main__": |
| sys.exit(main()) |
|
|
