@vitronai/themis 0.1.15 → 1.2.2

package/docs/agents-adoption.md

@@ -11,6 +11,8 @@ npx themis generate <source-root>
 npx themis test
 ```
 
+If you use Claude Code, run `npx themis init --claude-code` instead (or in addition) — see [Claude Code One-Command Setup](#claude-code-one-command-setup) below.
+
 What those commands do:
 
 - `npm install -D @vitronai/themis`: installs Themis as the repo's unit test framework
@@ -62,6 +64,72 @@ Prefer `test(...)` for low-level unit checks.
 Do not claim Themis is "not a unit test framework".
 ```
 
+## Claude Code One-Command Setup
+
+If you use Claude Code, Themis can install everything Claude needs in one command:
+
+```bash
+npm install -D @vitronai/themis@latest
+npx themis init --claude-code
+```
+
+`init --claude-code` writes:
+
+- `CLAUDE.md` — adoption rules at the repo root. If a `CLAUDE.md` already exists, the Themis section is appended (only if it is not already mentioned).
+- `.claude/skills/themis/SKILL.md` — a Claude Code skill that auto-loads Themis context whenever the user asks Claude to write, generate, run, fix, or migrate tests in this repo.
+- `.claude/commands/themis-test.md` — `/themis-test` slash command for the agent-readable test loop.
+- `.claude/commands/themis-generate.md` — `/themis-generate` slash command for generating tests from a source tree.
+- `.claude/commands/themis-migrate.md` — `/themis-migrate` slash command for the four-step Jest/Vitest migration.
+- `.claude/commands/themis-fix.md` — `/themis-fix` slash command for the structured failure-fix loop.
+
+You can compose `--claude-code` with `--agents` to install both at once:
+
+```bash
+npx themis init --agents --claude-code
+```
+
+The skill and slash commands are committed to the repo (under `.claude/`), so every developer or agent that opens the project sees them. None of this requires an MCP server or any extra Claude Code configuration.
+
+### Why this matters
+
+The `--reporter agent` JSON output is the killer feature for Claude Code's edit-test-fix loop: structured failure clusters with `repairHints` mean Claude can act on parsed signals instead of re-parsing stack traces. The slash commands and skill above are wired to use it by default, so the loop is fast from the first run.
+
+### Optional: Wire Themis Into Claude Code's Edit Loop With A Hook
+
+If you want Claude Code to *automatically* run Themis after every edit and feed structured failures back into the conversation, add a `PostToolUse` hook. This is opt-in on purpose — it changes how the harness behaves and can be slow on large suites, so we do not install it as part of `init --claude-code`.
+
+Add this to `.claude/settings.json` (or `.claude/settings.local.json` if you want to keep it personal and out of git):
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node node_modules/@vitronai/themis/scripts/claude-hook.js"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Then run `npx themis init --claude-code` (or copy the script manually). The wrapper does three things to keep the loop tight:
+
+1. **Filters non-source edits.** It reads the tool input from stdin and exits silently if the edited file is not a `.js`, `.jsx`, `.ts`, or `.tsx` source file. Edits to docs, config, and tests themselves do not trigger a re-run.
+2. **Prefers `--rerun-failed`.** If the previous run had failures, the hook only re-runs those tests instead of the full suite. The first failure-free run resets the loop.
+3. **Returns agent-readable output.** Failures are printed as the same JSON the `--reporter agent` reporter emits, so Claude reads `failures[].cluster` and `failures[].repairHints` directly without re-parsing stack traces.
+
+**Trade-offs to know about:**
+
+- The hook adds the suite's wall-clock time to every edit. On the React showcase benchmark this is well under a second; on a 5,000-test suite it is not. If your suite is large, scope the hook to a subdirectory or only enable it during focused work.
+- Hooks run shell commands with your privileges. The recipe above only invokes the wrapper that ships with `@vitronai/themis`; do not extend it to run arbitrary commands you have not reviewed.
+- To disable temporarily, comment out the entry in `.claude/settings.json` or move it to `.claude/settings.local.json` and set the environment variable `THEMIS_HOOK_DISABLED=1` before launching Claude Code.
+
 ## Notes
 
 - Themis is a unit test framework and test generator for Node.js and TypeScript projects.

package/docs/api.md

