@vitronai/themis 0.1.0-beta.4 → 0.1.2

package/docs/schemas/contract-diff.v1.json

@@ -0,0 +1,120 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/vitron-ai/themis/docs/schemas/contract-diff.v1.json",
+  "title": "Themis Contract Diff v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "runId", "createdAt", "artifacts", "summary", "items"],
+  "properties": {
+    "schema": {
+      "type": "string",
+      "const": "themis.contract.diff.v1"
+    },
+    "runId": {
+      "type": "string"
+    },
+    "createdAt": {
+      "type": "string"
+    },
+    "artifacts": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["contractDiff"],
+      "properties": {
+        "contractDiff": {
+          "type": "string"
+        }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["total", "created", "updated", "drifted", "unchanged"],
+      "properties": {
+        "total": { "type": "number" },
+        "created": { "type": "number" },
+        "updated": { "type": "number" },
+        "drifted": { "type": "number" },
+        "unchanged": { "type": "number" }
+      }
+    },
+    "items": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/item"
+      }
+    }
+  },
+  "$defs": {
+    "item": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["key", "name", "file", "testName", "fullName", "contractFile", "status", "updateCommand", "diff"],
+      "properties": {
+        "key": { "type": "string" },
+        "name": { "type": "string" },
+        "file": { "type": "string" },
+        "testName": { "type": "string" },
+        "fullName": { "type": "string" },
+        "contractFile": { "type": "string" },
+        "status": {
+          "type": "string",
+          "enum": ["created", "updated", "drifted", "unchanged"]
+        },
+        "updateCommand": { "type": "string" },
+        "diff": {
+          "$ref": "#/$defs/diff"
+        }
+      }
+    },
+    "diff": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["equal", "unchangedCount", "added", "removed", "changed"],
+      "properties": {
+        "equal": { "type": "boolean" },
+        "unchangedCount": { "type": "number" },
+        "added": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/afterEntry" }
+        },
+        "removed": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/beforeEntry" }
+        },
+        "changed": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/changeEntry" }
+        }
+      }
+    },
+    "afterEntry": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["path", "after"],
+      "properties": {
+        "path": { "type": "string" },
+        "after": {}
+      }
+    },
+    "beforeEntry": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["path", "before"],
+      "properties": {
+        "path": { "type": "string" },
+        "before": {}
+      }
+    },
+    "changeEntry": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["path", "before", "after"],
+      "properties": {
+        "path": { "type": "string" },
+        "before": {},
+        "after": {}
+      }
+    }
+  }
+}

package/docs/showcases.md

@@ -0,0 +1,117 @@
+# Showcase Comparisons
+
+These examples are the clearest proof of where Themis should beat Jest and Vitest for AI-agent-heavy JS/TS test loops.
+
+## 1. Replace snapshots with contract capture
+
+Jest/Vitest snapshot flow:
+
+```ts
+test('banner state', () => {
+  expect(renderBanner(model)).toMatchSnapshot();
+});
+```
+
+Themis contract flow:
+
+```ts
+test('banner state', () => {
+  captureContract('banner state', {
+    title: renderBanner(model).title,
+    actions: renderBanner(model).actions
+  }, {
+    maskPaths: ['$.requestId'],
+    sortArrays: true
+  });
+});
+```
+
+Why it wins:
+
+- captures only the fields that matter
+- masks volatile IDs and timestamps instead of accepting noisy churn
+- writes machine-readable drift to `.themis/contract-diff.json`
+- updates stay explicit with `npx themis test --update-contracts`
+
+## 2. Migrate Jest/Vitest suites without a rewrite freeze
+
+Starting suite:
+
+```ts
+import { describe, it, expect } from '@jest/globals';
+
+describe('worker', () => {
+  it('records calls', () => {
+    const fnRef = fn();
+    fnRef('ok');
+    expect(fnRef).toBeCalledTimes(1);
+    expect({ status: 'ok' }).toStrictEqual({ status: 'ok' });
+  });
+});
+```
+
+After `npx themis migrate jest --convert`:
+
+```ts
+describe('worker', () => {
+  test('records calls', () => {
+    const fnRef = fn();
+    fnRef('ok');
+    expect(fnRef).toHaveBeenCalledTimes(1);
+    expect({ status: 'ok' }).toEqual({ status: 'ok' });
+  });
+});
+```
+
+Why it wins:
+
+- removes common compatibility imports
+- rewrites common matcher aliases into native Themis forms
+- emits `.themis/migration-report.json` so agents and humans can track what changed
+
+## 3. Give agents a repair loop humans can still read
+
+Jest/Vitest mostly produce console text plus optional snapshots.
+
+Themis produces:
+
+- `.themis/failed-tests.json`
+- `.themis/run-diff.json`
+- `.themis/fix-handoff.json`
+- `.themis/contract-diff.json`
+
+Why it wins:
+
+- agents get deterministic machine-readable artifacts
+- humans still get focused CLI and HTML diffs
+- rerun, repair, and acceptance loops are explicit instead of buried in terminal logs
+
+## 4. Keep local loops fast without losing determinism
+
+Themis local loop:
+
+```bash
+npx themis test --watch --isolation in-process --cache --reporter next
+```
+
+Why it wins:
+
+- optimized for short edit-rerun-review cycles
+- preserves canonical JSON and artifact contracts
+- keeps failure diffs and contract drift visible while iterating
+
+## 5. Surface migration and contract work directly in VS Code
+
+Themis sidebar groups:
+
+- `Contract Review`
+- `Migration Review`
+- `Failures`
+- `Generated Review`
+
+Why it wins:
+
+- the editor reads artifact contracts instead of reimplementing runner logic
+- one action accepts reviewed contracts
+- one action reruns migration codemods for the detected framework
+- humans and agents operate from the same source of truth

