fix(gates): close the BOM gate hole that let new files skip the check

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.
This commit is contained in:
2026-11-16 23:59:49 +08:00
parent 515db819ab
commit 12e0617909
14 changed files with 283 additions and 60 deletions
+124 -23
View File
@@ -19,7 +19,9 @@
改菜单/加页面只需编辑 ui_menu_tree.txt + 写页面实例文件,然后重跑本脚本。
用法(仓库根目录或任意目录均可,脚本自动定位仓库根):
python tools/menu_gen/gen_menu.py
python tools/menu_gen/gen_menu.py 写入模式:重写生成物 + 双端注册(默认,行为不变)
python tools/menu_gen/gen_menu.py --check 只读模式:只报告工作区是否已是最新,绝不写文件
一致 exit 0([OK]);不一致 exit 1([STALE] + 差异摘要)
"""
import os
import re
@@ -559,12 +561,15 @@ def _write_text(path, text):
fp.write(text)
def prune_registration():
"""删掉两份注册表里指向**已不存在的 ui_page_*.c** 的死条目,返回被删项。
def plan_prune():
"""算出"删掉两份注册表里指向**已不存在的 ui_page_*.c** 的死条目"后的文本。
与 sync_registration 对称:删页/改名后残留的条目会让 Keil 直接报
与 plan_sync 对称:删页/改名后残留的条目会让 Keil 直接报
"cannot open source input file"(模拟器同理报源文件缺失),属必须清掉的死引用;
只匹配 ui_page_*.c 这一类(生成器自己负责的范围),不碰其它组/其它模块的条目。
**本函数只算不写**(返回 (新文本, 被删项列表)),由调用方决定写盘还是只比对——
--check 模式必须能拿到同样的结果却不碰磁盘,这是把"算"与"写"拆开的唯一理由。
"""
pruned = []
@@ -581,8 +586,6 @@ def prune_registration():
return ''
new_uv = blk_re.sub(_drop, uv)
if new_uv != uv:
_write_text(UVPROJX, new_uv)
cm = _read_text(CMAKELISTS)
line_re = re.compile(r'^[ \t]*\$\{UI_DIR\}/(ui_page_[a-z0-9_]*\.c)[ \t]*\r?\n', re.M)
@@ -595,22 +598,23 @@ def prune_registration():
return ''
new_cm = line_re.sub(_drop_cm, cm)
if new_cm != cm:
_write_text(CMAKELISTS, new_cm)
return pruned
return (new_uv, new_cm), pruned
def sync_registration(filenames):
"""把 UI 目录下的 .c 文件名补进 uvprojx 与 CMakeLists 的显式列表,返回实际插入项。
def plan_sync(filenames, uv, cm):
"""算出"把 filenames 补进 uvprojx 与 CMakeLists 显式列表"后的文本。
只做定点插入、不重排不改写其余内容:uvprojx 由 UV4 维护,任何无关改动都会污染
diff("UV4 抖动不入库"铁律);已存在则不动(幂等,重复跑不产生 diff)。
**本函数只算不写**:uv / cm 由调用方传入(可来自磁盘,也可来自 plan_prune 的产物),
返回 (新 uv, 新 cm, 插入项列表)。--check 与写盘模式走同一条计算路径,
这样"检查说的"与"写入做的"不可能漂移。
"""
inserted = []
# ① uvprojx:Drivers/BSP/UI 组的 <Files> 末尾补 <File> 块
uv = _read_text(UVPROJX)
gi = uv.find('<GroupName>%s</GroupName>' % UI_GROUP)
if gi < 0:
sys.exit('ERROR: uvprojx 找不到组 %r,无法自动注册(请检查工程结构)' % UI_GROUP)
@@ -630,10 +634,8 @@ def sync_registration(filenames):
inserted.append(('uvprojx', fn))
if add:
uv = uv[:line_start] + add + uv[line_start:]
_write_text(UVPROJX, uv)
# ② CMakeLists:set(UI_SOURCES ...) 列表末尾补 ${UI_DIR}/xxx.c
cm = _read_text(CMAKELISTS)
si = cm.find('set(UI_SOURCES')
if si < 0:
sys.exit('ERROR: CMakeLists.txt 找不到 set(UI_SOURCES ...),无法自动注册')
@@ -649,12 +651,70 @@ def sync_registration(filenames):
inserted.append(('CMakeLists', fn))
if add:
cm = cm[:line_start] + add + cm[line_start:]
return uv, cm, inserted
def apply_registration(needed):
"""写盘模式:先清死引用再补缺目(改名场景两头都覆盖),返回 (pruned, inserted)。"""
(new_uv, new_cm), pruned = plan_prune()
if new_uv != _read_text(UVPROJX):
_write_text(UVPROJX, new_uv)
if new_cm != _read_text(CMAKELISTS):
_write_text(CMAKELISTS, new_cm)
# 补缺目要基于"刚清完死引用"的文本继续算,再落盘
uv, cm, inserted = plan_sync(needed, new_uv, new_cm)
if uv != new_uv:
_write_text(UVPROJX, uv)
if cm != new_cm:
_write_text(CMAKELISTS, cm)
return inserted
return pruned, inserted
def main():
def check_registration(needed):
"""只读模式:算出双端注册应有的最终文本,与磁盘逐字符比对。
返回 (差异列表, 待删项, 待补项);差异列表为 [(标签, 相对路径, 摘要)]。
**不写任何文件、不建临时文件**——只在内存里跑与写盘模式相同的两个 plan 函数,
因此"检查说的"与"写入做的"不可能漂移。
比较基准是**最终态**(清死引用 + 补缺目之后)对磁盘原文本,不是拿中间态比中间态:
否则同一处差异会被算两次,且 diff 摘要会误导。
"""
diffs = []
(pruned_uv, pruned_cm), pruned = plan_prune()
cur_uv = _read_text(UVPROJX)
cur_cm = _read_text(CMAKELISTS)
final_uv, final_cm, inserted = plan_sync(needed, pruned_uv, pruned_cm)
for label, path, cur, final in (
('uvprojx', UVPROJX, cur_uv, final_uv),
('CMakeLists', CMAKELISTS, cur_cm, final_cm)):
if cur == final:
continue
n_prune = len([1 for t, _ in pruned if t == label])
n_add = len([1 for t, _ in inserted if t == label])
parts = []
if n_prune:
parts.append('需删 %d 条死引用' % n_prune)
if n_add:
parts.append('需补 %d 条注册' % n_add)
if not parts:
parts.append('内容有差异(行数 %d 到 %d)' % (cur.count('\n'), final.count('\n')))
diffs.append((label, os.path.relpath(path, ROOT), ','.join(parts)))
return diffs, pruned, inserted
def main(argv=None):
argv = list(sys.argv[1:] if argv is None else argv)
if argv and argv not in (['--check'], ['-h'], ['--help']):
sys.exit('ERROR: 未知参数 %s\n用法: gen_menu.py [--check]' % ' '.join(argv))
readonly = argv == ['--check']
if not os.path.exists(SRC):
sys.exit('ERROR: 未找到 ui_menu_tree.txt(应在仓库根目录)')
text = open(SRC, encoding='utf-8-sig').read()
@@ -670,17 +730,47 @@ def main():
header, body, menus, max_depth = emit(nodes)
reg_h, reg_c = emit_registry(bound, password_stem)
# 双端注册:注册表本身 + 每个绑定页实例(密码页也必须是已绑定或 @password 声明的)
needed = ['ui_page_registry.c'] + sorted({'ui_page_%s.c' % p for _, _, p in bound})
generated = ((OUT_H, header), (OUT_C, body),
(OUT_REG_H, reg_h), (OUT_REG_C, reg_c))
if readonly:
# --check:全程只读。四个生成物按"写盘会产出的同一段字节"对比磁盘,
# 双端注册走 plan_prune + plan_sync 的纯计算,一次 open(...,'w') 都不发生。
stale = []
for path, content in generated:
try:
with open(path, 'r', encoding='utf-8-sig', newline='') as fp:
disk = fp.read()
except OSError:
stale.append((os.path.relpath(path, ROOT), '文件不存在'))
continue
if disk != content:
stale.append((os.path.relpath(path, ROOT), _diff_summary(disk, content)))
reg_diffs, _pruned, _inserted = check_registration(needed)
if stale or reg_diffs:
for rel, summary in stale:
print('[STALE] would rewrite %s (%s)' % (rel, summary))
for _label, rel, summary in reg_diffs:
print('[STALE] would rewrite %s (%s)' % (rel, summary))
print('[STALE] %d 个生成物与 ui_menu_tree.txt 不一致;'
'本次未写任何文件,执行不带参数的 gen_menu.py 即可刷新'
% (len(stale) + len(reg_diffs)))
return 1
print('[OK] up-to-date: %d 个生成物与双端注册均与 ui_menu_tree.txt 一致'
% len(generated))
return 0
# Drivers/BSP/UI/* 约定为 UTF-8 带 BOM(同 ui_menu.c);字符串字面量含中文,
# 无 BOM 时 cl.exe(代码页 936) 会按 GBK 误读 UTF-8 字节导致字符串解析错乱。
for path, content in ((OUT_H, header), (OUT_C, body),
(OUT_REG_H, reg_h), (OUT_REG_C, reg_c)):
for path, content in generated:
with open(path, 'w', encoding='utf-8-sig', newline='') as fp:
fp.write(content)
# 双端注册:注册表本身 + 每个绑定页实例(密码页也必须是已绑定或 @password 声明的)
needed = ['ui_page_registry.c'] + sorted({'ui_page_%s.c' % p for _, _, p in bound})
pruned = prune_registration() # 先清死引用,再补缺目(改名场景两头都覆盖)
inserted = sync_registration(needed)
pruned, inserted = apply_registration(needed)
protected = sum(1 for _, _, _, p, _ in nodes if p)
print('nodes=%d menu=%d leaf=%d protected=%d max_depth=%d'
@@ -696,7 +786,18 @@ def main():
print(' registered %-12s %s' % (target, fn))
if not pruned and not inserted:
print(' registration up-to-date (uvprojx + CMakeLists unchanged)')
return 0
def _diff_summary(disk, content):
"""给 --check 的 STALE 行找第一处差异,帮人直接跳到出错的地方。"""
disk_lines = disk.split('\n')
new_lines = content.split('\n')
for i in range(min(len(disk_lines), len(new_lines))):
if disk_lines[i] != new_lines[i]:
return '首个差异在第 %d 行' % (i + 1)
return '行数 %d 到 %d' % (len(disk_lines), len(new_lines))
if __name__ == '__main__':
main()
sys.exit(main())