Initial Commit

openspec/archive/2026-04-27-testing-runner-subpath/proposal.md

@@ -0,0 +1,56 @@
+# Add `@suaveplan/testing/runner` central runner subpath
+
+**Package**: `@suaveplan/testing`
+**Status**: PROPOSED
+**Type**: feature
+
+## Why
+
+~95 packages currently import `describe`, `it`, `expect`, `vi`, and
+`expectTypeOf` directly from `vitest`, which means the monorepo cannot
+swap, wrap, or instrument the test runner without touching ~983 files.
+`@suaveplan/testing-dom/runner` already provides this indirection for
+DOM packages, but DOM/React-specific dependencies make it unsuitable as
+the universal runner barrel. This change ports the same pattern into the
+universal `@suaveplan/testing` package so every non-DOM package can
+import the runner from one stable place.
+
+## What changes
+
+- ADDED: `@suaveplan/testing/runner` subpath export (vitest by default,
+  `bun:test` under the `bun` package.json condition)
+- ADDED: `src/runner/index.ts`, `src/runner/vitest.ts`,
+  `src/runner/bun-test.ts`, `src/runner/mocks.ts` exporting
+  `describe`, `it`, `test`, `expect`, `expectTypeOf`, `vi`,
+  `beforeAll`, `beforeEach`, `afterAll`, `afterEach`,
+  `fn<TArgs, TReturn>`, `spy`, `stub`, `mock`, `fakeClock`,
+  `restoreMocks`, `restoreTimers`, plus types `RunnerMock`, `SpyHandle`
+- ADDED: `expectTypeOf` shim for the bun-test path (Proxy-backed no-op
+  chain — type assertions are erased at compile time)
+- ADDED: `@types/bun` devDependency, `tsconfig.lib.json` `types` extended
+  with `bun`, and matching vite multi-entry build wiring
+- ADDED: `runner/mocks.test.ts` and `runner/runner.spec-conformance.test.ts`
+
+## Out of scope
+
+- Migrating ~983 vitest imports to the new subpath — handled in a
+  follow-up codemod commit (genesis branch, same PR)
+- DRY-linking `@suaveplan/testing-dom/runner` to this subpath — rule 8
+  forbids `testing-dom` from depending on `@suaveplan/testing`, so the
+  two surfaces stay duplicated by design
+
+## Verification approach
+
+- `src/runner/mocks.test.ts` — unit coverage for `fn`/`spy`/`stub`/
+  `fakeClock`/`restoreMocks`/`restoreTimers`
+- `src/runner/runner.spec-conformance.test.ts` — type-level pins via
+  `expectTypeOf` for `RunnerMock<TArgs, TReturn>` and `SpyHandle`
+- 5-gate triple (`bun run check`, `turbo lint typecheck test`,
+  `turbo test:coverage` 100/100/100/100, openspec-conformance,
+  `turbo build`) green for `@suaveplan/testing`
+
+## Migration impact
+
+Additive only. No existing exports change. Consumers continue to import
+the package barrel for utilities; the new `./runner` subpath is the sole
+addition.