@vitronai/themis 0.1.0-beta.0

package/src/snapshots.js

@@ -0,0 +1,90 @@
+const fs = require('fs');
+const path = require('path');
+const util = require('util');
+
+function createSnapshotState(filePath, options = {}) {
+  const snapshotDir = path.join(path.dirname(filePath), '__snapshots__');
+  const snapshotFile = path.join(snapshotDir, `${path.basename(filePath)}.snapshots.json`);
+  const existing = readSnapshotFile(snapshotFile);
+  const nextSnapshots = { ...existing };
+  const counters = new Map();
+  let dirty = false;
+  let currentTestName = null;
+
+  return {
+    setCurrentTestName(testName) {
+      currentTestName = testName;
+    },
+    clearCurrentTestName() {
+      currentTestName = null;
+    },
+    matchSnapshot(received, snapshotName) {
+      if (!currentTestName) {
+        throw new Error('toMatchSnapshot() must be called while a test is running');
+      }
+
+      const baseKey = snapshotName
+        ? `${currentTestName}: ${String(snapshotName)}`
+        : currentTestName;
+      const nextIndex = (counters.get(baseKey) || 0) + 1;
+      counters.set(baseKey, nextIndex);
+      const snapshotKey = nextIndex === 1 ? baseKey : `${baseKey} (${nextIndex})`;
+      const serialized = serializeSnapshot(received);
+
+      if (!Object.prototype.hasOwnProperty.call(existing, snapshotKey)) {
+        nextSnapshots[snapshotKey] = serialized;
+        dirty = true;
+        return;
+      }
+
+      if (existing[snapshotKey] !== serialized) {
+        if (options.updateSnapshots) {
+          nextSnapshots[snapshotKey] = serialized;
+          dirty = true;
+          return;
+        }
+
+        throw new Error(
+          `Snapshot mismatch for ${snapshotKey}\n\nExpected:\n${existing[snapshotKey]}\n\nReceived:\n${serialized}`
+        );
+      }
+    },
+    save() {
+      if (!dirty) {
+        return null;
+      }
+
+      fs.mkdirSync(snapshotDir, { recursive: true });
+      fs.writeFileSync(snapshotFile, `${JSON.stringify(nextSnapshots, null, 2)}\n`, 'utf8');
+      return snapshotFile;
+    },
+    path: snapshotFile
+  };
+}
+
+function readSnapshotFile(snapshotFile) {
+  if (!fs.existsSync(snapshotFile)) {
+    return {};
+  }
+
+  return JSON.parse(fs.readFileSync(snapshotFile, 'utf8'));
+}
+
+function serializeSnapshot(value) {
+  if (typeof value === 'string') {
+    return value;
+  }
+
+  return util.inspect(value, {
+    depth: 20,
+    colors: false,
+    sorted: true,
+    compact: false,
+    breakLength: 80,
+    maxArrayLength: null
+  });
+}
+
+module.exports = {
+  createSnapshotState
+};

package/src/stability.js

@@ -0,0 +1,98 @@
+function buildStabilityReport(runResults) {
+  if (!Array.isArray(runResults) || runResults.length === 0) {
+    return {
+      runs: 0,
+      summary: {
+        stablePass: 0,
+        stableFail: 0,
+        unstable: 0
+      },
+      tests: []
+    };
+  }
+
+  const runCount = runResults.length;
+  const byKey = new Map();
+
+  for (let runIndex = 0; runIndex < runCount; runIndex += 1) {
+    const result = runResults[runIndex] || {};
+    const files = Array.isArray(result.files) ? result.files : [];
+    for (const file of files) {
+      const tests = Array.isArray(file.tests) ? file.tests : [];
+      for (const test of tests) {
+        if (test.status === 'skipped') {
+          continue;
+        }
+
+        const key = `${file.file}::${test.fullName}`;
+        let entry = byKey.get(key);
+        if (!entry) {
+          entry = {
+            file: file.file,
+            testName: test.name,
+            fullName: test.fullName,
+            statuses: new Array(runCount).fill('missing')
+          };
+          byKey.set(key, entry);
+        }
+        entry.statuses[runIndex] = test.status;
+      }
+    }
+  }
+
+  const tests = [...byKey.values()].map((entry) => {
+    const classification = classifyStability(entry.statuses);
+    return {
+      file: entry.file,
+      testName: entry.testName,
+      fullName: entry.fullName,
+      statuses: entry.statuses,
+      classification
+    };
+  });
+
+  tests.sort((a, b) => {
+    const fileCompare = a.file.localeCompare(b.file);
+    if (fileCompare !== 0) {
+      return fileCompare;
+    }
+    return a.fullName.localeCompare(b.fullName);
+  });
+
+  const summary = {
+    stablePass: tests.filter((entry) => entry.classification === 'stable_pass').length,
+    stableFail: tests.filter((entry) => entry.classification === 'stable_fail').length,
+    unstable: tests.filter((entry) => entry.classification === 'unstable').length
+  };
+
+  return {
+    runs: runCount,
+    summary,
+    tests
+  };
+}
+
+function classifyStability(statuses) {
+  if (!Array.isArray(statuses) || statuses.length === 0) {
+    return 'unstable';
+  }
+  if (statuses.every((status) => status === 'passed')) {
+    return 'stable_pass';
+  }
+  if (statuses.every((status) => status === 'failed')) {
+    return 'stable_fail';
+  }
+  return 'unstable';
+}
+
+function hasStabilityBreaches(report) {
+  if (!report || !report.summary) {
+    return false;
+  }
+  return report.summary.stableFail > 0 || report.summary.unstable > 0;
+}
+
+module.exports = {
+  buildStabilityReport,
+  hasStabilityBreaches
+};

