packages/runner 按 runner.mdx 的「From Source」步骤起不来:vite 别名表漏了 5 个源码实际 import 的工作区包

[yinlianghui]

越界发现,记录于 #3537(给 runner 补 api 查询参数文档)期间的实测启动。未在该 PR 中顺手修改 —— 该单的文件面锁在 content/docs/utilities/runner.mdx + packages/runner/README.md,而这里要动的是 packages/runner/vite.config.ts(或 package.json)。

现象

packages/runner/vite.config.ts 把 7 个 @object-ui/* specifier 别名到 packages/*/src(components / react / core / types / data-objectql / plugin-kanban / plugin-charts)。但这些 src 文件自己又 import 了 5 个既不在别名表、也不在 packages/runner/package.json 里的工作区包:

未覆盖的包	import 它的文件
@object-ui/i18n	packages/components/src/renderers/basic/elements.tsx
@object-ui/fields	packages/plugin-kanban/src/ObjectKanban.tsx
@object-ui/plugin-detail	packages/plugin-kanban/src/ObjectKanban.tsx
@object-ui/sdui-parser	packages/components/src/renderers/layout/page.tsx
@object-ui/react-runtime	packages/components/src/renderers/layout/react-page.tsx

这 5 个包只能退回 node 解析,落到 packages/*/dist —— 而 dist 只在构建之后存在(实测干净 worktree 里这 5 个包的 dist 目录全部不存在,package.json 的 main 均指向 ./dist/...)。

实测

origin/main 的干净 worktree,只 pnpm install(不 build),packages/runner 起 vite(自选空闲端口 5387):

VITE v8.2.0  ready in 1477 ms
(!) Failed to run dependency scan. Skipping dependency pre-bundling. Error: The following dependencies are imported but could not be resolved:
  @object-ui/i18n (imported by .../packages/components/src/renderers/basic/elements.tsx)
  @object-ui/fields (imported by .../packages/plugin-kanban/src/ObjectKanban.tsx)
  @object-ui/plugin-detail (imported by .../packages/plugin-kanban/src/ObjectKanban.tsx)
  @object-ui/sdui-parser (imported by .../packages/components/src/renderers/layout/page.tsx)
  @object-ui/react-runtime (imported by .../packages/components/src/renderers/layout/react-page.tsx)

$ curl -s -o /dev/null -w "%{http_code}" "http://localhost:5387/@fs/.../packages/components/src/renderers/basic/elements.tsx"
500   → Failed to resolve import "@object-ui/i18n" from "../components/src/renderers/basic/elements.tsx". Does the file exist?

src/main.tsx 急切 import @object-ui/components,该链必被浏览器走到。(本次未跑无头浏览器 —— 容器内没有安装 playwright 浏览器,~/.cache/ms-playwright 不存在 —— 所以只有 500 这一层实测,没有白屏截图。)

与 #3528 的关系:同一形态,但严重度不同,不是重复单

#3528 是 examples/console-starter 的同款别名缺口(漏 5 个,另一组包),被判为 finding 并明写理由:该 example 的 README 已写明启动顺序是 pnpm install → pnpm -w build → pnpm dev,按文档走不会踩到。

runner 这边相反 —— content/docs/utilities/runner.mdx 的 "From Source" 就是

pnpm install
cd packages/runner
pnpm dev

没有构建步骤;## Using PNPM Workspace 一节的 pnpm --filter @object-ui/runner dev 同样没有。也就是说照着这一页做的读者一定会踩到。因此这里不是打磨类,而是「按文档操作即失败」,故未加 finding 标签,交 PM 分诊定级。

可选方向(不预设结论,与 #3528 同构)

1. 把这 5 个包补进 packages/runner/vite.config.ts 的别名表 —— 与现有 7 条同构,pnpm dev 从此不依赖 dist。
2. 把它们补进 packages/runner/package.json 的 dependencies —— 真去掉别名时才不缺依赖。
3. 只改文档:在 runner.mdx 的 "From Source" 里补 pnpm -w build(与 console-starter 的 vite 别名表漏了 5 个源码实际 import 的工作区包,未先构建就 pnpm dev 得到白屏 #3528 引用的 PR docs(examples): 给 console-starter 补 README #3524 同档)。

1/2/3 不互斥。哪个是长期正确取决于 runner 承诺的是「monorepo 内即跑」还是「发布后独立跑」(它 private: false、已在 npm 发布),这是维护者的判断,故本单不预设。

---

Generated by Claude Code

[yinlianghui]

认领(PM 分诊晋级)— 会话 session_01GTRjn8xBqp75dk7kFupVRt,分支 claude/issue-3575-runner-alias-closure。

分诊裁定(三向按既有机制定,不上交):方向 1 —— 补全 packages/runner/vite.config.ts 别名表。理由:7 条别名表就是本仓已选定的"runner 在 monorepo 内不依赖 dist 即跑"机制,表不完整是该机制自身不变量的破缺(restore-invariant 类);方向 2 改的是发布依赖面(npm 语义),那才是维护者裁量,本单不动;方向 3 等于让文档为机制的洞背锅,与别名表存在的目的相反,否决。runner "发布后独立跑"的承诺问题不因本单改变 —— 别名只影响 monorepo 内 dev。

执行要求:issue 列的 5 个是第一层缺口 —— 必须量出从 runner src 出发、穿过所有被别名包 src 的完整工作区 import 传递闭包,一次补齐(#3528 类陷阱就是补一层漏一层);表旁留一行注释写明重导闭包的方法。验收 = 干净 worktree 仅 install 起 vite:依赖扫描零 unresolved、@fs 探针 500→200。

文件面:packages/runner/vite.config.ts。⚠️ 与在飞 #3578(改同包 src/App.tsx)不同文件,零相交。越界即停。

---

Generated by Claude Code

[yinlianghui]

验收:ACCEPT — PR #3599(恰 2 文件:vite.config.ts + changeset)。

裁定要点:(1) 闭包纪律正是派单要的:5→14 包(两层传递 + 一个 esbuild 擦除的 type-only 隐形项 —— 依赖扫描永远看不见它,按不变量入表防未来值引用重开洞);注释剥离承重(三个幻影包差点被错误别名,逐个给出假阳性实例);自馈式重导命令双向验证。(2) 构建面测量推翻我的暂定"无 changeset"并当场自救:别名无 command 作用域→发布物真变(1765 preload 链接),同文件 modulePreload:false 对齐 console 同款守卫,急切载荷 -86%,patch changeset 有据 —— 这是"测量决定发货"的模范。(3) 前缀吞噬风险(react vs react-runtime)钉扎;#3593(data-objectql 幽灵别名,表的反向破缺)已核存在入池;tsbuildinfo 陈旧产物陷阱记录在案。(4) 浏览器渲染层未测如实声明(容器无 playwright),2381 模块 HTTP 爬取是可得的最强证据。17/17 完成检查全绿。PR 转 ready + auto-merge。

---

Generated by Claude Code