fix(unplugin): preserve Bun loader composition and build cache boundaries

[samchon]

Problem

The Bun adapter claims every TypeScript-shaped onLoad path and returns original source for paths the shared transform excludes. That prevents a later Bun plugin from handling declarations, node_modules sources, or another excluded match.

The adapter also has no build-boundary reset when it is used with Bun.build, even though that plugin builder exposes onStart. Bun runtime plugin builders in exact 1.3.14 do not expose the hook, so the lifecycle must remain feature-detected.

Evidence

packages/unplugin/src/bun.ts registers sourceFilePattern directly. Its loader then:

1. reads the matched path;
2. calls the raw Unplugin transform;
3. returns the original contents when no transform result exists.

The raw plugin's transformInclude is the owner that excludes declarations and node_modules, but the Bun adapter does not ask it before reading or returning.

Exact Bun 1.3.14 build controls used a later loader that replaces a dependency with export default 42:

Plugin order	Result
Replacement plugin only	42
Earlier broad loader returns undefined, then replacement	42
ttsc first with transforms disabled, then replacement	1

The third result proves that ttsc completed the load with original contents and shadowed the later plugin.

The exact Bun build plugin builder exposed onStart; the exact runtime builder supplied to Bun.plugin did not. Calling onStart unconditionally in runtime setup throws.

A custom-namespace Bun build control remained composable with ttsc registered first. Namespace capture was investigated and rejected.

Consequence surface

• A downstream loader cannot transform an excluded dependency that happens to match the TypeScript extension filter.
• ttsc performs avoidable filesystem reads for files it will not transform.
• Bun.build watch or repeated build sessions can retain a project cache across build boundaries, unlike the standard Unplugin adapters.
• Runtime registration must continue to work on Bun 1.3.14 without onStart.
• Lazy option resolution in bun-register must remain last-write-wins before the first load.
• Plugin-reported dependencies must remain harmless even though Bun runtime supplies no watch-registration channel.

Approach

Build the raw plugin lazily through one accessor. Before reading a path, call its transformInclude; return undefined when the file is excluded so Bun can continue to later loaders.

Feature-detect build.onStart. Where present, forward the build boundary to the raw plugin's buildStart hook so it clears the project cache. Where absent, register only onLoad.

Acceptance and verification

• An excluded node_modules TypeScript path returns undefined without reading the file.
• A later Bun loader handles that path.
• An included source still receives the ttsc transform and the correct ts or tsx loader.
• Bun runtime setup without onStart remains valid.
• Bun build setup with onStart clears a previously created raw cache at the next build boundary.
• Lazy explicit options in bun-register retain current ordering and idempotence.
• Exact Bun 1.3.14 composition is rechecked in addition to stub tests.
• Run:

pnpm --filter @ttsc/unplugin build
pnpm --filter @ttsc/test-unplugin start -- --include=bun
pnpm --filter @ttsc/test-unplugin start

Coordination

Issue #969 reports Bun runtime startup, while #252 owns the shared validation amplification. This issue corrects Bun-specific composition and lifecycle behavior without changing the checker-backed project transform contract.

[samchon]

A fresh adapter pass found one more branch of the same composition invariant.

The adapter must return undefined not only when raw.transformInclude(args.path) is false, but also when an included path produces no raw transform result. Exact Bun's plugins: false control takes that second path:

1. The project .ts file passes the extension and location filter.
2. ttsc reads it and the disabled transform returns undefined.
3. The adapter converts that into { contents: originalSource, loader: "ts" }.
4. Bun considers the load complete, so a later replacement loader never runs.

The observable result stays 1; the same later loader produces 42 when it runs alone or after an earlier loader returns undefined.

The implementation acceptance matrix is therefore:

• excluded path: decline before filesystem I/O;
• included path with a transformed string/object result: return that result;
• included path with no transform result: decline after the raw call so a later loader may handle it;
• no later loader: Bun's ordinary TypeScript loader reads and transpiles the source as before.

This refinement does not change the issue owner or require another issue.

[samchon]

Implemented in #980 and published in @ttsc/unplugin@0.21.0.

The Bun adapter now observes loader ownership and lifecycle boundaries separately:

• excluded paths are declined before filesystem I/O so a later Bun loader can handle them;
• an included path that produces no ttsc transform is also declined under Bun.build;
• Bun runtime registration retains its required pass-through behavior when the runtime API cannot accept an undefined load result;
• NUL virtual ids stay with the plugin that created them;
• configured BuildConfig.files entries stay with Bun's in-memory loader rather than being replaced by disk contents;
• onStart is feature-detected and forwarded only by builders that expose it; and
• one runtime setup defines one module-loading cache generation, while each Bun.build start opens a fresh generation.

The BuildConfig.files matching was derived from exact Bun behavior rather than a generic filesystem normalization. It preserves relative versus absolute spelling, dot segments, and path-component case; on Windows it normalizes only separators and drive-letter case. It also does not resolve keys against the current working directory, so a later process.chdir() cannot transfer ownership accidentally.

Exact Bun 1.3.14 controls covered loader order, excluded dependencies, no-op transforms, custom namespaces, runtime builders without onStart, build builders with onStart, in-memory files, NUL ids, separator and drive-letter behavior, dot segments, component case, relative/absolute spelling, and cwd changes. Stub coverage additionally verifies the shared raw-plugin lifecycle and last-write-wins lazy options.

This resolves the Bun-specific composition and build-boundary problem without changing the checker-backed project-compilation contract described in #969.

Release: https://github.com/samchon/ttsc/releases/tag/v0.21.0