STM32F4-Base/scripts/check_nested_comment.py

#!/usr/bin/env python3
"""块注释体内不得再出现 /*（ARMCC 诊断 9-D：nested comment is not allowed）。

为什么要有这根（2026-10-26 一天内真实复发三次的同类）:
    在注释里写通配路径是本仓的常态写法，而 C 的块注释**不嵌套**：注释体内出现 /* 时，
    ARMCC 报 "#9-D: nested comment is not allowed"，并且**每个 include 该头文件的编译单元
    都各打一行**——实测一例扩散到 16 条警告，一度把整批 10 条真警告挡住看不见。
    要害与 bom-guard 同形：**只在重编译那个 TU 时才暴露**，历史"0 警告"不代表安全。

判定（刻意只管这一件事）:
    逐字节状态机走 CODE / 行注释 / 块注释 / 字符串 / 字符字面量；只有在**块注释体内**
    看到的 /* 才算问题。所以这些一律不算：
        const char *s = "/* 不是注释";     // 字符串里的 /*
        // /* 行注释里写个 /*               <Drivers/BSP/UI/ui_x.c>  尖括号写法
    反过来，块注释里写 Drivers/BSP/UI/** 一定算（** 里第一个 * 后面紧跟的 / 就是 /*）。

增量拦截（照 bom-guard / bsp-err / layer-deps 三条现成先例，只减不增）:
    存量钉在 BASELINE（按 文件 + 上下文指纹 计数，不按行号——行号会随手改漂移）；
    基线之外的新命中 → 退出码 1。还清某条就删那一行，--prune 会把可删的打出来。

退出码:
    0 = 通过（或只剩存量基线）
    1 = 基线之外有新命中
    2 = 用法或环境错误（不在 git 仓库内、--all 取文件清单失败等）

用法:
    python scripts/check_nested_comment.py <file...>        # 钩子入口（pre-commit 传文件名）
    python scripts/check_nested_comment.py --all            # 全仓审计（跳过第三方与生成物）
    python scripts/check_nested_comment.py --emit-baseline  # 打出现存命中的基线条目（贴回本文件）
    python scripts/check_nested_comment.py --selftest       # 自证有牙 + 反例不误报
    python scripts/check_nested_comment.py --prune          # 对照现状点名"已还清、可删"的基线行
"""
import argparse
import os
import subprocess
import sys
import tempfile

try:
    sys.stdout.reconfigure(errors="replace")   # GBK 控制台打不出 ▶ 等符号
    sys.stderr.reconfigure(errors="replace")
except Exception:
    pass

REPO = os.path.normpath(os.path.join(os.path.dirname(os.path.abspath(__file__)), ".."))
EXTS = (".c", ".h")

# 第三方与生成物：与 .pre-commit-config.yaml 顶层 exclude 同口径（改动要两边对一遍）
SKIP_DIRS = (
    # 与 .pre-commit-config.yaml 顶层 exclude 同口径；test/ **不**排除（主机侧桩头文件里也真查出过
    # 嵌套注释，见 BASELINE），只排构建产物目录。本闸 --all 的文件集必须与钩子 types: [c] 实际喂进来的
    # 一致，否则"手跑面"与"提交面"又会变成两个数（本仓为这种不同源返工过好几次）。
    "Lib/", "Middlewares/", "Drivers/STM32F4xx_HAL_Driver/", "Drivers/CMSIS/",
    "MDK-ARM/", "simulator/build/", "test/board/build/",
)

# 存量基线：接线当天（2026-10-27）实测已存在的命中，**只减不增**（还清即删整条，--prune 打出台账）。
# 两处同一个形态：注释里写作用域 "test/host/**" —— 那个 /* 就是嵌套注释起点。它们今天不报，只因为
# 这两份假件头文件不参与 MCU 构建（换 GCC/clang 的 -Wcomment 就会报）；一旦有人把它 include 进板端
# TU，就会按包含者数量刷出一排 #9-D。修法是把作用域写成语义短语（"test/host 目录"），属 test/ 写域，
# 等那边的道顺手还；还清后删掉对应行，本闸立刻恢复"零豁免"。
BASELINE = (
    ("test/host/common/ch395f_fake.h",
     "件才能测。 * * ⚠ 仅供 test/host/** 使用，不参与 MCU 构建。 * * 为"),
    ("test/host/common/fatfs_fake.h",
     "rename。 * * 仅供 test/host/** 使用：不参与 MCU 构建，也不参与 sim"),
)

