Skip to content

fix: test fixture ergonomics vs src type surface (#1991) - #1992

Merged
ranxianglei merged 7 commits into
masterfrom
2026-10-03_test-fixture-ergonomics
Oct 3, 2026
Merged

ranxianglei merged 7 commits into
masterfrom
2026-10-03_test-fixture-ergonomics

Conversation

@ranxianglei

@ranxianglei ranxianglei commented Oct 3, 2026 •

Copy link
Copy Markdown
Owner

Closes #1991

Type-surface-only changes making the src API friendlier to test fixtures — zero runtime behavior change. Every checklist item from #1991 is handled: implemented (1, 2, 3, 5, 6, 8, 11), assessed-no-change with rationale (7, 10), owner decision pending (9), kernel-owned filed elsewhere (4).

Changes by item

Item 1 — ProxyOptions always-defaulted fields now optional (src/config.ts, src/cli.ts)
compat / streamErrorShape / passthroughSource / autoRestartOnUpdate / updateTag / advisoryCheck / releaseNotesCheck were required in the type while loadOptions() supplies defaults for all seven — every partial fixture had to retype the canonical block (and TS2352 comparability forced as unknown as ProxyOptions). Now optional. The only non-defensive read was cli.ts feeding the required AutoRestartHandlerConfig.enabled boolean → now opts.autoRestartOnUpdate ?? false (default OFF = loadOptions default, behavior-preserving). All other consumers already use ?. / truthy guards or accept string | undefined (normalizeUpdateTag).

Item 2 — zeroStats() factory (src/session.ts): exported zeroStats(): Session["stats"]; getSession() uses it. Fixtures build sessions without retyping 17 zero fields.

Item 3 — missing exports: PluginContext (dsh-native), ZodLike (opencode-native), CostRow (registry) now exported; CompressSettings re-exported from compress-settings.ts where tests already import its functions (drops the Parameters<typeof f>[N] cast).

Item 5 — OmpConfig/OpencodeConfig.providers optional: discovery tolerates absence (?? {} at all 8 read sites in client-config / launcher / discover); producers always set {}. parseOmpYaml refactored to build a local record and return { providers } (byte-identical object graph).

Item 6 — V2 registration callbacks accept synchronous returns (opencode-v2.ts): session.hook, tool.transform, command.transform return unions widened to include V2Registration. Production already consumes via await …?.(…) + truthy check, so sync returns were always handled at runtime; the union simply didn't admit them, forcing async/Promise.resolve mocks in fixtures. Strictly more permissive.

Item 8 — typed reads for server-stamped metadata (src/session.ts): AnonymousPrefixAffinityStamp type + peekAnonymousPrefixAffinity(session) / peekEffectiveContextLimit(session) accessors for the shapes stamped at server.ts:2230-2235 and :2771 — no more casting the Record<string, unknown> bag. Additive.

Item 11 — scripts/check-dist-import-annotations.d.mts: sibling declaration file so the test can statically import the checker (no dynamic-import-through-const workaround).

Test sites (tests/launcher.test.ts, tests/model-windows.test.ts, tests/launcher-max-outputs.test.ts): the 20 unguarded cfg.providers… assertion reads that item 5 newly flags — minimal ?. / ?? {} additions, assertions unchanged.

Assessed — no change (rationale)

  • Item 7 (OpencodeAcpHooks optional members): optionality models the host contract — opencode plugin modules may export any subset of hooks (the legacy module path does). createAcpCommandHooks always returns both members; the correct fixture remedy is ! where the factory guarantees definition (already done in Gate tests/ under CI typecheck — clear all pre-existing test type errors (#1970) #1990). Reverting to required would misrepresent the wire shape.
  • Item 10 (prompt_cache_key: string): kernel-owned wire type follows the OpenAI spec. bili's non-string defense already sits exactly at the boundary (preferPromptCacheKeyIdentity, session-id.ts); loosening the wire type to unknown degrades typing at every other site. Mentioned as a low-value facet in the acp-kernel issue below.

Pending owner decision (not touched)

  • Item 9 (test timeout options): node v22 silently ignores options passed after fn — trailing { timeout } args are dead code today. Reordering to (name, opts, fn) would start enforcing timeouts = potential new failures under CI load = behavior change. Left alone; needs an owner call.

Kernel-owned (filed elsewhere)

Behavior changes

None. Every change is type-surface (optional markers, exported names, additive factories/accessors, widened unions, declaration file) plus two ?? false defaults in cli.ts equal to the existing loadOptions default, and assertion-level ?. on parser results that are always present at runtime. No config keys, env vars, wire shapes, persistence formats, thresholds, or timing touched.

Verification

  • npm run typecheck (tsconfig.build.json) green; npm run build green including the dist annotation gate.
  • Root-tsconfig error set vs clean master: 1047 → 941 (108 pre-existing test errors incidentally resolved — e.g. ProxyOptions partial fixtures now compile). Zero new errors except two message-text drifts on pre-existing errors (fork-adoption / resume-ref-inheritance fixtures missing promptCache — part of Gate tests/ under CI typecheck — clear all pre-existing test type errors (#1970) #1990's cleanup scope, untouched here).
  • Targeted tests pass (local full suite left to CI per owner policy 2026-10-01): model-windows, launcher-max-outputs, dist-import-annotations, opencode-v2, fork-adoption, zero-config-routing, compress-settings, absorb, proxy-session-id.

Coordination note (#1990)

#1990 (tests typecheck gate) is still open and rewrites most test files. This PR touches only three test files (assertion-level ?. guards) — expect textual overlap when one rebases onto the other; resolution is union of intents. Merging either first keeps master green: this PR introduces no new root-tsconfig errors beyond the two pre-existing message drifts above.

@github-actions

github-actions Bot commented Oct 3, 2026

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-03_test-fixture-ergonomics (bfb7361)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.2006-pr.1992.7701c10

This exact version is immutable and reproducible. The rolling pr tag tracks the newest test build across all PRs.

Option B — Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr1992.tgz
npm install -g package

Install instructions are refreshed on each push.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 收到 PR #1992(Closes #1991)。开始核查:拉取分支、逐条对照 PR 声明与 #1991 checklist、本地定向验证(typecheck/build/定向测试)、CI 状态。结论稍后按结构化七问给出。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 PR #1992 核查完成。逐条对照了 PR 声明、#1991 checklist、实际 diff 与本地/CI 证据,结论如下(结构化七问):

1. 是什么问题
src 类型表面对测试 fixture 不友好:恒有默认值的字段被声明必填、fixture 常用类型未导出、server 内部 stamp 形状无类型模型——同一机制族的 11 个 facet(#1970 分析时发现,#1991 统一立项)。

2. 什么原因导致的
类型声明与消费者现实漂移:loadOptions 是唯一生产构造器且永远填齐默认值,但 ProxyOptions 把 7 个字段声明为必填;producer 永远写 providers: {} 但接口声明必填;V2 host 契约的同步返回分支、anonymous-prefix-affinity stamp 形状从未建模导出。根因在声明侧,不在消费者——修法因此全部落在声明侧(疏,不堵),没有在任何消费点加掩码。

3. 怎么修复的
按 facet 六个独立 commit:item 1(7 字段 optional + cli.ts 唯一非防御读点 ?? false)、item 2(zeroStats() 工厂)、item 3(导出 PluginContext/ZodLike/CostRow + CompressSettings re-export)、item 5(providers optional,parseOmpYaml 重构为局部 record)、item 6(V2 三个注册回调返回并集加同步 V2Registration)、item 8(stamp 类型 + 两个 peek accessor)、item 11(sibling .d.mts)。严格零运行时行为变更。

4. 是否有回归问题 — 无,逐项审过:

  • 验证了什么:① npm run typecheck(src gate)绿;② npm run build 绿含 dist-import-annotations 门禁;③ PR 列名的 9 个定向测试文件 145/145 过;④ CI 14/14 check runs 全 success(test ubuntu/windows × node22/24、e2e、registry e2e、codex/pi/dsh/opencode lane、build-artifact、version-guard);⑤ root-tsconfig 错误集 master vs branch 全量 diff:1047 → 941,与声明分毫不差;唯一"新增"的 2 条(fork-adoption / resume-ref-inheritance 的 TS2741 promptCache missing)经逐行比对证实是同一既有 fixture 缺陷在 master 上以 TS2740(缺多个属性)存在——本 PR 令部分属性变 optional 后缺失集缩小,tsc 降级为 TS2741,属已披露的消息漂移,非新错误。
  • 既有行为清点:ProxyOptions 变 optional 是纯类型层——loadOptions(config.ts:1096-1117)仍填齐全部 7 字段且为唯一生产构造器,运行时对象逐字节不变,web status 等读点拿到的值不变;cli.ts 两处 ?? false 与 feat(update): surface stale-install state to the human + opt-in self-restart (#806 §3) #811 默认 OFF 一致;parseOmpYaml 重构输出对象图相同(既有测试钉住);providers 变 optional 后 src 内全部读点(discover.ts:48/51、client-config.ts:1679-1720、launcher.ts:456-464)本就已 ?? {} 防护,producer 仍恒写 {};V2 返回并集加宽是纯加宽,消费点(opencode-v2.ts:333-373)await …?.(…)+truthy 本就兼容同步返回;zeroStats() 返回类型即 Session["stats"],编译器强制与 getSession() 原内联对象同构;stamp 类型与 server.ts:2360-2365 实际写入形状逐项比对一致(via "prefix"|"new"、lineage {parents, reason:"truncated"|"forked", sharedPrefix?},对 prefix-affinity.ts:85-105 的 AnonymousAffinity);.d.mts 两个签名与 .mjs 实际导出一一对应。无 fail-fast 变吞错、无阈值/时序/输出格式漂移。
  • 测试有效性:纯类型面变更,无新运行时行为需要钉;三个测试文件的改动仅加 ?./?? {},断言语义未变,现有套件继续钉住解析器行为,CI 双平台全量绿。
  • diff 整洁度:13 文件 81+/43-,每行都映射到 checklist 条目,6 个 commit 一 facet 一标注,干净。

5. 是否破坏缓存 — 不涉及。未触碰任何缓存/重试/增量游标/去重键路径;session 持久化格式不变。

6. 是否改了设计方向 — 否。类型面向既有运行时语义对齐,无架构/边界/数据流转向。item 7(OpencodeAcpHooks 可选成员正确反映 host 契约)、item 10(prompt_cache_key 保持 string,kernel-owned wire 类型,bili 的非 string 防御留在 session-id.ts 边界)评估后不动,判断成立;item 9(trailing-timeout 死参数,重排=行为变更)留 owner 拍板,未动;item 4(AbsorbConfig 五字段全必填)归 acp-kernel,已在 acp-kernel 立 #502(带合规来源标记,含 prompt_cache_key facet)。

7. 是否引入了新的配置 — 不涉及。无新 env/config key/默认值。

协调提示:#1990(tests typecheck gate)仍在途且重写大部分 test 文件,rebase 时预期文本重叠、按 union-of-intents 解;已验证两种合并顺序都不破坏 master(CI 门禁不含 root-tsconfig typecheck,唯一交互是那 2 条已披露漂移,#1990 清理范围)。

判定:可合并。 方向正确(修根因不修症状)、零运行时变更有完整证据链、CI 全绿。请 owner 自行 merge:#1992

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Gap] 测试 fixture 人体工学 vs src 类型表面:恒默认必填字段 + 缺失类型导出迫使测试样板/cast

1 participant