Repository navigation
docs(webui): correct twelve symbol citations, and check them on every change - #136
Merged
Merged
Conversation
added 3 commits
September 30, 2026 21:59
The architecture pair cited fifty symbols to files and twelve of them were wrong — a 24% error rate on a document that presents itself as the authoritative account of how the build is wired. getCachedMcodeCommands was filed under state-bus.js when it lives in acp-client.js; three symbols named functions the ACP refactor deleted; two files no longer exist at all. Checking by hand does not scale, so the citation check runs now: every bare path must exist, every file#symbol and "(in file)" must resolve to a definition once import lines are stripped, and the two language copies must mirror each other. It is wired into the verifier because an unwired check is decoration — this script previously ran only by hand and no change would have exercised it. It is not a complete fence: a symbol named in prose with no file attached is invisible to it, and it proves existence, not accuracy. Two whitelists need a human to keep honest.
The deleted ones are now recorded as removed, with the path that replaced them, rather than given an invented rename. render.js went with the vanilla-JS SPA; cancelSession is what cancellation uses now. Two citations were subtler than a stale file name. The sidebar's renderSessions is a same-named symbol in the trajectory studio — the main UI is session-tree.tsx#SessionTree. And section 9 tells new endpoints to join the router.js table, but most of them now live in the Hono OWNED_ROUTES in server/app.js, so following the text would put new work in the wrong file.
Adding a gate to verify.mjs is not self-registering. The source-sync fixture stubs the direct-path scripts it executes, and two profiles assert their gate list by deepEqual, so both went red the moment check:docs-alignment joined: the fixture hit MODULE_NOT_FOUND and the lists disagreed on one more entry. ci-release.yml filters on scripts/verify.mjs, so touching the verifier is what pulled that workflow in — the failure was always going to surface there first.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
问题
packages/webui/docs/ARCHITECTURE.md与.zh-CN.md自称是「构建方式唯一权威」，但它引用的 50 条「符号 → 文件」里12 条是错的——24%。几条值得单独说的
同名符号张冠李戴：侧栏的
renderSessions其实是轨迹工作室的同名符号——主 UI 是session-tree.tsx#SessionTree。这不是「文件过时」，是读者会照着找错地方。文档在教人往错文件里加代码：§9 让新端点加进
router.js路由表，但多数端点已归server/app.js（Hono）的OWNED_ROUTES——照原文做会加错地方。已删除的符号如实标「已移除」并写明替代（
runMcode()/stopExec()/isRunning()三个全被 ACP 重构删除，取消改走mcode-rpc.js#cancelSession）。没有编造改名。render.js整文件随 vanilla-JS SPA 迁移而删除。自动校验：手查不 scalable，所以进流水线
check-docs-alignment.mjs新增第 7 项，三层：file#symbol与(in file)能解析到定义（判定时剥离 import 行，否则会误判）接进
scripts/verify.mjs（docs:true, windows:true）——证伪测试（编排侧独立复跑过）
篡改
ARCHITECTURE.md:460的mcode-rpc.js#cancelSession→#cancelSessionXX：门禁防不住什么（如实说明）
stopExec()那句）路径门禁看不见门禁
pnpm webapp:typecheck/typecheckpnpm test:webapppnpm check:sourcecheck-docs-alignment.mjs顺带发现（未改，建议另开单）
§4 载荷字段层还有失真：
context.source不存在；NormalizedEvent结尾「See § 5」而 §5 正文恰恰否认那些帧。且server/app.js（Hono 层）此前从未在这份「构建权威」文档中出现——整个 HTTP 层缺失。🤖 Generated with DeepSeek Harness