@vitronai/themis 0.1.0-beta.0

package/docs/schemas/agent-result.v1.json

@@ -0,0 +1,277 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/vitron-ai/themis/docs/schemas/agent-result.v1.json",
+  "title": "Themis Agent Result v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "meta", "summary", "failures", "artifacts", "analysis", "hints"],
+  "properties": {
+    "schema": {
+      "type": "string",
+      "const": "themis.agent.result.v1"
+    },
+    "meta": {
+      "$ref": "#/$defs/meta"
+    },
+    "summary": {
+      "$ref": "#/$defs/summary"
+    },
+    "failures": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/failure"
+      }
+    },
+    "artifacts": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["lastRun", "failedTests", "runDiff", "runHistory"],
+      "properties": {
+        "lastRun": {
+          "type": "string"
+        },
+        "failedTests": {
+          "type": "string"
+        },
+        "runDiff": {
+          "type": "string"
+        },
+        "runHistory": {
+          "type": "string"
+        }
+      }
+    },
+    "analysis": {
+      "$ref": "#/$defs/analysis"
+    },
+    "hints": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["rerunFailed", "targetedRerun", "updateSnapshots", "diffLastRun"],
+      "properties": {
+        "rerunFailed": {
+          "type": "string"
+        },
+        "targetedRerun": {
+          "type": "string"
+        },
+        "updateSnapshots": {
+          "type": "string"
+        },
+        "diffLastRun": {
+          "type": "string"
+        }
+      }
+    }
+  },
+  "$defs": {
+    "meta": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["startedAt", "finishedAt", "maxWorkers"],
+      "properties": {
+        "startedAt": {
+          "type": "string"
+        },
+        "finishedAt": {
+          "type": "string"
+        },
+        "maxWorkers": {
+          "type": "number"
+        }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["total", "passed", "failed", "skipped", "durationMs"],
+      "properties": {
+        "total": {
+          "type": "number"
+        },
+        "passed": {
+          "type": "number"
+        },
+        "failed": {
+          "type": "number"
+        },
+        "skipped": {
+          "type": "number"
+        },
+        "durationMs": {
+          "type": "number"
+        }
+      }
+    },
+    "failure": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["file", "testName", "fullName", "durationMs", "message", "stack", "fingerprint"],
+      "properties": {
+        "file": {
+          "type": "string"
+        },
+        "testName": {
+          "type": "string"
+        },
+        "fullName": {
+          "type": "string"
+        },
+        "durationMs": {
+          "type": "number"
+        },
+        "message": {
+          "type": "string"
+        },
+        "stack": {
+          "type": "string"
+        },
+        "fingerprint": {
+          "type": "string"
+        }
+      }
+    },
+    "analysis": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["fingerprintVersion", "failureClusters", "stability", "comparison"],
+      "properties": {
+        "fingerprintVersion": {
+          "type": "string",
+          "const": "fnv1a32-message-v1"
+        },
+        "failureClusters": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/failureCluster"
+          }
+        },
+        "stability": {
+          "$ref": "#/$defs/stability"
+        },
+        "comparison": {
+          "$ref": "#/$defs/comparison"
+        }
+      }
+    },
+    "failureCluster": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["fingerprint", "count", "message", "tests"],
+      "properties": {
+        "fingerprint": {
+          "type": "string"
+        },
+        "count": {
+          "type": "number"
+        },
+        "message": {
+          "type": "string"
+        },
+        "tests": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "stability": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["runs", "summary", "tests"],
+      "properties": {
+        "runs": {
+          "type": "number"
+        },
+        "summary": {
+          "$ref": "#/$defs/stabilitySummary"
+        },
+        "tests": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/stabilityTest"
+          }
+        }
+      }
+    },
+    "stabilitySummary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["stablePass", "stableFail", "unstable"],
+      "properties": {
+        "stablePass": {
+          "type": "number"
+        },
+        "stableFail": {
+          "type": "number"
+        },
+        "unstable": {
+          "type": "number"
+        }
+      }
+    },
+    "stabilityTest": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["file", "testName", "fullName", "statuses", "classification"],
+      "properties": {
+        "file": {
+          "type": "string"
+        },
+        "testName": {
+          "type": "string"
+        },
+        "fullName": {
+          "type": "string"
+        },
+        "statuses": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["passed", "failed", "missing"]
+          }
+        },
+        "classification": {
+          "type": "string",
+          "enum": ["stable_pass", "stable_fail", "unstable"]
+        }
+      }
+    },
+    "comparison": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "previousRunId", "previousRunAt", "currentRunAt", "delta", "newFailures", "resolvedFailures"],
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": ["baseline", "changed"]
+        },
+        "previousRunId": {
+          "type": "string"
+        },
+        "previousRunAt": {
+          "type": "string"
+        },
+        "currentRunAt": {
+          "type": "string"
+        },
+        "delta": {
+          "$ref": "#/$defs/summary"
+        },
+        "newFailures": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "resolvedFailures": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

