@vitronai/themis 1.2.1 → 1.3.0

package/docs/api.md

@@ -28,7 +28,7 @@ For machine-readable agent adoption metadata, see [`themis.ai.json`](../themis.a
 themis test [options]
 themis init [--agents]
 themis generate [path]
-themis migrate <jest|vitest>
+themis migrate <jest|vitest|node>
 ```
 
 ## `themis init`
@@ -203,7 +203,7 @@ Migration options:
 | `--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. |
+| `--isolation worker\|in-process\|process` | string | Select isolation model. `worker` (default) = worker thread per file. `in-process` = sequential in the parent (fastest reruns; shares ESM cache + process state across files). `process` = `child_process.fork` per file, mirroring `node --test` (use when tests mutate `process.env`/`process.cwd()` at module load). |
 | `--cache` | flag | Enable file-level result caching for in-process local loops. |
 | `--update-contracts` | flag | Accept updated `captureContract(...)` baselines for the selected tests. |
 | `-w`, `--watch` | flag | Rerun the selected suite when watched project files change. |
@@ -219,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, migration mode details, assistant findings, and recommended next actions
+- `themis migrate <jest|vitest|node>` also emits `.themis/migration/migration-report.json` with detected files, migration mode details, assistant findings, and recommended next actions
 
 Additional option:
 
@@ -229,6 +229,7 @@ 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
+- `--isolation process` is required for tests that mutate `process.env`/`process.cwd()` at module load (matches `node --test`'s isolation model)
 - `--watch` is intended for short edit-run-review loops for both humans and AI agents
 
 Snapshot note:

package/docs/migration.md

@@ -1,4 +1,4 @@
-# Migrating From Jest And Vitest
+# Migrating From Jest, Vitest, And node:test
 
 Themis is designed for incremental migration. Start by running existing suites under the Themis runtime, then convert touched tests toward native contracts and `intent(...)` flows as you work.
 
@@ -12,14 +12,42 @@ npx themis migrate jest --assist
 npx themis test
 ```
 
-Use `vitest` instead of `jest` for Vitest suites.
+Use `vitest` for Vitest suites or `node` for `node:test` suites in place of `jest`.
 
 ## Migration modes
 
-- `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.
+- `themis migrate <jest|vitest|node>`: scaffold config and migration report. For `jest`/`vitest`, also writes a setup file and a compat bridge; `node` skips both (Themis provides the same globals natively).
+- `--rewrite-imports`: point framework imports at `themis.compat.js` (jest/vitest only — `node` source has no compat shim, conversion is direct).
+- `--convert`: remove common framework imports and rewrite matcher/test patterns into Themis-native forms.
+- `--assist`: run the safe rewrite and conversion passes together, then report leftover framework-specific helpers that still need manual follow-up.
+
+## node:test specifics
+
+`themis migrate node` handles the following transforms:
+
+| Input (node:test + node:assert/strict) | Output (Themis) |
+| --- | --- |
+| `import test from 'node:test'` | dropped (`test` is a Themis global) |
+| `import assert from 'node:assert/strict'` | dropped (`expect` replaces all asserts) |
+| `assert.equal(a, b)` / `strictEqual` | `expect(a).toBe(b)` |
+| `assert.deepEqual(a, b)` / `deepStrictEqual` | `expect(a).toEqual(b)` |
+| `assert.ok(v)` | `expect(v).toBeTruthy()` |
+| `assert.match(s, /re/)` | `expect(s).toMatch(/re/)` |
+| `await assert.rejects(fn, /re/)` | async try/catch wrapper + `toMatch` on the error message |
+| `test.after(fn)` / `test.afterEach(fn)` | `afterAll(fn)` / `afterEach(fn)` |
+| `test(name, { timeout }, fn)` | `test(name, fn)` (options arg silently dropped) |
+
+Not supported in this pass: `t.test()` subtests, `t.context`, `test.only`, `describe`/`it` exported from `node:test` (use Themis globals instead), `assert.throws`/`notEqual`/`fail`/`doesNotReject`, source-map line preservation. The optional 3rd-arg message string on `assert.equal`-family calls is silently dropped.
+
+## Process-state isolation
+
+`node:test` runs each test file in its own child process. If your suite mutates `process.env`, `process.cwd()`, or other process-level state at module load (e.g. `process.env.HOME = mkdtempSync(...)` before `await import('../dist/index.js')`), pair `themis test` with per-file process isolation:
+
+```bash
+npx themis test --isolation process
+```
+
+This spawns a fresh Node child process per test file via `child_process.fork`, mirroring `node --test`'s isolation model. The default `worker` mode shares process-state (especially `os.homedir()` cached at worker startup) across files and will surface as cross-file leakage for state-mutating tests.
 
 ## Before And After
 

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

@@ -12,7 +12,7 @@
     },
     "source": {
       "type": "string",
-      "enum": ["jest", "vitest"]
+      "enum": ["jest", "vitest", "node"]
     },
     "createdAt": {
       "type": "string"
@@ -35,6 +35,8 @@
         "jestGlobals",
         "vitest",
         "testingLibraryReact",
+        "nodeTest",
+        "nodeAssert",
         "rewrittenFiles",
         "rewrittenImports",
         "convertedFiles",
@@ -50,6 +52,8 @@
         "jestGlobals": { "type": "number" },
         "vitest": { "type": "number" },
         "testingLibraryReact": { "type": "number" },
+        "nodeTest": { "type": "number" },
+        "nodeAssert": { "type": "number" },
         "rewrittenFiles": { "type": "number" },
         "rewrittenImports": { "type": "number" },
         "convertedFiles": { "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,6 +1,6 @@
 {
   "name": "@vitronai/themis",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "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",
@@ -97,6 +97,8 @@
     "benchmark:first-try": "node scripts/benchmark-first-try.js",
     "benchmark:gate": "node scripts/benchmark-gate.js",
     "proof:migration": "node scripts/verify-migration-fixtures.js",
+    "proof:esm": "node scripts/verify-esm-fixtures.js",
+    "verify:dogfood": "node scripts/verify-alethia-bridge-dogfood.js",
     "pack:check": "npm pack --dry-run",
     "prepublishOnly": "npm run lint && npm test && npm run typecheck"
   },

package/src/cli.js

@@ -147,7 +147,11 @@ async function main(argv) {
       }
       console.log(`Report: ${formatCliPath(cwd, result.reportPath)}`);
     }
-    console.log('Runtime compatibility is enabled for @jest/globals, vitest, and @testing-library/react imports.');
+    if (result.source === 'node') {
+      console.log('node:test and node:assert imports are dropped during conversion; Themis provides test/expect/afterAll/afterEach as globals.');
+    } else {
+      console.log('Runtime compatibility is enabled for @jest/globals, vitest, and @testing-library/react imports.');
+    }
     console.log('Next: run npx themis test or npm run test:themis');
     return;
   }
@@ -778,10 +782,10 @@ function validateWorkerCount(flagValue, configValue) {
 }
 
 function validateIsolation(value) {
-  if (value === 'worker' || value === 'in-process') {
+  if (value === 'worker' || value === 'in-process' || value === 'process') {
     return;
   }
-  throw new Error(`Unsupported --isolation value: ${value}. Use one of: worker, in-process.`);
+  throw new Error(`Unsupported --isolation value: ${value}. Use one of: worker, in-process, process.`);
 }
 
 function resolveWorkerCount(flagValue, configValue) {
@@ -814,8 +818,8 @@ function printUsage() {
   console.log('  generate [path]         Scan source files and generate Themis contract tests');
   console.log('                         Options: [--json] [--plan] [--output path] [--files a,b] [--match-source regex] [--match-export regex] [--scenario name] [--min-confidence level] [--require-confidence level] [--include regex] [--exclude regex] [--review] [--update] [--clean] [--changed] [--force] [--strict] [--write-hints] [--fail-on-skips] [--fail-on-conflicts]');
   console.log('  scan [path]             Alias for generate');
-  console.log('  migrate <jest|vitest> [--rewrite-imports] [--convert] [--assist]   Scaffold an incremental migration bridge for existing suites');
-  console.log('  test [--json] [--agent] [--next] [--reporter spec|next|json|agent|html] [--workers N] [--stability N] [--environment node|jsdom] [--isolation worker|in-process] [--cache] [--update-contracts] [--fix] [-w|--watch] [--html-output path] [--match regex] [--rerun-failed] [--no-memes] [--lexicon classic|themis]');
+  console.log('  migrate <jest|vitest|node> [--rewrite-imports] [--convert] [--assist]   Scaffold an incremental migration bridge for existing suites');
+  console.log('  test [--json] [--agent] [--next] [--reporter spec|next|json|agent|html] [--workers N] [--stability N] [--environment node|jsdom] [--isolation worker|in-process|process] [--cache] [--update-contracts] [--fix] [-w|--watch] [--html-output path] [--match regex] [--rerun-failed] [--no-memes] [--lexicon classic|themis]');
 }
 
 function printGenerateSummary(summary, cwd) {

package/src/config.js

@@ -5,7 +5,7 @@ const os = require('os');
 const DEFAULT_CONFIG = {
   testDir: 'tests',
   generatedTestsDir: path.join('__themis__', 'tests'),
-  testRegex: '\\.(test|spec)\\.(js|jsx|ts|tsx)$',
+  testRegex: '\\.(test|spec)\\.(js|jsx|ts|tsx|mjs|cjs)$',
   maxWorkers: Math.max(1, os.cpus().length - 1),
   reporter: 'next',
   environment: 'node',

package/src/expect.js

@@ -70,6 +70,24 @@ function createExpect(_context = {}) {
 
         throw new Error('toContain only supports strings and arrays');
       },
+      toMatch(expected) {
+        if (typeof received !== 'string') {
+          throw new Error(`toMatch expects a string, received ${format(received)}`);
+        }
+        if (typeof expected === 'string') {
+          if (!received.includes(expected)) {
+            throw new Error(`Expected ${format(received)} to match substring ${format(expected)}`);
+          }
+          return;
+        }
+        if (expected instanceof RegExp) {
+          if (!expected.test(received)) {
+            throw new Error(`Expected ${format(received)} to match ${String(expected)}`);
+          }
+          return;
+        }
+        throw new Error('toMatch expects a string or RegExp');
+      },
       toThrow(match) {
         if (typeof received !== 'function') {
           throw new Error('toThrow expects a function');