@vitronai/themis 0.1.0-beta.0

package/index.d.ts

@@ -0,0 +1,190 @@
+export type Awaitable<T> = T | Promise<T>;
+
+export type TestStatus = 'passed' | 'failed' | 'skipped';
+
+export interface NormalizedError {
+  message: string;
+  stack: string;
+}
+
+export interface TestResult {
+  name: string;
+  fullName: string;
+  status: TestStatus;
+  durationMs: number;
+  error: NormalizedError | null;
+}
+
+export interface FileResult {
+  file: string;
+  tests: TestResult[];
+}
+
+export interface RunMeta {
+  startedAt: string;
+  finishedAt: string;
+  maxWorkers: number;
+}
+
+export interface RunSummary {
+  total: number;
+  passed: number;
+  failed: number;
+  skipped: number;
+  durationMs: number;
+}
+
+export type StabilityStatus = TestStatus | 'missing';
+export type StabilityClassification = 'stable_pass' | 'stable_fail' | 'unstable';
+
+export interface StabilityTestResult {
+  file: string;
+  testName: string;
+  fullName: string;
+  statuses: StabilityStatus[];
+  classification: StabilityClassification;
+}
+
+export interface StabilitySummary {
+  stablePass: number;
+  stableFail: number;
+  unstable: number;
+}
+
+export interface StabilityReport {
+  runs: number;
+  summary: StabilitySummary;
+  tests: StabilityTestResult[];
+}
+
+export interface RunResult {
+  meta: RunMeta;
+  files: FileResult[];
+  summary: RunSummary;
+  stability?: StabilityReport;
+}
+
+export type TestEnvironment = 'node' | 'jsdom';
+
+export interface RunOptions {
+  maxWorkers?: number;
+  match?: string | null;
+  allowedFullNames?: string[] | null;
+  noMemes?: boolean;
+  cwd?: string;
+  environment?: TestEnvironment;
+  setupFiles?: string[];
+  tsconfigPath?: string | null;
+  updateSnapshots?: boolean;
+}
+
+export interface ThemisConfig {
+  testDir: string;
+  testRegex: string;
+  maxWorkers: number;
+  reporter: string;
+  environment: TestEnvironment;
+  setupFiles: string[];
+  tsconfigPath: string | null;
+}
+
+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>;
+export function discoverTests(cwd: string, config: ThemisConfig): string[];
+export function loadConfig(cwd: string): ThemisConfig;
+export function initConfig(cwd: string): void;
+export const DEFAULT_CONFIG: ThemisConfig;
+
+export interface MockResult {
+  type: 'return' | 'throw';
+  value: unknown;
+}
+
+export interface MockState<TArgs extends unknown[] = unknown[]> {
+  calls: TArgs[];
+  results: MockResult[];
+}
+
+export interface MockFunction<TArgs extends unknown[] = unknown[], TReturn = unknown> {
+  (...args: TArgs): TReturn;
+  mock: MockState<TArgs>;
+  mockImplementation(implementation: (...args: TArgs) => TReturn): MockFunction<TArgs, TReturn>;
+  mockReturnValue(value: TReturn): MockFunction<TArgs, TReturn>;
+  mockResolvedValue(value: Awaited<TReturn>): MockFunction<TArgs, TReturn>;
+  mockRejectedValue(value: unknown): MockFunction<TArgs, TReturn>;
+  mockClear(): MockFunction<TArgs, TReturn>;
+  mockReset(): MockFunction<TArgs, TReturn>;
+  mockRestore?(): MockFunction<TArgs, TReturn>;
+  getMockName(): string;
+}
+
+export interface ExpectMatchers<TReceived = unknown> {
+  toBe(expected: TReceived): void;
+  toEqual(expected: unknown): void;
+  toMatchObject(expected: unknown): void;
+  toBeTruthy(): void;
+  toBeFalsy(): void;
+  toBeDefined(): void;
+  toBeUndefined(): void;
+  toBeNull(): void;
+  toHaveLength(expected: number): void;
+  toContain(item: unknown): void;
+  toThrow(match?: string | RegExp): void;
+  toHaveBeenCalled(): void;
+  toHaveBeenCalledTimes(expected: number): void;
+  toHaveBeenCalledWith(...expectedArgs: unknown[]): void;
+  toMatchSnapshot(snapshotName?: string): void;
+}
+
+export type Expect = <TReceived = unknown>(received: TReceived) => ExpectMatchers<TReceived>;
+export const expect: Expect;
+export type Fn = <TArgs extends unknown[] = unknown[], TReturn = unknown>(
+  implementation?: (...args: TArgs) => TReturn
+) => MockFunction<TArgs, TReturn>;
+export type SpyOn = <TTarget extends Record<string, unknown>, TKey extends keyof TTarget>(
+  target: TTarget,
+  methodName: TKey
+) => MockFunction<any[], any>;
+export type MockModule = (request: string, factoryOrExports?: unknown | (() => unknown)) => void;
+export type MockControl = () => void;
+
+export type SuiteFn = () => void;
+export type TestFn = () => Awaitable<void>;
+export type Describe = (name: string, fn: SuiteFn) => void;
+export type Test = (name: string, fn: TestFn) => void;
+export type Hook = (fn: TestFn) => void;
+
+export type IntentContext = Record<string, unknown>;
+export type IntentPhase<TContext extends IntentContext = IntentContext> = (ctx: TContext) => Awaitable<void>;
+export type IntentRegistrar<TContext extends IntentContext = IntentContext> = (
+  description: string | IntentPhase<TContext>,
+  fn?: IntentPhase<TContext>
+) => void;
+
+export interface IntentDSL<TContext extends IntentContext = IntentContext> {
+  context: IntentRegistrar<TContext>;
+  run: IntentRegistrar<TContext>;
+  verify: IntentRegistrar<TContext>;
+  cleanup: IntentRegistrar<TContext>;
+
+  arrange: IntentRegistrar<TContext>;
+  act: IntentRegistrar<TContext>;
+  assert: IntentRegistrar<TContext>;
+  given: IntentRegistrar<TContext>;
+  when: IntentRegistrar<TContext>;
+  then: IntentRegistrar<TContext>;
+  setup: IntentRegistrar<TContext>;
+  infer: IntentRegistrar<TContext>;
+  teardown: IntentRegistrar<TContext>;
+  finally: IntentRegistrar<TContext>;
+  cook: IntentRegistrar<TContext>;
+  yeet: IntentRegistrar<TContext>;
+  vibecheck: IntentRegistrar<TContext>;
+  wipe: IntentRegistrar<TContext>;
+}
+
+export type Intent = <TContext extends IntentContext = IntentContext>(
+  name: string,
+  define: (dsl: IntentDSL<TContext>) => void
+) => void;

