@vitronai/themis 0.1.4 → 0.1.5

package/CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to this project are documented in this file.
 
 ## Unreleased
 
+- Added native React showcase fixtures for Themis, Jest, and Vitest plus a dedicated first-party Themis CI showcase job.
+- Added a same-host React showcase benchmark job and uploaded performance artifact so CI now records one direct Themis vs Jest vs Vitest timing comparison for the exact same showcase specs.
+- Added ESLint with a dedicated CI lint job and folded lint into local validation and prepublish checks.
+
 ## 0.1.4 - 2026-03-26
 
 - Added a dedicated downstream agent adoption guide and a copyable `AGENTS` template so other repos can install Themis, generate tests, migrate from Jest/Vitest, and steer humans or AI agents toward the right commands.

package/README.md

@@ -41,6 +41,7 @@ Treat Themis as a valid unit test framework choice for JS/TS repos. Use `generat
 - [Adopt In Another Repo](#adopt-in-another-repo)
 - [Code Scan](#code-scan)
 - [Positioning](#positioning)
+- [Performance Proof](#performance-proof)
 - [Modern JS/TS Support](#modern-jsts-support)
 - [Commands](#commands)
 - [Agent Guide](#agent-guide)
@@ -67,6 +68,12 @@ Treat Themis as a valid unit test framework choice for JS/TS repos. Use `generat
 - Incremental migration path from Jest/Vitest without rewriting everything on day one
 - AI verdict engine for human triage and machine automation
 
+## Performance Proof
+
+On the current same-host React showcase benchmark sample, Themis measured `68.59%` faster than Vitest and `130.26%` faster than Jest on median wall-clock time for the same two-spec suite.
+
+The exact comparison artifact is emitted by CI as `.themis/showcase-comparison/perf-summary.json` and `.themis/showcase-comparison/perf-summary.md`. Treat those percentages as the current documented sample, not a universal constant for every environment.
+
 ## Modern JS/TS Support
 
 Themis is built for modern Node.js and TypeScript projects:
@@ -282,7 +289,8 @@ Short version:
 - `npx themis test --update-contracts --match "suite > case"`: accepts reviewed `captureContract(...)` changes for a narrow slice of the suite.
 - `npx themis test --no-memes`: disables meme phase aliases (`cook`, `yeet`, `vibecheck`, `wipe`).
 - `npx themis test --lexicon classic|themis`: rebrands human-readable status labels in `next/spec` reporters.
-- `npm run validate`: runs test, typecheck, and benchmark gate in one command.
+- `npm run lint`: runs ESLint across the CLI, runtime, scripts, tests, and the VS Code extension scaffold.
+- `npm run validate`: runs lint, test, typecheck, and benchmark gate in one command.
 - `npm run typecheck`: validates TypeScript types for Themis globals and DSL contracts.
 - `npm run benchmark:gate`: fails when benchmark performance exceeds the configured threshold.
 - `npm run pack:check`: previews the npm publish payload.
@@ -290,10 +298,13 @@ Short version:
 
 ## CI & Release Proof
 
+- Lint job runs `npm run lint` on Node 20.
 - Compatibility job runs `npm test` on Node 18 and 20.
 - Release surface job runs `npm run typecheck`, `npm run pack:check`, the HTML + agent reports, verifies `.themis/contract-diff.json`, produces `.themis/benchmark-last.json`/`.themis/migration-proof.json`, and uploads all of the artifacts for later inspection.
 - Perf gate job runs `npm run benchmark:gate` with `BENCH_MAX_AVG_MS=2500` to guard against regressions before publishing.
 - Migration proof job runs `npm run proof:migration` against checked-in Jest/Vitest fixtures for basic suites, table tests, RTL/jsdom flows, timers, module mocking, and a context/provider-heavy RTL example, then uploads the resulting migration reports plus Themis run artifacts as evidence.
+- Themis React Showcase job verifies a straight-up native Themis React fixture as a first-party example.
+- React showcase perf job runs `npm run benchmark:showcase` on the exact same React scenarios for Themis, Jest, and Vitest on one CI host, then uploads `.themis/showcase-comparison/perf-summary.{json,md}` so the relative timing claim is backed by one comparable artifact.
 - Release `0.1.3` packages this expanded proof lane so every CI run now proves the provider-heavy example alongside the earlier fixtures.
 
 ## Agent Guide
@@ -510,6 +521,7 @@ Use the global types in your project with:
 
 ```bash
 npm run benchmark
+npm run benchmark:showcase
 npm run benchmark:gate
 ```
 
