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

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.