[finding] examples/app-showcase/e2e/global-setup.ts is read by no tsc program — 6 errors, 3 of them holes in test/node-shim.d.ts

[hotlong]

Filed unassigned by the #7923 dev (PR #8061) as an out-of-scope observation. Nothing is red; this is a "should be covered" note.

What is dark

#7923 graduated @objectstack/example-showcase out of TEST_DEBT by widening its include to reach the e2e/ Playwright specs. The glob it added is spec-scoped — e2e + /**/*.spec.ts — deliberately, and NOT the wholesale e2e + /**/*, because the deleted TEST_DEBT note warned that the wholesale form would pull in e2e/global-setup.ts and bill the test layer 6 errors from a file that is not a test. That warning was re-measured on origin/main @ 3373a29 during #7923 and is exactly right.

So the three specs are now type-checked and the fixture beside them still is not. global-setup.ts is read by no tsc program at all — it is not a *.spec.ts, so the coverage gate (which counts test files) has no opinion on it either. It is genuinely invisible rather than ledgered.

Measured, at 3373a29

Adding e2e + /**/* to the package include and running tsc --noEmit:

e2e/global-setup.ts(2,10): error TS2305: Module '"node:fs"' has no exported member 'mkdirSync'.
e2e/global-setup.ts(2,21): error TS2724: '"node:fs"' has no exported member named 'writeFileSync'. Did you mean 'readFileSync'?
e2e/global-setup.ts(3,25): error TS2591: Cannot find name 'node:path'. Do you need to install type definitions for node?
e2e/global-setup.ts(11,21): error TS2339: Property 'env' does not exist on type '{ cwd(): string; }'.
e2e/global-setup.ts(12,23): error TS2339: Property 'env' does not exist on type '{ cwd(): string; }'.
e2e/global-setup.ts(13,26): error TS2339: Property 'env' does not exist on type '{ cwd(): string; }'.

Two different causes, and the split is the interesting part:

• 3 x TS2339 are the ordinary process.env shape. The package deliberately omits @types/node and each module that needs env reads declares a file-local declare const process — the idiom already in objectstack.config.ts, src/system/self-url.ts and test/connector-self-url.test.ts. [finding] The 3 test layers #7353 made visible are repair candidates, not permanent debt — metadata-fs (6) and example-showcase (4) look like same-day graduations #7923 applied the same one-liner to the three specs. This file just never got it, because nothing ever checked it.
• 3 x TS2305 / TS2724 / TS2591 are holes in test/node-shim.d.ts itself: the node:fs shim declares existsSync/readFileSync/readdirSync but not mkdirSync or writeFileSync, and there is no node:path module declaration at all. This half is not a global-setup.ts defect — it is the shim being narrower than what the package actually imports, and any future file reaching for those members hits the same wall.

That second half is why #7923 did not fold this in: extending a shim that serves the vitest layer, for the benefit of a non-test file, is a different change from the graduation it was scoped to.

Why it is worth closing anyway

global-setup.ts is what authenticates the e2e run (it reads SMOKE_API_URL / SMOKE_EMAIL / SMOKE_PASSWORD and writes a storage-state file). A type error in it fails the whole smoke suite at setup rather than in a spec, and test:smoke is non-blocking nightly — so a break here is quiet in exactly the way that costs an afternoon later.

Likely shape of the repair: add the file-local declare const process (3 gone), add mkdirSync/writeFileSync to the node:fs shim and a minimal node:path module declaration (3 gone), then widen the include glob to e2e + /**/*. Worth deciding as part of that: whether test/node-shim.d.ts is still the right home for a declaration the e2e/ tree also depends on.

Related: #7923 (PR #8061) · #7353 · #7312 · #5286

[hotlong]

Finding-grading round: promoted to pm:queue (domain:devx, type Task).