FIX_HINT = ("修法：注释里别写 /**（C 块注释不嵌套，那个 /* 会被当第二次注释起点并报 "
            "#9-D）——路径写全目录就好（Drivers/BSP/UI/），或按本仓既有做法用尖括号包住"
            "（<Drivers/BSP/UI/ui_x.c>）")


def rel_of(path):
    try:
        return os.path.relpath(os.path.abspath(path), REPO).replace(os.sep, "/")
    except Exception:
        return str(path).replace(os.sep, "/")


def scan_text(text):
    """状态机扫一份源码 → [(行号, 列号, 上下文指纹)]，只在块注释体内报 /*。"""
    hits = []
    state = 0          # 0 代码 1 行注释 2 块注释 3 字符串 4 字符字面量
    line, col = 1, 1
    i, n = 0, len(text)
    while i < n:
        c = text[i]
        nxt = text[i + 1] if i + 1 < n else ""
        if state == 2:                                  # 块注释体内
            if c == "*" and nxt == "/":
                state = 0
                i += 2
                col += 2
                continue
            if c == "/" and nxt == "*":                 # ← 唯一的问题形态
                hits.append((line, col, context_of(text, i)))
            if c == "\n":
                line += 1
                col = 0
            i += 1
            col += 1
            continue
        if state == 1:                                  # 行注释
            if c == "\n":
                state, line = 0, line + 1
                col = 0
            i += 1
            col += 1
            continue
        if state == 3:                                  # 字符串
            if c == "\\":
                i += 2
                col += 2
                continue
            if c == '"':
                state = 0
            i += 1
            col += 1
            continue
        if state == 4:                                  # 字符字面量
            if c == "\\":
                i += 2
                col += 2
                continue
            if c == "'":
                state = 0
            i += 1
            col += 1
            continue
        if c == "/" and nxt == "*":                     # 块注释开始
            state = 2
            i += 2
            col += 2
            continue
        if c == "/" and nxt == "/":                     # 行注释开始
            state = 1
        elif c == '"':
            state = 3
        elif c == "'":
            state = 4
        elif c == "\n":
            line += 1
            col = 0
            i += 1
            col += 1
            continue
        i += 1
        col += 1
    return hits


def context_of(text, pos, width=26):
    """取 /* 前后一小段做指纹：压掉空白与换行，避免行号漂移让基线失效。"""
    seg = text[max(0, pos - width):pos + width]
    return " ".join(seg.split())


def read_text(path):
    with open(path, "rb") as f:
        raw = f.read()
    return raw.decode("utf-8", errors="replace")


def check_file(path):
    """单个文件 → (rel, [(行, 列, 指纹)])。"""
    return rel_of(path), scan_text(read_text(path))


def tracked_sources():
    """--all 用的文件清单：git 跟踪的 C/C++，按 SKIP_DIRS 排除第三方与生成物。"""
    try:
        out = subprocess.run(["git", "-c", "core.quotePath=false", "ls-files", "-z"],
                             cwd=REPO, capture_output=True, check=True).stdout
    except Exception as e:
        print("[ENV] git ls-files 失败（不在 git 仓库里？）：%s" % e)
        return None
    files = []
    for chunk in out.split(b"\0"):
        p = chunk.decode("utf-8", errors="replace").strip().replace("\\", "/")
        if not p or not p.endswith(EXTS):
            continue
        if p.startswith(SKIP_DIRS):
            continue
        full = os.path.join(REPO, *p.split("/"))
        if os.path.isfile(full):
            files.append(full)
    return sorted(files)


def fingerprint_counts(rel, hits):
    d = {}
    for _line, _col, ctx in hits:
        key = (rel, ctx)
        d[key] = d.get(key, 0) + 1
    return d


def split_against_baseline(found, baseline):
    """→ (新命中列表, 存量在册列表, 已还清可删的基线行)。新命中 = 超出基线配额的部分。"""
    allow = {}
    for rel, ctx in baseline:
        allow[(rel, ctx)] = allow.get((rel, ctx), 0) + 1
    new, inbase = [], []
    for key, cnt in found.items():
        quota = allow.get(key, 0)
        if cnt > quota:
            new.append((key, cnt - quota))
        if quota:
            inbase.append((key, min(cnt, quota)))
    used = {}
    for key, cnt in found.items():
        used[key] = cnt
    cleared = [(rel, ctx) for (rel, ctx) in baseline if used.get((rel, ctx), 0) == 0]
    dedup_cleared = []
    seen = set()
    for row in cleared:
        if row not in seen:
            seen.add(row)
            dedup_cleared.append(row)
    return new, inbase, dedup_cleared


