对齐文件规范

scripts/validate_matrix_playbooks.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+"""校验 verify playbook 清单（抛弃“验证矩阵”概念后的替代校验）。
+
+规则（最小可用）：
+- ansible/playbooks/verify/ 目录下所有形如 XX-YY.yml 的文件，都必须存在对应 docs/XX-YY-*.md 文档
+- 仅检查“存在性 + 1:1 对齐”，不解析 Markdown 内容
+
+历史上本脚本用于校验 docs/00-03-验证矩阵.md ↔ labs/matrix-doc-playbooks.yml；
+该概念已废弃，但保留脚本名以减少 CI/用户习惯改动。
+"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().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():
+        print(f"ERR: 缺少目录 {VERIFY_DIR}", file=sys.stderr)
+        sys.exit(2)
+    if not DOCS_DIR.is_dir():
+        print(f"ERR: 缺少目录 {DOCS_DIR}", file=sys.stderr)
+        sys.exit(2)
+
+    doc_ids: list[str] = []
+    invalid_verify_names: list[str] = []
+    for p in VERIFY_DIR.iterdir():
+        if p.is_file() and len(p.name) == len("00-00.yml") and p.name[2:3] == "-" and p.name[5:] == ".yml":
+            if is_exec_domain(p.stem):
+                doc_ids.append(p.stem)
+            else:
+                invalid_verify_names.append(p.name)
+
+    missing_docs: list[str] = []
+    missing_files_dir: list[str] = []
+    weak_doc_exec_refs: list[str] = []
+    for did in sorted(set(doc_ids)):
+        matches = sorted(DOCS_DIR.glob(f"{did}-*.md"))
+        if not matches:
+            missing_docs.append(did)
+            continue
+        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)
+        expects_files_dir = (f"ansible/files/{did}/" in content) or ("```yaml" in content)
+        if expects_files_dir and not (ROOT / "ansible" / "files" / did).is_dir():
+            missing_files_dir.append(did)
+
+    if invalid_verify_names:
+        print(
+            f"ERR: verify 仅允许执行域命名（XX>0 且 YY>0），以下文件不合规: {sorted(invalid_verify_names)}",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+    if missing_docs:
+        print(f"ERR: 存在 verify/<doc_id>.yml 但缺少 docs/<doc_id>-*.md: {missing_docs}", 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(sorted(set(doc_ids)))} 条）")
+
+
+if __name__ == "__main__":
+    main()