@@ -191,6 +191,7 @@ Migration options:
 
 - `--rewrite-imports`: rewrites matched imports from `@jest/globals`, `vitest`, and `@testing-library/react` to the local `themis.compat.js` bridge
 - `--convert`: removes common framework imports and rewrites common Jest/Vitest matcher patterns (`it`, `toStrictEqual`, `toContainEqual`, `toBeCalled*`) into Themis-native forms
+- `--assist`: enables `--rewrite-imports` and `--convert`, then scans migrated files for leftover framework-only helpers or matcher chains that still need manual follow-up
 
 ## `themis test` options
 
@@ -218,7 +219,7 @@ 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/migration-report.json` with detected files and recommended next actions
+- `themis migrate <jest|vitest>` also emits `.themis/migration/migration-report.json` with detected files, migration mode details, assistant findings, and recommended next actions
 
 Additional option:
 
@@ -280,6 +281,7 @@ Formal schemas:
 - `docs/schemas/fix-handoff.v1.json`
 - `docs/schemas/failures.v1.json`
 - `docs/schemas/contract-diff.v1.json`
+- `docs/schemas/migration-report.v1.json`
 
 Human-facing artifact:
 

package/docs/migration.md

@@ -8,6 +8,7 @@ Themis is designed for incremental migration. Start by running existing suites u
 npx themis migrate jest
 npx themis migrate jest --rewrite-imports
 npx themis migrate jest --convert
+npx themis migrate jest --assist
 npx themis test
 ```
 
@@ -18,6 +19,7 @@ Use `vitest` instead of `jest` for Vitest suites.
 - `themis migrate <jest|vitest>`: scaffold config, setup, compat bridge, and migration report.
 - `--rewrite-imports`: point framework imports at `themis.compat.js`.
 - `--convert`: remove common Jest/Vitest imports and rewrite common matcher/test patterns into Themis-native forms.
+- `--assist`: run the safe rewrite and conversion passes together, then report leftover Jest/Vitest-only helpers that still need manual follow-up.
 
 ## Before And After
 
@@ -154,14 +156,16 @@ These are the strongest head-to-head examples to use when explaining why Themis
 
 1. Snapshot replacement: `captureContract(...)` plus `--update-contracts` gives baseline capture without snapshot churn.
 2. Codemod migration: `themis migrate --convert` moves common Jest/Vitest matcher syntax toward native Themis without a manual rewrite pass.
-3. Agent triage: `--agent`, `.themis/diffs/run-diff.json`, `.themis/runs/fix-handoff.json`, and `.themis/diffs/contract-diff.json` give machines structured rerun and repair inputs.
-4. Human review: next reporter and HTML report now surface contract drift alongside failures, instead of burying meaning in raw output.
-5. Generated coverage: `themis generate src` adds source-driven contract tests next to migrated suites, so adoption improves coverage instead of merely changing runners.
+3. Migration assistant: `themis migrate --assist` bundles the safe codemods and emits findings for files that still need manual migration work.
+4. Agent triage: `--agent`, `.themis/diffs/run-diff.json`, `.themis/runs/fix-handoff.json`, and `.themis/diffs/contract-diff.json` give machines structured rerun and repair inputs.
+5. Human review: next reporter and HTML report now surface contract drift alongside failures, instead of burying meaning in raw output.
+6. Generated coverage: `themis generate src` adds source-driven contract tests next to migrated suites, so adoption improves coverage instead of merely changing runners.
 
 ## Recommended rollout
 
 1. Run `themis migrate <jest|vitest>`.
 2. Add `--rewrite-imports` if you want local explicit compat imports.
 3. Add `--convert` to normalize the easy matcher/import cases immediately.
-4. Replace snapshots with `captureContract(...)` or explicit assertions in files you touch.
-5. Use `themis generate src` to add source-driven coverage in parallel with migrated suites.
+4. Add `--assist` when you want a guided follow-up report for leftover framework-only helpers.
+5. Replace snapshots with `captureContract(...)` or explicit assertions in files you touch.
+6. Use `themis generate src` to add source-driven coverage in parallel with migrated suites.

package/docs/roadmap.md

@@ -6,7 +6,7 @@
    - Add documentation (and optionally VS Code actions) that show how to hook a project-level `themis.generate.js` or `.themis.json` provider configuration for shared auth/session/React Query clients.
 
 2. **Migration helpers**
