feat: tree shaking plugin

.changeset/qraft-tree-shaking-plugin.md

@@ -0,0 +1,5 @@
+---
+"@openapi-qraft/tree-shaking-plugin": minor
+---
+
+Add a cross-bundler tree-shaking plugin for generated context API clients.

.github/workflows/e2e.yml

@@ -39,7 +39,7 @@ jobs:
         run: yarn install --immutable
 
       - name: Build
-        run: yarn build:publishable
+        run: yarn build:publishable --force
 
       - name: Remove Verdaccio Storage
         run: rm -rf e2e/verdaccio-storage

.github/workflows/release.yml

@@ -30,7 +30,7 @@ jobs:
         run: yarn install --immutable
 
       - name: Build
-        run: yarn build:publishable
+        run: yarn build:publishable --force
 
       - name: Create dummy npmrc # Prevent creation of '.npmrc' by 'changesets-gitlab' with the 'NPM_TOKEN'
         run: touch ".npmrc"

docs/superpowers/plans/2026-05-08-qraft-tree-shaking-explicit-options-coverage.md

@@ -0,0 +1,86 @@
+# Qraft Tree-Shaking Explicit Options Coverage Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. When spawning workers, prefer a mini model and keep `reasoning_effort` at `high` or lower. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Cover the explicit `requestFn` and `queryClient` branches in the `tree-shaking-bundlers` fixture so the external e2e loop proves those overloads still tree-shake correctly.
+
+**Architecture:** This plan stays relative-path only so it isolates branch coverage from resolver diversity. Two small entrypoints exercise the generated client in context-style and precreated-style form, each with explicit options calls that must survive bundling. `scenarios.mjs` owns the new matrix rows and `assert-dist.mjs` verifies both the constructor choice and the option-branch tokens.
+
+**Tech Stack:** Node.js, Yarn 4, Vite, Rollup, Webpack, Rspack, esbuild, and the existing tree-shaking fixture scripts.
+
+**File Structure:**
+- `e2e/projects/tree-shaking-bundlers/src/context-explicit-options-relative.ts`: new context-style entrypoint that calls the generated client with explicit options.
+- `e2e/projects/tree-shaking-bundlers/src/precreated-explicit-options-relative.ts`: new precreated-style entrypoint that calls the precreated client with explicit options.
+- `e2e/projects/tree-shaking-bundlers/scripts/scenarios.mjs`: add the new scenarios and their expected tokens.
+- `e2e/projects/tree-shaking-bundlers/scripts/assert-dist.mjs`: assert the explicit-option branches and the constructor token choices.
+
+---
+
+### Task 1: Add the new explicit-options entrypoints and make the assertions fail first
+
+**Files:**
+- Create: `e2e/projects/tree-shaking-bundlers/src/context-explicit-options-relative.ts`
+- Create: `e2e/projects/tree-shaking-bundlers/src/precreated-explicit-options-relative.ts`
+- Modify: `e2e/projects/tree-shaking-bundlers/scripts/scenarios.mjs`
+- Modify: `e2e/projects/tree-shaking-bundlers/scripts/assert-dist.mjs`
+
+- [ ] **Step 1: Add a context-style entrypoint that exercises both option branches**
+
+Create `src/context-explicit-options-relative.ts` so it imports `createRelativeAPIClient` and exports both `createRelativeAPIClient({ requestFn: () => Promise.reject(new Error('stub')) })` and `createRelativeAPIClient({ queryClient: {} })`. Keep the file tiny and export the results so bundlers cannot drop either call.
+
+- [ ] **Step 2: Add a precreated-style entrypoint that exercises both option branches**
+
+Create `src/precreated-explicit-options-relative.ts` so it imports `createRelativePrecreatedAPIClient` and exports both `createRelativePrecreatedAPIClient({ requestFn: async () => ({}) })` and `createRelativePrecreatedAPIClient({ queryClient: {} })`.
+
+- [ ] **Step 3: Add scenario rows for the two new entrypoints**
+
+Add `context-explicit-options-relative` and `precreated-explicit-options-relative` to `scenarios.mjs`. Keep them relative-only; alias and extension diversity are already covered elsewhere in the matrix.
+
+- [ ] **Step 4: Tighten the output assertions around constructor choice and explicit-option branches**
+
+Update `assert-dist.mjs` so the context-style scenario must include `qraftReactAPIClient`, `requestFn`, and `queryClient`, while excluding `qraftAPIClient`. The precreated-style scenario must include `qraftAPIClient`, `requestFn`, and `queryClient`, while excluding `qraftReactAPIClient`. Keep the existing "unused context symbol must stay out" check for the precreated case.
+
+- [ ] **Step 5: Run the local e2e workflow and confirm the new matrix is green**
+
+Run:
+
+```bash
+cd e2e && yarn e2e:tree-shaking-bundlers-local
+```
+
+Expected: all bundlers pass for both new scenarios and the bundle text still reflects the intended branch selection.
+
+- [ ] **Step 6: Commit the explicit-options coverage**
+
+```bash
+git add e2e/projects/tree-shaking-bundlers
+git commit -m "test: cover explicit tree-shaking options branches"
+```
+
+### Task 2: Refresh the baseline after the new scenarios land
+
+**Files:**
+- Modify: `e2e/projects/tree-shaking-bundlers/dist/**`
+- Modify: `e2e/projects/tree-shaking-bundlers/scripts/assert-dist.mjs`
+- Modify: `e2e/projects/tree-shaking-bundlers/scripts/scenarios.mjs`
+
+- [ ] **Step 1: Re-run the local e2e workflow from a clean state**
+
+Run:
+
+```bash
+cd e2e && yarn e2e:tree-shaking-bundlers-local
+```
+
+Expected: the new explicit-options scenarios and the pre-existing matrix all pass together.
+
+- [ ] **Step 2: Refresh only the checked-in outputs that changed**
+
+If the new scenarios change bundle text, update the checked-in fixture outputs under `e2e/projects/tree-shaking-bundlers/dist`. Keep the one-file bundle contract intact.
+
+- [ ] **Step 3: Commit the refreshed baseline**
+
+```bash
+git add e2e/projects/tree-shaking-bundlers
+git commit -m "test: refresh explicit options e2e baseline"
+```