package/src/test-utils.js

@@ -0,0 +1,201 @@
+const path = require('path');
+const util = require('util');
+
+function createTestUtils(options = {}) {
+  const activeMocks = new Set();
+  const activeSpies = new Set();
+  const moduleLoader = options.moduleLoader;
+
+  function fn(implementation) {
+    const mockFn = createMockFunction(implementation);
+    activeMocks.add(mockFn);
+    return mockFn;
+  }
+
+  function spyOn(target, methodName) {
+    if (!target || typeof target !== 'object') {
+      throw new Error('spyOn expects an object target');
+    }
+
+    const original = target[methodName];
+    if (typeof original !== 'function') {
+      throw new Error(`spyOn expects ${String(methodName)} to be a function`);
+    }
+
+    const spy = fn(function spiedMethod(...args) {
+      return original.apply(this, args);
+    });
+
+    spy.mockRestore = () => {
+      target[methodName] = original;
+      activeSpies.delete(spy);
+      return spy;
+    };
+
+    target[methodName] = spy;
+    activeSpies.add(spy);
+    return spy;
+  }
+
+  function mock(request, factoryOrExports) {
+    if (!moduleLoader) {
+      throw new Error('mock(...) is unavailable outside the Themis runtime');
+    }
+
+    const callerFile = resolveCallerFile();
+    const normalizedFactory = factoryOrExports === undefined ? {} : factoryOrExports;
+    moduleLoader.registerMock(request, callerFile, normalizedFactory);
+  }
+
+  function unmock(request) {
+    if (!moduleLoader) {
+      throw new Error('unmock(...) is unavailable outside the Themis runtime');
+    }
+
+    const callerFile = resolveCallerFile();
+    moduleLoader.unregisterMock(request, callerFile);
+  }
+
+  function clearAllMocks() {
+    for (const mockFn of activeMocks) {
+      mockFn.mockClear();
+    }
+  }
+
+  function resetAllMocks() {
+    for (const mockFn of activeMocks) {
+      mockFn.mockReset();
+    }
+
+    if (moduleLoader) {
+      moduleLoader.clearModuleMocks();
+    }
+  }
+
+  function restoreAllMocks() {
+    for (const spy of [...activeSpies]) {
+      if (typeof spy.mockRestore === 'function') {
+        spy.mockRestore();
+      }
+    }
+  }
+
+  return {
+    fn,
+    spyOn,
+    mock,
+    unmock,
+    clearAllMocks,
+    resetAllMocks,
+    restoreAllMocks
+  };
+}
+
+function createMockFunction(implementation) {
+  const state = {
+    calls: [],
+    results: [],
+    implementation: implementation
+  };
+
+  function mockFn(...args) {
+    state.calls.push(args);
+    try {
+      const value = state.implementation ? state.implementation.apply(this, args) : undefined;
+      state.results.push({ type: 'return', value });
+      return value;
+    } catch (error) {
+      state.results.push({ type: 'throw', value: error });
+      throw error;
+    }
+  }
+
+  Object.defineProperty(mockFn, '_isThemisMockFunction', {
+    configurable: false,
+    enumerable: false,
+    writable: false,
+    value: true
+  });
+
+  mockFn.mock = state;
+  mockFn.mockImplementation = (nextImplementation) => {
+    state.implementation = nextImplementation;
+    return mockFn;
+  };
+  mockFn.mockReturnValue = (value) => {
+    state.implementation = () => value;
+    return mockFn;
+  };
+  mockFn.mockResolvedValue = (value) => {
+    state.implementation = () => Promise.resolve(value);
+    return mockFn;
+  };
+  mockFn.mockRejectedValue = (value) => {
+    state.implementation = () => Promise.reject(value);
+    return mockFn;
+  };
+  mockFn.mockClear = () => {
+    state.calls.length = 0;
+    state.results.length = 0;
+    return mockFn;
+  };
+  mockFn.mockReset = () => {
+    state.calls.length = 0;
+    state.results.length = 0;
+    state.implementation = undefined;
+    return mockFn;
+  };
+  mockFn.getMockName = () => 'themis.fn';
+
+  return mockFn;
+}
+
+function isMockFunction(value) {
+  return Boolean(value && value._isThemisMockFunction);
+}
+
+function formatMockCalls(value) {
+  if (!isMockFunction(value)) {
+    return format(value);
+  }
+  return format(value.mock.calls);
+}
+
+function resolveCallerFile() {
+  const stack = String(new Error().stack || '').split('\n').slice(2);
+  for (const line of stack) {
+    const match = line.match(/\((.+?):\d+:\d+\)$/) || line.match(/at (.+?):\d+:\d+$/);
+    if (!match) {
+      continue;
+    }
+
+    const candidate = match[1];
+    if (candidate.startsWith('node:')) {
+      continue;
+    }
+
+    const normalized = candidate.replace(/\\/g, '/');
+    if (
+      normalized.endsWith('/src/test-utils.js') ||
+      normalized.endsWith('/src/runtime.js') ||
+      normalized.endsWith('/src/expect.js')
+    ) {
+      continue;
+    }
+
+    return candidate;
+  }
+
+  return path.join(process.cwd(), '__themis_unknown_caller__.js');
+}
+
+function format(value) {
+  return util.inspect(value, { depth: 5, colors: false, maxArrayLength: 20 });
+}
+
+module.exports = {
+  createTestUtils,
+  createMockFunction,
+  isMockFunction,
+  formatMockCalls
+};

