STM32F4-Base/scripts/check_test_traceability.py

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""check_test_traceability.py - 用例追溯校验（默认仅告警，不阻断提交）。

背景（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>`
         （2026-10-30 测试说明目录分层后改**递归**匹配，板级指南现居 `板级测试/`）。

      [DOC-ONLY]  文档有、代码无 -> 未实现（或代码未标注）
      [CODE-ONLY] 代码有、文档无 -> 未登记（或文档漏写）

    作用域**只取 `*_Test_Guide.md`**：TC-CFG / TC-CLK / TC-WD 属主机侧单元
    测试文档（`配置文件单元测试说明.md` 等），不参与板级追溯，天然被排除。

    **2026-10-21 B 层口径对齐**（docs/编号规范.md §8.1「口径修正记录」）：主机侧单测的
    号改认 `test/host/<模块>/*` 为属主登记处（实测这些号在代码目录外零消费者），
    于是"文档没有"不再一律算断链。真差异收敛为三条：
      ① 文档声明了、代码没有 → DOC-ONLY；
      ② 代码有、母号不在文档、**且号旁边没写人话意图** → CODE-ONLY（真未登记）；
      ③ 代码有、靠"旁边有意图"放过 → 单独打印为 IN-CODE，**弱于文档**，不算已登记。
    小写子项后缀（`TC-<模块码>-003b` 这类小写尾号）按母号算（`subitem_ok`），与编号门禁同口径。
    **批 6 再分两档**：硬件层人工用例（标题/章节含「（硬件层）」）记为 `BENCH`、文档已标未实现/待补/暂缓/已取消的记为 `NOTIMPL`，两者**单列示数**不进差异——但也不是「已覆盖」，只是「不该在这里期望代码」。
    **2026-10-21 第二次口径修正（批 5）**：变更记录行与 `[示例]`/`[计划]` 行**不参与比对**
    （冻结历史按编号规范 §8.1 不回改，旧号靠 `id_aliases.json` 解析；这条豁免另三支脚本早有，本脚本是最后缺它的一个，`DOC-ONLY` 因此 38 → 29、交集不变）；被豁免的号存进 `frozen_ids`，`--verbose` 全量列出——**豁免不等于已对应**，别拿它当收敛。

退出码:
    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

# 控制台编码兜底：pre-commit / CI 之外的裸跑环境代码页常是 936(GBK)，
# print 中文或 ⚠ 会抛 UnicodeEncodeError 让脚本带 traceback 以非零码死掉
# （同 check_ids.py / check_doc_links.py 的做法；2026-10-26 补齐，此前裸跑在第 245 行崩）。
for _stream in (sys.stdout, sys.stderr):
    if hasattr(_stream, "reconfigure"):
        _stream.reconfigure(encoding="utf-8", errors="replace")
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…）。
# 2026-10-20 收编进 id-check 门禁时补的三条（docs/编号规范.md §8「顺带收编」)：
#   ① 规范 §4.1 的合规形态 `TC-[A-Z]{1,4}-\d{3,4}[a-z]?`（带小写后缀，TC-NET-1502b）；
#   ② 现存的大写后缀形态（TC-AI-01A [示例]，§7.1 待统一小写）也要能抓出来，否则整条漏扫；
#   ③ 无模块码形态（iec104 文档里缺模块码的那批用例号，§7.2 列为孤儿）纳入比对而不是静默忽略。
# ⚠ 模块码上界必须跟着 §6 模块码表走：批 2 单词化后码长可达 9 位（ADCHEALTH），
#    这里曾停在 {0,4}，导致代码侧集合从 556 悄悄缩到 217——**同一批改名要复核所有
#    识别面，不止 check_ids.py**（2026-10-21 实测踩到）。
TC_RE = re.compile(r"TC-(?:[A-Z][A-Z0-9]{0,8}-\d{1,4}[A-Za-z]?|\d{2,4}[a-z]?)")
# 规范合规形态（用于 --verbose 里区分"形态待迁移"与"纯追溯断链"）
TC_CANON_RE = re.compile(r"^TC-[A-Z][A-Z0-9]{0,8}-\d{3,4}[a-z]?$")  # 与 §4.1 实测形态同步
# 占位符前缀（文档模板里的 `TC-XXX-…`）不参与比对
PLACEHOLDER_PREFIXES = {"XXX"}
# 与 check_ids.py / rename_ids.py / check_doc_links.py **同一套**豁免口径：
# 变更记录行与 [示例] / [计划] 行是**冻结历史或写法示例**，不是活引用（§8.1 纪律：
# 历史行里的旧号不回改，靠别名表解析）。追溯器原先缺这一条，产生系统性假阳性——
# 2026-10-21 实测：DOC-ONLY 38 处里 12 处来自变更记录行，例如
# `| 2026-10-10 | 新增 TC-AI-070..078（70 → 79 用例）|` 写的是**当年**的用例名，
# 该号在批 2 已随代码改名成 TC-ADCIN-*，历史行不该回改，拿它去代码里找同号必然落空。
SKIP_LINE = re.compile(r"\[示例\]|\[计划\]|^\s*\|\s*20\d\d-\d\d-\d\d\s*\|")
frozen_ids: set = set()   # 只在 --verbose 里列：被豁免的号（历史/示例），不是"已对应"
# 2026-10-21 批 6：`DOC-ONLY` 里混着两种"不是缺口"的号，一律**单列示数**而不是塞进差异，
# 也**不静默消失**——数量恒打印，明细 `--verbose` 可查：
#   BENCH    硬件层人工用例（标题或所属章节含「（硬件层）」）：本来就没有代码载体，
#            属主是人工台架步骤，不是 C 代码（例：§12.5 阶段 15「自愈驱动原语（硬件层，无需 PC）」）。
#   NOTIMPL  文档已显式标了状态词（未实现 / 待补 / 暂缓 / 已取消）：是**已登记的欠账**，
#            不是"查无此号"的假警报。
# ⚠ 反过来别把 BENCH 当"已覆盖"：它只说明"不该期望代码里有"，不证明人工真做过。
BENCH_RX = re.compile(r"[（(]\s*硬件层")
NOTIMPL_RX = re.compile(r"未实现|待补|暂缓|已取消")
# 定义行（决定这个号的**载体类型**）：markdown 标题行，或表格里号在**首格**的行。
# 引用行（正文里"同 TC-NET-601"、"参见 TC-NET-302"）不改变载体判断——否则一个人工
# 用例只要在别处被提一次，就又被要求"代码里必须有"（2026-10-21 实测：按"任意行都算"
# 实现时，BENCH 收了 16 个号却只消掉 1 处差异，等于没生效）。
DEF_LINE_RX = re.compile(r"^(?:#{2,6}\s|\|\s*\*{0,2}\s*TC-)")
bench_ids: set = set()
notimpl_ids: set = set()


def _prefix(tc: str) -> str:
    return tc.rsplit("-", 1)[0]


def _base(tc: str) -> str:
    """去掉小写子项后缀：`TC-TIMESYNC-003b` → `TC-TIMESYNC-003`（与 check_ids 的
    `subitem_ok` 同口径——母号已在登记处即视为已覆盖，子项差异不在这里报）。"""
    return re.sub(r"[a-z]$", "", tc) if re.search(r"\d[a-z]$", tc) else tc


def has_intent(text: str, tc: str) -> bool:
    """该号在代码里是否**旁边写着意图**（B 层口径：`test/host/<模块>/` 就是属主登记处，
    不逐号写文档，但号必须自带一句人话，否则"代码即登记处"等于没有登记处）。

    判据刻意保守：号后面（或本行注释里）要有 ≥6 个有效字符，且不能只是代码 token。
    这是**弱于文档**的保证，脚本会如实打印有多少号是靠这条弱判据过关的，别当成已登记。
    """
    for line in text.splitlines():
        if tc not in line:
            continue
        tail = line.split(tc, 1)[1]
        tail = re.sub(r"^[\"'\)\]\*[:：,，。\-_/`\\s]+", "", tail)
        tail = re.sub(r"[\"'\)\]\*\\s]+$", "", tail)
        body = re.sub(r"[A-Za-z0-9_]{1,3}$", "", tail)          # 尾随的短代码 token
        if len(re.sub(r"[\s\-\*=.。，,:：;；()（）\[\]{}<>|/\\'\"`,]+", "", body)) >= 6:
            if re.search(r"[一-鿿]|[A-Za-z]{4,}", body):
                return True
    return False


def collect(paths, label, want_intent=False):
    """返回 (ids_set, per_prefix_counts[, intent_set])。逐文件扫描，缺文件不致命。"""
    ids = set()
    intents = set()
    global frozen_ids, bench_ids, notimpl_ids
    in_bench_section = False
    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, None) if want_intent else (None, None)
        for line in text.splitlines():
            if re.match(r"^#{2,6}\s+\S", line):        # markdown 章节：记住是否硬件层
                in_bench_section = bool(BENCH_RX.search(line))
            is_def = bool(DEF_LINE_RX.search(line))
            bench = bool(BENCH_RX.search(line)) or (in_bench_section and is_def)
            notimpl = bool(NOTIMPL_RX.search(line))
            skip = bool(SKIP_LINE.search(line))
            for m in TC_RE.findall(line):
                if _prefix(m) in PLACEHOLDER_PREFIXES:
                    continue
                if skip:          # 冻结历史 / 示例行：不参与双向比对，只留痕
                    frozen_ids.add(m)
                    continue
                if label == "doc" and is_def:
                    # 只对文档侧分类：载体类型由**文档里的定义行**说了算，
                    # 且必须从全集里整体减掉（见上面注释的实测坑）
                    if bench:
                        bench_ids.add(m)      # 硬件层人工 → 不期望代码载体
                    if notimpl:
                        notimpl_ids.add(m)    # 已标未实现/待补 → 已登记的欠账
                ids.add(m)
                if want_intent and has_intent(line, m):
                    intents.add(m)
    counts = {}
    for i in sorted(ids):
        counts[_prefix(i)] = counts.get(_prefix(i), 0) + 1
    return (ids, counts, intents) if want_intent else (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))
    ap.add_argument("--board-only", action="store_true",
                    help="只比板级（test/board/*.c ↔ *_Test_Guide.md），"
                         "不含主机侧单测一侧（2026-10-20 起默认纳入 7 篇「单元测试说明.md」）")
    args = ap.parse_args()

    code_dir = Path(args.code_dir)
    doc_dir = Path(args.doc_dir)
    host_dir = REPO_ROOT / "test" / "host"

    code_files = sorted(code_dir.glob("*.c")) if code_dir.is_dir() else []
    # 2026-10-30：docs/测试说明 按用途分了子目录（板级测试/ 单元测试/ …，见
    # docs/测试说明/README.md），文档侧一律**递归**找，否则分层等于静默放行——
    # 这里若还是 glob 单层，doc_files 会变成空表并直接 return 2（门禁瞎掉）。
    doc_files = sorted(doc_dir.rglob("*_Test_Guide.md")) if doc_dir.is_dir() else []
    if not args.board_only:
        # 主机侧单测一侧：7 篇「单元测试说明.md」+ test/host 下的测试代码（*.c / *_test.py /
        # run_unit_test.py）——TC 编号在两侧都是**追溯链的锚点**，缺一侧就是断链。
        doc_files += sorted(doc_dir.rglob("*单元测试说明.md"))
        if host_dir.is_dir():
            code_files += sorted(host_dir.rglob("*.c"))
            code_files += sorted(host_dir.rglob("*.py"))

    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, code_intents = collect(code_files, "code", want_intent=True)
    doc_ids, doc_counts = collect(doc_files, "doc")
    if code_ids is None or doc_ids is None:
        return 2

    # 文档侧的两个单列档整体从文档全集里减掉后再比差异（数量已在上面打印，
    # --verbose 有明细）：BENCH = 人工台架定义，NOTIMPL = 已显式登记未实现
    doc_ids -= bench_ids | notimpl_ids
    doc_bases = {_base(i) for i in doc_ids}
    # 真差异定义（B 层口径 2026-10-21，docs/编号规范.md §8.1）：
    #   ① 文档声明了、代码里没有 → 未实现/未标注（保留，这是硬断链）；
    #   ② 代码有、文档没有，**且**母号也不在文档、**且**号旁边没写意图 → 真未登记；
    #   ③ 代码有、文档没有，但靠"代码即登记处"过关（旁边有意图）→ 单列统计，
    #      不算差异也不算合规达成——它是**弱于文档**的保证，必须看得见数量。
    doc_only = sorted(doc_ids - code_ids)
    code_only = sorted(i for i in code_ids - doc_ids
                       if _base(i) not in doc_bases and i not in code_intents)
    code_only_in_code = sorted(i for i in code_ids - doc_ids
                               if _base(i) not in doc_bases and i in code_intents)

    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)}")
    # 注意：交集/文档侧计数在减档之前打印，这里补一行减档后的口径
    print(f"（减 BENCH/NOTIMPL 后参与比对：文档 {len(doc_ids)}、交集 {len(code_ids & doc_ids)}）")
    print(f"豁免：变更记录/[示例]/[计划] 行的号 {len(frozen_ids)} 个（口径同 check_ids.py，见 §8.1）")
    print(f"单列 BENCH（硬件层人工用例，不期望有代码载体）：{len(bench_ids)} 个")
    print(f"单列 NOTIMPL（文档已标未实现/待补/暂缓/已取消）：{len(notimpl_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}")
    print(f"[IN-CODE]   代码有、文档无，但号旁边写着意图 → 按「代码即属主登记处」放过："
          f"{len(code_only_in_code)}")
    print("            ⚠ 这是**弱于文档**的保证（只证明该行有人话，不证明意图正确）；"
          "对外举证时仍需 C 层模块级说明，清单见 --verbose")
    if args.verbose:
        for i in code_only_in_code:
            print(f"    {i}")

    for name, bag in (("BENCH 硬件层人工", bench_ids), ("NOTIMPL 已登记未实现", notimpl_ids)):
        if args.verbose and bag:
            print("--- %s：不参与差异比对，但**不等于已验证**（共 %d 个）---" % (name, len(bag)))
            for i in sorted(bag):
                print("    ", i)

    if args.verbose and frozen_ids:
        print("--- 被豁免的号（变更记录 / [示例] / [计划] 行，共 %d 个）**不是已对应**，"
              "历史旧号靠 id_aliases.json 解析 ---" % len(frozen_ids))
        for i in sorted(frozen_ids):
            print("    ", 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())