12e0617909
The BOM gate claimed to stop BOMs from being stripped, but it only ever inspected files that were already tracked AND already had a BOM. A new file under a BOM-listed directory could be born without one and never be noticed, because the scan never returned it and, even if it had, the "no HEAD version" branch skipped it. Editing a listed file and losing its BOM is a real accident that already happened once; creating one without a BOM was the same accident with no safety net at all. Measured before and after on the same untracked file with no BOM: before: checked 101 files, no drift, exit 0 after: FAIL, names the file, exit 1 The count of 101 was itself the symptom: with one more file present the honest number is 102. The old code was not "silently passing a clean tree", it was not looking. The scan now includes untracked files, and a listed file with no HEAD version must carry a BOM. Files that are tracked without a BOM keep their historical pass so this does not flood existing code with failures; instead the two that were listed but had no BOM were given one so the list means what it says. That exposed a conflict nobody had hit yet. The font file is generated, and the generator rewrites it from scratch on every run, so a hand-added BOM survived until the next regeneration and then vanished. The BOM gate and the generated-fresh gate could not both pass. The generator now puts the BOM back as its last step, idempotently, so the two gates agree and the whole UI directory keeps its uniform encoding. Font content is untouched: everything after the first three bytes is byte-identical. The menu generator gains a real read-only mode. It previously had no options at all and always rewrote its outputs; the arrows it printed were accurate. That made it easy to mistake for a checker, since an unchanged tree produces identical bytes and looks untouched. --check now reports up to date or stale without writing anything, and the registration tables are checked the same way. Default behaviour and output are unchanged. The telemetry page header no longer restates the board's input hardware facts. They live in the IOBOARD README, which is where the board's electrical behaviour belongs; the page keeps only what it alone can say: that the output rows show the shadow register rather than contact feedback, why an invalid sample draws -- instead of 分, and that these twelve rows are not in the point table. One fact, one place. The team rule for experiments now requires the file hash, the located line number, and both runs. A report once cited a line number that did not exist in the final file, which left no way to confirm which version had actually been tested.
342 lines
15 KiB
Python
342 lines
15 KiB
Python
# -*- coding: utf-8 -*-
|
||
"""
|
||
模块名称:BOM 漂移检查(提交门禁 bom-guard 的实现)
|
||
模块功能:对给定文件集合(默认 = pre-commit 传进来的本次所改文件)逐个比较 HEAD 版本与工作区
|
||
版本的前 3 字节:HEAD 有 UTF-8 BOM(EF BB BF)而工作区没有 → FAIL 并列出补救动作。
|
||
为什么要这条:编码铁律记载的实测坑(口径 → docs/文档规范.md §2)——编辑工具会**静默剥掉**文件原有 BOM,ARMCC
|
||
于是按 CP936 解码带中文的源文件,报出 #870-D / #8 / #274 一类**假语法错**(错的位置
|
||
和内容都不指向真因);MSVC(模拟器侧)与任何"只跑编译"的门禁都不覆盖这一步,历史
|
||
"0 警告"不代表安全。2026-10-25 一天之内道E 一个任务踩了 4 次、道B 批 1 踩过 1 次,
|
||
此前全靠人工逐文件比 HEAD 兜底——人工审计只有"记得做的人"才会做,本脚本把它变成
|
||
提交时的硬闸。
|
||
刻意不做(写清楚比补上更容易维持):
|
||
① 不报"HEAD 无 BOM、工作区加了 BOM":那是另一个方向的改动,可能是有意的(把文件
|
||
纳入 BOM 名单),报红只会逼人 --no-verify,而绕过门禁的习惯比漏检更贵;
|
||
② 不自动补 BOM:正确修复是"在最前面加 3 个字节",用脚本整文件重写反而可能把中文
|
||
按错误编码重打一遍(本仓记录的更大的坑),所以只报文件与动作;
|
||
③ 不报已删除的文件:删除不是 BOM 漂移,且删除自有 review 兜。
|
||
名单互指(三处必须一致,本脚本每次运行都核一次,不一致即 FAIL):
|
||
AGENTS.md 铁律第 2 条列出的带 BOM 文件名单、.pre-commit-config.yaml 里 bom-guard
|
||
钩子的 files 正则、下面的 BOM_LIST。任何一处单独改动都会在别人的提交里被拦下——
|
||
这正是目的:名单散在三处而无人同步,等于没有名单。
|
||
用法: .venv/Scripts/python.exe scripts/check_bom_drift.py [文件名...] [--all] [--selftest]
|
||
不带文件名也不带 --all 时(pre-commit 的常规形态)只核传进来的文件;--all 核全仓
|
||
跟踪**及未跟踪**文件(人工审计/排查用,比 HEAD 全量比一遍慢,但不依赖"改没改过");--selftest
|
||
在临时 git 仓库里自证六条判定(含新增文件必须带 BOM、名单外不越权、存量两方向)。
|
||
退出码: 0 = 通过;1 = 有 BOM 漂移或名单不一致;2 = 用法或环境错误(不在 git 仓库内等)
|
||
创建日期:2026-10-25(道E task-20)
|
||
"""
|
||
|
||
import argparse
|
||
import os
|
||
import subprocess
|
||
import sys
|
||
import tempfile
|
||
|
||
BOM = bytes((0xEF, 0xBB, 0xBF))
|
||
|
||
# 名单项:(路径, 匹配方式),prefix = 目录内全部文件,eq = 恰好这一个文件
|
||
# 名单的语义是"这些文件**必须**带 BOM",不是"这些文件曾经带过 BOM":新增文件按此判
|
||
# (见 check_paths 的 hp is None 分支),存量文件若在 HEAD 里就没有 BOM 仍按历史状态放行,
|
||
# 但那属于名单登记不实,应逐个补齐后让名实相符——2026-11-16 补的是 App/cfg/cfg_file.c
|
||
# (ARMCC 编译的手写源文件、含数百行中文注释,正是 BOM 铁律要保护的对象,HEAD 无 BOM 纯属
|
||
# 历史疏漏)。补完后本名单内不再存在"登记了却没 BOM"的存量文件,故此处不设豁免名单。
|
||
BOM_LIST = [
|
||
("Drivers/BSP/UI/", "prefix"),
|
||
("App/task/ui_task.c", "eq"),
|
||
("App/cfg/cfg_file.c", "eq"),
|
||
("Lib/lv_conf.h", "eq"),
|
||
]
|
||
|
||
AGENTS_FILE = "AGENTS.md"
|
||
CONFIG_FILE = ".pre-commit-config.yaml"
|
||
|
||
# Windows 控制台默认按 CP936 写 stdout:本脚本要打印中文,先把输出锁到 UTF-8。
|
||
# 不锁的后果不是难看,是**崩在半路**——门禁脚本崩在半路等于一条都没检查(同一课已在
|
||
# tools/setview_check 脚本上记过一次,这里不再重犯)。
|
||
try:
|
||
sys.stdout.reconfigure(encoding="utf-8", errors="replace")
|
||
sys.stderr.reconfigure(encoding="utf-8", errors="replace")
|
||
except Exception:
|
||
pass
|
||
|
||
|
||
def in_list(path):
|
||
"""path 是否在带 BOM 名单内(git 与控制台都用正斜杠,不做转换)。"""
|
||
for name, kind in BOM_LIST:
|
||
if kind == "prefix":
|
||
if path.startswith(name):
|
||
return True
|
||
elif path == name:
|
||
return True
|
||
return False
|
||
|
||
|
||
def git_run(args):
|
||
try:
|
||
r = subprocess.run(["git"] + args, stdout=subprocess.PIPE,
|
||
stderr=subprocess.DEVNULL)
|
||
except OSError:
|
||
return None
|
||
if r.returncode != 0:
|
||
return None
|
||
return r.stdout
|
||
|
||
|
||
def head_prefix(path):
|
||
"""HEAD 版本前 3 字节;不在 HEAD(新增文件)返回 None → 不误报。"""
|
||
data = git_run(["show", "HEAD:" + path])
|
||
if data is None:
|
||
return None
|
||
return data[:3]
|
||
|
||
|
||
def work_prefix(path):
|
||
"""工作区版本前 3 字节;读不到(已删除等)返回 None → 不报。"""
|
||
try:
|
||
with open(path, "rb") as f:
|
||
return f.read(3)
|
||
except OSError:
|
||
return None
|
||
|
||
|
||
def check_paths(paths):
|
||
"""返回 (违规列表, 核过条数);违规项 = 路径。"""
|
||
bad = []
|
||
n = 0
|
||
for p in paths:
|
||
if not in_list(p):
|
||
continue
|
||
hp = head_prefix(p)
|
||
if hp is None:
|
||
# 新增文件(HEAD 里没有):名单内的就该有 BOM。这一支原先直接 continue,
|
||
# 于是"新建文件忘 BOM"永远拦不住——Scripts 自查实测:在 Drivers/BSP/UI/
|
||
# 造一个无 BOM 的未跟踪文件,--all 照样报"无漂移"。那正是本门禁最贵的一类
|
||
# 漏检:新建时没人改到它,等下一次有人编辑才炸,且炸在 ARMCC 的假语法错上。
|
||
n += 1
|
||
wp = work_prefix(p)
|
||
if wp is None:
|
||
continue # 已在工作区删除:不是本门禁的事
|
||
if wp != BOM:
|
||
bad.append(p)
|
||
continue
|
||
n += 1
|
||
if hp != BOM:
|
||
continue # HEAD 本来就没 BOM:不报(票面边界②)
|
||
wp = work_prefix(p)
|
||
if wp is None:
|
||
continue # 已删除:不是本门禁的事
|
||
if wp != BOM:
|
||
bad.append(p)
|
||
return bad, n
|
||
|
||
|
||
def tracked_files():
|
||
"""扫描全集 = 已跟踪 + 未跟踪(不含 gitignore)。
|
||
|
||
只用 ls-files 会漏掉"新建还没 add"的文件,而那恰恰是 BOM 门禁最该看住的时刻:
|
||
新建时忘 BOM 没人会被绊到,等下一次有人编辑该文件才炸,且炸在 ARMCC 的假语法错上
|
||
(错的位置和内容都不指向真因)。--others --exclude-standard 把未跟踪但非 gitignore
|
||
的文件一并纳入,使 --all 与"提交后会被跟踪的集合"一致。
|
||
"""
|
||
data = git_run(["ls-files", "-z", "--cached", "--others", "--exclude-standard"])
|
||
if data is None:
|
||
return []
|
||
seen = []
|
||
for x in data.decode("utf-8", "replace").split(chr(0)):
|
||
if x and x not in seen:
|
||
seen.append(x)
|
||
return seen
|
||
|
||
|
||
def list_crosscheck():
|
||
"""核 AGENTS 名单 / 钩子 files 正则 / BOM_LIST 三处是否互指一致。"""
|
||
problems = []
|
||
names = [n for n, _ in BOM_LIST]
|
||
try:
|
||
agents = open(AGENTS_FILE, encoding="utf-8").read()
|
||
except OSError:
|
||
agents = None
|
||
problems.append("读不到 " + AGENTS_FILE + "(不在仓库根执行?)")
|
||
try:
|
||
cfg = open(CONFIG_FILE, encoding="utf-8").read()
|
||
except OSError:
|
||
cfg = None
|
||
problems.append("读不到 " + CONFIG_FILE)
|
||
if agents is not None:
|
||
seg = ""
|
||
for line in agents.split(chr(10)):
|
||
if "BOM" in line:
|
||
seg += line
|
||
for n in names:
|
||
key = n.rstrip("/")
|
||
if key not in seg:
|
||
problems.append("AGENTS.md 的 BOM 条目里没有列到 " + n)
|
||
if cfg is not None:
|
||
seg = ""
|
||
hit = False
|
||
for line in cfg.split(chr(10)):
|
||
if "id: bom-guard" in line:
|
||
hit = True
|
||
elif hit and "files:" in line:
|
||
seg = line
|
||
break
|
||
if not seg:
|
||
problems.append("在 " + CONFIG_FILE + " 里找不到 bom-guard 钩子的 files 行")
|
||
else:
|
||
# 正则里的反斜杠与锚点是**写法**,不是名单内容:比之前先脱掉,否则
|
||
# App/task/ui_task\.c$ 会被判成"没覆盖 App/task/ui_task.c"。这条检查要核的是
|
||
# 三处的意图是否一致,不是字节是否相同
|
||
flat = seg.replace(chr(92), "").replace("^", "").replace("$", "")
|
||
for n in names:
|
||
key = n.rstrip("/")
|
||
if key not in flat:
|
||
problems.append("bom-guard 的 files 正则没覆盖 " + n)
|
||
return problems
|
||
|
||
|
||
def report(bad):
|
||
print("[FAIL] 以下名单内文件的 BOM 缺失或被剥掉(工程约定要求 EF BB BF 开头):")
|
||
for p in bad:
|
||
print(" " + p)
|
||
print(" 两种情况都算:① 已入库带 BOM 的文件被编辑工具剥掉了;② 名单内**新建**文件")
|
||
print(" 压根没带 BOM(HEAD 里没有它,但进了名单目录就必须带)。")
|
||
print(" 补救:只把 3 个字节 EF BB BF 补回文件最前面;**不要**整文件重写——")
|
||
print(" 用 PowerShell/Set-Content 之类整文件重写会按系统默认编码重打中文,")
|
||
print(" 那会把可修的丢 BOM 变成不可修的 U+FFFD(AGENTS 铁律第 1/2 条)。")
|
||
print(" 为什么必须修:ARMCC 无 BOM 时按 CP936 解码带中文的源文件,报的是 #870-D/#8/#274")
|
||
print(" 这类**假语法错**,模拟器(MSVC)0 警告照不出来,只有重编该文件才暴露。")
|
||
|
||
|
||
def selftest():
|
||
"""在临时 git 仓库里跑六条判定(含新增文件、名单外、存量两方向边界),任一不符返回 1。"""
|
||
ok = True
|
||
tmp = tempfile.mkdtemp(prefix="bomdrift_")
|
||
old = os.getcwd()
|
||
try:
|
||
os.chdir(tmp)
|
||
for a in (["init", "-q"], ["config", "user.email", "t@t"],
|
||
["config", "user.name", "t"]):
|
||
if git_run(a) is None:
|
||
print("[SELFTEST FATAL] 临时仓库 git 初始化失败")
|
||
return 1
|
||
os.makedirs("Drivers/BSP/UI")
|
||
os.makedirs("App/task")
|
||
os.makedirs("App/cfg")
|
||
os.makedirs("Lib")
|
||
bomf = "Drivers/BSP/UI/t.c"
|
||
with open(bomf, "wb") as f:
|
||
f.write(BOM + b"/* x */" + chr(0x4e2d).encode("utf-8"))
|
||
with open("App/task/ui_task.c", "wb") as f:
|
||
f.write(b"/* plain, no BOM in HEAD */")
|
||
git_run(["add", "-A"])
|
||
if git_run(["commit", "-q", "-m", "seed"]) is None:
|
||
print("[SELFTEST FATAL] 临时仓库提交失败")
|
||
return 1
|
||
|
||
bad, n = check_paths([bomf])
|
||
if n != 1 or bad:
|
||
print("[SELFTEST FAIL] 未改动的带 BOM 文件被判成违规(应 0 违规、核过 1 个)")
|
||
ok = False
|
||
|
||
with open(bomf, "rb") as f:
|
||
body = f.read()
|
||
with open(bomf, "wb") as f:
|
||
f.write(body[3:])
|
||
bad, n = check_paths([bomf])
|
||
if bad != [bomf]:
|
||
print("[SELFTEST FAIL] 剥掉 BOM 后没报(主用例失守 = 门禁等于没有)")
|
||
ok = False
|
||
with open(bomf, "wb") as f:
|
||
f.write(body)
|
||
|
||
# 边界①:HEAD 里根本没有的新文件**在名单内**就必须带 BOM(票面边界①,2026-11-16 收紧)
|
||
# 旧行为是直接放行,正是"新建文件忘 BOM 永远拦不住"的那层漏报。
|
||
with open("Drivers/BSP/UI/new.c", "wb") as f:
|
||
f.write(b"/* brand new, no BOM */")
|
||
bad, n = check_paths(["Drivers/BSP/UI/new.c"])
|
||
if bad != ["Drivers/BSP/UI/new.c"] or n != 1:
|
||
print("[SELFTEST FAIL] 名单内新增无 BOM 文件没被拦住(本次修复的主用例失守)")
|
||
ok = False
|
||
with open("Drivers/BSP/UI/new.c", "wb") as f:
|
||
f.write(BOM + b"/* brand new, with BOM */")
|
||
bad, n = check_paths(["Drivers/BSP/UI/new.c"])
|
||
if bad or n != 1:
|
||
print("[SELFTEST FAIL] 名单内新增文件**带** BOM 被误报")
|
||
ok = False
|
||
os.remove("Drivers/BSP/UI/new.c")
|
||
|
||
# 边界②:HEAD 无 BOM、工作区加了 BOM 不得报(另一个方向的改动,可能有意)
|
||
with open("App/task/ui_task.c", "wb") as f:
|
||
f.write(BOM + b"/* now with BOM */")
|
||
bad, n = check_paths(["App/task/ui_task.c"])
|
||
if bad:
|
||
print("[SELFTEST FAIL] HEAD 无 BOM 而工作区加了 BOM 被误报")
|
||
ok = False
|
||
# 名单外文件即使 BOM 丢了也不报(门禁不越权管名单外)
|
||
with open("Lib/lv_conf.h", "wb") as f:
|
||
f.write(b"x")
|
||
with open("App/cfg/cfg_file.c", "wb") as f:
|
||
f.write(b"/* listed but never committed, no BOM */")
|
||
bad, n = check_paths(["App/cfg/cfg_file.c"])
|
||
if bad != ["App/cfg/cfg_file.c"] or n != 1:
|
||
print("[SELFTEST FAIL] 名单内新增无 BOM 文件(eq 项)没被拦住")
|
||
ok = False
|
||
bad, n = check_paths(["README.md"])
|
||
if n != 0:
|
||
print("[SELFTEST FAIL] 名单外文件参与了检查")
|
||
ok = False
|
||
with open("Lib/lv_conf.h", "wb") as f:
|
||
f.write(BOM + b"/* lv_conf, already has BOM in HEAD */")
|
||
git_run(["add", "Lib/lv_conf.h"])
|
||
git_run(["commit", "-q", "-m", "lv_conf"])
|
||
with open("Lib/lv_conf.h", "wb") as f:
|
||
f.write(b"/* BOM stripped by an editor */")
|
||
bad, n = check_paths(["Lib/lv_conf.h"])
|
||
if bad != ["Lib/lv_conf.h"] or n != 1:
|
||
print("[SELFTEST FAIL] 已入库带 BOM 的文件被剥掉后没报(原有主用例失守)")
|
||
ok = False
|
||
finally:
|
||
os.chdir(old)
|
||
print("[SELFTEST] " + ("6 条判定全过(含新增文件必须带 BOM、名单外不越权等边界)"
|
||
if ok else "有判定未过"))
|
||
return 0 if ok else 1
|
||
|
||
|
||
def main():
|
||
ap = argparse.ArgumentParser(description="BOM 漂移检查(bom-guard 钩子实现)")
|
||
ap.add_argument("files", nargs="*", help="待核文件(仓库根相对路径)")
|
||
ap.add_argument("--all", action="store_true",
|
||
help="核 git 跟踪的与未跟踪(不含 gitignore)的全部文件")
|
||
ap.add_argument("--selftest", action="store_true", help="临时仓库自证判定")
|
||
args = ap.parse_args()
|
||
|
||
if args.selftest:
|
||
return selftest()
|
||
|
||
if git_run(["rev-parse", "--git-dir"]) is None:
|
||
print("[FATAL] 不在 git 仓库里(或 git 不可用),本检查无法比对 HEAD")
|
||
return 2
|
||
|
||
paths = tracked_files() if args.all else args.files
|
||
if not paths and not args.all:
|
||
return 0
|
||
|
||
bad, n = check_paths(paths)
|
||
problems = list_crosscheck()
|
||
if bad:
|
||
report(bad)
|
||
if problems:
|
||
print("[FAIL] BOM 名单三处互指不一致(名单散着改 = 名单失效):")
|
||
for m in problems:
|
||
print(" " + m)
|
||
print(" 要一起改的三处:AGENTS.md 铁律第 2 条、.pre-commit-config.yaml 的 bom-guard")
|
||
print(" files 正则、scripts/check_bom_drift.py 的 BOM_LIST。")
|
||
if not bad and not problems:
|
||
print("BOM 漂移检查:核过 %d 个名单内文件,无漂移;名单三处互指一致" % n)
|
||
return 1 if (bad or problems) else 0
|
||
|
||
|
||
if __name__ == "__main__":
|
||
sys.exit(main())
|