@mantaq/traversal 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anders Can
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,8 @@
+# @mantaq/traversal
+
+Graph extraction, traversal algorithms, and runtime 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.

package/dist/index.d.mts

@@ -0,0 +1,99 @@
+import { AnyActor, Snapshot } from "@mantaq/core";
+//#region src/types.d.ts
+interface GraphNode {
+  id: string;
+  label: string;
+  isActive: boolean;
+  isFinal: boolean;
+  isInitial?: boolean;
+}
+interface GraphEdge {
+  id: string;
+  source: string;
+  target: string;
+  label: string;
+  isActive: boolean;
+  isInternal?: boolean;
+  isUndetermined?: boolean;
+  payload?: {
+    action?: string;
+  };
+  contexts?: string[];
+}
+interface ActorGraph {
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+}
+interface StateVisit {
+  stateName: string;
+  timestamp: number;
+}
+interface TransitionRecord {
+  from: string;
+  event: string;
+  to: string | undefined;
+  timestamp: number;
+}
+interface EffectRecord {
+  stateName: string;
+  timestamp: number;
+}
+interface HistoryEntry {
+  type: "state_visit" | "transition" | "effect" | "send";
+  data: StateVisit | TransitionRecord | EffectRecord | {
+    event: string;
+    timestamp: number;
+  };
+}
+//#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(actor: AnyActor, 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();
+  append(entry: HistoryEntry): void;
+  entries(): readonly HistoryEntry[];
+  stateVisits(): StateVisit[];
+  transitions(): TransitionRecord[];
+  effects(): EffectRecord[];
+  sends(): Array<{
+    event: string;
+    timestamp: number;
+  }>;
+  visitedStates(): Set<string>;
+  firedTransitions(): Set<string>;
+  reset(): void;
+}
+//#endregion
+//#region src/instrument.d.ts
+interface InstrumentedActor {
+  history: History;
+  send(event: unknown): void;
+  state: AnyActor["state"];
+  snapshot(): Snapshot;
+  regions: Record<string, AnyActor>;
+  context?: Record<string, unknown>;
+  clock: AnyActor["clock"];
+  on(event: "change", fn: (snapshot: Snapshot) => void): () => void;
+  on(event: "error", fn: (error: unknown) => void): () => void;
+  on(event: "done", fn: () => void): () => void;
+  settled(): Promise<void>;
+  options?: AnyActor["options"];
+}
+declare function instrument(actor: AnyActor): InstrumentedActor;
+//#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 };

package/dist/index.mjs