def report(files, baseline, args):
    """跑一批文件 → (退出码, 汇总 dict)。"""
    found = {}
    per_file = {}
    for p in files:
        rel, hits = check_file(p)
        if hits:
            per_file[rel] = hits
            for key, cnt in fingerprint_counts(rel, hits).items():
                found[key] = found.get(key, 0) + cnt
    new, inbase, cleared = split_against_baseline(found, baseline)
    for (rel, ctx), cnt in sorted(new):
        first = per_file[rel][0]
        print("  [NEW ] %s:%d:%d  块注释体内出现 /*（出现 %d 次同形）" % (rel, first[0], first[1], cnt))
        print("         上下文：%s" % ctx)
        print("         %s" % FIX_HINT)
    if args.verbose:
        for (rel, ctx), cnt in sorted(inbase):
            print("  [BASE] %-40s 存量基线在册 %d 处：%s" % (rel, cnt, ctx))
    if cleared and baseline:
        print("  [TIGHTEN] 基线 %d 条本轮实测已还清，可下架（--prune 打出台账）：%s"
              % (len(cleared), ", ".join(sorted({r for r, _c in cleared}))))
    if args.prune:
        print("\n--- 存量基线台账（只减不增）---")
        for rel, ctx in baseline:
            print("  %-40s %s" % (rel, ctx))
    summary = {"files": len(files), "hits": sum(found.values()),
               "new": sum(c for _k, c in new), "baseline": sum(c for _k, c in inbase)}
    if summary["new"]:
        print("汇总：查 %d 个文件，新发 %d 处，存量基线在册 %d 处"
              % (summary["files"], summary["new"], summary["baseline"]))
        print("结论: FAIL —— 块注释里出现了 /*（重编译该 TU 时每个包含者都会多一行 #9-D 警告）")
        return 1, summary
    print("汇总：查 %d 个文件，新发 0 处，存量基线在册 %d 处（走 --prune 还清）"
          % (summary["files"], summary["baseline"]))
    print("结论: PASS —— 没有新的块注释嵌套 /*")
    return 0, summary


def emit_baseline(files):
    found = {}
    for p in files:
        rel, hits = check_file(p)
        for key, cnt in fingerprint_counts(rel, hits).items():
            found[key] = found.get(key, 0) + cnt
    print("# 贴回 scripts/check_nested_comment.py 的 BASELINE（只减不增）：")
    for (rel, ctx), cnt in sorted(found.items()):
        for _i in range(cnt):
            print('    ("%s",\n     "%s"),' % (rel, ctx.replace('"', "'")))
    return 0