All 6 errors independently re-derived from the shim text on origin/main (node-shim.d.ts lacks node:path entirely, process.env, and 2 node:fs members; tsconfig glob is e2e/**/*.spec.ts so global-setup.ts is read by no tsc program). Fully-enumerated repair with a named landing point; #7923 / PR #8061 left this deliberately. The "is test/node-shim.d.ts still the right home" sub-question is the dev's implementation choice, not a decision.

---

Generated by Claude Code

[hotlong]

Claim: PM loop round 7
Session: session_01PaiisQMhsYxwa5ZX6Mfmv2
Branch: claude/issue-8062-showcase-global-setup-typecheck
Worktree: objectstack-issue-8062
Domain: domain:devx
File surface: examples/app-showcase/**（e2e/global-setup.ts、test/node-shim.d.ts、该包的 tsconfig include）。⛔ 无 packages/**,⛔ 无 scripts/,⛔ 不动 TEST_DEBT 以外任何账本
Container & model: XS, mode:cloud, model: opus

前提复验

#7923 已关闭、PR #8061 已合 —— 也就是说本卡的全部读数取自 3373a29,而那是 #8061 落地前后的树。卡里 6 条错误是当时手工把 include 放宽到 e2e/**/* 跑出来的,不是当前 main 的实测值。

⇒ 派发令第一条裁决就是重新取数:在当前 origin/main 的干净 worktree 里,先按卡里的方法放宽 include 跑一次 tsc --noEmit,把真实错误列表贴进 PR 正文,再动手修。卡里的 3+3 拆分很可能仍然成立,但**「很可能」不是读数** —— 本席今天已经在三处栽在「用别人卡里的旧读数当现值」上。

Serial constraints cleared:无在飞 PR 触及 examples/app-showcase/。与同轮派发的 #8110(.github/workflows/lint.yml)文件面互斥。

---

Generated by Claude Code

[hotlong]

{
 "issue": 8062,
 "status": "done",
 "branch": "claude/issue-8062-showcase-global-setup-typecheck",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/8178",
 "premise_still_valid": true,
 "summary": "Re-measured first, per 裁决 1: widened the package include to the wholesale `e2e` + `/**/*` on origin/main @ 7cfe7ad and ran tsc --noEmit. The card reproduces EXACTLY — same 6 errors, same codes, same lines, same 3+3 split; baseline green, so none pre-existing. Both halves delivered: the include is widened (global-setup.ts is now genuinely in the program, proved with --listFiles, not merely error-free) and the 6 errors are fixed at source — file-local `declare const process` per the package's verified idiom, plus mkdirSync/writeFileSync on the node:fs shim and a minimal node:path module. Answered the card's open question rather than forwarding it: the shim moves test/node-shim.d.ts -> types/node-shim.d.ts, because measurement shows BOTH trees consume it (test/ for existsSync/readFileSync/readdirSync + the process.cwd() global, e2e/ for mkdirSync/writeFileSync/dirname + that global) — two real callers, not an abstraction for one; the vitest layer stays green (193 tests, before and after). Also included playwright.config.ts, dark in exactly the same way and taking the identical one-liner (measured: adds only its own 3 errors, pulls in no new types) — a deliberate scope call, flagged in the PR body so the PM can strike it. Deliberately did NOT include vitest.config.ts: measured, its `vitest/config` import transitively pulls the whole of @types/node into the program, the exact type-surface widening this package is built to avoid — a separate decision, not a rider.",
 "tests": "pnpm --filter @objectstack/example-showcase typecheck -> exit 0. --listFiles confirms e2e/global-setup.ts, playwright.config.ts and types/node-shim.d.ts are all IN the program, with @types/node still absent (grep -c '@types/node/' = 0). pnpm --filter @objectstack/example-showcase test -> 'Test Files 20 passed (20) / Tests 193 passed (193)', identical before and after the shim move. eslint over every touched path -> exit 0. pnpm check:nul-bytes -> OK (7422 files scanned). pnpm check:type-check-coverage -> OK (64/77 packages, self-test green). REVERSE VERIFICATION, direction predicted before running (expected: red, exactly the 6): restored the pre-fix global-setup.ts + shim while keeping the widened glob -> exactly those 6 errors, red; restored from the commit -> tsc exit 0 and `git status` clean. RUNTIME EQUIVALENCE (hypothesis D), proved not asserted: compiled pre- and post-change sources and diffed the emitted JS — global-setup.ts 0ed6c5be... == 0ed6c5be..., playwright.config.ts 11c4148d... == 11c4148d..., both BYTE-IDENTICAL. This took a second lap: the first placement put the `declare` between the leading block comment and the first statement, which detached the comment and dropped it from the emit; declaring it ABOVE the comment restores byte-identity, and both sites carry a note saying why. ⚠️ The smoke suite itself was NOT run — it needs a real backend on :3000 and this container has parallel agents on it; the claim is a byte-identity proof of the emitted module, not an execution of the suite. NOT RUN: pnpm check:type-check-debt — `--re-measure` refuses without the full package closure built (it names @objectstack/service-knowledge as unbuilt here) and the script is explicit that measuring anyway records a different world; CI builds that closure first. It cannot move in any case: this package left TEST_DEBT in #7923, and the one DEBT entry tracking showcase files (@objectstack/spec-monorepo, 4 of its 80) counts files under examples/app-showcase/src, untouched here. GATE DERIVATION: ran `node scripts/pm/dispatch-gates.mjs` on the actual changed paths — it returned 'No check family names the given paths in its own source', 25 repo-wide/undetermined families, judgment left to the PM. So NO gate family came from the re-derivation that the dispatch prompt missed; check:nul-bytes and the two type-check-coverage families are the convention-scoped ones I judged implicated and ran. CHANGESET ROUTE: derived, not assumed — @objectstack/example-showcase is `private: true` and absent from .changeset/config.json's `fixed` list, so it is unreleased and this PR ships nothing; took the `skip-changeset` route. Label written as the union and READ BACK: ['size/m', 'skip-changeset'].",
 "open_questions": [],
 "out_of_scope_findings": []
}