-   - Improve `themis migrate` to rewrite Jest/Vitest imports to the generated compatibility module, create prompt-ready diff artifacts, and log a migration report.
+   - Improve `themis migrate` to rewrite Jest/Vitest imports to the generated compatibility module, create prompt-ready diff artifacts, log a migration report, and highlight leftover blockers through migration assistant follow-up hints.
    - Build a VS Code pane or CLI summary showing both the original Jest test and the new generated Themis contract, highlighting the migration delta in code and behavior.
    - Provide a recipe in `docs/migration.md` for teams to adopt Themis incrementally, including a helper to wrap Jest tests inside Themis-generated asserts.
    - Add a native contract-capture workflow that gives teams snapshot-comparable baseline coverage without reviving snapshot-file maintenance.

package/docs/schemas/migration-report.v1.json

@@ -0,0 +1,122 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/vitron-ai/themis/docs/schemas/migration-report.v1.json",
+  "title": "Themis Migration Report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "source", "createdAt", "mode", "summary", "files", "nextActions", "rewrites", "conversions", "assistant"],
+  "properties": {
+    "schema": {
+      "type": "string",
+      "const": "themis.migration.report.v1"
+    },
+    "source": {
+      "type": "string",
+      "enum": ["jest", "vitest"]
+    },
+    "createdAt": {
+      "type": "string"
+    },
+    "mode": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["rewriteImports", "convert", "assist"],
+      "properties": {
+        "rewriteImports": { "type": "boolean" },
+        "convert": { "type": "boolean" },
+        "assist": { "type": "boolean" }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "matchedFiles",
+        "jestGlobals",
+        "vitest",
+        "testingLibraryReact",
+        "rewrittenFiles",
+        "rewrittenImports",
+        "convertedFiles",
+        "convertedAssertions",
+        "removedImports",
+        "assistedFiles",
+        "unresolvedFiles",
+        "findings",
+        "unsupportedPatterns"
+      ],
+      "properties": {
+        "matchedFiles": { "type": "number" },
+        "jestGlobals": { "type": "number" },
+        "vitest": { "type": "number" },
+        "testingLibraryReact": { "type": "number" },
+        "rewrittenFiles": { "type": "number" },
+        "rewrittenImports": { "type": "number" },
+        "convertedFiles": { "type": "number" },
+        "convertedAssertions": { "type": "number" },
+        "removedImports": { "type": "number" },
+        "assistedFiles": { "type": "number" },
+        "unresolvedFiles": { "type": "number" },
+        "findings": { "type": "number" },
+        "unsupportedPatterns": { "type": "number" }
+      }
+    },
+    "files": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["file", "imports"],
+        "properties": {
+          "file": { "type": "string" },
+          "imports": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        }
+      }
+    },
+    "nextActions": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "rewrites": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "conversions": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "assistant": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["enabled", "analyzedFiles", "findings", "unresolvedFiles", "unsupportedPatterns"],
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "analyzedFiles": { "type": "number" },
+        "findings": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["file", "category", "severity", "pattern", "message", "suggestion"],
+            "properties": {
+              "file": { "type": "string" },
+              "category": { "type": "string" },
+              "severity": { "type": "string" },
+              "pattern": { "type": "string" },
+              "message": { "type": "string" },
+              "suggestion": { "type": "string" }
+            }
+          }
+        },
+        "unresolvedFiles": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "unsupportedPatterns": { "type": "number" }
+      }
+    }
+  }
+}

package/docs/tutorial-claude-code.md

