Files
STM32F4-Base/scripts/check_bom_drift.py
T
wandering1 e4981aa2f6 refactor(docs): point entry-file references at their new homes
AGENTS.md stopped being the store of record for build steps, Python env,
hardware pins, doc conventions, log cost and task ownership. Those facts
already live in docs, skills and role files; the entry file now only
points at them. This commit moves every reference that used to name the
entry file to the authoritative landing point, so a reader who follows a
link arrives at the fact instead of at a sentence that no longer exists.

What changed is links and prose, not behaviour. Code, scripts and tests
only have comment and docstring lines touched; the only non-comment edit
in the whole changeset is one note string inside the generated pin table
JSON, and its generator was changed in the same step so the two stay
byte-identical.

New landing points created before the references were retargeted:
- The console single-writer log design doc, section 7.1, is now the single
  authority for log cost: about 90 B flash and 216 B stack per DBG_ line,
  and the rule that deep call chains must predefine DBG_LINE_BUF_MAX.
  It also carries the full list of the twelve translation units that have
  tightened it, plus the grep command that decides the truth if the list
  and the code ever disagree.
- The document writing standard, section 2, now holds the BOM list.
- keil-build skill gains an exit code table: 0 success, 1 build failure,
  2 BuildEnvError, 3 usage, 4 build lock held. This corrects a belief
  that was never actually written down anywhere: exit 2 does not simply
  mean environment error, argparse also exits 2 and the wrapper script
  was remapped so the two no longer collide.

Regenerated and checked byte for byte:
- The end-to-end architecture SVG in docs/images from its generator.
- tools/netlist_semantics/pinout_kb.json from gen_kb.py.
Both are idempotent; running the generators again produces no diff.

Deliberately not touched, because machines read them:
- scripts/check_bom_drift.py joins every line containing BOM and asserts
  four paths are present, so the entry file BOM line must stay one line.
- scripts/gen_task_table.py reads the TASK_TABLE anchors directly.
- scripts/rename_maps and scripts/archive keep their historical wording;
  they describe what happened, not what is true now.

Verified: doc links report the same six pre-existing findings as the base
commit and no new ones, generated-fresh passes, bom drift is clean across
101 files, and AGENTS.md itself is unchanged in this commit.
2026-11-16 19:38:27 +08:00

293 lines
12 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# -*- 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 仓库里自证四条判定(含票面要求的两条边界)。
退出码: 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_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:
continue # 新增文件:HEAD 无 BOM 可谈,不误报(票面边界①)
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():
data = git_run(["ls-files", "-z"])
if data is None:
return []
return [x for x in data.decode("utf-8", "replace").split(chr(0)) if x]
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 被剥掉了(HEAD 有 EF BB BF,工作区没有):")
for p in bad:
print(" " + p)
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 里根本没有的新文件(哪怕在名单目录内)不得误报
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 or n != 0:
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")
bad, n = check_paths(["App/cfg/cfg_file.c"])
if bad or n != 0:
print("[SELFTEST FAIL] 名单内但不在 HEAD 的文件被误报")
ok = False
bad, n = check_paths(["README.md"])
if n != 0:
print("[SELFTEST FAIL] 名单外文件参与了检查")
ok = False
finally:
os.chdir(old)
print("[SELFTEST] " + ("4 条判定全过(含两条票面要求的边界)" 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 跟踪的全部文件")
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())