@mantaq/inspect 0.3.0 → 0.5.0

package/README.md

@@ -1,16 +1,12 @@
 # @mantaq/inspect
 
-Turns your Mantaq machine into a picture you can walk: one command, no config.
+Turns your Mantaq machine into a picture you can walk: add the Vite plugin, no other config.
 
-```sh
-mantaq-inspect src/cart.ts     # writes mantaq-viz.html and opens it
-```
-
-It finds every exported actor, or function that builds one, from the file's types. It reads handler explanations and sample payloads from the source, fuzzes each machine that runs on a `VirtualClock`, and writes one self-contained HTML page that works offline: commit it, attach it to a PR. The viewer is [`@mantaq/viz`](../viz/README.md).
+It finds every exported actor, or function that builds one, from the file's types. It reads handler explanations and sample payloads from the source, fuzzes each machine that runs on a `VirtualClock`, and shows them in a live page on your Vite dev server. The viewer is [`@mantaq/viz`](../viz/README.md).
 
-## Three ways in
+## Ways in
 
-**CLI**: `mantaq-inspect <file.ts>... [--out FILE] [--json] [--live] [--no-fuzz] [--iterations N] [--config FILE] [--mode MODE] [--no-open] [--check]`. `--config` loads the files with that Vite config (env, aliases, plugins) and `--mode` picks its mode; without `--config` no project config is read. `--check` exits 1 if a warning was printed or fuzzing found a handler error (printed as `error:`), so CI can gate on design errors. `--json` writes the viz document instead of the page. `--live` bundles your machine files into the page with Vite, so it is still one offline HTML file but its steps run the real actors (same rules as the Vite plugin's live page); it cannot be combined with `--json`. Seed: `MANTAQ_SEED` (default from `@mantaq/pbt`). Same seed → same output.
+**Gate in tests**: see the docs page "Design gate in vitest" for `expectNoDesignErrors`, `expectReached` and `expectAllStatesReached`.
 
 **Vite plugin**: a live page on your dev server that redraws, keeping your walk, when you save.
 
@@ -26,6 +22,8 @@ export default defineConfig({
 
 The live page runs the real actor, so it needs an exported factory on a `VirtualClock`; instance or `RealClock` machines fall back to the static walk.
 
+`vite build` with the plugin also writes the page as a static site: `index.html`, `viz.json` and a script under `base` (set `base: "/"` to put them at the output root). Machines load through your Vite config, and the fuzz runs at build time.
+
 Options: `base` (default `/__mantaq/`), `fuzz` (`false`, or `{ seed, iterations }`; default 500 iterations so a save redraws fast).
 
 **Library**: one call per machine.
@@ -38,19 +36,21 @@ const { machine, warnings } = inspect({
   id: "cart",
   create: () => createCart(), // a fresh actor every call
   source: { file: "/abs/src/cart.ts", root: "/abs" }, // optional: explanations + payloads from types
-  tests: [[{ kind: "event", event: "addItem", payload: { sku: "A1" } }]], // optional: "example tests" coverage
+  tests: [
+    { name: "add an item", steps: [{ kind: "event", event: "addItem", payload: { sku: "A1" } }] },
+  ], // optional: named runs for "example tests" coverage
 });
 const json = serializeViz(vizDocument([machine]));
 ```
 
-`inspectFile(file)` / `inspectModule(file, { load })` do the discovery the CLI does. The building blocks (`toVizMachine`, `annotateMachine`, `fuzz`, `fuzzedMachine`, `withTestCoverage`, `guidance`) stay exported for custom pipelines.
+`inspectFile(file)` / `inspectModule(file, { load })` do the discovery the Vite plugin does, and read recorded runs from `__runs__/*.json` next to the machine file (`{ [machineId]: { name, end, steps }[] }`). A run is replayed on a fresh actor; internal events the replay already produces (timers, synchronous emits) are dropped, and a run that replays to a different state than `end` is dropped with a warning. The building blocks (`toVizMachine`, `annotateMachine`, `fuzz`, `fuzzedMachine`, `withTestCoverage`, `guidance`) stay exported for custom pipelines.
 
 ## What it needs from your file
 
 - **Exports.** An actor, or a function that returns one (or `{ actor }`). Functions are called with no arguments, with a `VirtualClock` when the first parameter is a clock, or with `{ clock }` when it is an options object with a `clock`. Functions with other required parameters are skipped. Discovery reads types only; nothing is called to find out.
 - **A fresh actor per call**, to fuzz. A file that only exports one actor instance is drawn, not fuzzed. When a file has factories, its actor instances are skipped.
 - **Exported factories.** Export a factory that takes ports and a clock, not only a built instance. See [Machines in an application](https://anderscan.github.io/mantaq/guides/machines-in-an-app/).
-- **A factory, for `--live`.** The live page recreates the actor on every step, so it needs an exported factory; a file that only exports an instance stays a static walk, with the usual warning.
+- **A factory, for the live page.** The page recreates the actor on every step, so it needs an exported factory; a file that only exports an instance stays a static walk, with the usual warning.
 - **A `VirtualClock`**, to fuzz. An actor on the real clock is drawn, with a warning.
 
 Every part that cannot run is skipped with a warning, never guessed.
@@ -59,7 +59,8 @@ Every part that cannot run is skipped with a warning, never guessed.
 
 The viewer's "Coverage from" picker dims elements with zero hits. What dimmed means depends on the source:
 
-- **example tests** (`tested`): no test exercises this. Collected by replaying the event sequences you pass as `tests`, each on a fresh actor.
+- **examples + fuzz** (`reached`): neither an example nor fuzzing reached this. The default when both sources are present, and the same merge `expectReached` uses. Fix a miss by adding an example to `tests`.
+- **example tests** (`tested`): no test exercises this. Collected by replaying the named runs you pass as `tests`, each on a fresh actor.
 - **fuzz runs** (`coverage`): no fuzz run produced this. Fuzzing reaches almost everything, so little is dimmed. What does stay dimmed is usually a **declared but unreached edge**: the handler lists the target in `to`, but its guards may never allow it. Saga's `compensatingRefund -REFUND_DONE-> failed` is an example. The edge panel calls these out. Fuzzing is not proof, so check the handler.
 
 ## How each tool works
@@ -74,6 +75,18 @@ The viewer's "Coverage from" picker dims elements with zero hits. What dimmed me
 
 **Guidance** (`guidance`, Phase 5): literal seeding plus a branch-distance guide built from AST comparisons on payload and context. It helps when handlers compare payload fields against literals far from the samples, or count in context toward a threshold. See `docs/atlas/phase5-comparison.md`.
 
+## Record runs from your tests
+
+In a vitest file, wrap the factory once and your tests become runs:
+
+```ts
+import { recordRuns } from "@mantaq/inspect/record";
+
+const make = recordRuns(createInviteLinkActor);
+```
+
+Every passing test that builds an actor with `make` writes its events and clock moves to `__runs__/<test file>.json` next to the test, keyed by machine id. `inspectModule` and the Vite plugin read those files, so each test shows up in the live page's Runs list and counts as an example run. Run the whole test file to refresh it. With `CI` set, a run that differs from the committed file fails the test, like a stale snapshot. The factory may be called in the test or in `beforeEach`; a retried test is recorded once. Runs with a payload that does not survive JSON (functions, `bigint`, `Map`, class instances) are skipped with a warning. `vitest` is an optional peer dependency.
+
 ## What it cannot show
 
 - **Guards** are not evaluated. A declared edge says "the handler may return this", not "some input reaches it". Fuzz coverage and the AST's branch conditions are the evidence; neither is proof.

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { a as eventCatalog, i as Trace, n as Observation, o as execute, r as RunError, t as FuzzTarget } from "./run-BLt0mwXe.mjs";
-import { a as ModuleOptions, c as machineId, i as InspectedModule, l as vizDocument, n as InspectTarget, o as inspect, r as Inspected, s as inspectModule, t as FuzzSettings, u as AnalysisSource } from "./inspect-DvQtAcwv.mjs";
+import { a as ModuleOptions, c as machineId, i as InspectedModule, l as vizDocument, n as InspectTarget, o as inspect, r as Inspected, s as inspectModule, t as FuzzSettings, u as AnalysisSource } from "./inspect-vSdt2qtL.mjs";
 import { VizComparison, VizDocument, VizExplanation, VizFuzzError, VizJson, VizMachine, VizStep } from "@mantaq/viz";
 import { History } from "@mantaq/traversal";
 import { Either } from "@mantaq/utils";
@@ -37,6 +37,8 @@ interface FuzzOptions {
    * the run in the corpus as a stepping stone even without new coverage.
    */
   guide?: (trace: Trace) => boolean;
+  /** Known-good sequences (e.g. example tests) the corpus starts from, before any mutation. */
+  initial?: ReadonlyArray<ReadonlyArray<VizStep>>;
 }
 interface CorpusEntry {
   steps: VizStep[];
@@ -149,8 +151,39 @@ interface LoadOptions {
 /** Load `file` with Vite (TS, tsconfig paths, extensionless imports) and inspect its machines. */
 export declare function inspectFile(file: string, options?: FileOptions, load?: LoadOptions): Promise<LoadedFile>;
 /**
- * A self-contained HTML page for `document`: open it from disk, attach it, commit it.
- * With `live` (a built script that drives the machines), that script replaces the static viewer.
+ * States no edge path leads to from the initial state. Empty when an undetermined
+ * edge hides the answer. Region states are never reported: the graph does not
+ * record where a region starts.
  */
-export declare function htmlPage(document: VizDocument, title: string, live?: string): Promise<string>;
-export { type AnalysisSource, type CorpusEntry, type FileOptions, type FuzzOptions, type FuzzResult, type FuzzSettings, type FuzzTarget, type HandlerSite, type InspectTarget, type Inspected, type InspectedModule, type LiteralPool, type MachineExport, type ModuleAnalysis, type ModuleOptions, type Observation, type RunError, type Trace, type VizInput, eventCatalog, execute, inspect, inspectModule, machineId, vizDocument };
+export declare function unreachableStates(machine: VizMachine): string[];
+/** Design errors of an inspected machine, one line each. Unreached edges and routing warnings are not errors. */
+export declare function designErrors(machine: VizMachine): string[];
+/**
+ * Call from a test: throws when fuzzing finds a handler or effect that throws,
+ * an effect sends an event its state does not handle, or a declared state has
+ * no path from the initial state. Runs are seeded, so the result is stable.
+ */
+export declare function expectNoDesignErrors(target: InspectTarget): void;
+interface ReachTransition {
+  from: string;
+  event: string;
+  /** Omit to accept any target. */
+  to?: string;
+}
+interface ReachExpectation {
+  states?: ReadonlyArray<string>;
+  transitions?: ReadonlyArray<ReachTransition>;
+}
+/** Ids of the states a fuzz run or the supplied test sequences visited. */
+export declare function reachedStates(machine: VizMachine): string[];
+/** What the expectation asks for and the machine did not reach, one line each. */
+export declare function missedReach(machine: VizMachine, expected: ReachExpectation): string[];
+/**
+ * Call from a test: throws unless fuzzing or the target's `tests` visited every
+ * listed state and took every listed transition. Reaching is proof; a miss only
+ * says nothing got there yet.
+ */
+export declare function expectReached(target: InspectTarget, expected: ReachExpectation): void;
+/** Call from a test: throws unless fuzzing or the target's `tests` visited every declared state. */
+export declare function expectAllStatesReached(target: InspectTarget): void;
+export { type AnalysisSource, type CorpusEntry, type FileOptions, type FuzzOptions, type FuzzResult, type FuzzSettings, type FuzzTarget, type HandlerSite, type InspectTarget, type Inspected, type InspectedModule, type LiteralPool, type MachineExport, type ModuleAnalysis, type ModuleOptions, type Observation, type ReachExpectation, type ReachTransition, type RunError, type Trace, type VizInput, eventCatalog, execute, inspect, inspectModule, machineId, vizDocument };

package/dist/index.mjs

@@ -1,4 +1,99 @@
-import { C as toViz, S as shrink, _ as guidance, b as withTestCoverage, c as inspect, d as vizDocument, f as analyzeModule, g as branchDistanceGuide, h as branchDistance, l as inspectModule, m as annotateMachine, p as analyzeSource, s as inspectFile, u as machineId, v as literalPool, w as toVizMachine, x as fuzz, y as fuzzedMachine } from "./vite-BBW0CmYr.mjs";
+import { _ as toViz, a as vizDocument, c as annotateMachine, d as guidance, f as literalPool, g as shrink, h as fuzz, l as branchDistance, m as withTestCoverage, n as inspectModule, o as analyzeModule, p as fuzzedMachine, r as machineId, s as analyzeSource, t as inspect, u as branchDistanceGuide, v as toVizMachine } from "./inspect-B7ZQCNM2.mjs";
 import { i as execute, r as eventCatalog } from "./run-B5huYj_r.mjs";
-import { t as htmlPage } from "./page-CK7-IsLJ.mjs";
-export { analyzeModule, analyzeSource, annotateMachine, branchDistance, branchDistanceGuide, eventCatalog, execute, fuzz, fuzzedMachine, guidance, htmlPage, inspect, inspectFile, inspectModule, literalPool, machineId, shrink, toViz, toVizMachine, vizDocument, withTestCoverage };
+import { r as inspectFile } from "./load-CWubcSZU.mjs";
+import { coveredByAny, unhandledSends } from "@mantaq/viz";
+// src/gate.ts
+/**
+* States no edge path leads to from the initial state. Empty when an undetermined
+* edge hides the answer. Region states are never reported: the graph does not
+* record where a region starts.
+*/
+function unreachableStates(machine) {
+	const reached = new Set(machine.states.filter((state) => state.initial || state.region !== null).map((state) => state.id));
+	const queue = [...reached];
+	let undetermined = false;
+	for (let next = queue.shift(); next !== void 0; next = queue.shift()) {
+		const from = next;
+		for (const edge of machine.edges) {
+			if (edge.kind === "effect" || edge.from !== from && !coveredByAny(edge.from, from)) continue;
+			if (edge.to === null) {
+				undetermined = true;
+				continue;
+			}
+			if (reached.has(edge.to)) continue;
+			reached.add(edge.to);
+			queue.push(edge.to);
+		}
+	}
+	if (undetermined) return [];
+	return machine.states.map((state) => state.id).filter((id) => !reached.has(id));
+}
+/** Design errors of an inspected machine, one line each. Unreached edges and routing warnings are not errors. */
+function designErrors(machine) {
+	const thrown = (machine.fuzz?.errors ?? []).map((error) => `${error.event} in ${error.from} throws: ${error.message}`);
+	const sends = machine.states.flatMap((state) => unhandledSends(machine, state.id).map(({ effect, event }) => `effect ${effect} in ${state.id} sends ${event}, but ${state.id} has no handler for it`));
+	const orphans = unreachableStates(machine).map((id) => `state ${id} is declared but no path leads to it from the initial state`);
+	return [
+		...thrown,
+		...sends,
+		...orphans
+	];
+}
+/**
+* Call from a test: throws when fuzzing finds a handler or effect that throws,
+* an effect sends an event its state does not handle, or a declared state has
+* no path from the initial state. Runs are seeded, so the result is stable.
+*/
+function expectNoDesignErrors(target) {
+	const { machine } = inspect(target);
+	const errors = designErrors(machine);
+	if (errors.length === 0) return;
+	throw new Error(`${machine.id} has ${errors.length} design error${errors.length === 1 ? "" : "s"}:\n${errors.map((each) => `  - ${each}`).join("\n")}`);
+}
+// src/reach.ts
+function hitCount(coverage) {
+	return coverage?.hits ?? 0;
+}
+/** Ids of the states a fuzz run or the supplied test sequences visited. */
+function reachedStates(machine) {
+	return machine.states.filter((state) => hitCount(state.coverage) + hitCount(state.tested) > 0).map((state) => state.id);
+}
+function isTaken(edge) {
+	return hitCount(edge.coverage) + hitCount(edge.tested) > 0;
+}
+function describeTransition({ from, event, to }) {
+	return to === void 0 ? `${from} --${event}-->` : `${from} --${event}--> ${to}`;
+}
+/** What the expectation asks for and the machine did not reach, one line each. */
+function missedReach(machine, expected) {
+	const reached = new Set(reachedStates(machine));
+	const states = (expected.states ?? []).map((id) => {
+		if (!machine.states.some((state) => state.id === id)) return `state ${id} does not exist`;
+		return reached.has(id) ? null : `state ${id} was not reached`;
+	});
+	const transitions = (expected.transitions ?? []).map((wanted) => {
+		const matching = machine.edges.filter((edge) => edge.kind !== "effect" && edge.kind !== "initial" && edge.from === wanted.from && edge.event === wanted.event && (wanted.to === void 0 || edge.to === wanted.to));
+		if (matching.length === 0) return `transition ${describeTransition(wanted)} does not exist`;
+		return matching.some(isTaken) ? null : `transition ${describeTransition(wanted)} was not taken`;
+	});
+	return [...states, ...transitions].filter((line) => line !== null);
+}
+function failOnMiss(machine, misses) {
+	if (misses.length === 0) return;
+	throw new Error(`${machine.id} missed ${misses.length} expected ${misses.length === 1 ? "reach" : "reaches"}:\n${misses.map((each) => `  - ${each}`).join("\n")}\nAdd a named run to \`tests\`, or raise \`fuzz.iterations\`, to cover it.`);
+}
+/**
+* Call from a test: throws unless fuzzing or the target's `tests` visited every
+* listed state and took every listed transition. Reaching is proof; a miss only
+* says nothing got there yet.
+*/
+function expectReached(target, expected) {
+	const { machine } = inspect(target);
+	failOnMiss(machine, missedReach(machine, expected));
+}
+/** Call from a test: throws unless fuzzing or the target's `tests` visited every declared state. */
+function expectAllStatesReached(target) {
+	const { machine } = inspect(target);
+	failOnMiss(machine, missedReach(machine, { states: machine.states.map((state) => state.id) }));
+}
+export { analyzeModule, analyzeSource, annotateMachine, branchDistance, branchDistanceGuide, designErrors, eventCatalog, execute, expectAllStatesReached, expectNoDesignErrors, expectReached, fuzz, fuzzedMachine, guidance, inspect, inspectFile, inspectModule, literalPool, machineId, missedReach, reachedStates, shrink, toViz, toVizMachine, unreachableStates, vizDocument, withTestCoverage };