dev_harness/scripts/check_harness.py

"""检查 DevHarness 必需文件和任务归档的基本结构。"""

from __future__ import annotations

import argparse
import re
from pathlib import Path

from wiki_docs import WikiDocsError, load_config, parse_mirror


ROOT = Path(__file__).resolve().parents[1]
REQUIRED_FILES = (
    "AGENTS.md",
    "README.md",
    "docs/00-project-profile.md",
    "docs/01-workflow.md",
    "docs/templates/task-archive.md",
    "wiki-docs.json",
    "scripts/wiki_docs.py",
    "scripts/sync_wiki_docs.py",
    ".gitea/issue_template/epic.md",
    ".gitea/issue_template/mvp.md",
    ".gitea/issue_template/task.md",
)
ARCHIVE_HEADINGS = (
    "## 背景与目标",
    "## 最终方案",
    "## 修改文件",
    "## 验收结果",
    "## 测试",
    "## 相关提交",
)


def check_required_files(errors: list[str]) -> None:
    for relative_path in REQUIRED_FILES:
        if not (ROOT / relative_path).is_file():
            errors.append(f"缺少必需文件：{relative_path}")


def check_project_profile(errors: list[str], warnings: list[str], strict: bool) -> None:
    profile = ROOT / "docs" / "00-project-profile.md"
    if not profile.is_file():
        return
    if "<填写" in profile.read_text(encoding="utf-8"):
        message = "项目档案仍有未填写内容"
        (errors if strict else warnings).append(message)


def check_archives(errors: list[str]) -> None:
    task_dir = ROOT / "docs" / "task"
    for path in task_dir.glob("*.md"):
        if not re.match(r"^\d+-.+\.md$", path.name):
            errors.append(f"归档文件名不符合 <编号>-<标题>.md：{path.name}")
        content = path.read_text(encoding="utf-8")
        for heading in ARCHIVE_HEADINGS:
            if heading not in content:
                errors.append(f"{path.name} 缺少章节：{heading}")
        if "**未验证部分**：" not in content:
            errors.append(f"{path.name} 没有记录未验证部分")


def check_wiki_mirrors(errors: list[str]) -> None:
    """检查每份本地文档都有显式映射和可追踪的镜像头。"""

    try:
        config = load_config()
    except WikiDocsError as exc:
        errors.append(str(exc))
        return

    mapped_paths = {mapping.path for mapping in config.mappings}
    actual_paths = {
        path.relative_to(ROOT).as_posix() for path in (ROOT / "docs").rglob("*.md")
    }
    for path in sorted(actual_paths - mapped_paths):
        errors.append(f"docs 中存在未登记的 Wiki 镜像：{path}")

    for mapping in config.mappings:
        path = ROOT / mapping.path
        if not path.is_file():
            errors.append(f"缺少 Wiki 镜像：{mapping.path}")
            continue
        try:
            metadata, _ = parse_mirror(path.read_text(encoding="utf-8"))
        except (OSError, UnicodeDecodeError, WikiDocsError) as exc:
            errors.append(f"Wiki 镜像无效 {mapping.path}：{exc}")
            continue
        if metadata.get("generated") != "true (请先修改 Gitea Wiki，禁止直接编辑本文件)":
            errors.append(f"{mapping.path} 没有只读镜像标记")
        if metadata.get("wiki_page") != mapping.page:
            errors.append(f"{mapping.path} 的 wiki_page 与映射不一致")
        revision = metadata.get("wiki_revision", "")
        if re.fullmatch(r"[0-9a-f]{40,64}", revision) is None:
            errors.append(f"{mapping.path} 的 wiki_revision 无效")
        if not metadata.get("synchronized_at"):
            errors.append(f"{mapping.path} 缺少 synchronized_at")


def main() -> int:
    parser = argparse.ArgumentParser(description="检查 DevHarness 项目结构")
    parser.add_argument(
        "--strict",
        action="store_true",
        help="项目档案有占位内容时返回失败",
    )
    args = parser.parse_args()

    errors: list[str] = []
    warnings: list[str] = []
    check_required_files(errors)
    check_project_profile(errors, warnings, args.strict)
    check_wiki_mirrors(errors)
    check_archives(errors)

    for warning in warnings:
        print(f"警告：{warning}")
    for error in errors:
        print(f"错误：{error}")

    if errors:
        print(f"检查失败：{len(errors)} 个问题")
        return 1
    print("DevHarness 检查通过")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())