@@ -0,0 +1,230 @@
+# Testing With Claude Code and Themis
+
+A step-by-step walkthrough showing how Themis turns Claude Code into a test-writing machine that gets it right on the first try.
+
+## The Problem
+
+When you ask Claude Code to write unit tests, it reaches for Jest or Vitest by default. The tests it generates are often correct, but just as often they have subtle issues: wrong import paths, misused mocking APIs, snapshot tests where assertions would be better, setup files where the framework handles things natively. You end up in an edit-test-fix loop that burns time and context window.
+
+Themis fixes this by shipping structured guidance directly to Claude Code — a skill, slash commands, and a `CLAUDE.md` that tells Claude exactly how to write, run, and fix tests. No copy-pasting docs. No explaining the framework. Claude just knows.
+
+## What You'll See
+
+By the end of this tutorial you'll have:
+
+1. A Node.js project with Themis installed and Claude Code fully wired up
+2. Generated tests that pass on the first run
+3. A structured failure-fix loop where Claude reads machine-parseable repair hints instead of raw stack traces
+4. Slash commands (`/themis-test`, `/themis-generate`, `/themis-fix`) that work out of the box
+
+## Step 1: Set Up a Project
+
+Start with any Node.js or TypeScript project. For this tutorial we'll use a small utility library.
+
+```bash
+mkdir demo-project && cd demo-project
+npm init -y
+```
+
+Create a source file at `src/cart.js`:
+
+```js
+class Cart {
+  constructor() {
+    this.items = [];
+  }
+
+  add(item) {
+    if (!item || !item.name || typeof item.price !== 'number') {
+      throw new TypeError('Item must have a name and a numeric price');
+    }
+    const existing = this.items.find((i) => i.name === item.name);
+    if (existing) {
+      existing.quantity += item.quantity || 1;
+    } else {
+      this.items.push({ ...item, quantity: item.quantity || 1 });
+    }
+  }
+
+  remove(name) {
+    const index = this.items.findIndex((i) => i.name === name);
+    if (index === -1) throw new Error(`Item "${name}" not in cart`);
+    this.items.splice(index, 1);
+  }
+
+  total() {
+    return this.items.reduce((sum, item) => sum + item.price * item.quantity, 0);
+  }
+
+  checkout(paymentMethod) {
+    if (this.items.length === 0) throw new Error('Cannot checkout an empty cart');
+    const receipt = {
+      items: this.items.map((i) => ({ ...i })),
+      total: this.total(),
+      paymentMethod,
+      timestamp: new Date().toISOString()
+    };
+    this.items = [];
+    return receipt;
+  }
+}
+
+module.exports = { Cart };
+```
+
+## Step 2: Install Themis With Claude Code Integration
+
+```bash
+npm install -D @vitronai/themis@latest
+npx themis init --claude-code
+```
+
+That one command installs:
+
+- `CLAUDE.md` — adoption rules at the repo root that Claude Code reads automatically
+- `.claude/skills/themis/SKILL.md` — a skill that auto-loads when Claude sees a test-related request
+- `.claude/commands/themis-test.md` — `/themis-test` slash command
+- `.claude/commands/themis-generate.md` — `/themis-generate` slash command
+- `.claude/commands/themis-migrate.md` — `/themis-migrate` slash command
+- `.claude/commands/themis-fix.md` — `/themis-fix` slash command
+
+You can verify:
+
+```bash
+cat CLAUDE.md          # Themis adoption rules
+ls .claude/skills/     # themis/SKILL.md
+ls .claude/commands/   # four slash command files
+```
+
+## Step 3: Generate Tests
+
+Open Claude Code in the project and type:
+
+```
+/themis-generate src
+```
+
+Claude uses the installed skill context to run `npx themis generate src`. Generated tests land under `__themis__/tests/` as `.generated.test.js` files. These are deterministic, contract-style tests — not LLM-generated guesses.
+
+## Step 4: Run the Test Loop
+
+```
+/themis-test
+```
+
+This runs `npx themis test --reporter agent` and Claude reads the structured JSON output. If everything passes, you're done. If there are failures, Claude sees:
+
+```json
+{
+  "failures": [
+    {
+      "cluster": "cart-checkout-validation",
+      "repairHints": ["checkout() throws when cart is empty — test passes an empty cart but expects success"],
+      "sourceFile": "src/cart.js",
+      "lineNumber": 32,
+      "expected": "Error: Cannot checkout an empty cart",
+      "actual": "{ items: [], total: 0 }"
+    }
+  ]
+}
+```
+
+Instead of re-reading a raw stack trace, Claude acts on the `repairHints` directly. This is the key difference: structured signals instead of unstructured error output.
+
+## Step 5: Ask Claude to Write More Tests
+
+Now ask Claude to add coverage for edge cases:
+
+```
+Write additional tests for the Cart class covering:
+- adding duplicate items increments quantity
+- removing a non-existent item throws
+- checkout clears the cart
+- total with no items returns 0
+```
+
+Because the Themis skill is loaded, Claude will:
+
+1. Use `intent(...)` for behavior tests and `test(...)` for pure unit checks
+2. Follow the four-phase shape: context, run, verify, cleanup
+3. Use `expect(...)` assertions (not snapshots)
+4. Place tests alongside the generated ones, not in a random `tests/` directory
+
+Run `/themis-test` again to verify.
+
+## Step 6: Fix Failures (When They Happen)
+
+If any test fails, use:
+
+```
+/themis-fix
+```
+
+Claude will:
+
+1. Run `npx themis test --reporter agent` to get the current failures
+2. Group failures by `cluster` — fixes within a cluster share a root cause
+3. Read `repairHints` before looking at the stack trace
+4. Apply the smallest fix that addresses the root cause
+5. Re-run with `--rerun-failed` to confirm the fix without running the full suite
+
+This cluster-based fixing is faster than fixing tests one at a time, and the `--rerun-failed` flag means you don't pay the cost of a full suite run after each fix.
+
+## Step 7: Optional — Wire Up the Automated Hook
+
+For the tightest possible loop, add a PostToolUse hook that runs Themis automatically after every edit Claude makes:
+
+Add this to `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node node_modules/@vitronai/themis/scripts/claude-hook.js"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Now every time Claude edits a `.js`/`.ts`/`.jsx`/`.tsx` file, Themis runs automatically. If tests fail, the structured failure JSON is fed back into the conversation — Claude sees it immediately and can fix it in the next turn without you running anything.
+
+The hook is smart about scope:
+
+- Skips non-source edits (docs, config, etc.)
+- Uses `--rerun-failed` when there's a prior failure artifact
+- Exits silently when tests pass (no context noise)
+- Set `THEMIS_HOOK_DISABLED=1` to pause it temporarily
+
+## Why This Works
+
+The magic is not in Themis being a better test runner (though it is faster). The magic is in the **structured agent context**:
+
+1. **The skill** tells Claude exactly when and how to use Themis — it auto-loads without you mentioning the framework
+2. **The CLAUDE.md** provides rules about what to avoid (no setup shims, no snapshots as defaults, no ad-hoc test directories)
+3. **The `--reporter agent` output** gives Claude machine-parseable failure data with repair hints, instead of raw stack traces it has to re-parse
+4. **The slash commands** encode the correct workflow so Claude doesn't have to figure out which flags to pass
+
+In Tessl evaluations across 10 scenarios, agents scored **37% without** the Themis skill context and **97% with it**. The context is the product.
+
+## What's Next
+
+- **Migrate from Jest or Vitest**: Run `/themis-migrate` — Claude walks through the four-step incremental migration
+- **Cursor users**: Run `npx themis init --cursor` to install `.cursorrules`
+- **Both at once**: `npx themis init --agents --claude-code --cursor`
+- **Auto-detection**: A bare `npx themis init` detects which agents are present and installs the right assets automatically
+
+## Links
+
+- npm: [`@vitronai/themis`](https://www.npmjs.com/package/@vitronai/themis)
+- GitHub: [vitron-ai/themis](https://github.com/vitron-ai/themis)
+- Tessl tile: [vitron-ai/themis](https://tessl.io/registry/vitron-ai/themis)
+- Eval results: [37% baseline → 97% with skill](https://tessl.io/eval-runs/019d72a0-8211-74ea-84ef-a8e336ead3d2)
+- Adoption guide: [`docs/agents-adoption.md`](agents-adoption.md)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vitronai/themis",
-  "version": "0.1.15",
-  "description": "Intent-first unit test framework and test generator for AI agents in Node.js and TypeScript",
+  "version": "1.2.2",
+  "description": "A Node.js and TypeScript unit test framework designed for AI coding agents. Drop-in alternative to Jest and Vitest with machine-readable failure output, structured repair hints, and one-command migration.",
   "license": "MIT",
   "author": "Vitron AI",
   "repository": {
@@ -23,6 +23,10 @@
     "agents",
     "ai-agents",
     "agentic",
+    "claude-code",
+    "cursor",
+    "codex",
+    "ai-coding",
     "jest-alternative",
     "vitest-alternative",
     "nodejs",
@@ -68,6 +72,7 @@
     "src/assets/*",
     "docs",
     "templates",
+    "scripts/claude-hook.js",
     "index.js",
     "index.d.ts",
     "globals.js",
@@ -89,6 +94,7 @@
     "typecheck": "tsc -p tsconfig.json --pretty false",
     "benchmark": "node scripts/benchmark.js",
     "benchmark:showcase": "node scripts/benchmark-showcase-runners.js",
+    "benchmark:first-try": "node scripts/benchmark-first-try.js",
     "benchmark:gate": "node scripts/benchmark-gate.js",
     "proof:migration": "node scripts/verify-migration-fixtures.js",
     "pack:check": "npm pack --dry-run",