Two things worth the PM's eye, neither changed here

1. Hypothesis C is partly falsified. The card reads the shim gaps as "the package has no @types/node". It is installed at the workspace root and physically resolvable from this package — it is simply not in the program, because nothing names it in compilerOptions.types. Probing with types: ["node"]: the three node-builtin errors disappear, but the three process.env errors stay, because the shim's global declare const process: { cwd(): string } shadows the real one. So "just add @types/node" is not the smaller repair — it fixes half, forces the shim's process global out, and widens a type surface two comments in this package record as a deliberate choice. Kept the narrow shim; the reasoning is now written into types/node-shim.d.ts so nobody re-derives it.

2. A stale illustration inside the scripts/ fence. scripts/check-type-check-coverage.mjs (~line 1410) uses this exact file as its worked example of why hidden tests are added one at a time — "e2e/**/* would have pulled e2e/global-setup.ts into app-showcase's measurement and billed the test layer 6 errors". The mechanism rationale stays correct; the illustration is now historical, since the file sits in the real program with zero errors. scripts/ was fenced off this card (裁决 4), so it is untouched and flagged rather than filed — it is a comment inside the fence the PM drew, so the PM is the right owner. No issue filed; say the word and I will.

Not filed as issues, because neither is a defect: vitest.config.ts's darkness is recorded in the PR body with its measured cost, and item 2 is a comment that is still substantively true.

---

Generated by Claude Code

[hotlong]

ACCEPT — PR #8178，已翻 ready，auto-merge 已挂（squash）。27 条 check 零 failure，TypeScript Type Check 18:57:59Z 绿 —— 放宽后的 include 在 CI 里真的编译干净，不是本地读数。

裁决对账

