feat: add next and interaction generation review

Author: vitronai

CHANGELOG.md

@@ -6,7 +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, 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`, and `.themis/generate-backlog.json`; supports hint sidecars, 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.
+- 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`, and `.themis/generate-backlog.json`; supports 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.
@@ -16,6 +16,7 @@ All notable changes to this project are documented in this file.
 - 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.
 - 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

README.md

@@ -91,7 +91,7 @@ npx themis test --watch --reporter next
 
 ## Code Scan
 
-Themis can scan your JS/TS source tree and generate deterministic unit-layer tests for exported modules, React components, React hooks, route handlers, and Node services:
+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
@@ -102,7 +102,8 @@ Generated files land under `tests/generated` by default. Each generated test:
 
 - checks the scanned export names when Themis can resolve them exactly
 - snapshots a normalized runtime contract for the module surface
-- adds scenario adapters for React components/hooks, route handlers, and service functions when Themis can infer or read useful inputs
+- 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
 - 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, args, route requests, and route context. When those sidecars do not exist yet, `--write-hints` can scaffold them automatically from the current source analysis.
@@ -118,7 +119,7 @@ Use these flags to control the generation loop:
 - `--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` or `route-handler`
+- `--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
@@ -167,6 +168,7 @@ See [`docs/why-themis.md`](docs/why-themis.md) for positioning, differentiators,
 - `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 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.
@@ -216,8 +218,9 @@ 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
 

docs/api.md

@@ -29,7 +29,8 @@ Default behavior:
 - output directory: `tests/generated`
 - generated files mirror the scanned source tree with `*.generated.test.js`
 - generated tests snapshot normalized runtime export contracts
-- scenario adapters cover React components, React hooks, route handlers, and Node service functions when inputs can be inferred or hinted
+- scenario adapters cover React components, React hooks, Next app components, Next route handlers, generic route handlers, and Node service functions when inputs can be inferred or hinted
+- React component and hook adapters also snapshot inferred interaction/state contracts when event handlers or zero-argument stateful methods are available
 - `.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
@@ -71,6 +72,8 @@ Per-file hint sidecars are supported via `<source>.themis.json`. These can provi
 - `excludeExports`
 - `scenarios`
 
+`componentProps` and `routeRequests`/`routeContext` also steer Next app component and Next route handler adapters.
+
 ## `themis test` options
 
 | Option | Type | Description |

docs/vscode-extension.md

@@ -8,6 +8,7 @@ This is the intended shape of the editor UX:
 - a results sidebar driven by `.themis/*` artifacts
 - commands to run tests, rerun failures, refresh results, and open the HTML report
 - failure navigation that jumps from artifact data into the source file
+- generated-review navigation for source files, generated tests, hint sidecars, and backlog items
 
 ## Current MVP Scope
 
@@ -16,7 +17,12 @@ The scaffold currently supports:
 - reading `.themis/last-run.json`
 - reading `.themis/failed-tests.json`
 - reading `.themis/run-diff.json`
+- reading `.themis/generate-last.json`
+- reading `.themis/generate-map.json`
+- reading `.themis/generate-backlog.json`
 - opening `.themis/report.html` in a webview
+- surfacing generated source/test/hint mappings in the sidebar
+- surfacing unresolved generate backlog and gate state in the sidebar
 - refreshing when `.themis/*` files change
 
 The extension is intentionally thin. It shells out to Themis commands and treats the CLI plus artifacts as the canonical contract.

packages/themis-vscode/package.json

@@ -1,7 +1,7 @@
 {
   "name": "themis-vscode",
   "displayName": "Themis",
-  "description": "View Themis test results, rerun suites, and open the HTML verdict report inside VS Code.",
+  "description": "Review Themis test and generate artifacts, rerun suites, and open the HTML verdict report inside VS Code.",
   "version": "0.1.0-beta.0",
   "license": "MIT",
   "publisher": "vitron-ai",
@@ -29,7 +29,8 @@
     "onCommand:themis.runTests",
     "onCommand:themis.rerunFailed",
     "onCommand:themis.openHtmlReport",
-    "onCommand:themis.refreshResults"
+    "onCommand:themis.refreshResults",
+    "onCommand:themis.openArtifactFile"
   ],
   "contributes": {
     "viewsContainers": {
@@ -69,6 +70,11 @@
         "command": "themis.refreshResults",
         "title": "Themis: Refresh Results",
         "category": "Themis"
+      },
+      {
+        "command": "themis.openArtifactFile",
+        "title": "Themis: Open Artifact File",
+        "category": "Themis"
       }
     ],
     "menus": {