@vitronai/themis 0.1.0-beta.0 → 0.1.0-beta.1

package/CHANGELOG.md

@@ -6,6 +6,7 @@ All notable changes to this project are documented in this file.
 
 ### Changed
 
+- Added a first-party `themis generate` / `themis scan` code-scan flow that generates deterministic contract tests for exported modules, React components, hooks, Next app/router files, route handlers, and Node services; emits richer machine-readable `--json` results for agents; writes `.themis/generate-map.json`, `.themis/generate-last.json`, `.themis/generate-handoff.json`, `.themis/generate-backlog.json`, and `.themis/fix-handoff.json`; supports project-level `themis.generate.js` providers, interaction/state adapters for React components and hooks, automatic `--write-hints` scaffolding, targeted regeneration, planning mode, scenario/confidence steering, review/update/clean workflows, strict quality gates, and backlog remediation commands; and fails generated tests with direct regeneration guidance when scanned sources drift.
 - Moved the package line from alpha to beta and defined beta compatibility expectations for CLI, artifacts, and the JS/TS package surface.
 - Tightened npm/package positioning around Themis as an intent-first unit test framework for AI agents in Node.js and TypeScript.
 - Updated publish-facing docs to consistently frame Themis as an AI verdict engine for human and agent review loops.
@@ -13,8 +14,22 @@ All notable changes to this project are documented in this file.
 - Expanded the HTML report with quick actions, failure-first triage, richer file cards, and test-level drilldown.
 - Added embedded brand/report asset visuals to the README.
 - Added project-aware JS/TS runtime support for TSX, ESM `.js`, `tsconfig` path aliases, `setupFiles`, and `jsdom` environments.
-- Added first-party snapshots, mocks, run-diff artifacts, and watch mode for tighter agent rerun loops.
+- Removed first-party snapshot-file workflows in favor of direct contract assertions and generated flow contracts; retained mocks, run-diff artifacts, and watch mode for tighter agent rerun loops.
+- Added a lightweight DOM-oriented `jsdom` UI test layer with `render`, `screen`, `fireEvent`, `waitFor`, `cleanup`, and UI matchers for text, attributes, and document presence.
+- Added deterministic async UI test controls with fake timers, microtask flushing, and first-party fetch mocking for `jsdom` tests.
+- Expanded generated React and Next component adapters with direct DOM-state contract assertions and provider-aware `wrapRender(...)` support in `themis.generate.js` / `themis.generate.cjs`.
+- Added provider-driven `componentFlows` plus richer `applyMocks(...)` context so generated React/Next adapters can emit async behavioral flow contracts with mocked fetch/timer control.
+- Added provider preset wrappers for router, React Query, Zustand, and Redux-style app patterns in `themis.generate.js` / `themis.generate.cjs`, plus richer inferred async input/submit/loading/success component flows.
+- Added an incremental `themis migrate <jest|vitest>` scaffold and runtime compatibility imports for `@jest/globals`, `vitest`, and `@testing-library/react`.
+- Added a zero-IPC `--isolation in-process` test mode plus `--cache` for faster local rerun loops and in-process watch execution.
+- Deepened provider/app adapter presets with Next navigation and auth/session wrapper metadata alongside the existing router, React Query, Zustand, and Redux presets.
+- Strengthened failure-to-fix automation with richer `.themis/fix-handoff.json` entries (`repairStrategy`, `candidateFiles`, `autofixCommand`) and added `.themis/migration-report.json` for migration inventories and next actions.
+- Extended provider/app presets with route history/state, auth permissions/roles, query status/query keys, and store selector/action metadata for richer generated UI wrappers.
+- Added richer generated DOM flow assertions for empty, disabled, retry, error, and recovery paths with role- and attribute-aware expectations.
+- Added `themis migrate --rewrite-imports`, which rewrites matched Jest/Vitest/Testing Library imports to a local `themis.compat.js` bridge for more automated incremental migration.
+- Added config-level `testIgnore` discovery patterns so repos can keep generated output, fixture sandboxes, and other local test noise out of default suite runs deterministically.
 - Added an in-repo VS Code extension scaffold for artifact-driven result viewing, reruns, and HTML report opening.
