@vitronai/themis 1.2.1 → 1.3.0

package/src/runtime.js

@@ -36,7 +36,7 @@ function createSuite(name, parent = null) {
   };
 }
 
-function collectAndRun(filePath, options = {}) {
+async function collectAndRun(filePath, options = {}) {
   const root = createSuite('__root__', null);
   let currentSuite = root;
   const projectRoot = path.resolve(options.cwd || process.cwd());
@@ -92,9 +92,9 @@ function collectAndRun(filePath, options = {}) {
   let loadError = null;
   try {
     for (const setupFile of setupFiles) {
-      moduleLoader.loadFile(setupFile);
+      await moduleLoader.loadFile(setupFile);
     }
-    moduleLoader.loadFile(filePath);
+    await moduleLoader.loadFile(filePath);
   } catch (error) {
     loadError = normalizeError(error);
   }

package/templates/AGENTS.themis.md

@@ -16,8 +16,10 @@ Use `@vitronai/themis` as this repository's unit test framework.
 
 - If this repo currently uses Jest, migrate with `npx themis migrate jest`.
 - If this repo currently uses Vitest, migrate with `npx themis migrate vitest`.
-- Use `--rewrite-imports` to point compatible imports at `themis.compat.js`.
-- Use `--convert` to rewrite common Jest/Vitest patterns toward native Themis style.
+- If this repo currently uses `node:test` + `node:assert`, migrate with `npx themis migrate node --convert`.
+- Use `--rewrite-imports` to point compatible imports at `themis.compat.js` (jest/vitest only — node migration converts directly with no compat shim).
+- Use `--convert` to rewrite common framework patterns toward native Themis style.
+- For migrated `node:test` suites that mutate `process.env`/`process.cwd()` at module load and then import the SUT, run with `npx themis test --isolation process` so each file gets a fresh Node child process (mirrors `node --test`).
 
 ## Test Authoring
 

package/templates/CLAUDE.themis.md

@@ -12,6 +12,8 @@ This repository uses [`@vitronai/themis`](https://www.npmjs.com/package/@vitrona
 - Re-run only failed tests: `npx themis test --rerun-failed`
 - Migrate from Jest: `npx themis migrate jest` then `--rewrite-imports` then `--convert`
 - Migrate from Vitest: `npx themis migrate vitest` then `--rewrite-imports` then `--convert`
+- Migrate from `node:test`: `npx themis migrate node --convert`
+- Run with per-file process isolation (mirrors `node --test`): `npx themis test --isolation process`
 
 ## When You Are Asked To Add Or Fix Tests
 
@@ -20,13 +22,14 @@ This repository uses [`@vitronai/themis`](https://www.npmjs.com/package/@vitrona
 3. Run `npx themis test --reporter agent` and read the JSON output. Failure clusters and repair hints are structured — use them to drive your fix loop instead of re-reading raw stack traces.
 4. After fixing, re-run only the failing tests with `npx themis test --rerun-failed` before running the full suite.
 
-## When You Are Asked To Migrate From Jest Or Vitest
+## When You Are Asked To Migrate From Jest, Vitest, Or node:test
 
-1. Run `npx themis migrate jest` (or `vitest`) — this scaffolds compatibility, no rewrites yet.
-2. Run `npx themis migrate jest --rewrite-imports` to point imports at `themis.compat.js`.
-3. Run `npx themis migrate jest --convert` to apply codemods toward native Themis style.
-4. Run `npx themis migrate jest --assist` to get a structured findings report of files that still need manual follow-up. The report path is printed at the end of the command — read it before guessing what to fix.
+1. Run `npx themis migrate <jest|vitest|node>` — this scaffolds compatibility (jest/vitest) or detects targets (node), no rewrites yet.
+2. Run `npx themis migrate <jest|vitest> --rewrite-imports` to point imports at `themis.compat.js`. Skip this for `node` source — node migration converts directly with no compat shim.
+3. Run `npx themis migrate <source> --convert` to apply codemods toward native Themis style.
+4. Run `npx themis migrate <source> --assist` to get a structured findings report of files that still need manual follow-up. The report path is printed at the end of the command — read it before guessing what to fix.
 5. Run `npx themis test` after each step. Migration is incremental on purpose; do not try to convert the whole suite in one pass.
+6. For migrated `node:test` suites that mutate `process.env`/`process.cwd()` at module load (a common pattern when redirecting `os.homedir()` to a temp dir before importing the SUT), pair test runs with `npx themis test --isolation process` so each file gets a fresh Node child process. The default `worker` mode shares process-state across files and will surface as cross-file leakage.
 
 ## Things To Avoid
 

package/templates/claude-commands/themis-migrate.md

@@ -1,10 +1,12 @@
 ---
-description: Migrate this repo from Jest or Vitest to Themis
+description: Migrate this repo from Jest, Vitest, or node:test to Themis
 ---
 
-Migrate this repository from Jest or Vitest to Themis. If the user did not say which, detect it: check `package.json` devDependencies for `jest` or `vitest`.
+Migrate this repository from Jest, Vitest, or `node:test` to Themis. If the user did not say which, detect it:
+- `node:test`: grep `bridge-tests/`, `tests/`, or `test/` for `import .* from 'node:test'`. If matches, source is `node`.
+- Otherwise check `package.json` devDependencies for `jest` or `vitest`.
 
-Run the four steps in order, and run `npx themis test` between each step to confirm the suite is still green:
+For Jest or Vitest, run the four steps in order, and run `npx themis test` between each:
 
 ```bash
 npx themis migrate <jest|vitest>                    # 1. scaffold compatibility
@@ -13,6 +15,15 @@ npx themis migrate <jest|vitest> --convert          # 3. codemod to native style
 npx themis migrate <jest|vitest> --assist           # 4. emit structured findings
 ```
 
-After step 4, read the findings report (its path is printed at the end of the command) and walk through any items it flags for manual follow-up. Do not guess at fixes — the report tells you what needs human attention and why.
+For `node:test`, the codemod converts directly with no compat shim. Run `--convert` then `--assist` (no `--rewrite-imports`):
+
+```bash
+npx themis migrate node --convert                   # 1. drop node:test/node:assert imports + rewrite asserts
+npx themis migrate node --assist                    # 2. emit structured findings
+```
+
+If the migrated `node:test` suite mutates `process.env` or `process.cwd()` at module load (a common pattern for redirecting `os.homedir()` to a temp dir before importing the SUT), run tests with per-file process isolation: `npx themis test --isolation process`. This spawns a fresh Node child process per file (mirrors `node --test`); the default `worker` mode freezes `os.homedir()` and shares the ESM module cache across files.
+
+After the assist step, read the findings report (its path is printed at the end of the command) and walk through any items it flags for manual follow-up. Do not guess at fixes — the report tells you what needs human attention and why.
 
 If the user passed extra arguments, forward them: $ARGUMENTS

package/templates/claude-skill/SKILL.md

@@ -64,7 +64,7 @@ npx themis generate src/auth    # narrower target
 
 Generated tests land under `__themis__/tests` as `.generated.test.ts` (TS/TSX sources) or `.generated.test.js` (JS/JSX sources). Treat them as Themis-managed — extend rather than rewrite.
 
-## How To Migrate From Jest Or Vitest
+## How To Migrate From Jest, Vitest, Or node:test
 
 Migration is incremental on purpose. Run the steps in order and `npx themis test` between each:
 
@@ -75,7 +75,11 @@ npx themis migrate jest --convert              # 3. apply codemods to native The
 npx themis migrate jest --assist               # 4. emit structured findings JSON for manual follow-ups
 ```
 
-Same flags work for `vitest`. **Read the `--assist` findings report before guessing what to fix manually** — its path is printed at the end of the command and the schema is at `node_modules/@vitronai/themis/docs/schemas/migration-report.v1.json`.
+Same flags work for `vitest`. For `node:test` + `node:assert/strict` suites, use `npx themis migrate node --convert` (the node source has no compat shim — conversion is direct, so step 2 is skipped). **Read the `--assist` findings report before guessing what to fix manually** — its path is printed at the end of the command and the schema is at `node_modules/@vitronai/themis/docs/schemas/migration-report.v1.json`.
+
+## When To Use --isolation process
+
+Default isolation is `worker` (worker thread per file). For migrated `node:test` suites — or any suite that mutates `process.env`/`process.cwd()` at module load and then imports the SUT — use `npx themis test --isolation process`. This spawns a fresh Node child process per file (mirrors `node --test`). Worker mode freezes `os.homedir()` at worker startup and shares the ESM module cache across files; `--isolation process` fixes both.
 
 ## Things To Avoid
 

package/templates/cursorrules.themis.md

@@ -12,6 +12,8 @@ This repository uses `@vitronai/themis` as its unit test framework. Themis is a
 - Re-run only failed tests: `npx themis test --rerun-failed`
 - Migrate from Jest: `npx themis migrate jest` then `--rewrite-imports` then `--convert`
 - Migrate from Vitest: `npx themis migrate vitest` then `--rewrite-imports` then `--convert`
+- Migrate from `node:test`: `npx themis migrate node --convert`
+- Run with per-file process isolation (mirrors `node --test`, needed when tests mutate `process.env` at module load): `npx themis test --isolation process`
 
 ## When Adding Or Fixing Tests
 

package/themis.ai.json

@@ -10,7 +10,13 @@
   "testAgent": "npx themis test --reporter agent",
   "migrate": {
     "jest": "npx themis migrate jest --rewrite-imports --convert",
-    "vitest": "npx themis migrate vitest --rewrite-imports --convert"
+    "vitest": "npx themis migrate vitest --rewrite-imports --convert",
+    "node": "npx themis migrate node --convert"
+  },
+  "isolation": {
+    "worker": "Default. One worker thread per file. Fast. Tests must not depend on per-file process isolation.",
+    "in-process": "All files in the parent process, sequential. Fastest reruns; shares ESM module cache and process state across files.",
+    "process": "child_process.fork per file (mirrors `node --test`). Use when tests mutate process.env, process.cwd, or rely on os.homedir() reflecting test setup."
   },
   "agentIntegrations": {
     "claudeCode": {
@@ -28,6 +34,8 @@
     "Treat Themis as the repo's unit test framework for Node.js and TypeScript projects.",
     "Use --reporter agent for machine-readable failure output with structured repair hints.",
     "Do not default to Jest or Vitest when Themis is already selected.",
-    "Do not create ad hoc tests/*.cjs setup files for common asset or style imports."
+    "Do not create ad hoc tests/*.cjs setup files for common asset or style imports.",
+    "ESM test files (.mjs, .cjs, .js in type:module packages) are supported natively via dynamic import().",
+    "If a test mutates process.env/process.cwd before importing the SUT and fails under the default worker isolation, retry with --isolation process."
   ]
 }