package/src/verdict.js

@@ -0,0 +1,71 @@
+async function verdictReveal(options = {}) {
+  const {
+    ok = true,
+    stream = process.stdout,
+    title = 'VERDICT',
+    detail = ok ? 'TRUTH UPHELD' : 'TRUTH VIOLATED',
+    delayMs = 120
+  } = options;
+
+  if (!canReveal(stream)) {
+    return;
+  }
+
+  const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+  const frames = ok
+    ? [
+        '⚖️  [=    ]',
+        '⚖️  [==   ]',
+        '⚖️  [===  ]',
+        '⚖️  [==== ]',
+        '⚖️  [=====]'
+      ]
+    : [
+        '⚖️  [==== ]',
+        '⚖️  [===  ]',
+        '⚖️  [==   ]',
+        '⚖️  [=    ]',
+        '⚖️  [     ]'
+      ];
+
+  const waitMs = normalizeDelay(delayMs);
+
+  stream.write('\x1B[?25l');
+  try {
+    for (const frame of frames) {
+      stream.write(`\r${frame}  ${title}`);
+      await sleep(waitMs);
+    }
+    stream.write(`\r${ok ? '✔' : '✖'}  ${title}: ${detail}\n`);
+  } finally {
+    stream.write('\x1B[?25h');
+  }
+}
+
+function canReveal(stream) {
+  if (!stream || typeof stream.write !== 'function') {
+    return false;
+  }
+  if (!stream.isTTY) {
+    return false;
+  }
+  if (process.env.NO_COLOR) {
+    return false;
+  }
+  if (process.env.THEMIS_NO_REVEAL === '1') {
+    return false;
+  }
+  return true;
+}
+
+function normalizeDelay(value) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    return 120;
+  }
+  return parsed;
+}
+
+module.exports = {
+  verdictReveal
+};

package/src/watch.js