+- Expanded the VS Code extension scaffold with generated-review navigation for source/test/hint mappings and unresolved generation backlog.
 - Refreshed README, AGENTS, and supporting docs to match the current package scope, JS/TS feature set, artifact contracts, and extension surface.
 
 ## 0.1.0-alpha.1 - 2026-02-13

package/README.md

@@ -18,12 +18,13 @@ It is built to be the best test loop for agent workflows: deterministic reruns,
 ## Contents
 
 - [Quickstart](#quickstart)
+- [Code Scan](#code-scan)
 - [Positioning](#positioning)
 - [Modern JS/TS Support](#modern-jsts-support)
 - [Commands](#commands)
 - [Agent Guide](#agent-guide)
 - [VS Code](#vs-code)
-- [Snapshots And Mocks](#snapshots-and-mocks)
+- [Mocks And UI Primitives](#mocks-and-ui-primitives)
 - [Intent Syntax](#intent-syntax)
 - [Config](#config)
 - [TypeScript](#typescript)
@@ -52,8 +53,10 @@ Themis is built for modern Node.js and TypeScript projects:
 - `tsconfig` path alias resolution
 - `node` and `jsdom` environments
 - `setupFiles` for harness bootstrapping
-- first-party snapshots, mocks, and spies
-- `--watch` and `--rerun-failed` for tight local and agent rerun loops
+- `testIgnore` patterns for deterministic discovery boundaries
+- first-party mocks, spies, and deterministic UI primitives
+- compatibility imports for `@jest/globals`, `vitest`, and `@testing-library/react`
+- `--watch`, `--rerun-failed`, `--isolation in-process`, and `--cache` for tight local and agent rerun loops
 
 ## Visuals
 
@@ -66,6 +69,7 @@ Themis is built for modern Node.js and TypeScript projects:
 ```bash
 npm install -D @vitronai/themis
 npx themis init
+npx themis generate src
 npx themis test
 ```
 
@@ -84,9 +88,83 @@ npx themis test --agent
 Stay in a local rerun loop while editing:
 
 ```bash
-npx themis test --watch --reporter next
+npx themis test --watch --isolation in-process --cache --reporter next
 ```
 
+Incrementally migrate existing Jest/Vitest suites:
+
+```bash
+npx themis migrate jest
+npx themis migrate jest --rewrite-imports
+npx themis test
+```
+
+## Code Scan
+
+Themis can scan your JS/TS source tree and generate deterministic unit-layer tests for exported modules, React components, React hooks, Next app components, Next route handlers, generic route handlers, and Node services:
+
+```bash
+npx themis generate src
+npx themis test
+```
+
+Generated files land under `tests/generated` by default. Each generated test:
+
+- checks the scanned export names when Themis can resolve them exactly
+- asserts the normalized runtime export contract directly in generated source
+- adds scenario adapters for React components/hooks, Next app/router files, route handlers, and service functions when Themis can infer or read useful inputs
+- captures React interaction and hook state-transition contracts when event handlers or stateful methods are available
+- asserts DOM-state and behavioral flow contracts directly for generated React and Next component adapters
+- emits async behavioral flow contracts for generated React and Next component adapters when flow plans are inferred or hinted, including richer inferred input/submit/loading/success paths for common async forms
+- supports provider-driven DOM flow contracts for empty, disabled, retry, error, and recovery states with attribute- and role-aware assertions
+- fails with a regeneration hint when the source drifts after the scan
+
+Themis also supports per-file generation hints with sidecars like `src/components/Button.themis.json` so humans and agents can provide props, component flows, args, route requests, and route context. When those sidecars do not exist yet, `--write-hints` can scaffold them automatically from the current source analysis.
+
+For repo-wide generation defaults, add `themis.generate.js` or `themis.generate.cjs` at the project root. Providers in that file can match source paths, supply shared props/args/flow plans, register runtime mocks for generated UI scenarios, and wrap generated component renders so generated DOM contracts run inside the same provider shells humans use in app tests. Providers can also declare preset wrapper metadata for router, Next navigation, auth/session shells, React Query, Zustand, and Redux-style app state patterns, including route history/state, query status, auth permissions, and store selector/action metadata.
+
+For CI and agent loops, Themis can also enforce generation quality instead of only writing files. Strict runs emit a structured backlog, fail on unresolved scan debt, and hand back exact remediation commands.
+
+Use these flags to control the generation loop:
+
+- `--json`: machine-readable payload for agents, including prompt-ready next steps
+- `--plan`: alias for `--review --json` with persisted handoff artifacts
+- `--review`: dry-run create/update/remove decisions without writing files
+- `--update`: refresh existing generated files only
+- `--clean`: remove generated files for the selected scope
+- `--changed`: target changed files in a git worktree
+- `--write-hints`: scaffold missing `.themis.json` sidecars so the next generate pass has explicit component props, hook args, service args, and route requests
+- `--scenario`: limit generation to one adapter family such as `react-hook`, `next-app-component`, or `next-route-handler`
+- `--min-confidence`: keep only entries at or above a confidence threshold
+- `--strict`: fail the generate run on skips, conflicts, or entries below `high` confidence
+- `--fail-on-skips`, `--fail-on-conflicts`: turn unresolved scan debt into a non-zero exit code
+- `--require-confidence`: fail if selected generated tests fall below a confidence threshold
+- `--files`, `--match-source`, `--match-export`, `--include`, `--exclude`: narrow the scan scope
+- `--force`: replace a conflicting non-Themis file
+- `--output <dir>`: change the generated test directory
+
+Every generation run also writes:
+
+- `.themis/generate-map.json`: source-to-generated-test mapping plus scenario/confidence metadata
+- `.themis/generate-last.json`: the full machine-readable generate payload
+- `.themis/generate-handoff.json`: a compact agent handoff artifact with prompt-ready next actions
+- `.themis/generate-backlog.json`: unresolved skips, conflicts, and confidence debt with suggested fixes
+
+Local test loops can also opt into a zero-IPC execution path:
+
+- `npx themis test --isolation in-process`: executes suites in-process instead of worker mode
+- `npx themis test --watch --isolation in-process --cache`: keeps a fast local rerun loop with file-level result caching
+- `npx themis test --isolation worker`: keeps process isolation for CI or global-heavy suites
+
+When generated tests fail, Themis also writes:
+
+- `.themis/fix-handoff.json`: a deduped failure-to-fix artifact that maps generated failures back to source files, categories, repair strategies, candidate files, and remediation commands
+
+Migration scaffolds also write:
+
+- `.themis/migration-report.json`: a machine-readable inventory of detected Jest/Vitest compatibility imports and recommended next actions
+- `themis.compat.js`: an optional local compatibility bridge used by `themis migrate --rewrite-imports`
+
 ## Why Themis
 
 See [`docs/why-themis.md`](docs/why-themis.md) for positioning, differentiators, and community messaging.
@@ -98,6 +176,11 @@ See [`docs/why-themis.md`](docs/why-themis.md) for positioning, differentiators,
 - Publish guide: [`docs/publish.md`](docs/publish.md)
 - VS Code extension notes: [`docs/vscode-extension.md`](docs/vscode-extension.md)
 - Agent result schema: [`docs/schemas/agent-result.v1.json`](docs/schemas/agent-result.v1.json)
+- Generate result schema: [`docs/schemas/generate-result.v1.json`](docs/schemas/generate-result.v1.json)
+- Generate map schema: [`docs/schemas/generate-map.v1.json`](docs/schemas/generate-map.v1.json)
+- Generate handoff schema: [`docs/schemas/generate-handoff.v1.json`](docs/schemas/generate-handoff.v1.json)
+- Generate backlog schema: [`docs/schemas/generate-backlog.v1.json`](docs/schemas/generate-backlog.v1.json)
+- Fix handoff schema: [`docs/schemas/fix-handoff.v1.json`](docs/schemas/fix-handoff.v1.json)
 - Failures artifact schema: [`docs/schemas/failures.v1.json`](docs/schemas/failures.v1.json)
 - Changelog: [`CHANGELOG.md`](CHANGELOG.md)
 - Contributing: [`CONTRIBUTING.md`](CONTRIBUTING.md)
@@ -106,6 +189,25 @@ See [`docs/why-themis.md`](docs/why-themis.md) for positioning, differentiators,
 ## Commands
 
 - `npx themis init`: creates `themis.config.json` and a sample test.
+- `npx themis generate src`: scans source files and generates contract tests under `tests/generated`.
+- `npx themis generate src --json`: emits a machine-readable generation payload for agents and automation.
+- `npx themis generate src --plan`: emits a planning payload and handoff artifact without writing generated tests.
+- `npx themis generate src --review --json`: previews create/update/remove decisions without writing files.
+- `npx themis generate src --review --strict --json`: fails fast on unresolved generation debt while still emitting a machine-readable plan.
+- `npx themis generate src --write-hints`: scaffolds missing hint sidecars and uses them in the same generate pass.
+- `npx themis generate src --update`: refreshes existing generated tests only.
+- `npx themis generate src --clean`: removes generated tests for the selected scope.
+- `npx themis generate src --changed`: regenerates against changed files in the current git worktree.
+- `npx themis generate src --scenario react-hook --min-confidence high`: targets one adapter family at a confidence threshold.
+- `npx themis generate app --scenario next-route-handler`: focuses generation on Next app router request handlers.
+- `npx themis migrate jest`: scaffolds a Themis config/setup bridge for existing Jest suites.
+- `npx themis migrate jest --rewrite-imports`: rewrites matched Jest/Vitest/Testing Library imports to a local `themis.compat.js` bridge file.
+- `npx themis migrate vitest`: scaffolds the same bridge for Vitest suites.
+- `npx themis generate src --require-confidence high`: enforces a quality bar for all selected generated tests.
+- `npx themis generate src --files src/routes/ping.ts`: targets one or more explicit source files.
+- `npx themis generate src --match-source "routes/" --match-export "GET|POST"`: narrows generation by source path and exported symbol.
+- `npx themis generate src --output tests/contracts`: writes generated tests to a custom directory.
+- `npx themis generate src --force`: replaces conflicting files in the target output directory.
 - `npx themis test`: discovers and runs tests.
 - `npx themis test --next`: next-gen console output mode.
 - `npx themis test --json`: emits JSON result payload.
@@ -113,9 +215,11 @@ See [`docs/why-themis.md`](docs/why-themis.md) for positioning, differentiators,
 - `npx themis test --reporter html`: generates a next-gen HTML report file.
 - `npx themis test --reporter html --html-output reports/themis.html`: writes HTML report to a custom path.
 - `npx themis test --watch`: reruns the suite when watched project files change.
+- `npx themis test --watch --isolation in-process --cache`: runs a zero-IPC cached local loop for fast edit/rerun cycles.
 - `npx themis test --workers 8`: overrides worker count (positive integer).
+- `npx themis test --isolation in-process`: runs test files in-process instead of worker processes.
+- `npx themis test --cache`: enables file-level result caching for in-process local loops.
 - `npx themis test --environment jsdom`: runs tests in a browser-like DOM environment.
-- `npx themis test -u`: updates stored snapshots.
 - `npx themis test --stability 3`: runs the suite three times and classifies each test as `stable_pass`, `stable_fail`, or `unstable`.
 - `npx themis test --match "intent DSL"`: runs only tests whose full name matches regex.
 - `npx themis test --rerun-failed`: reruns failing tests from `.themis/failed-tests.json`.
@@ -136,9 +240,12 @@ Each run writes artifacts to `.themis/`:
 - `failed-tests.json`: compact failure list for retry loops.
 - `run-diff.json`: diff against the previous run, including new and resolved failures.
 - `run-history.json`: rolling recent-run history for agent comparison loops.
+- `fix-handoff.json`: source-oriented repair handoff for generated test failures.
+- `migration-report.json`: compatibility inventory and next actions for migrated Jest/Vitest suites.
+- `themis.compat.js`: optional local compat bridge for rewritten migration imports.
 - `report.html`: interactive HTML verdict report.
 
-`--agent` output includes deterministic failure fingerprints, grouped `analysis.failureClusters`, stability classifications, and previous-run comparison data to help AI agents deduplicate and prioritize failures.
+`--agent` output includes deterministic failure fingerprints, grouped `analysis.failureClusters`, stability classifications, previous-run comparison data, and a direct pointer to `.themis/fix-handoff.json` so AI agents can jump from generated failures to exact regeneration commands. Fix handoff entries also carry repair strategies, candidate files, and autofix commands for tighter failure-to-fix loops.
 
 Machine-facing reporters intentionally emit compact JSON. Agents and tooling should parse the payloads rather than depend on whitespace formatting.
 
@@ -150,14 +257,15 @@ The repo now includes a thin VS Code extension scaffold at [`packages/themis-vsc
 
 The extension is intentionally artifact-driven:
 
-- reads `.themis/last-run.json`, `.themis/failed-tests.json`, `.themis/run-diff.json`, and `.themis/report.html`
+- reads `.themis/last-run.json`, `.themis/failed-tests.json`, `.themis/run-diff.json`, `.themis/generate-last.json`, `.themis/generate-map.json`, `.themis/generate-backlog.json`, and `.themis/report.html`
 - shows the latest verdict and failures in a sidebar
+- adds generated-review navigation for source/test/hint mappings plus unresolved generation backlog
 - reruns Themis from VS Code commands
 - opens the HTML report inside a webview
 
 It does not replace the CLI. The CLI and `.themis/*` artifacts remain the source of truth.
 
-## Snapshots And Mocks
+## Mocks And UI Primitives
 
 Themis now ships first-party test utilities for agent-generated tests:
 
@@ -171,10 +279,12 @@ const { fetchUser } = require('../src/api');
 test('captures a stable UI contract', () => {
   const user = fetchUser();
   expect(fetchUser).toHaveBeenCalledTimes(1);
-  expect(user).toMatchSnapshot();
+  expect(user).toMatchObject({ id: 'u_1', name: 'Ada' });
 });
 ```
 
+Themis intentionally avoids first-party snapshot-file workflows. Prefer direct assertions, generated contract tests, and explicit flow expectations over large opaque snapshots.
+
 Available globals:
 
 - `fn(...)`
@@ -184,7 +294,57 @@ Available globals:
 - `clearAllMocks()`
 - `resetAllMocks()`
 - `restoreAllMocks()`
-- `expect(value).toMatchSnapshot()`
+
+For UI-oriented `jsdom` tests, Themis also ships a lightweight DOM layer:
+
+- `render(ui)`
+- `screen.getByText(...)`
+- `screen.getByRole(...)`
+- `screen.getByLabelText(...)`
+- `fireEvent.click/change/input/submit/keyDown(...)`
+- `waitFor(asyncAssertion)`
+- `cleanup()`
+- `useFakeTimers()`, `advanceTimersByTime(ms)`, `runAllTimers()`, `useRealTimers()`
+- `flushMicrotasks()`
+- `mockFetch(...)`, `resetFetchMocks()`, `restoreFetch()`
+
+Example:
+
+```tsx
+test('submits the form', async () => {
+  render(<button onClick={() => document.body.setAttribute('data-state', 'sent')}>Send</button>);
+
+  fireEvent.click(screen.getByRole('button', { name: 'Send' }));
+
+  await waitFor(() => {
+    expect(document.body).toHaveAttribute('data-state', 'sent');
+  });
+});
+```
+
+Network and async example:
+
+```ts
+test('loads api state deterministically', async () => {
+  useFakeTimers();
+  const fetchMock = mockFetch({ json: { ok: true } });
+
+  let done = false;
+  setTimeout(async () => {
+    const response = await fetch('/api/status');
+    const payload = await response.json();
+    done = payload.ok;
+  }, 50);
+
+  advanceTimersByTime(50);
+  await flushMicrotasks();
+
+  expect(done).toBe(true);
+  expect(fetchMock).toHaveBeenCalled();
+  useRealTimers();
+  restoreFetch();
+});
+```
 
 ## Intent Syntax
 
@@ -226,11 +386,13 @@ Easter egg aliases are also available: `cook`, `yeet`, `vibecheck`, `wipe`.
   "reporter": "next",
   "environment": "node",
   "setupFiles": ["tests/setup.ts"],
-  "tsconfigPath": "tsconfig.json"
+  "tsconfigPath": "tsconfig.json",
+  "testIgnore": ["^tests/generated(?:/|$)"]
 }
 ```
 
 Modern JS/TS projects can opt into `environment: "jsdom"` for DOM-driven tests and `setupFiles` for hooks, polyfills, or harness bootstrapping.
+Use `testIgnore` when you need local generated output, fixture folders, or scratch suites to stay out of the default discovery pass.
 
 ## TypeScript