#!/usr/bin/env python3
"""校验执行域 verify/doc/files 一致性。

该脚本是“离线门禁”的一部分：发现 doc_id 三元契约不一致时应 fail-fast，
并输出可定位的冲突清单（doc_id + 路径集合）。
"""
from __future__ import annotations

import re
import sys
from pathlib import Path

ROOT = Path(__file__).resolve().parent.parent.parent
VERIFY_DIR = ROOT / "ansible" / "playbooks" / "verify"
DOCS_DIR = ROOT / "docs"
EXEC_ID_RE = re.compile(r"^(0[1-9]|[1-9][0-9])-(0[1-9]|[1-9][0-9])$")


def is_exec_domain(doc_id: str) -> bool:
    return EXEC_ID_RE.fullmatch(doc_id) is not None


def main() -> None:
    if not VERIFY_DIR.is_dir() or not DOCS_DIR.is_dir():
        print("ERR: verify/docs 目录缺失", file=sys.stderr)
        sys.exit(2)

    # --- scan verify playbooks (.yml/.yaml) ---
    verify_by_doc_id: dict[str, list[Path]] = {}
    invalid_verify_names: list[str] = []

    for p in sorted(VERIFY_DIR.iterdir()):
        if not p.is_file():
            continue
        if p.name.startswith("_"):
            # private helpers are allowed but not part of doc_id contract
            continue
        if p.suffix not in {".yml", ".yaml"}:
            continue

        # Only accept <doc_id>.yml|yaml
        stem = p.stem
        if len(stem) != len("00-00") or stem[2:3] != "-":
            invalid_verify_names.append(p.name)
            continue

        if not is_exec_domain(stem):
            invalid_verify_names.append(p.name)
            continue

        verify_by_doc_id.setdefault(stem, []).append(p)

    # Same doc_id with multiple verify entrypoints is a hard conflict (EC1).
    verify_conflicts: dict[str, list[str]] = {}
    for did, paths in verify_by_doc_id.items():
        if len(paths) > 1:
            verify_conflicts[did] = [str(p.relative_to(ROOT)) for p in sorted(paths)]

    missing_docs: list[str] = []
    missing_files_dir: list[str] = []
    weak_doc_exec_refs: list[str] = []
    multi_docs: dict[str, list[str]] = {}

    for did in sorted(verify_by_doc_id.keys()):
        matches = sorted(DOCS_DIR.glob(f"{did}-*.md"))
        if not matches:
            missing_docs.append(did)
            continue
        if len(matches) > 1:
            multi_docs[did] = [str(p.relative_to(ROOT)) for p in matches]
        doc = matches[0]
        content = doc.read_text(encoding="utf-8", errors="ignore")
        if f"ansible/files/{did}/" not in content and "```yaml" in content:
            weak_doc_exec_refs.append(did)
        # Execution-domain doc_id must always have a files truth-source directory (ADR-002 / R4).
        if not (ROOT / "ansible" / "files" / did).is_dir():
            missing_files_dir.append(did)

    if invalid_verify_names:
        print(f"ERR: verify 仅允许执行域命名: {sorted(invalid_verify_names)}", file=sys.stderr)
        sys.exit(2)
    if verify_conflicts:
        print("ERR: verify 入口冲突（同一 doc_id 多个入口，必须 fail-fast）:", file=sys.stderr)
        for did in sorted(verify_conflicts.keys()):
            paths = verify_conflicts[did]
            print(f"  - {did}: {paths}", file=sys.stderr)
        sys.exit(2)
    if missing_docs:
        print(f"ERR: 缺少 docs/<doc_id>-*.md: {missing_docs}", file=sys.stderr)
        sys.exit(2)
    if multi_docs:
        print("ERR: docs 命名冲突（同一 doc_id 匹配到多篇 docs/<doc_id>-*.md）:", file=sys.stderr)
        for did in sorted(multi_docs.keys()):
            print(f"  - {did}: {multi_docs[did]}", file=sys.stderr)
        sys.exit(2)
    if missing_files_dir:
        print(f"ERR: 缺少 ansible/files/<doc_id>/ 目录: {missing_files_dir}", file=sys.stderr)
        sys.exit(2)
    if weak_doc_exec_refs:
        print(f"ERR: 文档 YAML 未映射 ansible/files/<doc_id>/ 真源: {weak_doc_exec_refs}", file=sys.stderr)
        sys.exit(2)

    print(f"[OK] 执行域 verify/doc/files 一致性通过（{len(verify_by_doc_id)} 条）")


if __name__ == "__main__":
    main()