package/docs/schemas/failures.v1.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/vitron-ai/themis/docs/schemas/failures.v1.json",
+  "title": "Themis Failures Artifact v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "runId", "createdAt", "summary", "failedTests"],
+  "properties": {
+    "schema": {
+      "type": "string",
+      "const": "themis.failures.v1"
+    },
+    "runId": {
+      "type": "string"
+    },
+    "createdAt": {
+      "type": "string"
+    },
+    "summary": {
+      "$ref": "#/$defs/summary"
+    },
+    "failedTests": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/failedTest"
+      }
+    }
+  },
+  "$defs": {
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["total", "passed", "failed", "skipped", "durationMs"],
+      "properties": {
+        "total": {
+          "type": "number"
+        },
+        "passed": {
+          "type": "number"
+        },
+        "failed": {
+          "type": "number"
+        },
+        "skipped": {
+          "type": "number"
+        },
+        "durationMs": {
+          "type": "number"
+        }
+      }
+    },
+    "failedTest": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["file", "name", "fullName", "durationMs", "message", "stack"],
+      "properties": {
+        "file": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string"
+        },
+        "fullName": {
+          "type": "string"
+        },
+        "durationMs": {
+          "type": "number"
+        },
+        "message": {
+          "type": "string"
+        },
+        "stack": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

package/docs/vscode-extension.md

@@ -0,0 +1,40 @@
+# VS Code Extension
+
+Themis includes an in-repo VS Code extension scaffold at [`packages/themis-vscode`](../packages/themis-vscode).
+
+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
+- failure navigation that jumps from artifact data into the source file
+
+## Current MVP Scope
+
+The scaffold currently supports:
+
+- reading `.themis/last-run.json`
+- reading `.themis/failed-tests.json`
+- reading `.themis/run-diff.json`
+- opening `.themis/report.html` in a webview
+- refreshing when `.themis/*` files change
+
+The extension is intentionally thin. It shells out to Themis commands and treats the CLI plus artifacts as the canonical contract.
+
+## Local Development
+
+Open the repository in VS Code and use an Extension Development Host pointed at:
+
+`packages/themis-vscode`
+
+The extension does not need marketplace publishing to be exercised locally.
+
+## Publishing Later
+
+When you decide to publish:
+
+1. create a VS Code publisher
+2. package the extension under `packages/themis-vscode`
+3. publish it separately from the npm package
+
+The npm package and the VS Code extension should version together, but they do not need to ship from the same registry.

package/docs/why-themis.md

@@ -0,0 +1,111 @@
+# Why Themis
+
+Themis is built for AI-era testing loops where humans and agents both need reliable signals, fast reruns, and machine-readable context.
+
+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
+
+## What "Next-Gen" Means Here
+
+Next-gen is not styling. It means test infrastructure designed for:
+
+- deterministic execution
+- agent-native output contracts
+- explicit intent modeling
+- performance accountability
+
+## Why It Can Be Best-in-Class
+
+## 1) Intent-First Test Design
+
+The `intent(...)` DSL makes behavior explicit through ordered phases:
+
+- `context`
+- `run`
+- `verify`
+- `cleanup`
+
+This gives agents and humans a clearer semantic map than flat assertion blocks.
+Legacy aliases (`arrange/act/assert`, `given/when/then`) remain available for compatibility.
+
+## 2) Agent-Native Outputs
+
+Themis supports structured outputs for tooling loops:
+
+- `--json` for generic automation
+- `--agent` for AI-agent workflows
+- `.themis/failed-tests.json` for deterministic reruns
+
+## 3) Deterministic Rerun Workflow
+
+`--rerun-failed`, `--watch`, and test-name filtering (`--match`) reduce iteration time and keep failure focus tight.
+
+## 4) Modern JS/TS Project Parity
+
+Themis is built for current Node.js and TypeScript repos:
+
+- `.js`, `.jsx`, `.ts`, `.tsx`
+- ESM `.js` in `type: "module"` projects
+- `tsconfig` path aliases
+- `node` and `jsdom` environments
+- `setupFiles` for project harness bootstrapping
+
+## 5) Strong Runtime Guarantees
+
+The runtime enforces intent ordering rules and clear phase-level failure annotation, reducing ambiguous failures.
+
+## 6) TypeScript-Ready Without Runtime Tax
+
+Themis keeps a lean JS runtime and ships first-party typings:
+
+- package API types (`index.d.ts`)
+- global test API types (`globals.d.ts`)
+- typecheck lane (`npm run typecheck`)
+
+## 7) First-Party Agent Loop Utilities
+
+Themis ships workflow features agents can use directly:
+
+- snapshots with `toMatchSnapshot()`
+- 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
+
+Performance is measured and guarded:
+
+- synthetic benchmark runner (`npm run benchmark`)
+- regression gate (`npm run benchmark:gate`)
+- threshold config (`benchmark-gate.json`)
+
+## 9) 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
+
+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.
+
+## Proof Checklist
+
+Run these to validate core claims:
+
+```bash
+npm test
+npm run typecheck
+npm run benchmark:gate
+```
+
+## Messaging for the Community
+
+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"
+- "JS-fast runtime with first-party TypeScript DX and benchmark-gated discipline"

package/globals.d.ts

@@ -0,0 +1,22 @@
+import type { Describe, Expect, Fn, Hook, Intent, MockControl, MockModule, SpyOn, Test } from './index';
+
+declare global {
+  var describe: Describe;
+  var test: Test;
+  var it: Test;
+  var intent: Intent;
+  var beforeAll: Hook;
+  var beforeEach: Hook;
+  var afterEach: Hook;
+  var afterAll: Hook;
+  var expect: Expect;
+  var fn: Fn;
+  var spyOn: SpyOn;
+  var mock: MockModule;
+  var unmock: MockModule;
+  var clearAllMocks: MockControl;
+  var resetAllMocks: MockControl;
+  var restoreAllMocks: MockControl;
+}
+
+export {};

package/globals.js

@@ -0,0 +1 @@
+module.exports = {};