def selftest(args):
    """正例必须照出来，反例必须安静——两种形态一起测，防止只会对着字符串叫。"""
    print("\n--- 自证有牙（临时目录，不碰仓库）---")
    tmp = tempfile.mkdtemp(prefix="dsh_nested_")
    good = os.path.join(tmp, "ok_case.h")
    bad = os.path.join(tmp, "bad_case.h")
    with open(good, "w", encoding="utf-8", newline="\n") as f:
        f.write('/* 尖括号写法 <Drivers/BSP/UI/ui_w_soe.c> 没问题 */\n'
                'static const char *g = "/* 字符串里的不算 */";\n'
                '// /* 行注释里写个 /* 也不算\n'
                '/* 第一段结束 */\n/* 第二段正常开始 */\n')
    with open(bad, "w", encoding="utf-8", newline="\n") as f:
        f.write('/* 类型名表在 UI 侧 Drivers/BSP/UI/**，不在本道写域 */\n')
    rel_g, hits_g = check_file(good)
    rel_b, hits_b = check_file(bad)
    print("    反例（尖括号 / 字符串 / 行注释 / 两段正常注释）→ 命中 %d 处（要求 0）" % len(hits_g))
    print("    正例（注释里写 Drivers/BSP/UI/**）→ 命中 %d 处（要求 ≥1）：行 %s 列 %s"
          % (len(hits_b), hits_b[0][0] if hits_b else "-", hits_b[0][1] if hits_b else "-"))
    ok_neg, ok_pos = (len(hits_g) == 0), (len(hits_b) >= 1)
    # 基线机制也要测：同一份命中，钉进基线后必须从「新发」变成「在册」
    found = fingerprint_counts(rel_b, hits_b)
    total = sum(found.values())
    fake_baseline = tuple((rel_b, ctx) for (_l, _col, ctx) in hits_b)
    n_new_raw, _b_raw, _c_raw = split_against_baseline(found, ())
    n_new, n_base, cleared = split_against_baseline(found, fake_baseline)
    print("    基线机制：命中 %d 处 —— 不钉基线算新发 %d；钉成基线后新发 %d / 在册 %d / 还清可删 %d"
          % (total, sum(c for _k, c in n_new_raw), sum(c for _k, c in n_new),
             sum(c for _k, c in n_base), len(cleared)))
    ok_bl = (sum(c for _k, c in n_new_raw) == total and not n_new
             and sum(c for _k, c in n_base) == total and not cleared)
    # 「只减不增」的牙：同一个文件里再来一处**不同形态**的嵌套，必须算新发而不是被基线吞掉
    bad2 = os.path.join(tmp, "bad2_case.c")
    with open(bad2, "w", encoding="utf-8", newline="\n") as f:
        f.write("/* 第一处：Drivers/BSP/UI/** 存量形态 */\n"
                "/* 第二处：新写的 App/algo/* 作用域，基线里没有 */\n")
    rel2, hits2 = check_file(bad2)
    two = fingerprint_counts(rel2, hits2)
    only_first = tuple((rel2, sorted(two)[0][1]) for _i in range(1))
    n2_new, n2_base, _c2 = split_against_baseline(two, only_first)
    print("    只减不增：同文件两处命中、只把第一处钉进基线 → 新发 %d / 在册 %d（要求 1 / 1）"
          % (sum(c for _k, c in n2_new), sum(c for _k, c in n2_base)))
    ok_bl = ok_bl and (sum(c for _k, c in n2_new) == 1 and sum(c for _k, c in n2_base) == 1)
    try:
        os.remove(bad2)
    except OSError:
        pass
    for p in (good, bad):
        try:
            os.remove(p)
        except OSError:
            pass
    return ok_neg and ok_pos and ok_bl




def main(argv=None):
    ap = argparse.ArgumentParser(description="块注释体内不得再出现 /*（ARMCC #9-D）")
    ap.add_argument("files", nargs="*", help="待检查文件（钩子入口）")
    ap.add_argument("--all", action="store_true", help="全仓审计（git 跟踪的 C/C++，排除第三方）")
    ap.add_argument("--verbose", action="store_true", help="逐条打印存量基线在册项")
    ap.add_argument("--emit-baseline", action="store_true", help="打出现存命中对应的基线条目")
    ap.add_argument("--prune", action="store_true", help="打印基线台账并点名已还清的行")
    ap.add_argument("--selftest", action="store_true", help="正例照得出 + 反例不误报 + 基线机制有效")
    args = ap.parse_args(argv)

    if not os.path.exists(os.path.join(REPO, ".git")):
        print("[ENV] 仓库根定位失败：%s 里没有 .git（目录或 worktree 的 gitdir 文件都算）" % REPO)
        return 2

    print("=== 块注释嵌套检查 check_nested_comment.py（注释体内出现 /* = ARMCC 诊断 9-D）===")
    print("    仓库根 %s / 存量基线 %d 条（只减不增）" % (REPO, len(BASELINE)))

    if args.all:
        files = tracked_sources()
        if files is None:
            return 2
    elif args.files:
        files = [f if os.path.isabs(f) else os.path.join(REPO, f) for f in args.files]
        files = [f for f in files if f.endswith(EXTS) and os.path.isfile(f)]
    else:
        files = []

    if args.selftest and not selftest(args):
        print("  [SELFTEST] FAIL：正例/反例/基线机制有一项不对 → 别信这根闸，先修脚本")
        return 1
    if args.selftest:
        print("  [SELFTEST] PASS：注释里写 /** 必被点名；字符串/行注释/尖括号写法不误报")
        if not (args.all or args.files):
            return 0      # 只要了自测就别往下走（pre-commit 自测入口用）

    if args.emit_baseline:
        if not files:
            print("[USAGE] --emit-baseline 要配 --all 或给文件清单")
            return 2
        return emit_baseline(files)

    if not files:
        print("[USAGE] 没给文件，也没 --all/--selftest/--emit-baseline")
        return 2

    code, _s = report(files, BASELINE, args)
    return code


if __name__ == "__main__":
    sys.exit(main())