docs/superpowers/plans/2026-05-08-qraft-tree-shaking-path-rendering.md

@@ -0,0 +1,130 @@
+# Qraft Tree-Shaking Path Rendering Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. When spawning workers, prefer a mini model and keep `reasoning_effort` at `high` or lower. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Extract the import-path rendering rules out of `src/core.ts` so path normalization lives in one focused helper module, while keeping emitted import strings unchanged.
+
+**Architecture:** This spec depends on the earlier pipeline split and source-map work. `src/lib/transform/path-rendering.ts` owns `composeImportPath`, `resolveRelativeImportPath`, `composeResolvedSourceImportPath`, `resolvePrecreatedOptionsImportPath`, `normalizeResolvedId`, `stripQueryAndHash`, `stripSourceExtension`, and `stripIndexSourceExtension`. `src/core.ts` imports those helpers instead of reimplementing path logic. `README.md` gets a short convention note so the output format stays documented.
+
+**Tech Stack:** TypeScript, Node `path`, Vitest, Yarn 4.
+
+---
+
+### Task 1: Add helper-level tests that pin the rendering rules
+
+**Files:**
+
+- Create: `packages/tree-shaking-plugin/src/lib/transform/path-rendering.test.ts`
+- Modify: `packages/tree-shaking-plugin/src/core.ts`
+
+- [x] **Step 1: Write the helper test before the new module exists**
+
+```ts
+import {
+  composeImportPath,
+  composeResolvedSourceImportPath,
+  resolvePrecreatedOptionsImportPath,
+} from './path-rendering.js';
+
+it('renders relative source imports without source extensions or /index', () => {
+  expect(
+    composeResolvedSourceImportPath('/src/App.tsx', '/src/api/index.ts')
+  ).toBe('./api');
+  expect(
+    composeResolvedSourceImportPath('/src/App.tsx', '/src/api/client.tsx')
+  ).toBe('./api/client');
+  expect(
+    resolvePrecreatedOptionsImportPath(
+      '/src/App.tsx',
+      './client-options',
+      '/src/client-options/index.ts'
+    )
+  ).toBe('./client-options');
+  expect(composeImportPath('/src/App.tsx', '@openapi-qraft/react')).toBe(
+    '@openapi-qraft/react'
+  );
+});
+```
+
+- [x] **Step 2: Run the helper test and confirm it fails because the module has not been extracted yet**
+
+Run:
+
+```bash
+yarn workspace @openapi-qraft/tree-shaking-plugin test -- src/lib/transform/path-rendering.test.ts
+```
+
+Expected: FAIL because `path-rendering.ts` does not exist yet.
+
+- [x] **Step 3: Add the helper module and move the path logic out of `core.ts`**
+
+Move these functions unchanged except for imports and exports, and update `core.ts` to import them from the new module:
+
+```ts
+import {
+  composeImportPath,
+  composeResolvedSourceImportPath,
+  normalizeResolvedId,
+  resolvePrecreatedOptionsImportPath,
+  resolveRelativeImportPath,
+  stripIndexSourceExtension,
+  stripQueryAndHash,
+  stripSourceExtension,
+} from './lib/transform/path-rendering.js';
+```
+
+- [x] **Step 4: Re-run the helper test and one representative core snapshot**
+
+Run:
+
+```bash
+yarn workspace @openapi-qraft/tree-shaking-plugin test -- src/lib/transform/path-rendering.test.ts src/core.test.ts -t "renders relative source imports without source extensions or /index"
+```
+
+Expected: PASS, and the representative tree-shaking snapshot still emits the same bundler-friendly relative imports.
+
+### Task 2: Document the convention and validate the external fixture
+
+**Files:**
+
+- Modify: `packages/tree-shaking-plugin/README.md`
+- Modify: `packages/tree-shaking-plugin/src/core.ts`
+
+- [x] **Step 1: Add a short README note for the rendering rule**
+
+Add this note near the options or path-convention section:
+
+```md
+Relative generated imports are emitted without source extensions or `/index` so the output stays bundler-friendly.
+Bare module specifiers are preserved as-is.
+```
+
+- [x] **Step 2: Run the package unit suite and typecheck**
+
+Run:
+
+```bash
+yarn workspace @openapi-qraft/tree-shaking-plugin test
+yarn workspace @openapi-qraft/tree-shaking-plugin typecheck
+```
+
+Expected: both commands pass after the helper extraction.
+
+- [x] **Step 3: Run the external tree-shaking e2e checkpoint**
+
+Run:
+
+```bash
+cd e2e && yarn e2e:tree-shaking-bundlers-local
+```
+
+Expected: the external multi-bundler fixture still produces the same output shape and the path strings remain bundler-friendly.
+
+- [x] **Step 4: Commit the extraction**
+
+```bash
+git add packages/tree-shaking-plugin/src/lib/transform/path-rendering.ts packages/tree-shaking-plugin/src/lib/transform/path-rendering.test.ts packages/tree-shaking-plugin/src/core.ts packages/tree-shaking-plugin/README.md
+git commit -m "refactor: centralize tree-shaking path rendering"
+```
+
+---