Initial Commit

openspec/changes/enforce-canonical-test-runner-imports/specs/monorepo-structure/spec.md

@@ -0,0 +1,37 @@
+## ADDED Requirements
+
+### Requirement: Test files import test-runner primitives via the canonical wrapper
+
+Every `*.test.ts` / `*.test.tsx` file in the monorepo SHALL import test-runner primitives (`describe`, `it`, `test`, `expect`, `expectTypeOf`, `vi`, `inject`, `beforeAll`, `beforeEach`, `afterAll`, `afterEach`, and the runner-neutral mock helpers `fn`, `spy`, `stub`, `mock`, `fakeClock`, `restoreMocks`, `restoreTimers`) from `@suaveplan/testing/runner`. Direct imports from `vitest` or `bun:test` are forbidden EXCEPT in the testing-infrastructure packages that author or extend the wrapper.
+
+The exempt allowlist is defined by `package.json#name` and SHALL be exactly:
+
+- `@suaveplan/testing`
+- `@suaveplan/testing-dom`
+- `@suaveplan/testing-e2e`
+- `@suaveplan/testing-integration`
+- `@suaveplan/testing-integration-step-ca`
+
+Adding a package to the allowlist requires its own OpenSpec change with justification (the package must author runner-internal machinery — extending fixtures or production-side `@suaveplan/testing` consumers do NOT qualify).
+
+#### Scenario: Non-exempt package uses canonical wrapper
+
+- **WHEN** any test file under `packages/*/<pkg>/src/**/*.test.{ts,tsx}` is inspected, where `<pkg>` is not in the exempt allowlist
+- **THEN** every import of `describe`, `it`, `test`, `expect`, `expectTypeOf`, `vi`, `inject`, `beforeAll`, `beforeEach`, `afterAll`, or `afterEach` MUST resolve to a `from "@suaveplan/testing/runner"` source AND the file MUST contain zero `from "vitest"` / `from "bun:test"` import statements
+
+#### Scenario: Exempt testing-infra package may import vitest / bun:test directly
+
+- **WHEN** a test or implementation file inside `@suaveplan/testing`, `@suaveplan/testing-dom`, `@suaveplan/testing-e2e`, `@suaveplan/testing-integration`, or `@suaveplan/testing-integration-step-ca` is inspected
+- **THEN** the file MAY import directly from `vitest` and/or `bun:test` (these packages author or extend the runner wrapper itself)
+
+#### Scenario: CI gate blocks regression
+
+- **WHEN** the `lint:test-runner-imports` script (`scripts/lint/check-test-runner-imports.ts`) runs in CI on any commit
+- **THEN** it walks every `packages/*/*/package.json`, skips packages whose `name` is in the exempt allowlist, greps the package's `src/**/*.{ts,tsx}` for `from ['"]vitest['"]` and `from ['"]bun:test['"]`, and exits non-zero with a per-file error list when any matches are found
+
+#### Scenario: Migration prerequisite
+
+- **WHEN** a package is migrated from upstream `../suaveplan/` into the genesis monorepo (per `enterprise-package-migration` workflow)
+- **THEN** every `from "vitest"` / `from "bun:test"` import in the source MUST be rewritten to `from "@suaveplan/testing/runner"` as part of the migration commit, NOT as a follow-up — mirroring the `export *` → explicit named-exports rule from §6a
+
+**Verified by:** `scripts/lint/check-test-runner-imports.ts` MUST pass on the full monorepo as a precondition for merging any change to `main`.