@happyvertical/smrt-vitest 0.30.0

package/AGENTS.md

@@ -0,0 +1,109 @@
+# @happyvertical/smrt-vitest
+
+Vitest plugin for manifest generation and test database utilities. **Required for all SMRT projects.**
+
+## Plugin Setup
+
+```typescript
+// vitest.config.ts
+import { defineConfig } from 'vitest/config';
+import { smrtVitestPlugin } from '@happyvertical/smrt-vitest';
+export default defineConfig({
+  plugins: [smrtVitestPlugin()],
+  test: { setupFiles: ['@happyvertical/smrt-vitest/setup'] } // optional: globalThis isolation
+});
+```
+
+Without the plugin → "unregistered class" / "No field metadata found" errors.
+
+## What the Plugin Does
+
+1. Scans `src/**/*.ts` for SMRT classes via ManifestBuilder
+2. Discovers `@happyvertical/smrt-*` dependencies from package.json
+3. Loads external manifests via ManifestManager
+4. Registers all classes in ObjectRegistry
+5. Watch mode caveat: manifest only generated at startup — restart vitest after adding new classes/fields
+
+## CI retry (flaky-test resilience)
+
+The plugin injects `test.retry` into every consuming package's config: **2 in CI
+(`process.env.CI`), 0 locally** (`resolveCiRetry`). Several packages have rare,
+CI-environment-specific timing flakes that pass on re-run (none reproducible
+locally); retry keeps the shared cross-package "Test Packages" job reliable
+without masking real failures — a deterministic failure still fails all attempts,
+and vitest flags retried tests as `flaky`. Local runs keep retry at 0 so flakes
+surface during development. Override with `SMRT_VITEST_RETRY=<n>`.
+
+Packages that don't use `smrtVitestPlugin` (notably `cli`, plus `core`) set the
+same `retry` policy inline in their own `vitest.config.ts`.
+
+## Test Database Utilities
+
+| Function | Use Case |
+|----------|----------|
+| `createIsolatedTestDbFromManifest()` | Multi-table tests — auto-creates schema from manifest with FK ordering and STI dedup |
+| `createIsolatedTestDb({ schema })` | Single-table tests — pass raw DDL |
+| `createTestDb()` | No transaction isolation (legacy) |
+| `getTestDbConfig()` | Get DB config for current environment |
+
+**DB adapter auto-detection**: `DATABASE_URL` set → PostgreSQL; otherwise → SQLite temp files.
+
+```typescript
+let db, cleanup;
+beforeEach(async () => {
+  ({ db, cleanup } = await createIsolatedTestDbFromManifest());
+});
+afterEach(async () => { await cleanup(); }); // rolls back transaction
+```
+
+## Singleton Cache Gotcha
+
+Module-level singleton caches (common in SMRT collections) persist across tests, ignoring new mocks.
+
+**Fix**: `vi.resetModules()` in beforeEach + `await import(...)` in each test (not top-level imports).
+
+## Svelte component testing (S11 #1416)
+
+Shared component-test harness so any UI package can render Svelte components, drive
+them, and assert a11y — without copying setup or adding Testing Library deps
+(smrt-vitest carries `@testing-library/{svelte,jest-dom,user-event}` + `axe-core`).
+
+Wire it into a package's `vitest.config.ts` (keep `environment: 'node'` as default
+so DB tests are unaffected — the harness only activates under a DOM):
+
+```typescript
+test: {
+  environment: 'node',
+  setupFiles: [smrtVitestSetupPath, '@happyvertical/smrt-vitest/svelte-setup'],
+}
+```
+
+`svelte-setup` adds jest-dom matchers, Testing Library auto-cleanup, and a jsdom
+`<dialog>` `showModal`/`close` polyfill — guarded behind a `document` check, so it
+is inert in node-environment test files.
+
+Component tests opt into the DOM per-file and import the whole surface from one place:
+
+```typescript
+// @vitest-environment jsdom
+import { render, screen, userEvent, expectNoA11yViolations }
+  from '@happyvertical/smrt-vitest/svelte';
+
+const { container } = render(MyComponent, { props });
+await userEvent.click(screen.getByRole('button', { name: 'Save' }));
+await expectNoA11yViolations(container); // axe; color-contrast off (jsdom can't paint)
+```
+
+Exports: `./svelte` (render/screen/fireEvent/within/userEvent + `expectNoA11yViolations`),
+`./svelte-setup` (the setupFiles entry), `./a11y` (just the axe helper). The plugin
+aliases these subpaths to source for workspace consumers (`getWorkspaceViteAliases`).
+Pattern: render → assert role/name/state → drive with user-event → prove axe-clean.
+
+## Key Files
+
+- `src/index.ts` — Vite plugin, manifest generation, workspace aliases, all exports
+- `src/setup.ts` — globalThis isolation setup file
+- `src/svelte-setup.ts` — Svelte component-test setup (jest-dom, cleanup, dialog polyfill)
+- `src/svelte.ts` — component-test surface (Testing Library + a11y, one import)
+- `src/a11y.ts` — `expectNoA11yViolations` (axe-core)
+- `src/test-db.ts` — createIsolatedTestDb, createIsolatedTestDbFromManifest, createTestDb

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright <2025> <Happy Vertical Corporation>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# @happyvertical/smrt-vitest
+
+Vitest plugin for SMRT projects -- **required** for all SMRT tests. Auto-generates manifests, loads cross-package class metadata, and provides transaction-isolated test database utilities.
+
+## Installation
+
+```bash
+pnpm add -D @happyvertical/smrt-vitest
+```
+
+## Usage
+
+### Required Plugin Setup
+
+Every SMRT project must include `smrtVitestPlugin()` in vitest.config.ts:
+
+```typescript
+import { defineConfig } from 'vitest/config';
+import { smrtVitestPlugin } from '@happyvertical/smrt-vitest';
+
+export default defineConfig({
+  plugins: [smrtVitestPlugin()],
+});
+```
+
+Without this plugin, tests fail with `"No field metadata found"` or `"unregistered class"` errors.
+
+### Plugin Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `generateManifest` | `boolean` | `true` | Auto-generate manifest at startup |
+| `include` | `string[]` | `['src/**/*.ts']` | Source patterns to scan |
+| `exclude` | `string[]` | `['**/*.d.ts', ...]` | Patterns to exclude |
+| `packages` | `string[]` | `[]` | Additional packages beyond auto-discovered |
+| `verbose` | `boolean` | `false` | Enable detailed logging |
+| `root` | `string` | `process.cwd()` | Root directory |
+
+### Watch Mode Note
+
+The manifest is generated once at vitest startup. Restart vitest after adding new `@smrt()` classes or fields.
+
+## API
+
+### Plugin
+
+| Export | Description |
+|--------|-------------|
+| `smrtVitestPlugin(options?)` | Vite plugin -- generates manifest and loads cross-package classes |
+| `setupSmrtManifests(options?)` | Imperative alternative for non-Vite setups (e.g., globalSetup files) |
+
+### Test Database Utilities
+
+| Export | Description |
+|--------|-------------|
+| `createIsolatedTestDbFromManifest(options?)` | Create DB from manifest with FK ordering and STI dedup (recommended) |
+| `createIsolatedTestDb(options?)` | Create DB with raw DDL schema and transaction isolation |
+| `createTestDb(prefix?)` | Create DB with cleanup function (no transaction isolation) |
+| `getTestDbConfig(prefix?)` | Get DB config for current environment |
+| `getInMemoryDbConfig()` | Get in-memory SQLite config |
+| `getTestAdapter()` | Detect adapter: `'postgres'` or `'sqlite'` |
+| `getAdapterDisplayName()` | Human-readable adapter name for test labels |
+| `isPostgresAvailable()` | Check if `DATABASE_URL` is set |
+
+DB adapter auto-detection: `DATABASE_URL` set -> PostgreSQL; otherwise -> SQLite temp files.
+
+### Transaction Isolation Example
+
+```typescript
+import { createIsolatedTestDb } from '@happyvertical/smrt-vitest';
+
+let db, cleanup;
+
+beforeEach(async () => {
+  ({ db, cleanup } = await createIsolatedTestDb({
+    schema: `CREATE TABLE users (id TEXT PRIMARY KEY, name TEXT NOT NULL)`
+  }));
+});
+
+afterEach(async () => {
+  await cleanup(); // Rolls back transaction
+});
+
+it('should insert and query', async () => {
+  await db.insert('users', { id: '1', name: 'Alice' });
+  const user = await db.get('users', { id: '1' });
+  expect(user?.name).toBe('Alice');
+});
+```
+
+### Types
+
+`IsolatedTestDbOptions`, `IsolatedTestDbResult`, `ManifestTestDbOptions`, `TestDbAdapter`, `TestDbConfig`, `TransactionHandle`
+
+## Dependencies
+
+- `@happyvertical/smrt-core` -- manifest builder, object registry
+- `@happyvertical/sql` -- database connections and transactions
+- `vitest` (peer) -- Vite test framework
+
+## License
+
+MIT