feat: add in-process local loops and repair automation

Author: vitronai

CHANGELOG.md

@@ -21,6 +21,9 @@ All notable changes to this project are documented in this file.
 - 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.
 - 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.

README.md

@@ -56,7 +56,7 @@ Themis is built for modern Node.js and TypeScript projects:
 - `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` and `--rerun-failed` for tight local and agent rerun loops
+- `--watch`, `--rerun-failed`, `--isolation in-process`, and `--cache` for tight local and agent rerun loops
 
 ## Visuals
 
@@ -88,7 +88,7 @@ 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:
@@ -119,7 +119,7 @@ Generated files land under `tests/generated` by default. Each generated test:
 
 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, React Query, Zustand, and Redux-style app state patterns.
+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.
 
 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.
 
@@ -148,9 +148,19 @@ Every generation run also writes:
 - `.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, and remediation commands
+- `.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
 
 ## Why Themis
 
@@ -201,7 +211,10 @@ 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 --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.
@@ -224,9 +237,10 @@ Each run writes artifacts to `.themis/`:
 - `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.
 - `report.html`: interactive HTML verdict report.
 
-`--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.
+`--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.
 

docs/api.md

@@ -35,7 +35,7 @@ Default behavior:
 - React and Next component adapters also emit direct DOM-state contract assertions that capture visible text, inferred roles, non-event attributes, and interaction-driven UI changes
 - React and Next component adapters can also emit async behavioral flow contracts when `componentFlows` are inferred or supplied, including richer inferred input/submit/loading/success flows for common async forms
 - project-level providers from `themis.generate.js` / `themis.generate.cjs` can match source files, inject shared fixture data, register runtime mocks, and wrap generated component renders for provider-aware DOM contracts and behavioral flow coverage
-- provider presets can declare router, React Query, Zustand, and Redux-style wrapper metadata without hand-writing every wrapper shell
+- provider presets can declare router, Next navigation, auth/session, React Query, Zustand, and Redux-style wrapper metadata without hand-writing every wrapper shell
 - `.themis/generate-map.json` records source-to-generated-test mappings plus scenario metadata
 - `.themis/generate-last.json` stores the full machine-readable generate payload
 - `.themis/generate-handoff.json` stores a compact prompt-ready handoff payload for agents
@@ -87,6 +87,8 @@ Project-level provider modules are supported via `themis.generate.js` or `themis
 - `include` / `exclude` / `files`: source matching rules
 - any of the same static fixture keys as sidecars (`componentProps`, `componentInteractions`, `componentFlows`, `hookArgs`, `hookInteractions`, `serviceArgs`, `routeRequests`, `routeContext`, `scenarios`)
 - `router`: preset router wrapper metadata (`path`, `params`, `search`)
+- `nextNavigation`: preset Next navigation wrapper metadata (`pathname`, `params`, `searchParams`)
+- `auth`: preset auth/session wrapper metadata (`user`, `session`, `state`)
 - `reactQuery`: preset React Query wrapper metadata (`clientName`, `state`, `cache`)
 - `zustand`: preset Zustand wrapper metadata (`name`, `state`)
 - `redux`: preset Redux wrapper metadata (`slice`, `state`)