package/docs/vscode-extension.md

@@ -7,8 +7,10 @@ This is the intended shape of the editor UX:
 - a Themis activity-bar container
 - a results sidebar driven by `.themis/*` artifacts
 - commands to run tests, rerun failures, refresh results, and open the HTML report
+- commands to accept reviewed contract baselines and rerun migration codemods
 - failure navigation that jumps from artifact data into the source file
 - generated-review navigation for source files, generated tests, hint sidecars, and backlog items
+- contract-review and migration-review groups driven by `.themis/contract-diff.json` and `.themis/migration-report.json`
 
 ## Current MVP Scope
 
@@ -17,6 +19,8 @@ The scaffold currently supports:
 - reading `.themis/last-run.json`
 - reading `.themis/failed-tests.json`
 - reading `.themis/run-diff.json`
+- reading `.themis/contract-diff.json`
+- reading `.themis/migration-report.json`
 - reading `.themis/generate-last.json`
 - reading `.themis/generate-map.json`
 - reading `.themis/generate-backlog.json`
@@ -27,6 +31,15 @@ The scaffold currently supports:
 
 The extension is intentionally thin. It shells out to Themis commands and treats the CLI plus artifacts as the canonical contract.
 
+Current command surface:
+
+- `Themis: Run Tests`
+- `Themis: Rerun Failed`
+- `Themis: Update Contracts`
+- `Themis: Run Migration Codemods`
+- `Themis: Open HTML Report`
+- `Themis: Refresh Results`
+
 ## Local Development
 
 Open the repository in VS Code and use an Extension Development Host pointed at:

package/docs/why-themis.md

@@ -6,6 +6,7 @@ The core positioning is simple:
 
 - The best unit test framework for AI agents in Node.js and TypeScript
 - An AI verdict engine for human and agent review loops
+- A contract-first alternative to snapshot-heavy test maintenance
 
 ## What "Next-Gen" Means Here
 
@@ -42,6 +43,8 @@ Themis supports structured outputs for tooling loops:
 
 `--rerun-failed`, `--watch`, and test-name filtering (`--match`) reduce iteration time and keep failure focus tight.
 
+The fast local loop matters for AI-assisted editing too: `--watch --isolation in-process --cache` gives agents and humans a short edit-run-review cycle instead of full-suite friction.
+
 ## 4) Modern JS/TS Project Parity
 
 Themis is built for current Node.js and TypeScript repos:
@@ -69,11 +72,38 @@ Themis keeps a lean JS runtime and ships first-party typings:
 Themis ships workflow features agents can use directly:
 
 - direct contract assertions instead of snapshot-file churn
+- generated contract tests that keep baselines in readable source instead of opaque snapshot blobs
+- machine-readable artifacts that let agents inspect and explain changes before updating tests
 - mocks and spies with `fn`, `spyOn`, and `mock`
 - `.themis/run-diff.json` and `.themis/run-history.json`
 - HTML verdict reports for human review
 