package/index.js

@@ -0,0 +1,17 @@
+const { main } = require('./src/cli');
+const { collectAndRun } = require('./src/runtime');
+const { runTests } = require('./src/runner');
+const { discoverTests } = require('./src/discovery');
+const { loadConfig, initConfig, DEFAULT_CONFIG } = require('./src/config');
+const { expect } = require('./src/expect');
+
+module.exports = {
+  main,
+  collectAndRun,
+  runTests,
+  discoverTests,
+  loadConfig,
+  initConfig,
+  DEFAULT_CONFIG,
+  expect
+};

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "@vitronai/themis",
+  "version": "0.1.0-beta.0",
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vitron-ai/themis.git"
+  },
+  "homepage": "https://github.com/vitron-ai/themis#readme",
+  "bugs": {
+    "url": "https://github.com/vitron-ai/themis/issues"
+  },
+  "keywords": [
+    "testing",
+    "unit-test",
+    "test-runner",
+    "ai",
+    "agents",
+    "ai-agents",
+    "agentic",
+    "nodejs",
+    "typescript",
+    "tsx",
+    "esm",
+    "jsdom",
+    "react-testing",
+    "html-report",
+    "json-report",
+    "cli",
+    "verdict-engine",
+    "deterministic",
+    "rerun-failed",
+    "intent-dsl",
+    "node-test-runner"
+  ],
+  "type": "commonjs",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "require": "./index.js",
+      "default": "./index.js"
+    },
+    "./globals": {
+      "types": "./globals.d.ts",
+      "require": "./globals.js",
+      "default": "./globals.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "src/*.js",
+    "src/assets/*",
+    "docs",
+    "index.js",
+    "index.d.ts",
+    "globals.js",
+    "globals.d.ts",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "benchmark-gate.json"
+  ],
+  "bin": {
+    "themis": "bin/themis.js"
+  },
+  "scripts": {
+    "test": "node bin/themis.js test",
+    "validate": "npm test && npm run typecheck && npm run benchmark:gate",
+    "typecheck": "tsc -p tsconfig.json --pretty false",
+    "benchmark": "node scripts/benchmark.js",
+    "benchmark:gate": "node scripts/benchmark-gate.js",
+    "pack:check": "npm pack --dry-run",
+    "prepublishOnly": "npm test && npm run typecheck"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "jsdom": "^26.1.0",
+    "typescript": "^5.9.3"
+  }
+}

package/src/artifacts.js

@@ -0,0 +1,207 @@
+const fs = require('fs');
+const path = require('path');
+
+const ARTIFACT_DIR = '.themis';
+const LAST_RUN_FILE = 'last-run.json';
+const FAILED_TESTS_FILE = 'failed-tests.json';
+const RUN_DIFF_FILE = 'run-diff.json';
+const RUN_HISTORY_FILE = 'run-history.json';
+
+function writeRunArtifacts(cwd, result) {
+  const artifactDir = path.join(cwd, ARTIFACT_DIR);
+  fs.mkdirSync(artifactDir, { recursive: true });
+
+  const runPath = path.join(artifactDir, LAST_RUN_FILE);
+  const previousRun = readJsonIfExists(runPath);
+  const runId = createRunId(result.meta?.startedAt || new Date().toISOString());
+  const comparison = buildRunComparison(previousRun, result);
+  const relativePaths = {
+    lastRun: path.join(ARTIFACT_DIR, LAST_RUN_FILE),
+    failedTests: path.join(ARTIFACT_DIR, FAILED_TESTS_FILE),
+    runDiff: path.join(ARTIFACT_DIR, RUN_DIFF_FILE),
+    runHistory: path.join(ARTIFACT_DIR, RUN_HISTORY_FILE)
+  };
+
+  result.artifacts = {
+    runId,
+    comparison,
+    paths: relativePaths
+  };
+
+  fs.writeFileSync(runPath, `${stringifyArtifact(result)}\n`, 'utf8');
+
+  const failedTests = [];
+  for (const fileEntry of result.files || []) {
+    for (const test of fileEntry.tests || []) {
+      if (test.status !== 'failed') {
+        continue;
+      }
+      failedTests.push({
+        file: fileEntry.file,
+        name: test.name,
+        fullName: test.fullName,
+        durationMs: test.durationMs,
+        message: test.error ? test.error.message : '',
+        stack: test.error ? test.error.stack : ''
+      });
+    }
+  }
+
+  const failuresPayload = {
+    schema: 'themis.failures.v1',
+    runId,
+    createdAt: new Date().toISOString(),
+    summary: result.summary,
+    failedTests
+  };
+
+  const failuresPath = path.join(artifactDir, FAILED_TESTS_FILE);
+  fs.writeFileSync(failuresPath, `${stringifyArtifact(failuresPayload)}\n`, 'utf8');
+
+  const diffPayload = {
+    schema: 'themis.run.diff.v1',
+    runId,
+    ...comparison
+  };
+  const diffPath = path.join(artifactDir, RUN_DIFF_FILE);
+  fs.writeFileSync(diffPath, `${stringifyArtifact(diffPayload)}\n`, 'utf8');
+
+  const historyPath = path.join(artifactDir, RUN_HISTORY_FILE);
+  const previousHistory = readJsonIfExists(historyPath);
+  const nextHistory = Array.isArray(previousHistory) ? previousHistory.slice(-19) : [];
+  nextHistory.push({
+    runId,
+    startedAt: result.meta?.startedAt || '',
+    finishedAt: result.meta?.finishedAt || '',
+    summary: result.summary,
+    failedTests: failedTests.map((entry) => entry.fullName),
+    comparison
+  });
+  fs.writeFileSync(historyPath, `${stringifyArtifact(nextHistory)}\n`, 'utf8');
+
+  return {
+    runPath,
+    failuresPath,
+    diffPath,
+    historyPath,
+    failuresPayload,
+    comparison
+  };
+}
+
+function readFailedTestsArtifact(cwd) {
+  const failuresPath = path.join(cwd, ARTIFACT_DIR, FAILED_TESTS_FILE);
+  if (!fs.existsSync(failuresPath)) {
+    return null;
+  }
+
+  const raw = fs.readFileSync(failuresPath, 'utf8');
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    return {
+      failuresPath,
+      failedTests: [],
+      parseError: String(error?.message || error)
+    };
+  }
+
+  if (!parsed || !Array.isArray(parsed.failedTests)) {
+    return {
+      failuresPath,
+      failedTests: [],
+      parseError: 'Invalid artifact shape: expected "failedTests" to be an array'
+    };
+  }
+
+  return {
+    failuresPath,
+    failedTests: parsed.failedTests
+  };
+}
+
+function buildRunComparison(previousRun, result) {
+  const currentFailures = collectFailureNames(result);
+  const currentFailureSet = new Set(currentFailures);
+
+  if (!previousRun) {
+    return {
+      status: 'baseline',
+      previousRunId: '',
+      previousRunAt: '',
+      currentRunAt: result.meta?.startedAt || '',
+      delta: {
+        total: Number(result.summary?.total || 0),
+        passed: Number(result.summary?.passed || 0),
+        failed: Number(result.summary?.failed || 0),
+        skipped: Number(result.summary?.skipped || 0),
+        durationMs: roundDuration(result.summary?.durationMs || 0)
+      },
+      newFailures: currentFailures,
+      resolvedFailures: []
+    };
+  }
+
+  const previousFailures = collectFailureNames(previousRun);
+  const previousFailureSet = new Set(previousFailures);
+
+  return {
+    status: 'changed',
+    previousRunId: String(previousRun.artifacts?.runId || ''),
+    previousRunAt: String(previousRun.meta?.startedAt || ''),
+    currentRunAt: String(result.meta?.startedAt || ''),
+    delta: {
+      total: Number(result.summary?.total || 0) - Number(previousRun.summary?.total || 0),
+      passed: Number(result.summary?.passed || 0) - Number(previousRun.summary?.passed || 0),
+      failed: Number(result.summary?.failed || 0) - Number(previousRun.summary?.failed || 0),
+      skipped: Number(result.summary?.skipped || 0) - Number(previousRun.summary?.skipped || 0),
+      durationMs: roundDuration(Number(result.summary?.durationMs || 0) - Number(previousRun.summary?.durationMs || 0))
+    },
+    newFailures: currentFailures.filter((name) => !previousFailureSet.has(name)),
+    resolvedFailures: previousFailures.filter((name) => !currentFailureSet.has(name))
+  };
+}
+
+function collectFailureNames(result) {
+  const names = [];
+  for (const fileEntry of result.files || []) {
+    for (const test of fileEntry.tests || []) {
+      if (test.status === 'failed') {
+        names.push(test.fullName);
+      }
+    }
+  }
+  return names.sort();
+}
+
+function createRunId(startedAt) {
+  return String(startedAt || '')
+    .replace(/[:.]/g, '-')
+    .replace(/[^a-zA-Z0-9_-]/g, '');
+}
+
+function readJsonIfExists(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    return null;
+  }
+}
+
+function roundDuration(value) {
+  return Math.round(Number(value || 0) * 100) / 100;
+}
+
+function stringifyArtifact(value) {
+  return JSON.stringify(value);
+}
+
+module.exports = {
+  writeRunArtifacts,
+  readFailedTestsArtifact
+};