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:
@@ -549,8 +549,34 @@ def main():
|
||||
verify_coverage(OUT) # 生成后校验:字符集全部码位必须进字体(防静默丢字)
|
||||
fix_trailing_newline(OUT) # 规范化末尾换行(pre-commit end-of-file-fixer)
|
||||
normalize_project_conventions(OUT, args.size, args.bpp) # 对齐工程约定(文件头/包含路径/版本守卫压平)
|
||||
if ensure_bom(OUT): # 必须最后一步:前面的中间步骤会整文件重写,BOM 补早了会被冲掉
|
||||
print('已补 UTF-8 BOM(Drivers/BSP/UI/ 整目录带 BOM 的工程约定,幂等)')
|
||||
print('OK %d bytes -> %s' % (os.path.getsize(OUT), OUT))
|
||||
|
||||
|
||||
def ensure_bom(path):
|
||||
"""保证生成物带头 BOM(EF BB BF),且幂等。
|
||||
|
||||
为什么要这一步:`Drivers/BSP/UI/` 整目录是工程约定的带 BOM 名单(AGENTS 铁律第 2 条),
|
||||
目录里其它生成物(如菜单生成器产物)都是带头的,字体是这个目录里唯一会掉队的生成物——
|
||||
因为本脚本每次都在 :544 调 lv_font_conv **整文件重写**输出,产物天然无 BOM;后面几步虽然
|
||||
各自读 has_bom 再原样回写,但那是"读到的已经是没有 BOM 的那份",于是 `has_bom` 恒为 False,
|
||||
"保留原样"压根无从发生(手动补的 BOM 下一轮就被覆盖掉)。
|
||||
|
||||
为什么不改成"让每步都保留":真正决定这里要不要 BOM 的是**工程约定**,不是上游产物,所以
|
||||
收敛在末尾一步显式补,比在 6 个中间步骤里各自维持一个 has_bom 便宜得多,也不依赖调用顺序
|
||||
(本次踩的坑正是"装配顺序把事实冲掉了")。
|
||||
|
||||
幂等:已有 BOM 直接返回,不重复加。只碰最前面 3 字节,字体字节/字形数/glyph_id 全不受影响。
|
||||
"""
|
||||
with open(path, 'rb') as fp:
|
||||
raw = fp.read()
|
||||
if raw.startswith(b'\xef\xbb\xbf'):
|
||||
return False
|
||||
with open(path, 'wb') as fp:
|
||||
fp.write(b'\xef\xbb\xbf' + raw)
|
||||
return True
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
||||
|
||||
@@ -10,10 +10,49 @@
|
||||
|
||||
## 使用方式
|
||||
|
||||
两种模式,**写不写盘是唯一区别**;两者的生成/注册逻辑共用同一段代码(`plan_prune` +
|
||||
`plan_sync` 只算不写,写盘模式再落盘),所以"检查说的"与"写入做的"不可能漂移。
|
||||
|
||||
### 写入模式(默认,不带参数)
|
||||
|
||||
```bash
|
||||
& '.venv\Scripts\python.exe' tools/menu_gen/gen_menu.py
|
||||
```
|
||||
|
||||
重写 4 个生成物(`ui_menu_tab.c/.h`、`ui_page_registry.c/.h`)+ 同步双端注册
|
||||
(`MDK-ARM/STM32F407-Demo.uvprojx`、`simulator/CMakeLists.txt`)。
|
||||
输出里的箭头行(`-> Drivers/BSP/UI/ui_menu_tab.h` 等)**表示文件确实被重写了**——
|
||||
注意重写不代表内容变了:内容相同时字节不变、`git status` 也就没有 diff。
|
||||
|
||||
**什么时候用**:改了 `ui_menu_tree.txt` 或增删页面实例后,这是唯一会刷新生成物的途径。
|
||||
|
||||
### 只读模式(`--check`)
|
||||
|
||||
```bash
|
||||
& '.venv\Scripts\python.exe' tools/menu_gen/gen_menu.py --check
|
||||
```
|
||||
|
||||
只报告"工作区生成物是否已与 `ui_menu_tree.txt` 同步",**一次写操作都不发生**,
|
||||
也不建临时文件;双端注册同样只比对不写入。退出码即结论:
|
||||
|
||||
| 情形 | 输出 | 退出码 |
|
||||
|---|---|---|
|
||||
| 已同步 | `[OK] up-to-date: 4 个生成物与双端注册均与 ui_menu_tree.txt 一致` | 0 |
|
||||
| 有漂移 | 每个待刷新文件一行 `[STALE] would rewrite <路径> (原因)`,末行给总数 | 1 |
|
||||
|
||||
`[STALE]` 行**刻意不使用箭头符号**——那个符号在只读场景里会被误读成"已经写过了"。
|
||||
差异摘要会给出首个不同的行号,或"需删 N 条死引用 / 需补 N 条注册",便于直接定位。
|
||||
|
||||
**什么时候用**:改完菜单树、提交前想确认"我这笔改动是否已经重跑过生成器",
|
||||
或 review 别人的菜单改动时。它不替代强制门禁——见下节。
|
||||
|
||||
## 与 `check_generated_fresh.py` 的分工
|
||||
|
||||
`scripts/check_generated_fresh.py`(pre-commit 钩子「生成器幂等性」)把生成器拷到临时目录
|
||||
重跑再逐字节比对,是**强制的红绿门禁**,保证"生成物比生成器旧"必 FAIL。
|
||||
`--check` 是**给人看差异的**:门禁只说红或绿,`--check` 说差在哪个文件、第几行、缺哪条注册。
|
||||
日常改菜单用 `--check` 自查,提交时由门禁兜底,两者都要在。
|
||||
|
||||
菜单树输入的权威副本:仓库根 `ui_menu_tree.txt`。
|
||||
|
||||
## ⚠️ 注意
|
||||
|
||||
+124
-23
@@ -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())
|
||||
|
||||
Reference in New Issue
Block a user