fixup! docs: split qraft tree-shaking plans

Author: radist2s

docs/superpowers/plans/2026-05-08-qraft-tree-shaking-source-maps.md

@@ -8,6 +8,13 @@
 
 **Tech Stack:** TypeScript, Babel generator, unplugin, `@jridgewell/trace-mapping`, Vitest, Yarn 4.
 
+**File Structure:**
+- `packages/tree-shaking-plugin/src/lib/plugin/create-qraft-tree-shake-plugin.ts` forwards `this.inputSourceMap` from the bundler context into the core transform.
+- `packages/tree-shaking-plugin/src/core.ts` accepts an optional incoming map and passes it to Babel generator through `inputSourceMap`.
+- `packages/tree-shaking-plugin/src/core.test.ts` adds the regression test, updates the local test helper to pass the optional map, and verifies the composed position with `@jridgewell/trace-mapping`.
+- `packages/tree-shaking-plugin/package.json` and `yarn.lock` add the direct dev dependency required by the new test.
+- `e2e/projects/tree-shaking-bundlers/` is not expected to change for this feature, but it is the external validation target.
+
 ---
 
 ### Task 1: Add the failing composed-map regression test
@@ -19,6 +26,40 @@
 
 - [ ] **Step 1: Add a source-map test that traces the rewritten call site back to the original source**
 
+Update the local test helper first so the new regression test can pass the incoming map through to the real transform:
+
+```ts
+async function transformQraftTreeShaking(
+  code: string,
+  id: string,
+  options: TransformOptions,
+  inputSourceMap?: unknown
+) {
+  const fixtureRoot = path.dirname(path.dirname(id));
+  const fixtureResolver = createFixtureResolver(fixtureRoot);
+  const resolver = async (specifier: string, importer: string) => {
+    if (options.resolve) {
+      try {
+        const resolved = await options.resolve(specifier, importer);
+        if (resolved) return resolved;
+      } catch {
+        // Fall through to the fixture resolver.
+      }
+    }
+
+    return fixtureResolver(specifier, importer);
+  };
+
+  return transformQraftTreeShakingImpl(
+    code,
+    id,
+    options,
+    resolver,
+    inputSourceMap
+  );
+}
+```
+
 ```ts
 import { originalPositionFor, TraceMap } from '@jridgewell/trace-mapping';
 
@@ -65,25 +106,25 @@ export function App() {
 });
 ```
 
-- [ ] **Step 2: Run the focused test before plumbing exists and confirm it fails**
+- [ ] **Step 2: Add `@jridgewell/trace-mapping` as a direct dev dependency**
 
 Run:
 
 ```bash
-yarn workspace @openapi-qraft/tree-shaking-plugin test -- src/core.test.ts -t "keeps the rewritten call site traceable through the composed source map"
+yarn workspace @openapi-qraft/tree-shaking-plugin add -D @jridgewell/trace-mapping
 ```
 
-Expected: FAIL because the incoming bundler map is not threaded into the transform yet.
+Expected: `packages/tree-shaking-plugin/package.json` and `yarn.lock` now list `@jridgewell/trace-mapping` directly, so the new test can compile under Yarn PnP.
 
-- [ ] **Step 3: Record the dependency update**
+- [ ] **Step 3: Run the focused test before plumbing exists and confirm it fails**
 
 Run:
 
 ```bash
-yarn workspace @openapi-qraft/tree-shaking-plugin add -D @jridgewell/trace-mapping
+yarn workspace @openapi-qraft/tree-shaking-plugin test -- src/core.test.ts -t "keeps the rewritten call site traceable through the composed source map"
 ```
 
-Expected: the package manifest and lockfile both include the source-map assertion dependency.
+Expected: FAIL because the incoming bundler map is not threaded into the transform yet, so the composed-map assertion still points at generated-only positions.
 
 ### Task 2: Thread the incoming map through the plugin and generator
 
@@ -103,17 +144,26 @@ handler(this: any, code, id) {
 }
 ```
 
-- [ ] **Step 2: Pass the incoming map into Babel generator**
+- [ ] **Step 2: Extend the core transform signature and pass the incoming map into Babel generator**
 
-Use this generator call in `src/core.ts`:
+Update `packages/tree-shaking-plugin/src/core.ts` so the function accepts the optional map and forwards it unchanged:
 
 ```ts
+export async function transformQraftTreeShaking(
+  code: string,
+  id: string,
+  options: QraftTreeShakeOptions,
+  resolver: QraftResolver = createAgnosticResolver(options.resolve),
+  inputSourceMap?: unknown
+) {
+  // ...
   const result = generate(ast, {
     sourceMaps: true,
     sourceFileName: id,
     inputSourceMap,
     jsescOption: { minimal: true },
   });
+}
 ```
 
 Keep the rest of the transform unchanged. This spec is only about source-map composition for rewritten user call sites; synthetic generated statements do not need bespoke original-source mapping.