-## 8) Performance Discipline, Not Guesswork
+### Comparable To Snapshot Workflows, Without Snapshot Rot
+
+Many teams use snapshots because they want cheap baseline capture, safe review, and easy updates. Themis should meet that need without copying the snapshot mechanism.
+
+Themis favors:
+
+- normalized contract assertions over broad serialized dumps
+- readable generated tests over hidden `.snap` files
+- field-level and behavior-level diffs over large text churn
+- intentional regeneration and migration flows over blanket "accept all changes"
+
+The result is comparable coverage value with clearer semantics for both humans and agents.
+
+## 8) Migration Path From Jest And Vitest
+
+Adoption does not need to be a rewrite.
+
+Themis already supports:
+
+- runtime compatibility for `@jest/globals`, `vitest`, and `@testing-library/react`
+- `themis migrate <jest|vitest>` scaffolding for incremental adoption
+- optional import rewriting to a local compatibility bridge
+
+The strategic direction is clear: start with compatibility, then move suites toward native Themis contracts and intent-first tests as teams touch them.
+
+## 9) Performance Discipline, Not Guesswork
 
 Performance is measured and guarded:
 
@@ -81,13 +111,13 @@ Performance is measured and guarded:
 - regression gate (`npm run benchmark:gate`)
 - threshold config (`benchmark-gate.json`)
 
-## 9) CLI Designed for Humans and Machines
+## 10) CLI Designed for Humans and Machines
 
 - high-signal human reporter (`--next`)
 - strict machine reporter outputs (`--json`, `--agent`)
 - branded banner for human mode only
 
-## 10) Editor Surface Without Replacing The CLI
+## 11) Editor Surface Without Replacing The CLI
 
 Themis includes a thin VS Code extension scaffold that reads `.themis/*` artifacts, reruns tests, and opens the HTML report. The CLI remains the source of truth.
 
@@ -108,4 +138,5 @@ If you describe Themis publicly, use this framing:
 - "The best unit test framework for AI agents in Node.js and TypeScript"
 - "An AI verdict engine for human and agent review loops"
 - "Intent-first testing with deterministic reruns and machine-readable artifacts"
+- "A better alternative to snapshot-heavy workflows: explicit contracts, readable diffs, intentional updates"
 - "JS-fast runtime with first-party TypeScript DX and benchmark-gated discipline"

package/globals.d.ts