@@ -0,0 +1,479 @@
+import { Either } from "@mantaq/utils";
+//#region src/graph.ts
+const INITIAL_NODE_ID = "__initial__";
+function collectActiveStates(snapshot, prefix, activeSet) {
+	if (!snapshot || !snapshot.path) return;
+	const currentName = snapshot.path[snapshot.path.length - 1];
+	if (!currentName) return;
+	const fullId = nodeId(prefix, currentName);
+	activeSet.add(fullId);
+	if (snapshot.regions && !snapshot.done) for (const [regionName, regionSnap] of Object.entries(snapshot.regions)) collectActiveStates(regionSnap, regionName, activeSet);
+}
+function nodeId(prefix, name) {
+	return prefix ? `${prefix}.${name}` : name;
+}
+function buildNodesFromStates(states, activeSet, pathPrefix) {
+	return states.map((stateRef) => {
+		const nid = nodeId(pathPrefix, stateRef.name);
+		return {
+			id: nid,
+			label: stateRef.name,
+			isActive: activeSet.has(nid),
+			isFinal: stateRef.isFinal
+		};
+	});
+}
+function invokeHandler(handler, eventId, ctx, actor) {
+	return Either.from(() => {
+		const result = handler({ id: eventId }, {
+			context: ctx,
+			actor
+		});
+		return {
+			targetName: result?.state?.name,
+			emitNames: result?.emit?.map((e) => e.id).filter((id) => Boolean(id)) ?? []
+		};
+	});
+}
+function upsertEdge(sink, traversal, eventId, handled) {
+	const undetermined = !handled.targetName;
+	const targetId = handled.targetName ? nodeId(traversal.pathPrefix, handled.targetName) : `${sink.sourceId}-undetermined-${eventId}`;
+	const edgeId = `${sink.sourceId}-${eventId}-${targetId}`;
+	const existing = sink.edgeMap.get(edgeId);
+	if (existing) existing.contexts.push(sink.ctxName);
+	else sink.edgeMap.set(edgeId, {
+		id: edgeId,
+		source: sink.sourceId,
+		target: targetId,
+		label: eventId,
+		isActive: traversal.activeSet.has(sink.sourceId),
+		isInternal: traversal.internalIds?.has(eventId),
+		isUndetermined: undetermined,
+		contexts: [sink.ctxName],
+		...handled.emitNames.length > 0 && { payload: { action: `emit(${handled.emitNames.join(", ")})` } }
+	});
+}
+function processStateTransitions(stateTransitions, pass) {
+	const stateTransitionedEvents = /* @__PURE__ */ new Set();
+	for (const [eventId, handler] of Object.entries(stateTransitions)) {
+		if (typeof handler !== "function") continue;
+		for (const ctxName of pass.traversal.contextNames) {
+			const ctx = pass.traversal.contexts[ctxName];
+			const handled = Either.getOrElse(invokeHandler(handler, eventId, ctx, pass.traversal.actor), () => ({
+				targetName: void 0,
+				emitNames: []
+			}));
+			if (handled.targetName) stateTransitionedEvents.add(eventId);
+			upsertEdge({
+				edgeMap: pass.edgeMap,
+				sourceId: pass.sourceId,
+				ctxName
+			}, pass.traversal, eventId, handled);
+		}
+	}
+	return stateTransitionedEvents;
+}
+function mergeAnyTransitions(anyTransitions, stateTransitionedEvents, pass) {
+	for (const [eventId, handler] of Object.entries(anyTransitions)) {
+		if (typeof handler !== "function") continue;
+		if (stateTransitionedEvents.has(eventId)) continue;
+		for (const ctxName of pass.traversal.contextNames) {
+			const ctx = pass.traversal.contexts[ctxName];
+			const handled = Either.getOrElse(invokeHandler(handler, eventId, ctx, pass.traversal.actor), () => ({
+				targetName: void 0,
+				emitNames: []
+			}));
+			upsertEdge({
+				edgeMap: pass.edgeMap,
+				sourceId: pass.sourceId,
+				ctxName
+			}, pass.traversal, eventId, handled);
+		}
+	}
+}
+function collectTransitionsForState(stateTransitions, anyTransitions, sourceId, traversal) {
+	const edgeMap = /* @__PURE__ */ new Map();
+	const pass = {
+		edgeMap,
+		sourceId,
+		traversal
+	};
+	const stateTransitionedEvents = stateTransitions ? processStateTransitions(stateTransitions, pass) : /* @__PURE__ */ new Set();
+	if (anyTransitions) mergeAnyTransitions(anyTransitions, stateTransitionedEvents, pass);
+	return edgeMap;
+}
+function buildEdgesFromTransitions(states, transitions, traversal) {
+	if (!transitions) return [];
+	const anyTransitions = transitions["Any"];
+	const edges = [];
+	for (const stateRef of states) {
+		const sourceId = nodeId(traversal.pathPrefix, stateRef.name);
+		const edgeMap = collectTransitionsForState(transitions[stateRef.name], anyTransitions, sourceId, traversal);
+		edges.push(...edgeMap.values());
+	}
+	return edges;
+}
+function addNodesForActor(actor, pathPrefix, activeSet) {
+	return buildNodesFromStates(actor.options?.states ?? [], activeSet, pathPrefix);
+}
+function addEdgesForActor(actor, traversal) {
+	return buildEdgesFromTransitions(actor.options?.states ?? [], actor.options?.transitions, traversal);
+}
+function recurseRegions(actor, traversal) {
+	const nodes = [];
+	const edges = [];
+	if (actor.regions) for (const [regionName, childActor] of Object.entries(actor.regions)) {
+		const child = buildForActor(childActor, {
+			...traversal,
+			pathPrefix: nodeId(traversal.pathPrefix, regionName)
+		});
+		nodes.push(...child.nodes);
+		edges.push(...child.edges);
+	}
+	return {
+		nodes,
+		edges
+	};
+}
+function addEffectSelfLoops(actor, pathPrefix, activeSet) {
+	const edges = [];
+	const effects = actor.options?.effects;
+	if (effects) {
+		for (const [stateName, fns] of Object.entries(effects)) if (Array.isArray(fns) && fns.length > 0) {
+			const sid = nodeId(pathPrefix, stateName);
+			edges.push({
+				id: `${sid}-effect:${stateName}-${sid}`,
+				source: sid,
+				target: sid,
+				label: `effect:${stateName}`,
+				isActive: activeSet.has(sid),
+				isInternal: true
+			});
+		}
+	}
+	return edges;
+}
+function buildForActor(actor, traversal) {
+	if (!actor) return {
+		nodes: [],
+		edges: []
+	};
+	const nodes = addNodesForActor(actor, traversal.pathPrefix, traversal.activeSet);
+	const edges = addEdgesForActor(actor, traversal);
+	const region = recurseRegions(actor, traversal);
+	nodes.push(...region.nodes);
+	edges.push(...region.edges);
+	edges.push(...addEffectSelfLoops(actor, traversal.pathPrefix, traversal.activeSet));
+	return {
+		nodes,
+		edges
+	};
+}
+function addInitialNode(actor, nodes, edges) {
+	const initialName = actor.options?.initial?.name;
+	if (!initialName) return;
+	const initNodeId = nodeId("", INITIAL_NODE_ID);
+	const targetId = nodeId("", initialName);
+	nodes.push({
+		id: initNodeId,
+		label: "",
+		isActive: false,
+		isFinal: false,
+		isInitial: true
+	});
+	edges.push({
+		id: `${initNodeId}->${targetId}`,
+		source: initNodeId,
+		target: targetId,
+		label: "",
+		isActive: true
+	});
+}
+function collectActorsFromSnapshot(snapshot) {
+	const activeSet = /* @__PURE__ */ new Set();
+	collectActiveStates(snapshot, "", activeSet);
+	return activeSet;
+}
+function collectNamedContexts(options) {
+	return options?.sampleContexts ?? (options?.sampleContext ? { default: options.sampleContext } : void 0);
+}
+function buildGraph(actor, options) {
+	if (!actor) return {
+		nodes: [],
+		edges: []
+	};
+	return Either.match(Either.from(() => {
+		const activeSet = collectActorsFromSnapshot(actor.snapshot());
+		const contexts = collectNamedContexts(options) ?? { default: { ...actor.context } };
+		const { nodes, edges } = buildForActor(actor, {
+			actor,
+			pathPrefix: "",
+			activeSet,
+			internalIds: options?.internalIds,
+			contexts,
+			contextNames: Object.keys(contexts)
+		});
+		addInitialNode(actor, nodes, edges);
+		return {
+			nodes,
+			edges
+		};
+	}), (error) => {
+		console.error("[mantaq/traversal] buildGraph failed:", error);
+		return {
+			nodes: [],
+			edges: []
+		};
+	}, (result) => result);
+}
+//#endregion
+//#region src/history.ts
+const entriesMap = /* @__PURE__ */ new WeakMap();
+function entriesOfType(entries, type) {
+	return entries.filter((e) => e.type === type).map((e) => e.data);
+}
+var History = class {
+	constructor() {
+		entriesMap.set(this, []);
+	}
+	append(entry) {
+		entriesMap.get(this).push(entry);
+	}
+	entries() {
+		return entriesMap.get(this);
+	}
+	stateVisits() {
+		return entriesOfType(entriesMap.get(this), "state_visit");
+	}
+	transitions() {
+		return entriesOfType(entriesMap.get(this), "transition");
+	}
+	effects() {
+		return entriesOfType(entriesMap.get(this), "effect");
+	}
+	sends() {
+		return entriesOfType(entriesMap.get(this), "send");
+	}
+	visitedStates() {
+		const result = /* @__PURE__ */ new Set();
+		for (const visit of this.stateVisits()) result.add(visit.stateName);
+		return result;
+	}
+	firedTransitions() {
+		const result = /* @__PURE__ */ new Set();
+		for (const t of this.transitions()) result.add(`${t.from}:${t.event}`);
+		return result;
+	}
+	reset() {
+		const arr = entriesMap.get(this);
+		arr.length = 0;
+	}
+};
+//#endregion
+//#region src/instrument.ts
+function wrapWithProxy(actor, hooks) {
+	const { history, origSend, pendingEventId } = hooks;
+	return {
+		get history() {
+			return history;
+		},
+		get state() {
+			return actor.state;
+		},
+		get regions() {
+			return actor.regions;
+		},
+		get context() {
+			return actor.context;
+		},
+		get clock() {
+			return actor.clock;
+		},
+		get options() {
+			return actor.options;
+		},
+		send(event) {
+			const { id: eventId } = trackSendEvent(history, event);
+			pendingEventId.value = eventId;
+			try {
+				origSend(event);
+			} finally {
+				pendingEventId.value = void 0;
+			}
+		},
+		snapshot() {
+			return actor.snapshot();
+		},
+		on: actor.on.bind(actor),
+		settled: actor.settled.bind(actor)
+	};
+}
+function recordTransition(history, from, to, eventId) {
+	history.append({
+		type: "transition",
+		data: {
+			from,
+			event: eventId,
+			to,
+			timestamp: Date.now()
+		}
+	});
+	history.append({
+		type: "state_visit",
+		data: {
+			stateName: to,
+			timestamp: Date.now()
+		}
+	});
+	history.append({
+		type: "effect",
+		data: {
+			stateName: to,
+			timestamp: Date.now()
+		}
+	});
+}
+function trackSendEvent(history, event) {
+	const eventId = event?.id ?? "unknown";
+	history.append({
+		type: "send",
+		data: {
+			event: eventId,
+			timestamp: Date.now()
+		}
+	});
+	return { id: eventId };
+}
+function instrument(actor) {
+	const history = new History();
+	const origSend = actor.send.bind(actor);
+	let prevStateName = actor.state.name;
+	const pendingEventId = { value: void 0 };
+	history.append({
+		type: "state_visit",
+		data: {
+			stateName: actor.state.name,
+			timestamp: Date.now()
+		}
+	});
+	const wrapped = wrapWithProxy(actor, {
+		history,
+		origSend,
+		pendingEventId
+	});
+	actor.on("change", () => {
+		const currentName = actor.state.name;
+		if (currentName !== prevStateName) {
+			recordTransition(history, prevStateName, currentName, pendingEventId.value ?? "unknown");
+			prevStateName = currentName;
+		}
+	});
+	return wrapped;
+}
+//#endregion
+//#region src/algorithms.ts
+function buildAdjacency(graph) {
+	const adj = {};
+	for (const node of graph.nodes) adj[node.id] = [];
+	for (const edge of graph.edges) if (adj[edge.source]) adj[edge.source].push({
+		target: edge.target,
+		label: edge.label
+	});
+	return adj;
+}
+function bfsWalk(adj, start, visit) {
+	const visited = {};
+	const queue = [start];
+	while (queue.length > 0) {
+		const current = queue.shift();
+		if (visited[current]) continue;
+		visited[current] = true;
+		if (visit(current)) break;
+		const neighbors = adj[current] || [];
+		for (let i = 0; i < neighbors.length; i++) {
+			const target = neighbors[i].target;
+			if (!visited[target]) queue.push(target);
+		}
+	}
+	return visited;
+}
+function reachable(graph, fromId, toId) {
+	return bfsWalk(buildAdjacency(graph), fromId, (node) => node === toId)[toId] === true;
+}
+function allPaths(graph, fromId, toId) {
+	const adj = buildAdjacency(graph);
+	const results = [];
+	const visited = {};
+	function dfs(current, path) {
+		if (current === toId) {
+			results.push(path.slice());
+			return;
+		}
+		if (visited[current]) return;
+		visited[current] = true;
+		const neighbors = adj[current] || [];
+		for (let i = 0; i < neighbors.length; i++) {
+			path.push(neighbors[i].target);
+			dfs(neighbors[i].target, path);
+			path.pop();
+		}
+		delete visited[current];
+	}
+	dfs(fromId, [fromId]);
+	return results;
+}
+function findCycles(graph) {
+	const adj = buildAdjacency(graph);
+	const cycles = [];
+	const visited = {};
+	const inStack = {};
+	const path = [];
+	function dfs(node) {
+		if (inStack[node]) {
+			const cycleStart = path.indexOf(node);
+			if (cycleStart !== -1) cycles.push(path.slice(cycleStart).concat(node));
+			return;
+		}
+		if (visited[node]) return;
+		visited[node] = true;
+		inStack[node] = true;
+		path.push(node);
+		const neighbors = adj[node] || [];
+		for (let i = 0; i < neighbors.length; i++) dfs(neighbors[i].target);
+		path.pop();
+		delete inStack[node];
+	}
+	for (const node of graph.nodes) dfs(node.id);
+	return cycles;
+}
+function unreachableNodes(graph, fromId) {
+	const visited = bfsWalk(buildAdjacency(graph), fromId, () => false);
+	const result = [];
+	for (const node of graph.nodes) if (!visited[node.id]) result.push(node.id);
+	return result;
+}
+function shortestPath(graph, fromId, toId) {
+	const adj = buildAdjacency(graph);
+	const visited = {};
+	const queue = [{
+		node: fromId,
+		path: [fromId]
+	}];
+	while (queue.length > 0) {
+		const { node: current, path } = queue.shift();
+		if (current === toId) return path;
+		if (visited[current]) continue;
+		visited[current] = true;
+		const neighbors = adj[current] || [];
+		for (let i = 0; i < neighbors.length; i++) {
+			const target = neighbors[i].target;
+			if (!visited[target]) queue.push({
+				node: target,
+				path: path.concat(target)
+			});
+		}
+	}
+	return null;
+}
+//#endregion
+export { History, INITIAL_NODE_ID, allPaths, buildGraph, collectActiveStates, findCycles, instrument, reachable, shortestPath, unreachableNodes };

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@mantaq/traversal",
+  "version": "0.0.1",
+  "description": "Graph extraction, traversal algorithms, and runtime tracking for mantaq actors.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AndersCan/mantaq",
+    "directory": "packages/traversal"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@mantaq/core": "0.0.1",
+    "@mantaq/utils": "0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "@typescript/native-preview": "7.0.0-dev.20260707.2",
+    "@vitest/coverage-v8": "4.1.10",
+    "typescript": "^7.0.2",
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.2.8",
+    "vite-plus": "0.2.8"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "check": "vp check",
+    "coverage": "vp test run --coverage"
+  }
+}