fix(runtime): keep transpiler cache scopes within configured paths

[luvs01]

Summary

Keep Bun transpiler-cache version scoping within the explicitly configured cache path. A directory named bun-<version> is ordinary user configuration, so switching runtimes must append beneath it rather than infer its parent and select a sibling.

A path already ending in the target runtime's leaf is preserved, retaining same-version idempotence. Windows environment-name handling, drive-relative paths, disabled/unset caches, and unknown versions retain their contracts. The launcher and durable-child consumers share the same helper; no launcher authority or environment-provenance mechanism is added.

Tradeoff

An inherited process chain that alternates runtime versions now nests inward (base/bun-A/bun-B/bun-A). It no longer reuses the first version's sibling cache. Repeated same-version starts do not add levels, and a fresh launch with the original base still adds one level. This deliberately favors containment over unbounded cross-version rescoping; very deep mixed-version chains can accumulate path length and extra cache directories.

Verification

• Windows, official Bun 1.4.3: bun scripts/test.ts --changed=12025981e5a304cdb6b1b54f525ba8554f623977 tests/cli/bun-transpiler-cache-scope.test.ts selected 1/1 test file: 9 passed, 0 failed, 52 assertions.
• Coverage includes version-shaped configured bases, same-version reuse, A→B→A inheritance, unrelated marker-like environment values, POSIX separators/case, Windows case variants, UNC/drive-relative/root paths, disabled/unknown controls, durable-child environment, and the published launcher.
• Root TypeScript, structure SSOT, privacy scan, and git diff --check passed. Independent design and final source reviews found no remaining actionable issue.
• Hosted CI on this exact head passed, including all four test shards, the structure gate, npm-global Ubuntu, and the final ci gate. The full local suite and a new cross-user runtime exercise were not run. No production configuration or account was changed.

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Runtime and cross-platform CI documentation describe the new scoping contract and tradeoff.
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults.

Summary by CodeRabbit

• Bug Fixes

  • Improved transpiler cache handling by nesting runtime-version directories under configured cache paths.
  • Preserved cache paths that already include the active runtime version.
  • Added consistent behavior across POSIX and Windows paths, including roots, UNC paths, and drive-relative paths.
  • Prevented cache paths from being redirected to sibling directories when runtime versions change.

• Documentation

  • Clarified how inherited transpiler cache paths are scoped by runtime version.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: lidge-jun/opencodex/.coderabbit.yaml
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: efcc674d-a142-4bcb-8b68-8c81e406040a

📥 Commits

Reviewing files that changed from the base of the PR and between 1202598 and 29f7202.

📒 Files selected for processing: 4

• src/lib/bun-transpiler-cache-scope.mjs
• structure/ops/cross-platform-ci.md
• structure/runtime.md
• tests/cli/bun-transpiler-cache-scope.test.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 7 remain after this review.

📝 Walkthrough

Bun transpiler cache scoping now appends a runtime-version directory beneath the configured path. It preserves paths that already end in the current version’s directory. Tests cover POSIX and Windows paths, and documentation describes the updated behavior.

Changes: Bun cache scoping

Layer / File(s)	Summary
Append runtime version scope src/lib/bun-transpiler-cache-scope.mjs, tests/cli/bun-transpiler-cache-scope.test.ts, structure/ops/cross-platform-ci.md, structure/runtime.md	The scoping logic appends bun-<version> unless the configured path already ends in the current runtime’s version directory. Tests cover POSIX and Windows path forms, repeated version changes, and marker-style environment variables. The documentation describes the updated path behavior.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix

Merge Risk: ⚪ Minimal · up to 29f72

The cache-path change is mergeable after normal checks; no specific behavior requiring correction before merge is established.

Pre-merge checks: 5

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely describes the main change: keeping Bun transpiler cache version scopes within configured paths.
Docstring Coverage		Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 2 files. (2 skipped: 2 …
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 2 files. (2 skipped: 2 unsupported.)

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

✅ Deterministic PR hygiene checks passed.