STM32F4-Base/scripts/check_font_charset.py

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""check_font_charset.py - UI 字符集差集门禁（防"缺字显示白框"，报告 §6.5 U4 残余）。

背景:
    本工程唯一中文字体 `Drivers/BSP/UI/ui_font_cn_12.c` 是**子集**字体：只包含
    `ui_cn_chars.txt` 列出的码位。生成链（font-regen skill 四步）：
        UI 源码 --extract_cn.py--> ui_cn_chars.txt --make_font.py--> ui_font_cn_12.c
    `make_font.py` 的 `verify_coverage()` 只在**生成期**校验"txt ⊆ 字体 cmap"；
    若开发者改了 UI 字符串却忘了重跑 extract_cn / make_font，提交期**无任何门禁**
    能拦住——缺字上机渲染为空白（白框），无日志无报错，只能靠肉眼截图发现。
    本钩子把这条约定机械化（U4 三钩子之二，golden 已建、registration-check 见 §2.18）。

判定口径（两段链条，缺一环即白框）:
    A. 必需字符集（源码在用 ∪ KEEP_EXTRA 保留字）  vs  ui_cn_chars.txt
       必需、txt 无   -> [GAP] FAIL（字体必然缺此字形 → 白框；保留字被剔同样 FAIL——
                          防未来 extract_cn 按"源码已不用"静默删掉已落盘记录的用字）
       txt 有、非必需 -> [WARN] 不拦（未知冗余字形只费 Flash 不致白框；--strict 升级为
                          FAIL；KEEP_EXTRA 内的字不计入冗余——刻意保留 ≠ 未知冗余）
    B. ui_cn_chars.txt      vs  ui_font_cn_12.c 的 cmap
       txt 有、字体无  -> [GAP] FAIL（lv_font_conv 对缺字形/低码位会**静默丢字**）
    A 通过（txt ⊇ 必需）+ B 通过（字体 ⊇ txt）⟹ 字体 ⊇ 源码在用与刻意保留的每个字。

刻意保留清单 KEEP_EXTRA（同构 check_registration.py 的 KNOWN_GAPS：存量 + 逐条理由）:
    extract_cn 是**静态扫描**，照不出运行期**已落盘数据**里的汉字——典型如
    /log/selftest.log 的定长 64 B 记录（跨固件持久，自检页直接渲染 desc）。这类字
    源码已不用、但删字形会让**历史审计记录**渲染空白且不可逆；收益（每字 ~200 B RO，
    占 1 MB Flash 万分之几）与代价完全不对称（同 2026-10-15 内存优化簇"收益不抵风险"
    整簇暂缓的裁定逻辑）。新增条目必须写理由与出处；确认相关落盘数据已不存在后方可
    删条目（删条目后下次 font-regen 自然瘦身）。
    ⚠ font-regen 流程：extract_cn 重生成 txt 时**不会**带上保留字（源码已不用），须把
      KEEP_EXTRA 的字并回 ui_cn_chars.txt 再跑 make_font.py，否则本钩子 A 段 FAIL 并
      逐字给出理由——刻意设计（静默丢失 = 事故），不是误报。

单一规则源（关键设计）:
    本脚本**不自创**第二套解析规则——字符集提取复用 `tools/font_gen/extract_cn.py`
    的 `SCAN` 清单与 `collect()` 状态机（跳过注释/字符常量、只取双引号串内非 ASCII），
    cmap 覆盖判定复用 `tools/font_gen/make_font.py` 的 `verify_coverage()`（含稀疏
    unicode_list 与补回字形的单码位 cmap 条目）。两套规则必然漂移，这正是本项目
    反复在防的（见 pre-commit使用说明.md §5.5 教训）。

用法（仓库根目录）:
    & '.venv\\Scripts\\python.exe' scripts/check_font_charset.py
    & '.venv\\Scripts\\python.exe' scripts/check_font_charset.py --strict
    # 注入测试用覆盖（不改动仓库文件即可复现"缺字"场景）:
    #   --chars <副本>   模拟字符集文件缺/多字
    #   --font  <副本>   模拟字体 cmap 丢字形

退出码:
    0 = 通过（必需字符——源码在用 ∪ KEEP_EXTRA——全部在字体里；未知冗余仅 WARN）
    1 = 失败（存在白框方向的缺口：必需字不在 txt（含 KEEP_EXTRA 保留字被剔），或 txt 字不在字体；--strict 时未知冗余也算）
    2 = 环境错误（字符集文件 / 字体文件 / 生成器脚本缺失）

