@mantaq/traversal 0.1.2 → 0.3.0

package/README.md

@@ -1,8 +1,155 @@
 # @mantaq/traversal
 
-Graph extraction, traversal algorithms, and runtime tracking for
+Graph extraction, traversal algorithms, and runtime coverage tracking for
 [@mantaq/core](https://www.npmjs.com/package/@mantaq/core) actors.
 
-Build the state-machine graph from an actor, walk it with traversal
-algorithms, and instrument coverage as the actor runs — useful for
-verifying that every declared transition is reachable and exercised.
+Use it to:
+
+- **Inspect** a state machine statically. Turn an actor into a
+  `nodes`/`edges` graph of its states and transitions.
+- **Reason** about that graph. Which states are reachable, what paths exist
+  between two states, and whether any declared transition can never fire.
+- **Verify** coverage at runtime. Wrap an actor so every visited state,
+  fired transition, and executed effect is recorded as it runs.
+
+All three pieces work on the same `ActorGraph` shape, so you can build the
+graph once and walk it however your check needs.
+
+## Install
+
+```sh
+npm install @mantaq/traversal
+```
+
+> `@mantaq/traversal` depends on `@mantaq/core` and `@mantaq/utils`, which are
+> resolved as workspace packages in this repo.
+
+## Building the graph
+
+`buildGraph` walks an actor (and any nested regions) and returns an
+`ActorGraph`:
+
+```ts
+import { buildGraph } from "@mantaq/traversal";
+import { createActor } from "@mantaq/core";
+
+const actor = createActor(myMachine);
+const graph = buildGraph(actor);
+// graph.nodes: GraphNode[]   — one per declared state (+ an `__initial__` node)
+// graph.edges: GraphEdge[]   — one per (state, event) handler
+```
+
+Each `GraphNode` carries `id`, `label`, `isActive`, `isFinal`, and
+`isInitial`. Each `GraphEdge` carries `source`, `target`, `label` (the event
+that triggers it), `isActive`, `isInternal`, and `isUndetermined`.
+
+An edge is **undetermined** when its handler runs but does not declare a target
+state for the sampled context (e.g. a guard that resolves only at runtime). The
+graph is a _static_ approximation: it invokes each handler with a sample
+context to discover the transitions it _could_ take, so it documents intent
+and reachability, not live execution.
+
+### Sampling contexts
+
+Handlers may branch on context. Pass one or more named sample contexts to see
+how the graph differs per context shape:
+
+```ts
+const graph = buildGraph(actor, {
+  sampleContexts: {
+    guest: { loggedIn: false },
+    member: { loggedIn: true },
+  },
+});
+```
+
+Each context name is recorded on the relevant edges (`edge.contexts`), so you
+can tell which branches belong to which context. With a single context, use
+`sampleContext` instead.
+
+### Constants
+
+- `INITIAL_NODE_ID`. The synthetic id of the graph's entry node (the edge
+  from it points to the actor's initial state).
+
+## Walking the graph
+
+The algorithms module operates on an `ActorGraph` and is pure. No actor
+needed:
+
+```ts
+import { reachable, allPaths, findCycles, unreachableNodes, shortestPath } from "@mantaq/traversal";
+```
+
+| Function                            | Returns            | Use                                                 |
+| ----------------------------------- | ------------------ | --------------------------------------------------- |
+| `reachable(graph, fromId, toId)`    | `boolean`          | Is `toId` reachable from `fromId`?                  |
+| `allPaths(graph, fromId, toId)`     | `string[][]`       | Every distinct path of node ids between two states. |
+| `findCycles(graph)`                 | `string[][]`       | Every cycle in the graph, as node-id loops.         |
+| `unreachableNodes(graph, fromId)`   | `string[]`         | Nodes no walk from `fromId` can ever reach.         |
+| `shortestPath(graph, fromId, toId)` | `string[] \| null` | The fewest-edge path, or `null` if unreachable.     |
+
+A common check is "every declared state is reachable from the initial state":
+
+```ts
+import { INITIAL_NODE_ID, unreachableNodes } from "@mantaq/traversal";
+
+const dead = unreachableNodes(graph, INITIAL_NODE_ID);
+if (dead.length > 0) {
+  throw new Error(`Unreachable states: ${dead.join(", ")}`);
+}
+```
+
+## Tracking coverage at runtime
+
+`instrument` wraps an actor so it records everything it does into a `History`.
+The wrapped actor has the same surface as the original (`send`, `on`,
+`snapshot`, `context`, `regions`, `inject`, `dispose`, `recover`, `settled`)
+plus a `history` property.
+
+```ts
+import { instrument } from "@mantaq/traversal";
+
+const wrapped = instrument(actor);
+wrapped.send({ type: "START" });
+
+const history = wrapped.history;
+history.visitedStates(); // Set<string>  — every state the actor entered
+history.firedTransitions(); // Set<string>  — "from:event" for each fired transition
+history.effects(); // EffectRecord[] — effects executed per state
+history.transitions(); // TransitionRecord[] — full from/event/to log
+history.sends(); // { event: string }[] — every event sent in
+history.entries(); // HistoryEntry[] — the raw, ordered record
+```
+
+`History` records state visits, transitions, effects, and sends. Call
+`history.reset()` to reuse a wrapper across independent runs.
+
+Combine static and runtime views to assert coverage. E.g. that every
+reachable state in the graph was actually visited by a scenario:
+
+```ts
+const graph = buildGraph(actor);
+const wrapped = instrument(actor);
+runScenario(wrapped); // exercise the actor
+
+const graphStates = new Set(graph.nodes.map((n) => n.id));
+const missed = [...wrapped.history.visitedStates()].filter((s) => !graphStates.has(s));
+```
+
+## Types
+
+```ts
+import type {
+  ActorGraph,
+  GraphNode,
+  GraphEdge,
+  StateVisit,
+  TransitionRecord,
+  EffectRecord,
+  HistoryEntry,
+} from "@mantaq/traversal";
+```
+
+`ActorGraph` is `{ nodes: GraphNode[]; edges: GraphEdge[] }`. See the package
+source for the full field shapes.

package/dist/index.d.mts

@@ -1,11 +1,45 @@
 import { AnyActor, Context, ErrorInfo, InternalEvent, Snapshot, TransitionInfo } from "@mantaq/core";
-//#region src/types.d.ts
+/**
+ * Type guard for untyped transition-handler results. The single sanctioned
+ * `as` site for graph invocation: handler output crosses the untyped boundary.
+ */
+interface HandlerResult {
+  state?: {
+    name?: string;
+  };
+  emit?: Array<{
+    type?: string;
+  }>;
+}
+/** Synthetic event object for graph introspection — matches minimal InternalEvent shape */
+interface SyntheticEvent {
+  type: string;
+  payload?: unknown;
+}
+type TransitionHandler = (event: SyntheticEvent, options: {
+  context: Context<Record<string, unknown>>;
+  actor: AnyActor<unknown>;
+}) => HandlerResult | undefined;
+/** Map of state/Any → event → handler */
+type TransitionDispatchMap = Record<string, Record<string, TransitionHandler>>;
+/** State definition — matches AnyActor.options.states element type */
+type StateDef = {
+  name: string;
+  isFinal: boolean;
+};
 interface GraphNode {
   id: string;
   label: string;
   isActive: boolean;
   isFinal: boolean;
   isInitial?: boolean;
+  /** The `*` source of `onAny` edges: any non-final state. */
+  isAny?: boolean;
+}
+/** An effect a state runs on entry. `sends`: declared event types; null = not declared. */
+interface GraphEffect {
+  name: string;
+  sends: string[] | null;
 }
 interface GraphEdge {
   id: string;
@@ -15,10 +49,16 @@ interface GraphEdge {
   isActive: boolean;
   isInternal?: boolean;
   isUndetermined?: boolean;
+  /** Handled without a state change: the registration declares no `to`. */
+  isStay?: boolean;
+  /** Target comes from the builder's `to` list, not from running the handler. */
+  isDeclared?: boolean;
   payload?: {
     action?: string;
   };
-  contexts?: string[];
+  contexts: string[];
+  /** Effect self-loops only: the effects the state runs on entry, in registration order. */
+  effects?: GraphEffect[];
 }
 interface ActorGraph {
   nodes: GraphNode[];
@@ -26,66 +66,70 @@ interface ActorGraph {
 }
 interface StateVisit {
   stateName: string;
-  timestamp: number;
 }
 interface TransitionRecord {
   from: string;
   event: string;
   to: string | undefined;
-  timestamp: number;
 }
 interface EffectRecord {
   stateName: string;
-  timestamp: number;
+  effectName: string;
 }
+type SendRecord = {
+  event: string;
+};
 interface HistoryEntry {
   type: "state_visit" | "transition" | "effect" | "send";
-  data: StateVisit | TransitionRecord | EffectRecord | {
-    event: string;
-    timestamp: number;
-  };
+  data: StateVisit | TransitionRecord | EffectRecord | SendRecord;
 }
-//#endregion
-//#region src/graph.d.ts
-declare const INITIAL_NODE_ID = "__initial__";
-declare function collectActiveStates(snapshot: Snapshot, prefix: string, activeSet: Set<string>): void;
-declare function buildGraph<C>(actor: AnyActor<C>, options?: {
-  internalIds?: Set<string>;
-  sampleContext?: Record<string, unknown>;
-  sampleContexts?: Record<string, Record<string, unknown>>;
-}): ActorGraph;
-//#endregion
-//#region src/history.d.ts
-declare class History {
-  constructor();
+interface History {
   append(entry: HistoryEntry): void;
   entries(): readonly HistoryEntry[];
   stateVisits(): StateVisit[];
   transitions(): TransitionRecord[];
   effects(): EffectRecord[];
-  sends(): Array<{
-    event: string;
-    timestamp: number;
-  }>;
+  sends(): SendRecord[];
   visitedStates(): Set<string>;
   firedTransitions(): Set<string>;
   reset(): void;
 }
-//#endregion
-//#region src/instrument.d.ts
+/**
+ * History records the runtime trace of an instrumented actor. A closure over
+ * the entry list keeps the recorder mutable without exposing the raw array.
+ */
+export declare function createHistory(): History;
+export declare const INITIAL_NODE_ID = "__initial__";
+/** Source of `onAny` edges: any non-final state of the machine (`region.*` inside a region). */
+export declare const ANY_NODE_NAME = "*";
+export declare function isAnyNode(id: string): boolean;
+export declare function collectActiveStates(snapshot: Snapshot, options: {
+  prefix: string;
+  activeSet: Set<string>;
+}): void;
+export declare function buildGraph<C>(actor: AnyActor<C>, options?: {
+  internalIds?: Set<string>;
+  sampleContext?: Record<string, unknown>;
+  sampleContexts?: Record<string, Record<string, unknown>>;
+}): ActorGraph;
+export declare function parseStates(options: unknown): ReadonlyArray<StateDef>;
+export declare function parseTransitionMap(source: unknown): TransitionDispatchMap;
+export declare function parseInitialName(options: unknown): string | undefined;
+export declare function parseContextRecord(context: unknown): Record<string, unknown>;
+export declare function parseInternalEventIds(options: unknown): Set<string>;
+type SubscriberEventName = "change" | "done" | "transition" | "error" | "output";
+type SubscriberHandler<C, E extends SubscriberEventName> = E extends "change" ? (snapshot: Snapshot<C>, prev: Snapshot<C>) => void : E extends "done" ? () => void : E extends "transition" ? (info: TransitionInfo) => void : E extends "error" ? (info: ErrorInfo) => void : E extends "output" ? (event: InternalEvent) => void : never;
 interface InstrumentedActor<C = Record<string, unknown>> {
   history: History;
-  send(event: unknown): void;
+  send(event: InternalEvent): void;
   state: AnyActor["state"];
   snapshot(): Snapshot<C>;
   regions: Record<string, AnyActor>;
   context?: C;
   clock: AnyActor["clock"];
-  on(event: "change", fn: (snapshot: Snapshot<C>, prev: Snapshot<C>) => void): () => void;
-  on(event: "transition", fn: (info: TransitionInfo) => void): () => void;
-  on(event: "done", fn: () => void): () => void;
-  on(event: "error", fn: (info: ErrorInfo) => void): () => void;
-  on(event: "output", fn: (event: InternalEvent) => void): () => void;
+  on<E extends SubscriberEventName>(event: E, options: {
+    fn: SubscriberHandler<C, E>;
+  }): () => void;
   recover(target: {
     state: AnyActor["state"];
     context: C;
@@ -95,13 +139,21 @@ interface InstrumentedActor<C = Record<string, unknown>> {
   inject(event: InternalEvent): void;
   dispose(): void;
 }
-declare function instrument<C>(actor: AnyActor<C>): InstrumentedActor<C>;
-//#endregion
-//#region src/algorithms.d.ts
-declare function reachable(graph: ActorGraph, fromId: string, toId: string): boolean;
-declare function allPaths(graph: ActorGraph, fromId: string, toId: string): string[][];
-declare function findCycles(graph: ActorGraph): string[][];
-declare function unreachableNodes(graph: ActorGraph, fromId: string): string[];
-declare function shortestPath(graph: ActorGraph, fromId: string, toId: string): string[] | null;
-//#endregion
-export { type ActorGraph, type EffectRecord, type GraphEdge, type GraphNode, History, type HistoryEntry, INITIAL_NODE_ID, type InstrumentedActor, type StateVisit, type TransitionRecord, allPaths, buildGraph, collectActiveStates, findCycles, instrument, reachable, shortestPath, unreachableNodes };
+export declare function instrument<C>(actor: AnyActor<C>): InstrumentedActor<C>;
+export declare function reachable(graph: ActorGraph, endpoints: {
+  fromId: string;
+  toId: string;
+}): boolean;
+export declare function allPaths(graph: ActorGraph, endpoints: {
+  fromId: string;
+  toId: string;
+}): string[][];
+export declare function findCycles(graph: ActorGraph): string[][];
+export declare function unreachableNodes(graph: ActorGraph, options: {
+  fromId: string;
+}): string[];
+export declare function shortestPath(graph: ActorGraph, endpoints: {
+  fromId: string;
+  toId: string;
+}): string[] | undefined;
+export type { ActorGraph, EffectRecord, GraphEdge, GraphNode, History, HistoryEntry, InstrumentedActor, SendRecord, StateDef, StateVisit, SyntheticEvent, TransitionDispatchMap, TransitionHandler, TransitionRecord };