@@ -0,0 +1,154 @@
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+
+const WATCHABLE_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx', '.json', '.mjs', '.cjs', '.mts', '.cts']);
+const IGNORED_DIRECTORIES = new Set(['node_modules', '.git', '.themis']);
+
+function stripWatchFlags(args) {
+  return args.filter((token) => token !== '--watch' && token !== '-w');
+}
+
+function collectWatchSignature(cwd) {
+  const entries = [];
+  walkWatchTree(path.resolve(cwd), entries);
+  return entries.sort();
+}
+
+function hasWatchSignatureChanged(previousSignature, nextSignature) {
+  if (previousSignature.length !== nextSignature.length) {
+    return true;
+  }
+
+  for (let i = 0; i < previousSignature.length; i += 1) {
+    if (previousSignature[i] !== nextSignature[i]) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+async function runWatchMode(options) {
+  const cwd = path.resolve(options.cwd || process.cwd());
+  const cliArgs = stripWatchFlags(options.cliArgs || []);
+  const cliPath = path.join(__dirname, '..', 'bin', 'themis.js');
+  const pollIntervalMs = Number(options.pollIntervalMs) > 0 ? Number(options.pollIntervalMs) : 400;
+  let previousSignature = collectWatchSignature(cwd);
+  let running = false;
+  let stopped = false;
+  let intervalId = null;
+  let activeChild = null;
+  let resolveStop = null;
+  const stopPromise = new Promise((resolve) => {
+    resolveStop = resolve;
+  });
+
+  const runOnce = () => new Promise((resolve, reject) => {
+    activeChild = spawn(process.execPath, [cliPath, 'test', ...cliArgs], {
+      cwd,
+      stdio: 'inherit',
+      env: process.env
+    });
+
+    let settled = false;
+    const finish = (handler) => (value) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      activeChild = null;
+      handler(value);
+      if (stopped && resolveStop) {
+        resolveStop();
+      }
+    };
+
+    activeChild.once('error', finish(reject));
+    activeChild.once('exit', () => {
+      finish(resolve)();
+    });
+  });
+
+  const shutdown = () => {
+    if (stopped) {
+      return;
+    }
+
+    stopped = true;
+    if (intervalId) {
+      clearInterval(intervalId);
+      intervalId = null;
+    }
+
+    process.removeListener('SIGINT', shutdown);
+    process.removeListener('SIGTERM', shutdown);
+
+    if (activeChild && !activeChild.killed) {
+      activeChild.kill('SIGINT');
+    } else if (resolveStop) {
+      resolveStop();
+    }
+
+    process.stdout.write('\nWatch mode stopped.\n');
+  };
+
+  process.once('SIGINT', shutdown);
+  process.once('SIGTERM', shutdown);
+
+  await runOnce();
+  process.stdout.write('\nWatching for changes...\n');
+
+  intervalId = setInterval(async () => {
+    if (running || stopped) {
+      return;
+    }
+
+    const nextSignature = collectWatchSignature(cwd);
+    if (!hasWatchSignatureChanged(previousSignature, nextSignature)) {
+      return;
+    }
+
+    previousSignature = nextSignature;
+    running = true;
+    process.stdout.write('\nChange detected. Re-running...\n');
+    await runOnce();
+    process.stdout.write('\nWatching for changes...\n');
+    running = false;
+  }, pollIntervalMs);
+
+  await stopPromise;
+}
+
+function walkWatchTree(dir, entries) {
+  const dirEntries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of dirEntries) {
+    if (entry.isDirectory()) {
+      if (IGNORED_DIRECTORIES.has(entry.name) || entry.name === '__snapshots__') {
+        continue;
+      }
+      walkWatchTree(path.join(dir, entry.name), entries);
+      continue;
+    }
+
+    if (!entry.isFile()) {
+      continue;
+    }
+
+    const extension = path.extname(entry.name);
+    if (!WATCHABLE_EXTENSIONS.has(extension)) {
+      continue;
+    }
+
+    const targetPath = path.join(dir, entry.name);
+    const stats = fs.statSync(targetPath);
+    entries.push(`${targetPath}:${Math.round(stats.mtimeMs)}:${stats.size}`);
+  }
+}
+
+module.exports = {
+  collectWatchSignature,
+  hasWatchSignatureChanged,
+  runWatchMode,
+  stripWatchFlags
+};

package/src/worker.js

@@ -0,0 +1,26 @@
+const { parentPort, workerData } = require('worker_threads');
+const { collectAndRun } = require('./runtime');
+
+(async () => {
+  try {
+    const result = await collectAndRun(workerData.file, {
+      match: workerData.match,
+      allowedFullNames: workerData.allowedFullNames,
+      noMemes: workerData.noMemes,
+      cwd: workerData.cwd,
+      environment: workerData.environment,
+      setupFiles: workerData.setupFiles,
+      tsconfigPath: workerData.tsconfigPath,
+      updateSnapshots: workerData.updateSnapshots
+    });
+    parentPort.postMessage({ ok: true, result });
+  } catch (error) {
+    parentPort.postMessage({
+      ok: false,
+      error: {
+        message: String(error?.message || error),
+        stack: String(error?.stack || error)
+      }
+    });
+  }
+})();