wandering1
f4fea70749
合并 docs/待处理内容.md（N/S/T-x）、审查记录/项目审计改进清单.md（P-x）、 审查记录/下一步任务规划.md（阶段与基线）、审查记录/测试与架构改进建议.md （S1x/A-x）为单一《待处理内容（统一待办登记簿）》。 - 结构：编号空间与来源 / 未闭环一览 / 任务排序（阶段 A~D）/ 逐条详述 / 待验证与待确认 / 设计基线 / 诊断基线 / 内存预算 / 维护约定。 - 编号沿用且不回收；E-xx 仍由 错误码传播审计.md 独立维护。 - 删除 3 份被合并文档；重定向下游引用：README、AGENTS、审查报告、 实机测试实施指南、Net 层架构、NET/cfg 模块 README、脚本注释。 - 同步订正计数：P1=2(+1 收尾) / P2=10 / P3=6。 pre-commit 17/17 Passed。
135 lines
5.2 KiB
Python
135 lines
5.2 KiB
Python
#!/usr/bin/env python3
|
||
# -*- coding: utf-8 -*-
|
||
"""check_test_traceability.py - S4 用例追溯校验（默认仅告警，不阻断提交）。
|
||
|
||
背景（docs/测试说明/实机测试实施指南.md §8.2；原复审项 S4，已闭环）:
|
||
文档声称 91 个 TC、代码有 222 个 TEST_CHECK（断言点数 > 用例数正常），
|
||
但**双向是否一一对应无人校验**——某个 TC 可能"文档写了、代码没实现"，
|
||
或"代码实现了、文档没登记"。纯靠人肉比对。
|
||
|
||
本脚本做什么:
|
||
提取两侧的 TC 编号集合，输出双向差异：
|
||
|
||
① 代码侧：`test/board/*.c`（含 `*_test_task.c` 与 `net_latency_test.c`）
|
||
里出现的 `TC-<PFX>-<NNN>`（注释、DBG_INFO 串皆计入）；
|
||
② 文档侧：`docs/测试说明/*_Test_Guide.md` 里出现的 `TC-<PFX>-<NNN>`。
|
||
|
||
[DOC-ONLY] 文档有、代码无 -> 未实现（或代码未标注）
|
||
[CODE-ONLY] 代码有、文档无 -> 未登记（或文档漏写）
|
||
|
||
作用域**只取 `*_Test_Guide.md`**：TC-CFG / TC-CLK / TC-WD 属主机侧单元
|
||
测试文档（`配置文件单元测试说明.md` 等），不参与板级追溯，天然被排除。
|
||
|
||
退出码:
|
||
0 = 无差异；或有差异但**默认仅告警**（与 doc-links 演进路径一致）
|
||
1 = 有差异且显式 `--strict`
|
||
2 = 环境错误（目录/文件缺失）
|
||
|
||
用法（仓库根目录）:
|
||
& '.venv\\Scripts\\python.exe' scripts/check_test_traceability.py
|
||
& '.venv\\Scripts\\python.exe' scripts/check_test_traceability.py --strict
|
||
& '.venv\\Scripts\\python.exe' scripts/check_test_traceability.py --verbose
|
||
|
||
设计依据：docs/测试说明/实机测试实施指南.md §8.2（S4 用例追溯，原复审项已闭环）
|
||
创建日期：2026-10-03
|
||
"""
|
||
|
||
import argparse
|
||
import re
|
||
import sys
|
||
from pathlib import Path
|
||
|
||
REPO_ROOT = Path(__file__).resolve().parent.parent
|
||
CODE_DIR = REPO_ROOT / "test" / "board"
|
||
DOC_DIR = REPO_ROOT / "docs" / "测试说明"
|
||
|
||
# TC 编号：TC-<PFX>-<NNN>。<PFX> 允许字母数字（NET/GD5F/STO/RTC…）
|
||
TC_RE = re.compile(r"TC-[A-Za-z0-9]+-\d+")
|
||
# 占位符前缀（文档模板里的 `TC-XXX-…`）不参与比对
|
||
PLACEHOLDER_PREFIXES = {"XXX"}
|
||
|
||
|
||
def _prefix(tc: str) -> str:
|
||
return tc.rsplit("-", 1)[0]
|
||
|
||
|
||
def collect(paths, label):
|
||
"""返回 (ids_set, per_prefix_counts)。逐文件扫描，缺文件不致命。"""
|
||
ids = set()
|
||
for p in paths:
|
||
try:
|
||
text = p.read_text(encoding="utf-8", errors="replace")
|
||
except OSError as e: # pragma: no cover - 环境错误
|
||
print(f"[ERR] 无法读取 {p}: {e}", file=sys.stderr)
|
||
return None, None
|
||
for m in TC_RE.findall(text):
|
||
if _prefix(m) in PLACEHOLDER_PREFIXES:
|
||
continue
|
||
ids.add(m)
|
||
counts = {}
|
||
for i in sorted(ids):
|
||
counts[_prefix(i)] = counts.get(_prefix(i), 0) + 1
|
||
return ids, counts
|
||
|
||
|
||
def main():
|
||
ap = argparse.ArgumentParser(description="S4 用例追溯校验（TC 编号双向比对）")
|
||
ap.add_argument("--strict", action="store_true",
|
||
help="有差异时返回退出码 1（默认仅告警，返回 0）")
|
||
ap.add_argument("--verbose", action="store_true",
|
||
help="额外打印各前缀的 TC 计数")
|
||
ap.add_argument("--code-dir", default=str(CODE_DIR))
|
||
ap.add_argument("--doc-dir", default=str(DOC_DIR))
|
||
args = ap.parse_args()
|
||
|
||
code_dir = Path(args.code_dir)
|
||
doc_dir = Path(args.doc_dir)
|
||
|
||
code_files = sorted(code_dir.glob("*.c")) if code_dir.is_dir() else []
|
||
doc_files = sorted(doc_dir.glob("*_Test_Guide.md")) if doc_dir.is_dir() else []
|
||
|
||
if not code_files:
|
||
print(f"[ERR] 未找到代码侧文件：{code_dir}/*.c", file=sys.stderr)
|
||
return 2
|
||
if not doc_files:
|
||
print(f"[ERR] 未找到文档侧文件：{doc_dir}/*_Test_Guide.md", file=sys.stderr)
|
||
return 2
|
||
|
||
code_ids, code_counts = collect(code_files, "code")
|
||
doc_ids, doc_counts = collect(doc_files, "doc")
|
||
if code_ids is None or doc_ids is None:
|
||
return 2
|
||
|
||
doc_only = sorted(doc_ids - code_ids)
|
||
code_only = sorted(code_ids - doc_ids)
|
||
|
||
print("=== S4 用例追溯校验（TC 编号双向比对）===")
|
||
print(f"代码侧：{len(code_files)} 个文件，{len(code_ids)} 个 TC")
|
||
print(f"文档侧：{len(doc_files)} 个文件，{len(doc_ids)} 个 TC")
|
||
print(f"交集：{len(code_ids & doc_ids)}")
|
||
|
||
if args.verbose:
|
||
print("--- 各前缀 TC 计数（代码 / 文档）---")
|
||
for pfx in sorted(set(code_counts) | set(doc_counts)):
|
||
print(f" {pfx}: code={code_counts.get(pfx, 0)} doc={doc_counts.get(pfx, 0)}")
|
||
|
||
print()
|
||
print(f"[DOC-ONLY] 文档有、代码无（未实现/代码未标注）：{len(doc_only)}")
|
||
for i in doc_only:
|
||
print(f" {i}")
|
||
print(f"[CODE-ONLY] 代码有、文档无（未登记/文档漏写）：{len(code_only)}")
|
||
for i in code_only:
|
||
print(f" {i}")
|
||
|
||
if not doc_only and not code_only:
|
||
print("\n[OK] 双向一一对应，无差异")
|
||
return 0
|
||
|
||
print(f"\n[WARN] 共 {len(doc_only) + len(code_only)} 处差异"
|
||
f"（默认仅告警，不阻断提交；收敛后再考虑升为门禁）")
|
||
return 1 if args.strict else 0
|
||
|
||
|
||
if __name__ == "__main__":
|
||
sys.exit(main())
|