Skip to content

fix: strip JSDoc import() annotations from dist bundles — dead opencode plugin lane (#1255) - #1256

Merged
ranxianglei merged 2 commits into
masterfrom
2026-09-24_opencode-plugin-jsdoc-strip
Sep 24, 2026
Merged

ranxianglei merged 2 commits into
masterfrom
2026-09-24_opencode-plugin-jsdoc-strip

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Fixes #1255

What

Every modern dist entry carries undici's JSDoc type annotations (@param {import('./client.js')} client, …) as plain text. Node ignores them; opencode's plugin loader resolves them as real files → ENOENT … dist/agent/client.js → failed to load plugin → the entire opencode lane (compression + proxy + updater) dies silently on every affected version (content scan: back to 0.1.57).

Why this shape

esbuild keeps class-member comments in non-minified ESM output (verified empirically against tsup 8.x's bundled esbuild: function-level JSDoc stripped by default, class-body JSDoc kept). Two parts:

  1. tsup.config.ts: minifyWhitespace: true via tsup's esbuildOptions hook — drops all non-legal comments, keeps code structure readable and license/legal footers intact.
  2. scripts/check-dist-import-annotations.mjs (new) wired into npm run build: fails the build if any relative import()/require() text ever reappears in dist *.js. The gate is what makes this stick — without it the lane can silently die again on any future dependency whose comments contain relative specifiers.

Pre-flight

  • Gate proven effective: with the flag off it reports all 770 existing refs across 11 entries and fails the build; with it on → dist-import-annotations: OK.
  • License footer preserved post-build (undici legal-comment paths still present in dist/index.js).
  • Node loads the built entry: full export list (14 exports).
  • End-to-end under isolated opencode 1.14.46: plugin loads with no ERROR line, marker plugin fires alongside, native bootstrap spawns the proxy from the npm-form copy.
  • typecheck clean; new gate tests 3/3; full suite matches unmodified master here (same 3 env-bound failures: macOS-path assertions ×2, live-registry test ×1).

⚠️ Behavior change: dist artifacts become whitespace-minified — no semantic change, stack-trace lines get denser (sourcemaps ship). Artifact size shrinks slightly.

Candidate follow-up (not done here, owner decides): report the loader behavior upstream to anomalyco/opencode — resolving JSDoc type annotations as files is arguably their bug too.

@github-actions

github-actions Bot commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-09-24_opencode-plugin-jsdoc-strip (af65c57)

Option A — Install from npm PR tag (recommended)

npm install -g billion-context@pr-1256

Each push to this PR publishes a new version under the pr-1256 npm tag.

Option B — Download artifact

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

Install instructions are refreshed on each push.

…de plugin lane (#1255)

Non-minified esbuild output keeps class-member JSDoc comments; undici's
{import('./client.js')}-style type annotations therefore survive into every
dist entry. Node's ESM loader ignores them, but opencode's plugin loader
resolves them as real files -> ENOENT -> 'failed to load plugin' -> silent
dead lane for all modern versions under opencode 1.x.

Set minifyWhitespace via tsup's esbuildOptions hook (drops non-legal
comments, keeps structure + license footers) and add a build gate that
fails if relative import()/require() text ever reappears in dist.
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Reviewed #1256 against current master (3aeb2b03, branch is fresh — no rebase needed). Verdict: sound fix, clean diff, ready to merge once the one red CI check clears (see below). Details:

① Original issue (#1255) — direction holds. I reproduced the root cause independently: building unmodified master leaves exactly 770 relative import()/require() refs across all 11 dist entries, including import('./client.js') in dist/agent/opencode-native.js — matching your content scan. Layer judgment: the proximate trigger is opencode's loader resolving JSDoc type annotations as files (their bug, out of our scope), but the fix belongs at the producer — bundled artifacts must never contain relative-specifier text in the first place. Fixing at the build config (esbuild comment handling) rather than filtering payload in transit passes the litmus test: any future dependency shipping tag-shaped comments hits the same wall and is caught. The gate makes it stick.

② Regression review — existing behaviors of touched paths:

  • dist self-containment (noExternal incl. acp-kernel/fzstd/node-forge/tar/undici/jsonc-parser): untouched, still self-contained ✓
  • legal/license footers: preserved — verified "MIT License" + undici legal-comment paths still present in built dist/index.js (undici text count 318→11 = exactly the stripped annotations) ✓
  • module export surfaces: byte-identical master↔PR on index.js/mcp.js/opencode.js/opencode-native.js (all entries also parse clean under node --check) ✓
  • sourcemaps: still emitted ✓
  • wire/protocol shape, config schema, persistence, runtime dep surface: zero src/ changes — nothing touched ✓
  • Intended change (disclosed in PR body, confirmed): dist becomes whitespace-minified → denser stack traces, smaller artifacts (measured: dist/index.js 3.50MB→2.62MB, −25%; total 82.3→74.1MB). No semantic change.
  • New failure mode is deliberate: npm run build now fails loudly instead of shipping a dead lane.

③ Code. Gate regex correctly targets relative specifiers only (./x, ../x) — a legitimate lazy import("sharp") cannot trip it; walk skips .map; CLI-only direct-execution guard. esbuildOptions is the documented tsup hook; minifyWhitespace is comments/whitespace only (no mangling/syntax rewrite), which the identical export surfaces above empirically confirm.

④ Tests. The 3 gate tests have teeth (specific bad-case forms incl. require()/spaced/dynamic, good-case no-false-positive, map-skip). Full suite local: master 2440 tests / 3 env-bound failures (claude-host e2e); PR 2443 / same 3 failures, +3 = the new gate tests, all pass. Failure sets byte-identical. Your isolated-opencode 1.14.46 e2e I took on faith — my independent checks were at the Node level (load + exports + parse).

⑤ Diff. Single commit, 4 files, +118/−1, every line on-purpose. No contention: no other open PR touches tsup.config.ts; only #1161 touches package.json (adds a devDependency, different hunk).

CI: 8/9 green. The one failure — test (windows-latest, 22) at resolveClaudeCli: bare names resolve via where.exe on Windows (tests/claude-native.test.ts:183) — is a transient Windows-runner flake, not this PR: the assertion got 'where' after a 5144ms duration ≈ the 5000ms timeout in spawnSync("where.exe", …) (src/plugin-install.ts:590), i.e. where.exe hung on that runner; nothing in the PR touches that path, npm test runs from source before the build step, and master was green on the same runner pool minutes earlier. I triggered a re-run of the failed job — will report the outcome in a follow-up.

Follow-up candidate you flagged (report the JSDoc-resolves-as-files behavior to anomalyco/opencode): agreed it's their side too — per the source-chain rule I'm leaving it to you to decide whether to file/report upstream.

修复了 opencode 插件通道静默死亡的问题(undici 的 JSDoc import() 注释被打包进 dist,opencode 加载器把它们当真实文件解析导致 ENOENT):构建时开 minifyWhitespace 去掉全部非 license 注释,并新增 dist 门禁防止复发;已本地复现根因(770 处残留)、验证导出面/许可证页脚/测试套件与 master 一致,唯一红项是 Windows 运行器上无关的 where.exe 超时 flake(已触发重跑),可以合并。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Follow-up: the failed test (windows-latest, 22) job was re-run on the same commit and passed — full CI is now green (run attempt 2, all jobs success). Confirms it was a transient Windows-runner flake (where.exe hang) in the pre-existing claude-native test, unrelated to this change. Nothing outstanding on my side: ready for you to merge.

Windows 重跑已通过,CI 全绿(确认为运行器瞬时故障),无遗留问题,可以合并。

… (review of #1256)

Node resolves entry-point symlinks, so when the gate script is invoked through a symlink (pnpm-style symlinked trees, /tmp -> /private/tmp), process.argv[1] no longer string-matches import.meta.url and the main-module guard silently skipped the whole check (exit 0, no output) — a silent gate death of exactly the class this gate exists to prevent. Compare realpathSync(fileURLToPath(import.meta.url)) against realpathSync(argv[1]) instead. Verified: direct/symlink/copy invocations all run the check; negative case still fails loudly; unit tests pass.
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

Review complete — this PR is the survivor of a duplicate pair: #1258 (same fix for #1255) has been closed as 重复; the full review report is in that thread. What I did to this branch during review:

  1. Rebased onto current master (a1b4b471) — no conflicts. Local pre-flight green on the rebased head: typecheck clean; build + gate OK; full suite 2448 pass / 3 fail / 2 skipped, with the 3 failures (tests/claude-native.test.ts live-process e2e) proven pre-existing on unmodified master via a clean baseline worktree.
  2. Fixed a gate weakness found in review (commit af65c573): the main-module guard string-compared process.argv[1] against pathToFileURL(...). Node resolves entry-point symlinks, so under a symlinked invocation (pnpm-style trees, /tmp→/private/tmp) the comparison went false and the gate exited 0 with no output — a silent skip, exactly the failure class this gate exists to prevent. Now compares realpathSync(fileURLToPath(import.meta.url)) against realpathSync(argv[1]). Verified: direct/symlink/copy invocations all run the check; negative case still fails loudly (exit 1 + violation list); unit tests pass.

CI is re-running on new head af65c573 (old head 0efd9211 was fully green — all 9 checks). Merge once the new CI is green.

中文摘要: 复核完成:#1256 为保留项(#1258 已作为重复关闭);分支已 rebase 到当前 master 并直接补了一个小修——原门禁在符号链接方式调用时会静默跳过检查,现改为 realpath 比较并已验证(直接/符号链接/拷贝三种调用都生效,负例仍响亮失败);等新 CI 全绿即可合并。

@ranxianglei

Copy link
Copy Markdown
Owner Author

Independent verification (human lane) on af65c57, fresh worktree + npm ci:

  • Root cause re-confirmed: unmodified build carries the undici JSDoc annotations; with this PR → dist-import-annotations: OK, grep -rEo "import(\"\./…\")" across dist = 0 hits; import('./dist/agent/opencode-native.js') under node returns full exports incl. default.
  • Gate proven both ways: negative fixture (import("./nope.js") + {import("./client.js")} JSDoc) → FAIL — 2 relative refs, exit 1; direct run → OK exit 0; symlinked invocation runs the check and fails loudly on missing dist (no silent exit-0 skip — the af65c57 guard fix works as intended).
  • The 3 claude-native failures do NOT reproduce here: tests/claude-native.test.ts 42/42 on this PR head AND on current master 088bb34; full suite on the PR head 2453 tests / 2451 pass / 0 fail / 2 skipped (E2E gates); typecheck 0 errors. ework's failures were live-process e2e on its runner, environmental.
  • Diff is exactly scoped (4 files: tsup.config.ts, gate script, gate tests, build script line); mergeable vs current master (behind, no conflicts — fix: pin acp-kernel 0.0.86 — count-triggered distillation default-off (#379) #1260's pin bump sits in a different package.json region).

Ready to merge. Note for release notes: dist becomes whitespace-minified (structure readable, sourcemaps ship).

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.

OpenCode plugin lane silently dead on modern versions: bundled JSDoc import() annotations crash opencode's plugin loader (ENOENT client.js)

1 participant