@@ -119,6 +121,8 @@ Project-level provider modules are supported via `themis.generate.js` or `themis
 - `element`
 - `withProviderShell(type, element, attrs)`
 - `withReactRouter(element, config?)`
+- `withNextNavigation(element, config?)`
+- `withAuthSession(element, config?)`
 - `withReactQuery(element, config?)`
 - `withZustandStore(element, config?)`
 - `withReduxStore(element, config?)`
@@ -132,6 +136,7 @@ Behavior:
 - writes or updates `themis.config.json`
 - adds `tests/setup.themis.js` to `setupFiles`
 - adds `test:themis` to `package.json` when missing
+- writes `.themis/migration-report.json` with detected compatibility imports and next actions
 - relies on built-in runtime compatibility for `@jest/globals`, `vitest`, and `@testing-library/react`
 
 ## `themis test` options
@@ -144,6 +149,8 @@ Behavior:
 | `--reporter spec\|next\|json\|agent\|html` | string | Explicit reporter override. |
 | `--workers <N>` | positive integer | Override worker count. Invalid values fail fast. |
 | `--environment node\|jsdom` | string | Override the configured test environment. |
+| `--isolation worker\|in-process` | string | Select worker isolation or a zero-IPC in-process execution mode. |
+| `--cache` | flag | Enable file-level result caching for in-process local loops. |
 | `-w`, `--watch` | flag | Rerun the selected suite when watched project files change. |
 | `--stability <N>` | positive integer | Run selected tests `N` times and classify stability (`stable_pass`, `stable_fail`, `unstable`). |
 | `--html-output <path>` | string | Output path for `--reporter html` (default: `.themis/report.html`). |
@@ -156,8 +163,17 @@ Migration compatibility:
 - imports from `@jest/globals` are supported at runtime
 - imports from `vitest` are supported at runtime
 - imports from `@testing-library/react` are supported via Themis `render`, `screen`, `fireEvent`, `waitFor`, `cleanup`, and `act`
+- `themis migrate <jest|vitest>` also emits `.themis/migration-report.json` with detected files and recommended next actions
+
+Additional option:
+
 | `--lexicon classic\|themis` | string | Human reporter terminology mode for `next/spec`. |
 
+Execution note:
+
+- `--watch --isolation in-process --cache` is the fastest local rerun mode
+- `--isolation worker` remains the safer mode for CI and global-heavy suites
+
 Snapshot note:
 
 - Themis no longer supports first-party snapshot files or `-u` update flows. Prefer direct assertions and generated contract tests.
@@ -182,6 +198,7 @@ Each run writes to `.themis/`:
 - `run-diff.json`: diff against the previous run
 - `run-history.json`: rolling recent-run history
 - `fix-handoff.json`: deduped repair artifact for generated test failures (`themis.fix.handoff.v1`)
+- `migration-report.json`: migration inventory for Jest/Vitest bridge scaffolds (`themis.migration.report.v1`)
 
 Formal schemas:
 
@@ -204,6 +221,7 @@ Agent payload details:
 - `analysis.stability` captures multi-run classifications and per-test status sequences
 - `analysis.comparison` reports delta stats plus new and resolved failures against the previous run
 - `artifacts.fixHandoff` points to `.themis/fix-handoff.json` for generated failure repair loops
+- fix handoff entries include `repairStrategy`, `candidateFiles`, and `autofixCommand` for machine repair loops
 
 ## UI Test Utilities
 

docs/schemas/fix-handoff.v1.json

@@ -57,8 +57,11 @@
           "category",
           "failureCount",
           "failedTests",
+          "repairStrategy",
+          "candidateFiles",
           "suggestedAction",
-          "suggestedCommand"
+          "suggestedCommand",
+          "autofixCommand"
         ],
         "properties": {
           "file": { "type": "string" },
@@ -83,8 +86,14 @@
             "type": "array",
             "items": { "type": "string" }
           },
+          "repairStrategy": { "type": "string" },
+          "candidateFiles": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
           "suggestedAction": { "type": "string" },
-          "suggestedCommand": { "type": ["string", "null"] }
+          "suggestedCommand": { "type": ["string", "null"] },
+          "autofixCommand": { "type": ["string", "null"] }
         }
       }
     },

index.d.ts

@@ -76,6 +76,8 @@ export interface RunOptions {
   environment?: TestEnvironment;
   setupFiles?: string[];
   tsconfigPath?: string | null;
+  isolation?: 'worker' | 'in-process';
+  cache?: boolean;
 }
 
 export interface ThemisConfig {
@@ -95,6 +97,23 @@ export interface MigrationResult {
   setupPath: string;
   packageJsonPath: string | null;
   packageUpdated: boolean;
+  reportPath: string;
+  report: {
+    schema: 'themis.migration.report.v1';
+    source: 'jest' | 'vitest';
+    createdAt: string;
+    summary: {
+      matchedFiles: number;
+      jestGlobals: number;
+      vitest: number;
+      testingLibraryReact: number;
+    };
+    files: Array<{
+      file: string;
+      imports: string[];
+    }>;
+    nextActions: string[];
+  };
 }
 
 export interface GenerateOptions {

src/artifacts.js

@@ -256,8 +256,11 @@ function buildFixHandoffPayload(cwd, result, context) {
       category,
       failureCount: 1,
       failedTests: [failedTest.fullName],
+      repairStrategy: resolveRepairStrategy(category, generatedEntry, backlogMatch),
+      candidateFiles: buildFixCandidateFiles(generatedEntry, backlogMatch),
       suggestedAction: resolveFixAction(category, generatedEntry, backlogMatch),
-      suggestedCommand: resolveFixCommand(category, generatedEntry, backlogMatch)
+      suggestedCommand: resolveFixCommand(category, generatedEntry, backlogMatch),
+      autofixCommand: resolveAutofixCommand(category, generatedEntry, backlogMatch)
     });
   }
 
@@ -317,6 +320,45 @@ function resolveFixCommand(category, entry, backlogMatch) {
   return null;
 }
 
+function resolveAutofixCommand(category, entry, backlogMatch) {
+  if (backlogMatch && backlogMatch.suggestedCommand) {
+    return backlogMatch.suggestedCommand;
+  }
+  if (category === 'source-drift' && entry && entry.sourceFile) {
+    return `npx themis generate ${entry.sourceFile} --update && npx themis test --match ${JSON.stringify(path.basename(entry.testFile || entry.sourceFile))}`;
+  }
+  if (entry && entry.sourceFile) {
+    return `npx themis generate ${entry.sourceFile} --update`;
+  }
+  return null;
+}
+
+function resolveRepairStrategy(category, entry, backlogMatch) {
+  if (category === 'source-drift') {
+    return 'regenerate-source';
+  }
+  if (backlogMatch && backlogMatch.hintsFile) {
+    return 'tighten-hints';
+  }
+  return 'inspect-contract';
+}
+
+function buildFixCandidateFiles(entry, backlogMatch) {
+  const files = [];
+  if (entry && entry.sourceFile) {
+    files.push(entry.sourceFile);
+  }
+  if (entry && entry.testFile) {
+    files.push(entry.testFile);
+  }
+  if (entry && entry.hintsFile) {
+    files.push(entry.hintsFile);
+  } else if (backlogMatch && backlogMatch.hintsFile) {
+    files.push(backlogMatch.hintsFile);
+  }
+  return [...new Set(files)];
+}
+
 function buildFixNextActions(summary) {
   const actions = [];
   if (summary.generatedFailures > 0) {