37 lines
3.3 KiB
Markdown
37 lines
3.3 KiB
Markdown
## Why
|
||
|
||
A repo-wide audit on 2026-05-03 found 19 packages importing test-runner primitives (`describe`, `it`, `expect`, `vi`) directly from `vitest` instead of from the canonical `@suaveplan/testing/runner` re-export wrapper. The wrapper exists precisely so the runner can swap (vitest ↔ bun:test ↔ future runners) via a single conditional export — but a package that bypasses it pins itself to vitest and breaks the dual-runner contract already specified in `testing` spec → "Central runner subpath". The drift accumulated silently during the bitpacker port, network rewrite, and voice/third-party-elevenlabs split because nothing in CI flags it.
|
||
|
||
## What Changes
|
||
|
||
- Migrate 19 packages from `from "vitest"` to `from "@suaveplan/testing/runner"` (and the equivalent `bun:test` direct imports where present in non-infra packages).
|
||
- bitpacker (7): `bitpacker-compressed`, `bitpacker-crypto`, `bitpacker-delta`, `bitpacker-network`, `bitpacker-schema`, `bitpacker-strategies`, `bitpacker-streaming`
|
||
- network (7): `network`, `network-failover`, `network-governance`, `network-plugin-protocol`, `network-plugin-registry`, `network-plugin-webrtc`, `network-topology`
|
||
- crypto (2): `crypto/crypto`, `crypto/crypto-cli`
|
||
- other (3): `media/voice`, `storage/storage`, `audio/third-party-elevenlabs`
|
||
- Codify the rule as a new requirement in the `monorepo-structure` capability (forbid direct `vitest` / `bun:test` imports outside an exempt allowlist of testing-infra packages).
|
||
- Add a CI grep gate (alongside the existing §13 barrel-export gate) that fails the build if a non-exempt package imports `vitest` or `bun:test` directly.
|
||
- Document the rule in `CLAUDE.md` (Critical Rules) and `openspec/AGENTS.md` (§6b or adjacent to §6a) with the verification grep.
|
||
- Treat the rule as a migration prerequisite: when porting a package from upstream, runner imports MUST be rewritten as part of the port (mirrors the §6a "convert `export *` during migration, not as follow-up" pattern).
|
||
|
||
This is **not** a breaking change for runtime consumers — it only reshapes test-file imports. Test behaviour, test counts, and coverage MUST be byte-identical after migration.
|
||
|
||
## Capabilities
|
||
|
||
### New Capabilities
|
||
|
||
(none)
|
||
|
||
### Modified Capabilities
|
||
|
||
- `monorepo-structure`: ADD a requirement that forbids direct `vitest` / `bun:test` imports from non-exempt packages and codifies the testing-infra exemption list. Existing requirements unchanged.
|
||
|
||
## Impact
|
||
|
||
- **Test files only.** No runtime / production source touched. No public API changes.
|
||
- **Affected files**: ~150–250 `*.test.ts` files across the 19 packages (count to be confirmed during apply).
|
||
- **CI pipeline**: one new grep-based check in the lint/typecheck stage, mirrors the existing barrel-export gate. Expected runtime <1s.
|
||
- **Docs**: `CLAUDE.md` Critical Rules section gains a new rule (numbered after current rule 10); `openspec/AGENTS.md` gains a sibling rule next to §6a. `MANIFEST.md` unchanged (rule is repo-level, not per-package).
|
||
- **Risk**: low. The `@suaveplan/testing/runner` subpath is already battle-tested by the 107 packages that use it today. Migration is a mechanical sed-style rewrite verified by `bunx turbo test --filter=<pkg>` post-migration.
|
||
- **Out of scope**: dev/testing-* infra packages (5) keep their direct `vitest` / `bun:test` imports — they author the wrapper.
|