@@ -44,6 +44,7 @@ declare global {
   var advanceTimersByTime: (ms: number) => void;
   var runAllTimers: () => void;
   var flushMicrotasks: FlushMicrotasks;
+  var captureContract: import('./index').CaptureContract;
   var mockFetch: (handlerOrResponse: unknown) => FetchMock;
   var restoreFetch: () => void;
   var resetFetchMocks: () => void;

package/index.d.ts

@@ -18,6 +18,7 @@ export interface TestResult {
 export interface FileResult {
   file: string;
   tests: TestResult[];
+  contracts?: ContractCaptureEvent[];
 }
 
 export interface RunMeta {
@@ -78,6 +79,7 @@ export interface RunOptions {
   tsconfigPath?: string | null;
   isolation?: 'worker' | 'in-process';
   cache?: boolean;
+  updateContracts?: boolean;
 }
 
 export interface ThemisConfig {
@@ -100,6 +102,8 @@ export interface MigrationResult {
   packageUpdated: boolean;
   rewriteImports: boolean;
   rewrittenFiles: string[];
+  convert?: boolean;
+  convertedFiles?: string[];
   reportPath: string;
   report: {
     schema: 'themis.migration.report.v1';
@@ -112,18 +116,23 @@ export interface MigrationResult {
       testingLibraryReact: number;
       rewrittenFiles: number;
       rewrittenImports: number;
+      convertedFiles: number;
+      convertedAssertions: number;
+      removedImports: number;
     };
     files: Array<{
       file: string;
       imports: string[];
     }>;
     rewrites: string[];
+    conversions?: string[];
     nextActions: string[];
   };
 }
 
 export interface MigrationOptions {
   rewriteImports?: boolean;
+  convert?: boolean;
 }
 
 export interface GenerateOptions {
@@ -208,6 +217,7 @@ export interface RunArtifactPaths {
   runDiff: string;
   runHistory: string;
   fixHandoff: string;
+  contractDiff: string;
 }
 
 export interface RunComparison {
@@ -226,6 +236,32 @@ export interface RunArtifacts {
   paths: RunArtifactPaths;
 }
 
+export interface ContractDiffEntry {
+  path: string;
+  before?: unknown;
+  after?: unknown;
+}
+
+export interface ContractDiff {
+  equal: boolean;
+  unchangedCount: number;
+  added: ContractDiffEntry[];
+  removed: ContractDiffEntry[];
+  changed: ContractDiffEntry[];
+}
+
+export interface ContractCaptureEvent {
+  key: string;
+  name: string;
+  status: 'created' | 'updated' | 'drifted' | 'unchanged';
+  contractFile: string;
+  file: string;
+  testName: string;
+  fullName: string;
+  updateCommand: string;
+  diff: ContractDiff;
+}
+
 export interface GenerateGateFailure {
   code: string;
   count: number;
@@ -448,6 +484,23 @@ export interface GenerateSummary {
   helperRemoved: boolean;
 }
 
+export interface ContractDiffPayload {
+  schema: 'themis.contract.diff.v1';
+  runId: string;
+  createdAt: string;
+  artifacts: {
+    contractDiff: string;
+  };
+  summary: {
+    total: number;
+    created: number;
+    updated: number;
+    drifted: number;
+    unchanged: number;
+  };
+  items: ContractCaptureEvent[];
+}
+
 export function main(argv: string[]): Promise<void>;
 export function collectAndRun(filePath: string, options?: Omit<RunOptions, 'maxWorkers'>): Promise<FileResult>;
 export function runTests(files: string[], options?: RunOptions): Promise<RunResult>;
@@ -471,6 +524,10 @@ export interface MockResult {
   value: unknown;
 }
 
+export interface CaptureContract {
+  (name: string, value: unknown, options?: { file?: string }): unknown;
+}
+
 export interface MockState<TArgs extends unknown[] = unknown[]> {
   calls: TArgs[];
   results: MockResult[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vitronai/themis",
-  "version": "0.1.0-beta.4",
+  "version": "0.1.2",
   "description": "Intent-first unit test framework for AI agents in Node.js and TypeScript, powered by an AI verdict engine",
   "license": "MIT",
   "author": "Vitron AI",

package/src/artifacts.js

@@ -7,6 +7,7 @@ const FAILED_TESTS_FILE = 'failed-tests.json';
 const RUN_DIFF_FILE = 'run-diff.json';
 const RUN_HISTORY_FILE = 'run-history.json';
 const FIX_HANDOFF_FILE = 'fix-handoff.json';
+const CONTRACT_DIFF_FILE = 'contract-diff.json';
 const GENERATE_MAP_FILE = 'generate-map.json';
 const GENERATE_BACKLOG_FILE = 'generate-backlog.json';
 
@@ -23,7 +24,8 @@ function writeRunArtifacts(cwd, result) {
     failedTests: path.join(ARTIFACT_DIR, FAILED_TESTS_FILE),
     runDiff: path.join(ARTIFACT_DIR, RUN_DIFF_FILE),
     runHistory: path.join(ARTIFACT_DIR, RUN_HISTORY_FILE),
-    fixHandoff: path.join(ARTIFACT_DIR, FIX_HANDOFF_FILE)
+    fixHandoff: path.join(ARTIFACT_DIR, FIX_HANDOFF_FILE),
+    contractDiff: path.join(ARTIFACT_DIR, CONTRACT_DIFF_FILE)
   };
 
   result.artifacts = {
@@ -83,6 +85,14 @@ function writeRunArtifacts(cwd, result) {
   });
   fs.writeFileSync(historyPath, `${stringifyArtifact(nextHistory)}\n`, 'utf8');
 
+  const contractDiffPayload = buildContractDiffPayload(result, {
+    runId,
+    createdAt: new Date().toISOString(),
+    relativePaths
+  });
+  const contractDiffPath = path.join(artifactDir, CONTRACT_DIFF_FILE);
+  fs.writeFileSync(contractDiffPath, `${stringifyArtifact(contractDiffPayload)}\n`, 'utf8');
+
   const fixHandoffPath = path.join(artifactDir, FIX_HANDOFF_FILE);
   let fixHandoff = null;
   if (failedTests.length > 0) {
@@ -100,9 +110,11 @@ function writeRunArtifacts(cwd, result) {
     diffPath,
     historyPath,
     fixHandoffPath,
+    contractDiffPath,
     failuresPayload,
     comparison,
-    fixHandoff
+    fixHandoff,
+    contractDiffPayload
   };
 }
 
@@ -192,6 +204,55 @@ function collectFailureNames(result) {
   return names.sort();
 }
 
+function buildContractDiffPayload(result, context) {
+  const items = [];
+  for (const fileEntry of result.files || []) {
+    for (const contract of fileEntry.contracts || []) {
+      items.push({
+        key: String(contract.key || ''),
+        name: String(contract.name || ''),
+        file: String(fileEntry.file || contract.file || ''),
+        testName: String(contract.testName || ''),
+        fullName: String(contract.fullName || ''),
+        contractFile: String(contract.contractFile || ''),
+        status: String(contract.status || 'unchanged'),
+        updateCommand: String(contract.updateCommand || ''),
+        diff: normalizeContractDiff(contract.diff)
+      });
+    }
+  }
+
+  const summary = {
+    total: items.length,
+    created: items.filter((item) => item.status === 'created').length,
+    updated: items.filter((item) => item.status === 'updated').length,
+    drifted: items.filter((item) => item.status === 'drifted').length,
+    unchanged: items.filter((item) => item.status === 'unchanged').length
+  };
+
+  return {
+    schema: 'themis.contract.diff.v1',
+    runId: context.runId,
+    createdAt: context.createdAt,
+    artifacts: {
+      contractDiff: context.relativePaths.contractDiff
+    },
+    summary,
+    items
+  };
+}
+
+function normalizeContractDiff(diff) {
+  const safeDiff = diff || {};
+  return {
+    equal: Boolean(safeDiff.equal),
+    unchangedCount: Number(safeDiff.unchangedCount || 0),
+    added: Array.isArray(safeDiff.added) ? safeDiff.added : [],
+    removed: Array.isArray(safeDiff.removed) ? safeDiff.removed : [],
+    changed: Array.isArray(safeDiff.changed) ? safeDiff.changed : []
+  };
+}
+
 function createRunId(startedAt) {
   return String(startedAt || '')
     .replace(/[:.]/g, '-')

package/src/cli.js

@@ -80,6 +80,9 @@ async function main(argv) {
     if (result.rewriteImports) {
       console.log(`Imports: rewrote ${result.rewrittenFiles.length} file(s) to local Themis compatibility imports.`);
     }
+    if (result.convertedFiles && result.convertedFiles.length > 0) {
+      console.log(`Codemods: converted ${result.convertedFiles.length} file(s) to Themis-native patterns.`);
+    }
     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;
@@ -180,6 +183,7 @@ async function executeTestRun(cwd, flags) {
       match: flags.match || null,
       allowedFullNames,
       noMemes: Boolean(flags.noMemes),
+      updateContracts: Boolean(flags.updateContracts),
       cwd,
       environment,
       setupFiles: config.setupFiles,
@@ -284,6 +288,10 @@ function parseFlags(args) {
       flags.noMemes = true;
       continue;
     }
+    if (token === '--update-contracts') {
+      flags.updateContracts = true;
+      continue;
+    }
     if (token === '-w' || token === '--watch') {
       flags.watch = true;
       continue;
@@ -345,13 +353,18 @@ function parseFlags(args) {
 function parseMigrateFlags(args) {
   const flags = {
     source: args[0],
-    rewriteImports: false
+    rewriteImports: false,
+    convert: false
   };
 
   for (let i = 1; i < args.length; i += 1) {
     const token = args[i];
     if (token === '--rewrite-imports') {
       flags.rewriteImports = true;
+      continue;
+    }
+    if (token === '--convert') {
+      flags.convert = true;
     }
   }
 
@@ -563,8 +576,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]   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] [-w|--watch] [--html-output path] [--match regex] [--rerun-failed] [--no-memes] [--lexicon classic|themis]');
+  console.log('  migrate <jest|vitest> [--rewrite-imports] [--convert]   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] [-w|--watch] [--html-output path] [--match regex] [--rerun-failed] [--no-memes] [--lexicon classic|themis]');
 }
 
 function printGenerateSummary(summary, cwd) {