创建日期：2026-10-15（U4 残余，报告 §6.5 / §7 交付物清单"字符集差集检查"行）
"""

import argparse
import importlib.util
import os
import re
import sys

# --- 仓库根（scripts/ 的上一级）---
REPO_ROOT = os.path.normpath(os.path.join(os.path.dirname(os.path.abspath(__file__)), ".."))
TOOLS_DIR = os.path.join(REPO_ROOT, "tools", "font_gen")

# --- 刻意保留的冗余字（同构 check_registration.py 的 KNOWN_GAPS：逐条理由 + 出处）---
# 这些字**源码已不用**，但 2026-09-14~09-20 窗口的固件把它们写进了 /log/selftest.log
# 定长 64 B 记录（跨固件持久，自检页渲染 desc）。删字形 = 历史故障行永久渲染空白，
# 而收益只有每字 ~200 B RO——不对称，故保留并登记（Lead 裁定 2026-10-15，task-6 D 案）。
# 钩子按"必需"对待：txt/字体里缺任一保留字 → FAIL（防下次 font-regen 静默再删）。
KEEP_EXTRA = {
    "异": "9eb1bd63(2026-09-14) 中文自检描述 \"NAND异常/ADC异常/时钟芯片异常/通讯异常/"
          "文件系统异常\" 曾落盘 /log/selftest.log；6f51c62a(2026-09-20 串口输出禁中文) "
          "改 ASCII，但已落盘记录跨固件持久，删字形使历史故障行渲染空白",
    "常": "同 \"异常\" 系记录（时钟芯片异常/文件系统异常 等，9eb1bd63 写入，落盘持久）",
    "芯": "9eb1bd63 写入的 \"时钟芯片异常\" 落盘 /log/selftest.log（SD2506 时钟芯片故障"
          "路径当时可触发，记录持久）",
    "片": "同 \"时钟芯片异常\"（9eb1bd63 写入，落盘持久）",
}


def load_tool(name):
    """按文件路径加载 tools/font_gen/<name>.py（无包结构，importlib 直载）。

    两个生成器模块级只有常量与函数定义（main 均有 __name__ 守卫），导入零副作用。
    """
    path = os.path.join(TOOLS_DIR, name + ".py")
    if not os.path.isfile(path):
        print("[ENV-ERROR] 生成器缺失: %s" % path)
        sys.exit(2)
    spec = importlib.util.spec_from_file_location(name, path)
    mod = importlib.util.module_from_spec(spec)
    spec.loader.exec_module(mod)
    return mod


def fmt_char(c):
    """字符 -> `你(U+4F60)` 形态；GBK 控制台打不出的符号由 stdout replace 兜底。"""
    return "%s(U+%04X)" % (c, ord(c))


def rel(path):
    """仓库相对路径；跨盘符（--font/--chars 指向临时目录）时退回原路径。"""
    try:
        return os.path.relpath(path, REPO_ROOT)
    except ValueError:
        return path


def fmt_chars(chars):
    return " ".join(fmt_char(c) for c in sorted(chars))


def extract_source_chars(extract_cn):
    """复用 extract_cn 的 SCAN 清单 + collect() 状态机提取源码实际用到的字符集。"""
    chars = set()
    n = 0
    for f in extract_cn.SCAN:
        if not os.path.exists(f):
            print("  skip (not found): %s" % os.path.relpath(f, REPO_ROOT))
            continue
        chars |= extract_cn.collect(open(f, encoding="utf-8-sig", errors="ignore").read())
        n += 1
    return chars, n


def check_font_coverage(make_font, font_path):
    """复用 make_font.verify_coverage 判定"字符集文件 ⊆ 字体 cmap"。

    返回 None = 通过；返回 (缺字列表 | None, 原始报错) —— 缺字列表由报错里的
    U+XXXX 码位反解而来（verify_coverage 只打印码位，这里补出字形便于定位）。
    """
    try:
        make_font.verify_coverage(font_path)
        return None
    except SystemExit as e:
        msg = str(e)
        codes = re.findall(r"U\+([0-9A-Fa-f]{4,6})", msg)
        missing = [chr(int(x, 16)) for x in codes] if codes else None
        return missing, msg
    except OSError as e:
        print("[ENV-ERROR] 读取字体失败: %s" % e)
        sys.exit(2)


def main():
    # Windows GBK 控制台打不出 ▶ 等符号：降级替换，避免 UnicodeEncodeError 崩溃
    # （与 make_font.py 同款处理；pre-commit 经管道捕获时同理）
    try:
        sys.stdout.reconfigure(errors="replace")
    except Exception:
        pass

    ap = argparse.ArgumentParser(description="UI 字符集差集门禁（源码 ↔ ui_cn_chars.txt ↔ ui_font_cn_12.c）")
    ap.add_argument("--chars", default=None,
                    help="覆盖字符集文件路径（默认 ui_cn_chars.txt；注入测试用）")
    ap.add_argument("--font", default=None,
                    help="覆盖字体 .c 路径（默认 Drivers/BSP/UI/ui_font_cn_12.c；注入测试用）")
    ap.add_argument("--strict", action="store_true",
                    help="未知冗余字（txt 有、源码无、且不在 KEEP_EXTRA）也按 FAIL 处理（供审计/瘦身排期）")
    args = ap.parse_args()

    extract_cn = load_tool("extract_cn")
    make_font = load_tool("make_font")

    chars_path = args.chars or make_font.CHARS_FILE
    font_path = args.font or make_font.OUT
    for path, label in ((chars_path, "字符集文件"), (font_path, "字体文件")):
        if not os.path.isfile(path):
            print("[ENV-ERROR] %s缺失: %s" % (label, path))
            return 2

    # --- A 段：必需字符（源码在用 ∪ KEEP_EXTRA）vs 字符集文件 ---
    src, nfiles = extract_source_chars(extract_cn)
    txt = set(open(chars_path, encoding="utf-8").read().strip())
    keep = set(KEEP_EXTRA)
    missing_src = sorted(src - txt)              # 白框方向 -> FAIL
    missing_keep = sorted(keep - txt - src)      # 保留字被静默剔除 -> FAIL（防历史落盘记录变白框）
    extra_in_txt = sorted(txt - src - keep)      # 未知冗余 -> WARN（--strict 升级）
    kept_present = sorted((keep & txt) - src)    # 保留字在位且源码不用 -> [KEEP] 信息行

    # --- B 段：字符集文件 vs 字体 cmap（复用 verify_coverage，其事实源 = CHARS_FILE）---
    make_font.CHARS_FILE = chars_path    # 允许 --chars 注入；默认即仓库根 ui_cn_chars.txt
    gaps = []
    warns = []
    keeps = []
    keep_reasons = []
    if missing_src:
        gaps.append("[GAP] 字符集缺字 %d 个（UI 源码在用、不在 %s -> 字体必然无此字形，上机白框）: %s"
                    % (len(missing_src), rel(chars_path), fmt_chars(missing_src)))
    if missing_keep:
        gaps.append("[GAP] 刻意保留字被剔除 %d 个（在 KEEP_EXTRA、不在 %s -> 历史落盘记录"
                    "（如 /log/selftest.log）将渲染空白，不可逆；把这些字并回字符集后重跑 make_font）: %s"
                    % (len(missing_keep), rel(chars_path), fmt_chars(missing_keep)))
        keep_reasons = ["  KEEP_EXTRA 理由 %s: %s" % (fmt_char(c), KEEP_EXTRA[c])
                        for c in missing_keep]
    if kept_present:
        keeps.append("[KEEP] 刻意保留 %d 个（源码已不用但按 KEEP_EXTRA 保留，不计冗余；"
                     "理由见脚本头部与字典）: %s" % (len(kept_present), fmt_chars(kept_present)))
    if extra_in_txt:
        line = ("[WARN] 字符集未知冗余 %d 个（在 txt、源码已不用且不在保留清单 -> 只费 Flash "
                "不致白框；重跑 font-regen 可瘦身）: %s" % (len(extra_in_txt), fmt_chars(extra_in_txt)))
        if args.strict:
            gaps.append(line.replace("[WARN]", "[GAP] (--strict)", 1))
        else:
            warns.append(line)

    result = check_font_coverage(make_font, font_path)
    if result is not None:
        missing, msg = result
        if missing:
            gaps.append("[GAP] 字体缺字 %d 个（在字符集、不在 %s 的 cmap -> lv_font_conv 静默丢字，上机白框）: %s"
                        % (len(missing), rel(font_path), fmt_chars(missing)))
        else:
            gaps.append("[GAP] 字体覆盖校验失败: %s" % msg)

    # --- 输出 ---
    print("== UI 字符集差集检查 ==")
    print("扫描 UI 源码: %d 个文件 | 源码在用: %d 字 | 保留清单: %d 字 | 字符集: %d 字"
          % (nfiles, len(src), len(keep), len(txt)))
    for k in keeps:
        print(k)
    for w in warns:
        print(w)
    for g in gaps:
        print(g)
    for kr in keep_reasons:
        print(kr)
    if gaps:
        print("修复：按 font-regen skill 四步重跑（extract_cn.py -> 并回 KEEP_EXTRA -> make_font.py -> diff 检查），"
              "ui_cn_chars.txt 与 ui_font_cn_12.c 随代码一起提交")
        print("结果: FAIL（%d 项缺口，%d 个 WARN）" % (len(gaps), len(warns)))
        return 1
    print("结果: PASS（必需字符（源码在用 ∪ 保留清单）全部在字体子集内%s%s）"
          % ("；%d 个保留字在位" % len(kept_present) if kept_present else "",
             "；%d 个未知冗余仅 WARN" % len(extra_in_txt) if warns else ""))
    return 0


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