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.

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

@@ -0,0 +1,41 @@
+# Capability Spec Delta: testing (2026-04-27-testing-runner-subpath)
+
+**Package**: `@suaveplan/testing`
+**Status**: PROPOSED
+
+## ADDED Requirements
+
+### Requirement: Central runner subpath
+
+The package SHALL expose a `./runner` subpath that re-exports the active
+test runner's primitives (`describe`, `it`, `test`, `expect`,
+`expectTypeOf`, `vi`, `beforeAll`/`beforeEach`/`afterAll`/`afterEach`)
+together with generic mock helpers (`fn`, `spy`, `stub`, `mock`,
+`fakeClock`, `restoreMocks`, `restoreTimers`) and runner-neutral types
+(`RunnerMock<TArgs, TReturn>`, `SpyHandle`). The subpath SHALL resolve
+to the vitest implementation by default and to `bun:test` under the
+`bun` package.json condition, so consumers swap runners without
+changing imports.
+
+#### Scenario: vitest path re-exports primitives
+
+- **WHEN** a consumer imports `describe`, `it`, `expect`, `vi`,
+  `expectTypeOf` from `@suaveplan/testing/runner` under the default or
+  `vitest` condition
+- **THEN** the imports resolve to the corresponding vitest exports
+
+#### Scenario: bun-test path re-exports primitives with `expectTypeOf` shim
+
+- **WHEN** a consumer imports the same surface under the `bun`
+  condition
+- **THEN** `describe`/`it`/`expect`/`vi` resolve to `bun:test`
+  equivalents and `expectTypeOf` resolves to a Proxy-backed no-op chain
+  whose calls succeed (type assertions are erased at compile time)
+
+#### Scenario: generic mock helpers preserve call signature
+
+- **WHEN** a test calls `fn<[string], number>()` from the subpath
+- **THEN** the returned `RunnerMock<[string], number>` is callable as
+  `(arg: string) => number` under both the vitest and bun-test paths
+
+**Verified by:** `src/runner/mocks.test.ts::"creates a mock that records calls"` AND `src/runner/runner.spec-conformance.test.ts::"fn<[string], number>() preserves call-signature typing"` AND `src/runner/runner.spec-conformance.test.ts::"BunRunnerMock<TArgs, TReturn> shape mirrors the vitest path"`

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

@@ -0,0 +1,37 @@
+# Tasks — Add `@suaveplan/testing/runner` central runner subpath
+
+## 1. Spec authoring
+
+- [x] 1.1 Read `openspec/specs/testing/spec.md`
+- [x] 1.2 Read `openspec/AGENTS.md` Sections 13 and 14
+- [x] 1.3 Draft `proposal.md` from `openspec/templates/proposal.md`
+- [x] 1.4 Draft `specs/testing/spec.md` ADDED requirement with `Verified by:` line
+
+## 2. Implementation
+
+- [x] 2.1 `src/runner/{vitest,bun-test,mocks,index}.ts` + sibling `.md`
+- [x] 2.2 `package.json` `./runner` conditional export, `@types/bun` devDep
+- [x] 2.3 `tsconfig.lib.json` `types: ["node", "bun"]`
+- [x] 2.4 `vite.config.ts` multi-entry for `runner/{index,vitest,bun-test}`
+
+## 3. Tests
+
+- [x] 3.1 `src/runner/mocks.test.ts`
+- [x] 3.2 `src/runner/runner.spec-conformance.test.ts`
+
+## 4. Documentation
+
+- [x] 4.1 `runner.md`, `vitest.md`, `bun-test.md`, `mocks.md` siblings
+
+## 5. Pre-archive verification
+
+- [x] 5.1 `bun run check` — 0/0/0
+- [x] 5.2 `bunx turbo lint typecheck test --filter=@suaveplan/testing` — green
+- [x] 5.3 `bunx turbo test:coverage --filter=@suaveplan/testing` — 100/100/100/100
+- [x] 5.4 `bun scripts/openspec-conformance.ts @suaveplan/testing` — exit 0
+- [x] 5.5 `bunx turbo build --filter=@suaveplan/testing` — green
+
+## 6. Archive
+
+- [x] 6.1 Fold spec delta into `openspec/specs/testing/spec.md`
+- [x] 6.2 Move to `openspec/archive/2026-04-27-testing-runner-subpath/`