裁决	实现	判定
先重新取数	在 origin/main @ 7cfe7ad 上放宽 glob 跑 tsc --noEmit：卡片逐条复现 —— 同样 6 条、同样错误码、同样行号、同样 3+3 拆分；基线绿，无一条是既有的	✅ 这次卡片没过期，但读数是自己取的
两半都要（修错误 且 让文件真进 program）	glob 改为整体 e2e/**/*，并用 --listFiles 证明 global-setup.ts 确实在 program 里 —— 不是「没报错所以大概在」	✅ 这一步是关键，卡片的失败模式正是「没人看它」
卡片的开放问题你来答	shim 从 test/node-shim.d.ts 移到 types/node-shim.d.ts，理由是实测两棵树都在消费它（test/ 用 existsSync/readFileSync/readdirSync + process.cwd() 全局，e2e/ 用 mkdirSync/writeFileSync/dirname + 同一个全局）。两个真实调用方，不是为一个调用方造抽象	✅ 且 vitest 层前后都是 193 tests 绿
文件面 examples/app-showcase/**	未越界	✅
changeset 要推导	private: true 且不在 .changeset/config.json 的 fixed 列表 ⇒ 未发布 ⇒ skip-changeset。标签写联合并回读	✅

假设 D —— 要求「论证」，交回来的是证明

我要的是「在 PR 正文里论证运行时逐字等价」。dev 做的是编译前后源码并对比产物 JS 哈希：global-setup.ts 0ed6c5be… == 0ed6c5be…，playwright.config.ts 11c4148d… == 11c4148d…，字节相同。

而且这一步抓到了一个真陷阱：第一次把 declare 放在前导块注释与第一条语句之间，注释被"脱钩"、从产物里掉了 —— 字节就不同了。改成declare 放注释上方才恢复字节相同，两处都留了注释说明为何这样排。这是那种没人会主动去查、查了才发现的偏差；假设 D 正是为它写的。

⚠️ 同时诚实标注：smoke 套件本身没跑（需要真后端在 :3000，容器上有并行 agent），所以主张是「产物模块字节相同」而不是「跑过一遍」。这个区分说清楚了，比含糊地说"验证过"强得多。

假设 C 被部分证伪 —— 记下来

卡片把 shim 的缺口读成「这个包没有 @types/node」。实测：它装在 workspace 根、从这个包物理可解析，只是没人在 compilerOptions.types 里点名它。用 types: ["node"] 探测：三条 node 内建错误消失，三条 process.env 错误照旧 —— 因为 shim 自己的全局 declare const process: { cwd(): string } 把真的遮住了。⇒「直接加 @types/node」不是更小的修法：只修一半、还会把 shim 的 process 全局挤掉、并放宽一处这个包用两条注释明确记录为刻意选择的类型面。理由已写进 types/node-shim.d.ts，下一个人不必重新推导。

一处 scope 判断，我不打回

playwright.config.ts 被一并纳入，dev 主动标了出来让我可以砍掉。我保留它。 它和 global-setup.ts 是同一条 smoke 通道、同一种「无人读」的暗处、同一条一行修法，实测代价只有它自己那 3 条错误、不引入新类型面。砍掉它等于在隔壁留一个一模一样的洞，将来还要为两行改动再开一次同一个 tsconfig —— 那比多这两行更吵。

vitest.config.ts 正确地没纳入：实测它的 vitest/config import 会把整个 @types/node 传递性拖进 program，正是这个包刻意规避的类型面。那是另一个决定，不是搭车。

报告里的第 2 项 —— 我接手，已立卡

scripts/check-type-check-coverage.mjs 用这个文件当「隐藏测试要一次加一个」的示范：「e2e/**/* would have pulled e2e/global-setup.ts into app-showcase's measurement and billed the test layer 6 errors」。机制论述仍然成立，但示范已成历史 —— 本 PR 之后 e2e/**/* 就是现行 glob 且零错误。dev 因为 scripts/ 被我划在文件面外而选择上报不自行处理,分寸正确。已立 #8181。

---

Generated by Claude Code