209 lines
6.5 KiB
Python
209 lines
6.5 KiB
Python
#!/usr/bin/env python3
|
||
"""校验 Vibe Coding 文档结构、链接、占位符和功能追溯。"""
|
||
|
||
from __future__ import annotations
|
||
|
||
import argparse
|
||
import re
|
||
import sys
|
||
from pathlib import Path
|
||
|
||
|
||
PLACEHOLDER = re.compile(r"\{\{[^{}\n]+\}\}")
|
||
MARKDOWN_LINK = re.compile(r"\[[^\]]+\]\(([^)]+)\)")
|
||
FUNCTION_ID = re.compile(r"\bF-\d{3}\b")
|
||
OLD_NAMES = {
|
||
"03.冒烟自测用例.md",
|
||
"06.逻辑验证报告.md",
|
||
"07.验收与交付报告.md",
|
||
}
|
||
|
||
|
||
class Report:
|
||
def __init__(self) -> None:
|
||
self.errors: list[str] = []
|
||
self.warnings: list[str] = []
|
||
|
||
def error(self, message: str) -> None:
|
||
self.errors.append(message)
|
||
|
||
def warning(self, message: str) -> None:
|
||
self.warnings.append(message)
|
||
|
||
|
||
def read_text(path: Path, report: Report) -> str:
|
||
try:
|
||
return path.read_text(encoding="utf-8")
|
||
except UnicodeDecodeError:
|
||
report.error(f"文件不是有效 UTF-8：{path}")
|
||
except OSError as exc:
|
||
report.error(f"无法读取文件：{path}（{exc}）")
|
||
return ""
|
||
|
||
|
||
def check_links(path: Path, text: str, report: Report) -> None:
|
||
for match in MARKDOWN_LINK.finditer(text):
|
||
target = match.group(1).strip()
|
||
if (
|
||
not target
|
||
or target.startswith(("#", "http://", "https://", "mailto:"))
|
||
or "{{" in target
|
||
):
|
||
continue
|
||
relative = target.split("#", 1)[0]
|
||
if not (path.parent / relative).resolve().exists():
|
||
report.error(f"失效链接：{path} -> {target}")
|
||
|
||
|
||
def required_root_files(root: Path) -> list[Path]:
|
||
return [
|
||
root / "README.md",
|
||
root / "STATUS.md",
|
||
root / "技术侧需求分析.md",
|
||
root / "source" / "README.md",
|
||
root / "code" / "MANIFEST.md",
|
||
]
|
||
|
||
|
||
def task_directories(root: Path) -> list[Path]:
|
||
tasks_root = root / "tasks"
|
||
if not tasks_root.is_dir():
|
||
return []
|
||
return sorted(path for path in tasks_root.iterdir() if path.is_dir())
|
||
|
||
|
||
def required_task_names(phase: str) -> list[str]:
|
||
names = ["01.需求分析.md"]
|
||
if phase in {"g2", "g3", "archive"}:
|
||
names += ["02.技术实现方案.md", "03.冒烟与逻辑验证.md"]
|
||
if phase in {"g3", "archive"}:
|
||
names += ["04.技术实现记录.md", "05.代码Review报告.md"]
|
||
if phase == "archive":
|
||
names += ["06.验收与交付报告.md"]
|
||
return names
|
||
|
||
|
||
def check_traceability(task: Path, report: Report) -> None:
|
||
requirement = read_text(task / "01.需求分析.md", report)
|
||
design = read_text(task / "02.技术实现方案.md", report)
|
||
validation = read_text(task / "03.冒烟与逻辑验证.md", report)
|
||
required_ids = set(FUNCTION_ID.findall(requirement))
|
||
if not required_ids:
|
||
report.warning(f"未在需求分析中发现功能编号：{task}")
|
||
return
|
||
for function_id in sorted(required_ids):
|
||
if function_id not in design:
|
||
report.error(f"{task.name} 的 {function_id} 未出现在技术方案中")
|
||
if function_id not in validation:
|
||
report.error(f"{task.name} 的 {function_id} 未出现在验证文档中")
|
||
|
||
|
||
def validate_l1(
|
||
root: Path,
|
||
allow_placeholders: bool,
|
||
report: Report,
|
||
) -> None:
|
||
document = root / "01.精简变更日志.md"
|
||
if not document.is_file():
|
||
report.error(f"缺少 L1 文档：{document}")
|
||
return
|
||
text = read_text(document, report)
|
||
if not allow_placeholders and PLACEHOLDER.search(text):
|
||
report.error(f"存在未填写占位符：{document}")
|
||
check_links(document, text, report)
|
||
|
||
|
||
def validate_l2(
|
||
root: Path,
|
||
phase: str,
|
||
allow_placeholders: bool,
|
||
report: Report,
|
||
) -> None:
|
||
required = required_root_files(root)
|
||
tasks = task_directories(root)
|
||
if not tasks:
|
||
report.error(f"未发现子任务目录：{root / 'tasks'}")
|
||
|
||
for task in tasks:
|
||
for name in required_task_names(phase):
|
||
required.append(task / name)
|
||
for child in task.iterdir():
|
||
if child.name in OLD_NAMES:
|
||
report.error(f"发现旧版文档名称：{child}")
|
||
|
||
if phase == "archive":
|
||
required.append(root / "归档记录.md")
|
||
|
||
existing_required: list[Path] = []
|
||
for path in required:
|
||
if not path.is_file():
|
||
report.error(f"缺少必需文件：{path}")
|
||
else:
|
||
existing_required.append(path)
|
||
|
||
status = root / "STATUS.md"
|
||
if status.is_file():
|
||
status_text = read_text(status, report)
|
||
for heading in ("原始需求版本", "确认文档及版本", "代码版本标识"):
|
||
if heading not in status_text:
|
||
report.error(f"STATUS.md 缺少门禁绑定字段：{heading}")
|
||
|
||
for path in existing_required:
|
||
text = read_text(path, report)
|
||
if not allow_placeholders and PLACEHOLDER.search(text):
|
||
report.error(f"存在未填写占位符：{path}")
|
||
check_links(path, text, report)
|
||
|
||
if phase in {"g2", "g3", "archive"}:
|
||
for task in tasks:
|
||
if all((task / name).is_file() for name in required_task_names("g2")):
|
||
check_traceability(task, report)
|
||
|
||
|
||
def build_parser() -> argparse.ArgumentParser:
|
||
parser = argparse.ArgumentParser(
|
||
description="校验 Vibe Coding 的 L1/L2 文档完整性。",
|
||
)
|
||
parser.add_argument("path", help="L1 所在目录或 L2 PM 目录")
|
||
parser.add_argument(
|
||
"--phase",
|
||
choices=["l1", "structure", "g1", "g2", "g3", "archive"],
|
||
required=True,
|
||
help="目标校验阶段",
|
||
)
|
||
parser.add_argument(
|
||
"--allow-placeholders",
|
||
action="store_true",
|
||
help="允许模板占位符，适合刚初始化后的结构检查",
|
||
)
|
||
return parser
|
||
|
||
|
||
def main() -> int:
|
||
args = build_parser().parse_args()
|
||
root = Path(args.path).resolve()
|
||
if not root.is_dir():
|
||
print(f"校验失败：目录不存在：{root}", file=sys.stderr)
|
||
return 1
|
||
|
||
report = Report()
|
||
if args.phase == "l1":
|
||
validate_l1(root, args.allow_placeholders, report)
|
||
else:
|
||
validate_l2(root, args.phase, args.allow_placeholders, report)
|
||
|
||
for warning in report.warnings:
|
||
print(f"警告：{warning}")
|
||
for error in report.errors:
|
||
print(f"错误：{error}", file=sys.stderr)
|
||
|
||
if report.errors:
|
||
print(f"校验失败：{len(report.errors)} 个错误，{len(report.warnings)} 个警告")
|
||
return 1
|
||
print(f"校验通过：0 个错误，{len(report.warnings)} 个警告")
|
||
return 0
|
||
|
||
|
||
if __name__ == "__main__":
|
||
raise SystemExit(main())
|