dsh-tiddlywiki 0.30.47 → 0.30.49

package/docs/CHANGELOG.md

@@ -4,6 +4,8 @@
 
 > 最近几个主要版本的一句话记录（完整变更见 [Releases](https://github.com/bbqisbbq/dsh-tiddlywiki/releases) / git log）。
 
+- **v0.30.49**（2026-09-30）：**修 v0.30.48 引入的真缺陷 + 补上「barrel 公共面」的守门**。① v0.30.48 用 `noUnusedLocals` 清理 import 时删掉了 `writeLocationState` 的 **import 行**，而同一文件里 `export { … } from './host/wiki-location.ts'` 是**独立语句**、不消费那个绑定 —— 于是 `lib/index.js` 不再导出它，`scripts/verify-wiki-switch.mjs` 在 **e2e** 阶段才崩（`does not provide an export named 'writeLocationState'`），而 `typecheck` / `verify:unit` / `verify:static` **全绿**。这正是 v0.30.42（误删 `MARKDOWN_PLUGIN`）那一类「**barrel 丢失对编译器和多数守门不可见**」的第二次事故。② 新增 `scripts/verify-index-barrel.mjs`（进 `verify:static`）：**凡是本仓库脚本从 `../lib/index.js` 具名导入的符号，`src/index.ts` 必须真的导出它**（解析的是 `export { … }` 与 `export <decl>`，**不是**「出现过这个名字」—— 后者挡不住「barrel 行被降级成 import」这种形态）。带两条反空转保险（导出数 ≥100、需求数 ≥50），并**反向验证**过两种注入（删掉导出 / 降级成 import，都稳定变红）。③ 写这条守门时自己踩了同一个坑的**第三种方向**：解析 `export { … }` 列表时按 `,` 切分，而列表里恰好有一段解释性注释 —— 注释里的逗号把名字切碎、注释里的右花括号提前终止列表，**症状是「源码明明导出了，守门却报缺」**。修法同 v0.30.45/48：**先剥注释再解析**（顺序照旧先剥行注释）。⇒ 「对源码文本做结构断言先剥注释」这条纪律，本仓库已经交了**四次**学费（v0.28.12 假红、v0.30.45 假绿、v0.30.48 假红、v0.30.49 解析器自己出错）。
+- **v0.30.48**（2026-09-30）：`src/index.ts` **955 → 724** —— 新模块 `index-routes.ts`(381)：**路由 / admin 装配阶段整片**（`RouteDeps` + `AdminDeps` 两个对象与两张路由表的注册，收进 `createRouteStage(deps)`）。**这是 `index.ts` 拆分第二轮**：v0.30.42 先切走了「纯」的配置面，这一轮切走的是**装配阶段里唯一自成一段**的部分 —— 读入口现在能一眼看到生命周期（farm → prompt/tools → 启动任务 → 路由 → 拆卸），而不再被 120 行 accessor 接线打断。三条刻意不动的东西：① **`disposed` 仍归入口**（它的主人是拆卸 effect 与启动任务），唯一需要它的那处守卫改为**传入谓词** `isDisposed()`；② **变更锁仍由入口建、并把同一个实例传进 stage**（v0.30.12：整插件一把锁）—— 顺手删掉一个**从未被读的依赖** `GitLayerDeps.isDisposed`，README 式的「按行删 import」交给 `noUnusedLocals`（一次点名 23 处，零猜）；③ **注册时机一字未改**（`ctx.inject(['webServer'])` 仍在 wikiViews 之后、拆卸 effect 之前 —— 顺序没有重排）。⚠️ 守门同步一处：`verify-mutation-lock` 的「只建一把锁」计数改成**按模块族**统计，并给该判据**剥注释** —— 新模块的说明文字里写了一句 `createMutationLock()`，未剥注释时会被当成**第二个调用点**（v0.30.45 那种「断言被自己的文档满足」的镜像：这次是假红）。
 - **v0.30.47**（2026-09-30）：`src/client/note-widget.ts` **588 → 573** —— 新模块 `note-widget-foot.ts`(73)：**底栏那一组**（左组：上传按钮 / 「🕘 最近」/ `Ctrl+Enter` 提示；右组：「✏️ 在 TW 中编辑」/「保存」）。这一片是**零卡片状态**的纯布局（与 v0.30.43 的 placement 片同类）：依赖面只有「一个已经建好的上传按钮」+「`recent.toggle` 的函数引用」，把 `{ foot, footLeft, footRight, saveBtn, editBtn }` 交回卡片 —— 两个按钮的 `click` 处理器**仍绑在卡片里**（紧挨着实现它们的 `note-widget-save.ts`），因为「谁实现动作」与「谁画按钮」是两件事。`footLeft`/`footRight` 两个 class 一并交回，因为 `.dsh-tw-note-foot-right` 的 flex 规则（右贴边 + 装不下时整组换行，v0.22.6 的按钮压成两行事故）是**契约**，卡片还要往里 append。
 - **v0.30.46**（2026-09-30）：`src/client/note-widget.ts` **615 → 588** —— 新模块 `note-widget-upload-ui.ts`(82)：上传的**接线**那一组（「上传」按钮 + 隐藏的 file input + 拖放到编辑器上，连同它自有的 `dragDepth`）。分层刻意分成两个文件：`note-widget-upload.ts` 是**动作**（`uploadInto`：校验大小 → POST → 在光标处插入 Markdown 行 → toast），`note-widget-upload-ui.ts` 是**接线**（File 从哪来、何时给编辑器挂 `.dsh-tw-note-drop` 高亮）。分界线：整组只问卡片要两样东西 —— 编辑器（拖放目标 + 插入点）与 `wikiQuery`（附件必须落在**这张卡片的目标库**里），卡片侧不再持有任何上传状态（`footLeft.append(upload.button, …)` 一行替代原 36 行）。
 - **v0.30.45**（2026-09-29）：**`note-widget.ts` 拆分第四轮 —— 抽出「保存 / 在 TW 中编辑」整组（677 → 615 行），并在同一轮**抓出一条被注释满足的假绿守门**。① 新模块 `src/client/note-widget-save.ts`（187 行）拿走 `saveDone` · `saving`（在途互斥）· `doSave` · `doEdit` —— 这四样是 `build()` 里唯一真的"说话"的一段（发请求、读回执、弹 toast、改按钮状态与文案）。**分界线（可复用）**：先把这段代码**读写到的闭包状态**列出来，再逐样决定怎么传 —— 它自带的 `saving` **跟着函数走**（同 v0.30.44）；卡片**留在原地**的四样各有理由：`close()` 是卡片自己的可见性收尾、`postEditAndOpen()` **两条路径共用**（`doEdit` 与 `openNative`）所以必须住在两者都看得见的地方、`loadedToken` 的**主人是「🕘 最近」picker**（它写、这里只读）⇒ 按 getter/setter 传、`scope` 这里只读**一个**方法（`stoppedTarget()`）⇒ 传函数而不是整个模块。② `const doSave = async (): Promise<void> => {` 这一行**逐字保留**：`verify-wiki-focus.mjs` 用 `indexOf(那句签名)` 定位函数体、再断言其后 900 字符内出现 `stoppedTarget()`（＝「卡片保存同样要拒绝未运行的目标库」，v0.29.0）；它是**族读**（`readFamily('src/client/note-widget')`）⇒ 搬到新文件仍命中。③ ⚠️ **本版最重要的一条：那条判据在搬迁后变成了假绿，是反向验证抓出来的。** 第一次跑两种注入（**删掉整个 `stoppedTarget()` 拒绝分支** / **把 `doSave` 改名**）——`verify-wiki-focus` **两次都照样绿**。根因：它是拿**未剥注释**的族文本做 `indexOf`，而新模块的**模块头注释**逐字引用了那句签名、还在同一段里提到 `stoppedTarget()` ⇒ `indexOf` 先命中**注释**，900 字符窗口里出现的 `stoppedTarget()` 也来自注释，**断言被自己的文档满足**（这条注释本身是为了解释"为什么这一行不许改名"，属于"越写越安全"的反面）。修法：`verify-wiki-focus.mjs` 新增 `stripComments()`（**先剥行注释、再剥块注释** —— 顺序承重，v0.30.14 在 `verify-client-i18n` 里踩过反序吞代码的坑），那条测试的五条断言全部改跑在剥注释的源码上。**加固后重跑同样的两种注入 ⇒ 两次都稳定 FAIL**（删分支 ⇒「卡片保存同样要拒绝未运行的目标库」；改名 ⇒「找不到 doSave」），还原后文件哈希与注入前**逐字节一致** ⇒ 绿。⇒ 结论：`grep`/`indexOf` 型判据在**拆分**这件事上尤其脆 —— 模块头注释几乎必然会引用被搬走的那句签名，所以凡"定位函数体 + 窗口内找符号"的断言，**必须剥注释**。④ **其余守门一条都不用改**（逐个核实，不是猜）：`verify-frame-guards` 按模块族读并在测试里剥注释行，`dispose()` / `open()` / `openNative()` / `installCardDrag()` / `positionCard()` 都留在卡片里；`verify-wiki-focus:770` 那条**按精确路径**读卡片、钉 `const mark = …note.defaultMark…` 的断言同样不受影响（被断言的那行没离开卡片）。⑤ 一个**诚实的差异**写进模块头（不改变可观察行为）：旧代码直接闭包引用 `editor`/`titleInput`/`tagEditor`/`saveBtn`/`editBtn`，新代码经 `deps.getUi()`，于是两个函数各多一条 `ui === undefined` 早退（实践中不可达 —— 两者都由 `build()` 建出来的按钮与编辑器键位触发，写出来只为类型收窄）。**验证**：`typecheck` / `build`（client bundle 770,645 字节，仍 minify）/ 客户端五守门（`verify-frame-guards` / `verify-wiki-focus` / `verify-tw-origin` / `verify-client-i18n` / `verify-frame-surface`）/ `verify-editor-popup` / `verify:unit`（退出码 0）/ 全量 `npm run verify` 四档退出码 0（E2E / WIKI SWITCH / WIKI FARM BOOT / LARGE WIKI CHECKS 全绿）/ `verify-line-endings`（260 个文本文件全 LF）/ `verify-version-consistency` 全绿。