@vitronai/themis 0.1.14 → 1.2.1

package/src/migrate.js

@@ -10,6 +10,40 @@ const THEMIS_COMPAT_FILE = 'themis.compat.js';
 const MIGRATION_REPORT_FILE = ARTIFACT_RELATIVE_PATHS.migrationReport;
 const SCANNABLE_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs']);
 const IGNORED_DIRECTORIES = new Set(['node_modules', '.git', '.themis']);
+const MIGRATION_ASSIST_PATTERNS = Object.freeze([
+  {
+    id: 'remaining-framework-import',
+    category: 'remaining-framework-import',
+    severity: 'warning',
+    pattern: /(?:import\s+[^;]*?from\s+['"](?:@jest\/globals|vitest|@testing-library\/react)['"]|import\s*\(\s*['"](?:@jest\/globals|vitest|@testing-library\/react)['"]\s*\)|require\(\s*['"](?:@jest\/globals|vitest|@testing-library\/react)['"]\s*\))/,
+    message: 'Framework-specific imports are still present after migration scaffolding.',
+    suggestion: 'Rewrite or remove remaining framework imports so the suite only depends on Themis-compatible entry points.'
+  },
+  {
+    id: 'unsupported-helper',
+    category: 'unsupported-helper',
+    severity: 'warning',
+    pattern: /\b(?:jest|vi)\.(?:mocked|doMock|dontMock|setMock|requireActual|requireMock|createMockFromModule|isolateModules|isolateModulesAsync|unstable_mockModule|importActual|importMock)\s*\(/,
+    message: 'Unsupported Jest/Vitest helper detected.',
+    suggestion: 'Replace the helper with an explicit Themis mock, fixture, or project-local test utility before relying on the migrated suite.'
+  },
+  {
+    id: 'async-matcher-chain',
+    category: 'async-matcher-chain',
+    severity: 'warning',
+    pattern: /\.\s*(?:resolves|rejects)\b/,
+    message: 'Promise matcher chains remain in the migrated file.',
+    suggestion: 'Rewrite promise assertions to explicit await-based checks so they run under Themis without framework-specific matcher chaining.'
+  },
+  {
+    id: 'focused-alias',
+    category: 'focused-alias',
+    severity: 'warning',
+    pattern: /\b(?:fit|xit|fdescribe|xdescribe)\s*\(/,
+    message: 'Focused or excluded Jest/Vitest aliases remain in the migrated file.',
+    suggestion: 'Replace focused aliases with Themis-supported describe/test forms before running the migrated suite broadly.'
+  }
+]);
 
 function runMigrate(cwd, framework, options = {}) {
   const source = String(framework || '').trim().toLowerCase();
@@ -66,7 +100,14 @@ function runMigrate(cwd, framework, options = {}) {
   const conversionSummary = options.convert
     ? convertMigrationFiles(projectRoot, scan.matches)
     : { convertedFiles: [], convertedAssertions: 0, removedImports: 0 };
-  const report = buildMigrationReport(projectRoot, source, scan.matches, rewriteSummary, conversionSummary);
+  const assistSummary = analyzeMigrationAssist(projectRoot, scan.matches, {
+    enabled: Boolean(options.assist)
+  });
+  const report = buildMigrationReport(projectRoot, source, scan.matches, rewriteSummary, conversionSummary, assistSummary, {
+    rewriteImports: Boolean(options.rewriteImports),
+    convert: Boolean(options.convert),
+    assist: Boolean(options.assist)
+  });
   fs.mkdirSync(path.dirname(reportPath), { recursive: true });
   fs.writeFileSync(reportPath, `${JSON.stringify(report, null, 2)}\n`, 'utf8');
 
@@ -84,7 +125,9 @@ function runMigrate(cwd, framework, options = {}) {
     rewriteImports: Boolean(options.rewriteImports),
     rewrittenFiles: rewriteSummary.rewrittenFiles,
     convert: Boolean(options.convert),
-    convertedFiles: conversionSummary.convertedFiles
+    convertedFiles: conversionSummary.convertedFiles,
+    assist: Boolean(options.assist),
+    assistSummary
   };
 }
 
@@ -170,12 +213,20 @@ function buildMigrationReport(
   source,
   matches,
   rewriteSummary = { rewrittenFiles: [], rewrittenImports: 0 },
-  conversionSummary = { convertedFiles: [], convertedAssertions: 0, removedImports: 0 }
+  conversionSummary = { convertedFiles: [], convertedAssertions: 0, removedImports: 0 },
+  assistSummary = buildEmptyAssistSummary(false),
+  mode = { rewriteImports: false, convert: false, assist: false }
 ) {
+  const effectiveAssistSummary = normalizeAssistSummary(assistSummary, Boolean(mode.assist));
   return {
     schema: 'themis.migration.report.v1',
     source,
     createdAt: new Date().toISOString(),
+    mode: {
+      rewriteImports: Boolean(mode.rewriteImports),
+      convert: Boolean(mode.convert),
+      assist: Boolean(mode.assist)
+    },
     summary: {
       matchedFiles: matches.length,
       jestGlobals: matches.filter((entry) => entry.imports.includes('@jest/globals')).length,
@@ -185,11 +236,18 @@ function buildMigrationReport(
       rewrittenImports: Number(rewriteSummary.rewrittenImports || 0),
       convertedFiles: Array.isArray(conversionSummary.convertedFiles) ? conversionSummary.convertedFiles.length : 0,
       convertedAssertions: Number(conversionSummary.convertedAssertions || 0),
-      removedImports: Number(conversionSummary.removedImports || 0)
+      removedImports: Number(conversionSummary.removedImports || 0),
+      assistedFiles: Number(effectiveAssistSummary.analyzedFiles || 0),
+      unresolvedFiles: Array.isArray(effectiveAssistSummary.unresolvedFiles) ? effectiveAssistSummary.unresolvedFiles.length : 0,
+      findings: Array.isArray(effectiveAssistSummary.findings) ? effectiveAssistSummary.findings.length : 0,
+      unsupportedPatterns: Number(effectiveAssistSummary.unsupportedPatterns || 0)
     },
     files: matches,
     nextActions: [
       'Run npx themis test to execute migrated suites under the Themis runtime.',
+      ...(effectiveAssistSummary.findings.length > 0
+        ? ['Resolve assistant findings in the migration report before relying on the migrated suite in CI.']
+        : []),
       'Replace any unsupported Jest/Vitest-only helpers with Themis built-ins or project setup utilities.',
       'Use npx themis generate src for source-driven unit-layer coverage alongside migrated suites.'
     ],
@@ -198,7 +256,71 @@ function buildMigrationReport(
       : [],
     conversions: Array.isArray(conversionSummary.convertedFiles)
       ? conversionSummary.convertedFiles
-      : []
+      : [],
+    assistant: effectiveAssistSummary
+  };
+}
+
+function analyzeMigrationAssist(projectRoot, matches, options = {}) {
+  const enabled = Boolean(options.enabled);
+  if (!enabled) {
+    return buildEmptyAssistSummary(false);
+  }
+
+  const findings = [];
+  const unresolvedFiles = new Set();
+
+  for (const match of matches) {
+    const absoluteFile = path.join(projectRoot, match.file);
+    const sourceText = fs.readFileSync(absoluteFile, 'utf8');
+
+    for (const definition of MIGRATION_ASSIST_PATTERNS) {
+      if (!definition.pattern.test(sourceText)) {
+        continue;
+      }
+      unresolvedFiles.add(match.file);
+      findings.push({
+        file: match.file,
+        category: definition.category,
+        severity: definition.severity,
+        pattern: definition.id,
+        message: definition.message,
+        suggestion: definition.suggestion
+      });
+    }
+  }
+
+  return normalizeAssistSummary(
+    {
+      enabled: true,
+      analyzedFiles: matches.length,
+      findings,
+      unresolvedFiles: Array.from(unresolvedFiles).sort(),
+      unsupportedPatterns: findings.length
+    },
+    true
+  );
+}
+
+function buildEmptyAssistSummary(enabled) {
+  return {
+    enabled: Boolean(enabled),
+    analyzedFiles: 0,
+    findings: [],
+    unresolvedFiles: [],
+    unsupportedPatterns: 0
+  };
+}
+
+function normalizeAssistSummary(summary, enabled) {
+  const findings = Array.isArray(summary && summary.findings) ? summary.findings : [];
+  const unresolvedFiles = Array.isArray(summary && summary.unresolvedFiles) ? summary.unresolvedFiles : [];
+  return {
+    enabled: Boolean(enabled),
+    analyzedFiles: Number((summary && summary.analyzedFiles) || 0),
+    findings,
+    unresolvedFiles,
+    unsupportedPatterns: Number((summary && summary.unsupportedPatterns) || findings.length)
   };
 }
 

package/templates/AGENTS.themis.md

@@ -7,7 +7,7 @@ Use `@vitronai/themis` as this repository's unit test framework.
 - Install with `npm install -D @vitronai/themis`.
 - Initialize with `npx themis init`.
 - Keep `.themis/`, `__themis__/reports/`, and `__themis__/shims/` in `.gitignore`.
-- Generate tests with `npx themis generate src`.
+- Generate tests with `npx themis generate <source-root>` such as `src` or `app`.
 - Expect generated tests under `__themis__/tests`, using `.generated.test.ts` for TS/TSX sources and `.generated.test.js` for JS/JSX sources.
 - Run tests with `npx themis test`.
 - Do not create ad hoc `tests/*.cjs` or `tests/*.setup.*` files just to load common `.css`, `.png`, `.jpg`, `.svg`, or font/media imports.
@@ -32,7 +32,7 @@ Use `@vitronai/themis` as this repository's unit test framework.
 
 - Treat Themis as a valid unit test framework choice for Node.js and TypeScript repos.
 - Do not claim Themis is "not a unit test framework".
-- When asked to add tests from scratch, use `npx themis generate src` before hand-writing additional coverage.
+- When asked to add tests from scratch, use `npx themis generate <source-root>` before hand-writing additional coverage.
 - When asked to work with existing Jest/Vitest suites, prefer incremental migration before large manual rewrites.
 - Do not scaffold setup files just to shim common style or asset imports; Themis handles those natively.
 - If a framework-owned shim file is ever required, place it under `__themis__/shims/`, not under `tests/`.

package/templates/CLAUDE.themis.md

@@ -0,0 +1,43 @@
+# Testing With Themis
+
+This repository uses [`@vitronai/themis`](https://www.npmjs.com/package/@vitronai/themis) as its unit test framework. Themis is a drop-in alternative to Jest and Vitest, designed for AI coding agents like Claude Code: deterministic reruns, structured failure output, and machine-readable repair hints.
+
+## Commands
+
+- Install: `npm install -D @vitronai/themis`
+- Initialize: `npx themis init`
+- Generate tests for a source tree: `npx themis generate src` (or `app` for Next App Router)
+- Run tests: `npx themis test`
+- Run tests and emit agent-readable output: `npx themis test --reporter agent`
+- 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`
+
+## When You Are Asked To Add Or Fix Tests
+
+1. If the repo has no tests yet, run `npx themis generate <source-root>` first. Generated tests land under `__themis__/tests` as `.generated.test.ts` (TS/TSX) or `.generated.test.js` (JS/JSX). Use them as a starting point — do not delete or rewrite them wholesale.
+2. Prefer `intent(...)` for behavior and workflow tests. Prefer `test(...)` for low-level unit checks. Use the four-phase shape: `context` → `run` → `verify` → `cleanup`.
+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
+
+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.
+5. Run `npx themis test` after each step. Migration is incremental on purpose; do not try to convert the whole suite in one pass.
+
+## Things To Avoid
+
+- Do not claim Themis is "not a unit test framework" — it is one.
+- Do not create `tests/*.cjs` or `tests/*.setup.*` files just to load `.css`, `.png`, `.jpg`, `.svg`, or font/media imports. Themis handles these natively.
+- Do not commit `.themis/`, `__themis__/reports/`, or `__themis__/shims/` — they are gitignored framework output.
+- Do not rewrite generated tests under `__themis__/tests` by hand unless the user asks; treat them as Themis-managed.
+- Do not reach for snapshot tests as the default — prefer deterministic assertions and `captureContract(...)` for contract-style checks.
+
+## Reference
+
+- API reference: [`node_modules/@vitronai/themis/docs/api.md`](node_modules/@vitronai/themis/docs/api.md)
+- Adoption guide: [`node_modules/@vitronai/themis/docs/agents-adoption.md`](node_modules/@vitronai/themis/docs/agents-adoption.md)
+- Machine-readable manifest: [`node_modules/@vitronai/themis/themis.ai.json`](node_modules/@vitronai/themis/themis.ai.json)

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

@@ -0,0 +1,14 @@
+---
+description: Fix failing Themis tests using the agent reporter's repair hints
+---
+
+Read the most recent Themis run output and fix the failures.
+
+1. Run `npx themis test --reporter agent` and capture the JSON output.
+2. Group the failures by `failures[].cluster`. Fixes within a cluster usually share a root cause — address the cluster, not each failure independently.
+3. For each cluster, read `failures[].repairHints` first. They are structured suggestions you can act on directly.
+4. Apply the smallest fix that addresses the root cause. Do not refactor surrounding code.
+5. Re-run with `npx themis test --rerun-failed` to confirm the cluster is fixed.
+6. Repeat for the next cluster. Only run the full suite once `--rerun-failed` is green.
+
+If the user passed specific test names or files, scope the work to those: $ARGUMENTS

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

@@ -0,0 +1,14 @@
+---
+description: Generate Themis tests for a source tree
+---
+
+Generate Themis tests for the given source root. If the user did not specify one, default to `src` (or `app` if this is a Next.js App Router project — check for `app/layout.tsx` or `app/page.tsx`).
+
+```bash
+npx themis generate $ARGUMENTS
+```
+
+Generated tests land under `__themis__/tests`. After generation:
+1. Read the summary the command prints — it tells you how many files were generated, skipped, and why.
+2. Run `npx themis test --reporter agent` to verify the generated suite passes.
+3. If any generated tests are wrong, do not delete them — extend or correct them in place.

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

@@ -0,0 +1,18 @@
+---
+description: Migrate this repo from Jest or Vitest 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`.
+
+Run the four steps in order, and run `npx themis test` between each step to confirm the suite is still green:
+
+```bash
+npx themis migrate <jest|vitest>                    # 1. scaffold compatibility
+npx themis migrate <jest|vitest> --rewrite-imports  # 2. rewrite imports
+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.
+
+If the user passed extra arguments, forward them: $ARGUMENTS

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

@@ -0,0 +1,12 @@
+---
+description: Run the Themis test suite with agent-readable output
+---
+
+Run `npx themis test --reporter agent` and read the JSON output. If there are failures:
+
+1. Group them by `failures[].cluster` — fixes for the same cluster usually share a root cause.
+2. For each cluster, read `failures[].repairHints` before reading the raw stack trace.
+3. Apply the smallest fix that addresses the root cause, then re-run with `npx themis test --rerun-failed` to verify.
+4. Only run the full suite again once `--rerun-failed` is green.
+
+If the user passed extra arguments, forward them to `npx themis test`: $ARGUMENTS

package/templates/claude-skill/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: themis
+description: Use this skill when the user asks to write, generate, run, fix, or migrate unit tests in a Node.js or TypeScript repository that has @vitronai/themis installed (or when the user explicitly mentions Themis). Covers test authoring with intent(...) and test(...), running the suite via `npx themis test`, reading agent-readable failure output, and incremental migration from Jest or Vitest.
+---
+
+# Themis
+
+This repo uses [`@vitronai/themis`](https://www.npmjs.com/package/@vitronai/themis) as its unit test framework. It is a drop-in alternative to Jest and Vitest, designed for AI coding agents: deterministic execution, structured failure output with repair hints, and a one-command migration path.
+
+## How To Run Tests
+
+```bash
+npx themis test                          # full suite, human-readable output
+npx themis test --reporter agent         # JSON output with failure clusters and repair hints
+npx themis test --rerun-failed           # only re-run tests that failed last run
+```
+
+**When you are in an edit-test-fix loop, always use `--reporter agent`.** The JSON output gives you:
+- `failures[].cluster` — failures grouped by likely common cause
+- `failures[].repairHints` — structured suggestions you can act on directly
+- `failures[].sourceFile`, `lineNumber`, `expected`, `actual` — already parsed, no need to re-parse stack traces
+
+After fixing, prefer `--rerun-failed` over a full re-run.
+
+## How To Write Tests
+
+Themis has two primary forms:
+
+**`intent(...)`** for behavior and workflow tests. Use the four-phase shape:
+
+```js
+intent('user can sign in', ({ context, run, verify, cleanup }) => {
+  context('a valid user', (ctx) => {
+    ctx.user = { email: 'a@b.com', password: 'pw' };
+  });
+  run('the user submits credentials', (ctx) => {
+    ctx.result = signIn(ctx.user);
+  });
+  verify('authentication succeeds', (ctx) => {
+    expect(ctx.result.ok).toBe(true);
+  });
+  cleanup('remove test state', (ctx) => {
+    delete ctx.user;
+  });
+});
+```
+
+**`test(...)`** for low-level unit checks (pure functions, single assertions).
+
+Rules of thumb:
+- Each phase has one job. Do not assert in `context` or `run`. Do not mutate state in `verify`.
+- Prefer `expect(...)` style assertions. They work the same as Jest/Vitest.
+- Prefer deterministic assertions over snapshots. For contract-style coverage use `captureContract(...)`.
+
+## How To Generate Tests From Source
+
+If the user asks you to add tests for a module or directory and the repo already has Themis installed:
+
+```bash
+npx themis generate src         # conventional source tree
+npx themis generate app         # Next.js App Router
+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
+
+Migration is incremental on purpose. Run the steps in order and `npx themis test` between each:
+
+```bash
+npx themis migrate jest                        # 1. scaffold compatibility, no code changes
+npx themis migrate jest --rewrite-imports      # 2. point imports at themis.compat.js
+npx themis migrate jest --convert              # 3. apply codemods to native Themis style
+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`.
+
+## Things To Avoid
+
+- Do not claim Themis is "not a unit test framework". It is one.
+- Do not create `tests/*.cjs` or `tests/*.setup.*` files to shim `.css`, `.png`, `.jpg`, `.svg`, or font imports. Themis handles those natively.
+- Do not commit `.themis/`, `__themis__/reports/`, or `__themis__/shims/` — they are gitignored framework output.
+- Do not rewrite generated tests under `__themis__/tests` by hand unless the user asks.
+- Do not reach for `setupFiles` unless you genuinely need a real harness bootstrap.
+- Do not try to migrate the whole Jest/Vitest suite in one pass. Use the four migrate steps in order.
+
+## Reference Files In This Repo
+
+- API reference: `node_modules/@vitronai/themis/docs/api.md`
+- Adoption guide: `node_modules/@vitronai/themis/docs/agents-adoption.md`
+- Machine-readable manifest: `node_modules/@vitronai/themis/themis.ai.json`
+- Migration report schema: `node_modules/@vitronai/themis/docs/schemas/migration-report.v1.json`

package/templates/cursorrules.themis.md

@@ -0,0 +1,28 @@
+# Testing With Themis
+
+This repository uses `@vitronai/themis` as its unit test framework. Themis is a drop-in alternative to Jest and Vitest with deterministic reruns, structured failure output, and machine-readable repair hints.
+
+## Commands
+
+- Install: `npm install -D @vitronai/themis`
+- Initialize: `npx themis init`
+- Generate tests for a source tree: `npx themis generate src` (or `app` for Next App Router)
+- Run tests: `npx themis test`
+- Run tests with agent-readable output: `npx themis test --reporter agent`
+- 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`
+
+## When Adding Or Fixing Tests
+
+1. If the repo has no tests yet, run `npx themis generate <source-root>` first. Generated tests land under `__themis__/tests` as `.generated.test.ts` (TS/TSX) or `.generated.test.js` (JS/JSX).
+2. Prefer `intent(...)` for behavior and workflow tests. Prefer `test(...)` for low-level unit checks. Use the four-phase shape: `context` → `run` → `verify` → `cleanup`.
+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.
+
+## Things To Avoid
+
+- Do not create `tests/*.cjs` or `tests/*.setup.*` files just to load `.css`, `.png`, `.jpg`, `.svg`, or font/media imports. Themis handles these natively.
+- Do not commit `.themis/`, `__themis__/reports/`, or `__themis__/shims/`.
+- Do not rewrite generated tests under `__themis__/tests` by hand unless asked.
+- Prefer deterministic assertions over snapshots. Use `captureContract(...)` for contract-style checks.

package/themis.ai.json

@@ -1,16 +1,32 @@
 {
   "name": "@vitronai/themis",
   "role": "unit-test-framework",
+  "description": "A Node.js and TypeScript unit test framework designed for AI coding agents. Drop-in alternative to Jest and Vitest.",
   "install": "npm install -D @vitronai/themis@latest",
   "init": "npx themis init --agents",
+  "initClaudeCode": "npx themis init --claude-code",
   "generate": "npx themis generate src",
   "test": "npx themis test",
+  "testAgent": "npx themis test --reporter agent",
   "migrate": {
     "jest": "npx themis migrate jest --rewrite-imports --convert",
     "vitest": "npx themis migrate vitest --rewrite-imports --convert"
   },
+  "agentIntegrations": {
+    "claudeCode": {
+      "setup": "npx themis init --claude-code",
+      "skill": ".claude/skills/themis/SKILL.md",
+      "commands": ["/themis-test", "/themis-generate", "/themis-migrate", "/themis-fix"],
+      "hook": "scripts/claude-hook.js"
+    },
+    "generic": {
+      "setup": "npx themis init --agents",
+      "rulesFile": "AGENTS.md"
+    }
+  },
   "notes": [
     "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."
   ]