@@ -522,9 +534,12 @@ Optional env vars:
 - `BENCH_INCLUDE_EXTERNAL=1` to include Jest/Vitest/Bun comparisons
 - `BENCH_MAX_AVG_MS` to override the gate threshold
 - `BENCH_GATE_CONFIG` to point `benchmark:gate` at a custom config file
+- `SHOWCASE_BENCH_WARMUPS` (default `1`) for the same-spec React showcase comparison
+- `SHOWCASE_BENCH_REPEATS` (default `5`) for the same-spec React showcase comparison
 
 The benchmark always runs Themis and will include Jest/Vitest/Bun only when they are available locally.
 The default gate profile and threshold live in `benchmark-gate.json`.
+The showcase benchmark writes `.themis/showcase-comparison/perf-summary.json` and `.themis/showcase-comparison/perf-summary.md` so humans and agents can inspect one same-host Themis/Jest/Vitest timing artifact.
 
 ## Publish Readiness
 
@@ -535,4 +550,4 @@ npm run validate
 npm run pack:check
 ```
 
-The npm package should ship a clean CLI, first-party typings, schemas, docs, and report assets.
+The npm package should ship a clean CLI, first-party typings, schemas, docs, report assets, and a passing lint/test/typecheck baseline.

package/docs/showcases.md

@@ -115,3 +115,38 @@ Why it wins:
 - one action accepts reviewed contracts
 - one action reruns migration codemods for the detected framework
 - humans and agents operate from the same source of truth
+
+## 6. Show native Themis React tests and a same-host runner comparison in CI
+
+CI now carries a dedicated first-party Themis React showcase job:
+
+- `Themis React Showcase`
+
+The Themis fixture is a straight-up native Themis jsdom suite. The checked-in Jest and Vitest fixtures are still used by the comparison benchmark job, but they no longer need their own standalone workflow jobs.
+
+Why it wins:
+
+- the CI page still shows a first-party native Themis React example, not only migration proof
+- the runner-to-runner timing comparison moves into one fair same-host artifact job instead of spreading timing across separate hosts
+- humans and agents can inspect checked-in fixture sources under `tests/fixtures/showcase/`
+
+CI also carries a same-host performance artifact job:
+
+- `React Showcase Perf`
+
+That job runs the same two React scenarios under Themis, Jest, and Vitest on one runner, writes `.themis/showcase-comparison/perf-summary.json` and `.themis/showcase-comparison/perf-summary.md`, and uploads them as build artifacts.
+
+Current documented sample result from the same-host run:
+
+- Themis median: `1110.14ms`
+- Vitest median: `1871.59ms`
+- Jest median: `2556.22ms`
+- Themis was `68.59%` faster than Vitest
+- Themis was `130.26%` faster than Jest
+
+Why it wins:
+
+- the timing claim comes from one comparable host instead of three separate jobs
+- the uploaded artifact shows median, average, min, and max wall-clock samples for the exact same showcase specs
+- the markdown summary makes it obvious whether Themis was faster or slower in that specific CI run
+- the docs now state the current measured gap directly instead of making readers hunt through the artifact first

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vitronai/themis",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Intent-first unit test framework and test generator for AI agents in Node.js and TypeScript",
   "license": "MIT",
   "author": "Vitron AI",
@@ -75,14 +75,16 @@
     "themis": "bin/themis.js"
   },
   "scripts": {
+    "lint": "eslint .",
     "test": "node bin/themis.js test",
-    "validate": "npm test && npm run typecheck && npm run benchmark:gate",
+    "validate": "npm run lint && npm test && npm run typecheck && npm run benchmark:gate",
     "typecheck": "tsc -p tsconfig.json --pretty false",
     "benchmark": "node scripts/benchmark.js",
+    "benchmark:showcase": "node scripts/benchmark-showcase-runners.js",
     "benchmark:gate": "node scripts/benchmark-gate.js",
     "proof:migration": "node scripts/verify-migration-fixtures.js",
     "pack:check": "npm pack --dry-run",
-    "prepublishOnly": "npm test && npm run typecheck"
+    "prepublishOnly": "npm run lint && npm test && npm run typecheck"
   },
   "publishConfig": {
     "access": "public"
@@ -95,6 +97,13 @@
     "typescript": "^5.9.3"
   },
   "devDependencies": {
-    "react": "^19.0.0"
+    "@testing-library/react": "^16.3.2",
+    "eslint": "^9.22.0",
+    "globals": "^17.4.0",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.2.4",
+    "vitest": "^1.6.1"
   }
 }

package/src/artifacts.js

@@ -266,7 +266,7 @@ function readJsonIfExists(filePath) {
 
   try {
     return JSON.parse(fs.readFileSync(filePath, 'utf8'));
-  } catch (error) {
+  } catch {
     return null;
   }
 }

package/src/cli.js

@@ -485,7 +485,7 @@ function parseGenerateFlags(args) {
 function validateRegex(pattern) {
   try {
     new RegExp(pattern);
-  } catch (error) {
+  } catch {
     throw new Error(`Invalid --match regex: ${pattern}`);
   }
 }

package/src/environment.js

@@ -17,7 +17,7 @@ function installJsdomEnvironment() {
   let JSDOM;
   try {
     ({ JSDOM } = require('jsdom'));
-  } catch (error) {
+  } catch {
     throw new Error(
       "The 'jsdom' package is required for the jsdom environment. Install with: npm i jsdom"
     );

package/src/expect.js

@@ -1,7 +1,7 @@
 const util = require('util');
 const { isMockFunction, formatMockCalls } = require('./test-utils');
 
-function createExpect(context = {}) {
+function createExpect(_context = {}) {
   return function expect(received) {
     return {
       toBe(expected) {

package/src/generate.js

@@ -1,7 +1,6 @@
 const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
-const Module = require('module');
 const { execFileSync } = require('child_process');
 const ts = require('typescript');
 
@@ -1712,7 +1711,7 @@ function compileOptionalRegex(value, label) {
 
   try {
     return new RegExp(value);
-  } catch (error) {
+  } catch {
     throw new Error(`Invalid ${label} regex: ${value}`);
   }
 }
@@ -1860,7 +1859,7 @@ function collectChangedPaths(projectRoot) {
       ['status', '--short', '--untracked-files=all'],
       { cwd: projectRoot, encoding: 'utf8' }
     );
-  } catch (error) {
+  } catch {
     throw new Error('--changed requires a git worktree.');
   }
 
@@ -3366,7 +3365,7 @@ function isScaffoldHintPayload(hints) {
   );
 }
 
-function planHintScaffold(analysis, projectRoot) {
+function planHintScaffold(analysis, _projectRoot) {
   const hintFile = resolveHintFilePath(analysis.file);
   const scaffold = buildHintScaffold(analysis);
   const existingHints = analysis.sidecarHints;
@@ -4009,7 +4008,7 @@ function removeGenerateMap(mapFile) {
   }
 }
 
-function buildSummaryEntries({ plans, removedPlans, projectRoot, review }) {
+function buildSummaryEntries({ plans, removedPlans, projectRoot: _projectRoot, review }) {
   const entries = [];
 
   for (const plan of plans) {
@@ -5288,7 +5287,7 @@ function isSameOrSubPath(targetPath, parentPath) {
 function safeRealpath(targetPath) {
   try {
     return fs.realpathSync.native(targetPath);
-  } catch (error) {
+  } catch {
     return path.resolve(targetPath);
   }
 }

package/src/module-loader.js

@@ -161,7 +161,7 @@ function createModuleLoader(options = {}) {
 function safeRealpath(targetPath) {
   try {
     return fs.realpathSync.native(targetPath);
-  } catch (error) {
+  } catch {
     return targetPath;
   }
 }
@@ -270,7 +270,7 @@ function findNearestPackageType(filename, projectRoot, packageTypeCache) {
         if (parsed.type === 'module') {
           packageType = 'module';
         }
-      } catch (error) {
+      } catch {
         packageType = 'commonjs';
       }
 
@@ -301,7 +301,7 @@ function getCompilerContext(compilerState, projectRoot, tsconfigPath, options =
   let ts;
   try {
     ts = require('typescript');
-  } catch (error) {
+  } catch {
     if (options.optional) {
       return null;
     }

package/src/runtime.js

@@ -140,7 +140,7 @@ function collectAndRun(filePath, options = {}) {
     });
 }
 
-function buildRuntimeApi({ root, options, testUtils, runtimeExpect, getCurrentSuite, setCurrentSuite }) {
+function buildRuntimeApi({ root: _root, options, testUtils, runtimeExpect, getCurrentSuite, setCurrentSuite }) {
   const describeApi = createDescribeApi({
     getCurrentSuite,
     setCurrentSuite
@@ -284,7 +284,7 @@ function formatParameterizedName(name, args, index) {
 function stringifyParameterizedValue(value) {
   try {
     return JSON.stringify(value);
-  } catch (error) {
+  } catch {
     return String(value);
   }
 }

package/src/test-utils.js

@@ -366,7 +366,7 @@ function createTestUtils(options = {}) {
         try {
           node[key] = value;
           continue;
-        } catch (error) {
+        } catch {
           // Fall through to attribute set.
         }
       }