machina-inspect 1.0.0

package/dist/index.cjs

@@ -0,0 +1,589 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") {
+		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+			key = keys[i];
+			if (!__hasOwnProp.call(to, key) && key !== except) {
+				__defProp(to, key, {
+					get: ((k) => from[k]).bind(null, key),
+					enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+				});
+			}
+		}
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+let machina = require("machina");
+let acorn = require("acorn");
+acorn = __toESM(acorn);
+
+//#region src/handler-analyzer.ts
+const CONDITIONAL_ANCESTORS = new Set([
+	"IfStatement",
+	"SwitchStatement",
+	"SwitchCase",
+	"ConditionalExpression",
+	"LogicalExpression",
+	"TryStatement"
+]);
+const PARSE_OPTS = {
+	ecmaVersion: 2022,
+	sourceType: "script"
+};
+/**
+* Try to parse a function's toString() output using several strategies.
+*
+* Function.prototype.toString() produces different formats:
+*   - Named function declaration: `function name() { ... }` → parses as-is
+*   - Anonymous function expression: `function () { ... }` → needs parens wrapper
+*   - Arrow function: `() => { ... }` → parses as-is
+*   - Method shorthand: `name() { ... }` → needs object literal wrapper
+*
+* Returns null if none of the strategies succeed (unusual syntax, etc.).
+*/
+function tryParse(source) {
+	try {
+		return acorn.parse(source, PARSE_OPTS);
+	} catch {}
+	try {
+		return acorn.parse(`(${source})`, PARSE_OPTS);
+	} catch {}
+	try {
+		return acorn.parse(`({${source}})`, PARSE_OPTS);
+	} catch {
+		return null;
+	}
+}
+/**
+* Find the first ArrowFunctionExpression node in a parsed AST.
+* Returns undefined if no arrow function exists at the top level.
+*/
+function findArrowFunction(node) {
+	if (node.type === "ArrowFunctionExpression") return node;
+	if (node.type === "Program" || node.type === "ExpressionStatement") {
+		const children = getChildren(node);
+		for (const child of children) {
+			const found = findArrowFunction(child);
+			if (found) return found;
+		}
+	}
+}
+/**
+* Handle concise arrow functions (`() => "state"` with no block body).
+*
+* Acorn represents these with `expression: true` on the ArrowFunctionExpression
+* and the body as a Literal directly — there is no ReturnStatement, so the
+* general walkForReturns() misses them entirely.
+*
+* Returns:
+*   - HandlerTarget[] with one definite entry if the body is a string Literal
+*   - [] if the body is a non-string expression (no false edges produced)
+*   - undefined if the AST doesn't match the concise arrow pattern at all
+*     (caller should fall through to the general walker)
+*/
+function checkConciseArrow(node) {
+	if (node.type !== "ArrowFunctionExpression" || !node.expression) return;
+	const body = node.body;
+	if (body && body.type === "Literal" && typeof body.value === "string") return [{
+		target: body.value,
+		confidence: "definite"
+	}];
+	return [];
+}
+/**
+* Handle concise arrow functions found inside a parsed Program/ExpressionStatement.
+* Used by analyzeHandler after tryParse() wraps the source in a Program node.
+*/
+function checkConciseArrowInAst(ast) {
+	const arrowNode = findArrowFunction(ast);
+	if (!arrowNode || !arrowNode.expression) return;
+	const body = arrowNode.body;
+	if (body && body.type === "Literal" && typeof body.value === "string") return [{
+		target: body.value,
+		confidence: "definite"
+	}];
+	return [];
+}
+/**
+* Walk a pre-parsed handler function AST node and extract transition targets.
+*
+* Accepts a FunctionDeclaration, FunctionExpression, or ArrowFunctionExpression
+* node (as produced by acorn or the ESLint rule engine). Returns an array of
+* { target, confidence } pairs. Empty array means no statically-determinable
+* string return targets were found.
+*
+* This is the shared core used by both:
+*   - analyzeHandler() — the runtime path (parses fn.toString() first)
+*   - ESLint rules — the AST path (ESLint already has the parsed node)
+*/
+function walkHandlerAst(node) {
+	const conciseResult = checkConciseArrow(node);
+	if (conciseResult !== void 0) return conciseResult;
+	const returns = [];
+	walkForReturns(node, [], returns);
+	if (returns.length === 0) return [];
+	const allNonConditional = returns.every((r) => !r.isConditional);
+	const isSoleReturn = returns.length === 1;
+	return returns.map(({ target, isConditional }) => ({
+		target,
+		confidence: allNonConditional && isSoleReturn && !isConditional ? "definite" : "possible"
+	}));
+}
+/**
+* Analyze a handler function and extract transition targets.
+*
+* Returns an array of { target, confidence } pairs. Empty array means
+* no statically-determinable string return targets were found.
+*
+* Safe to call on any function — parse errors return empty (fail silently).
+*/
+function analyzeHandler(fn) {
+	const source = fn.toString();
+	if (source.includes("[native code]")) return [];
+	const ast = tryParse(source);
+	if (!ast) return [];
+	const conciseResult = checkConciseArrowInAst(ast);
+	if (conciseResult !== void 0) return conciseResult;
+	const fnNode = findTopLevelFunctionNode(ast);
+	if (fnNode) return walkHandlerAst(fnNode);
+	const returns = [];
+	walkForReturns(ast, [], returns);
+	if (returns.length === 0) return [];
+	const allNonConditional = returns.every((r) => !r.isConditional);
+	const isSoleReturn = returns.length === 1;
+	return returns.map(({ target, isConditional }) => ({
+		target,
+		confidence: allNonConditional && isSoleReturn && !isConditional ? "definite" : "possible"
+	}));
+}
+/**
+* Find the top-level function node in a parsed Program AST.
+* Returns the first FunctionDeclaration, FunctionExpression, or
+* ArrowFunctionExpression at the top level.
+*/
+function findTopLevelFunctionNode(ast) {
+	const children = getChildren(ast);
+	for (const child of children) {
+		if (child.type === "FunctionDeclaration" || child.type === "FunctionExpression" || child.type === "ArrowFunctionExpression") return child;
+		if (child.type === "ExpressionStatement") {
+			const grandChildren = getChildren(child);
+			for (const gc of grandChildren) if (gc.type === "FunctionDeclaration" || gc.type === "FunctionExpression" || gc.type === "ArrowFunctionExpression") return gc;
+		}
+	}
+}
+/**
+* Collect string literals from a conditional expression tree.
+* Used when a ReturnStatement's argument is a ternary or logical expression.
+* All findings are marked as "possible" since they're conditional.
+*/
+function collectStringLiteralsFromExpression(node, results) {
+	if (!node || typeof node !== "object") return;
+	if (node.type === "Literal" && typeof node.value === "string") {
+		results.push({
+			target: node.value,
+			isConditional: true
+		});
+		return;
+	}
+	if (node.type === "ConditionalExpression") {
+		collectStringLiteralsFromExpression(node.consequent, results);
+		collectStringLiteralsFromExpression(node.alternate, results);
+	} else if (node.type === "LogicalExpression") {
+		collectStringLiteralsFromExpression(node.left, results);
+		collectStringLiteralsFromExpression(node.right, results);
+	}
+}
+/**
+* Recursively walk the AST, collecting ReturnStatement nodes that
+* return string literals. Tracks whether any CONDITIONAL_ANCESTOR
+* node exists in the ancestor chain.
+*
+* We skip nested function bodies (arrow functions, regular functions,
+* class methods) — their returns belong to a different function scope.
+*/
+function walkForReturns(node, ancestors, results) {
+	if (!node || typeof node !== "object") return;
+	if (node.type === "ReturnStatement") {
+		const arg = node.argument;
+		if (!arg) return;
+		if (arg.type === "Literal" && typeof arg.value === "string") {
+			const isConditional = ancestors.some((a) => CONDITIONAL_ANCESTORS.has(a));
+			results.push({
+				target: arg.value,
+				isConditional
+			});
+		} else collectStringLiteralsFromExpression(arg, results);
+		return;
+	}
+	if (node.type === "FunctionDeclaration" || node.type === "FunctionExpression" || node.type === "ArrowFunctionExpression") {
+		if (ancestors.some((a) => a === "FunctionDeclaration" || a === "FunctionExpression" || a === "ArrowFunctionExpression")) return;
+	}
+	const nextAncestors = [...ancestors, node.type];
+	const children = getChildren(node);
+	for (const child of children) if (child && typeof child === "object") walkForReturns(child, nextAncestors, results);
+}
+/**
+* Extract the child nodes we want to recurse into from an AST node.
+* Returns a flat list of child nodes (some may be arrays in the AST).
+*/
+function getChildren(node) {
+	const children = [];
+	const pushIfNode = (val) => {
+		if (val && typeof val === "object" && "type" in val) children.push(val);
+	};
+	const pushArray = (arr) => {
+		if (Array.isArray(arr)) for (const item of arr) pushIfNode(item);
+	};
+	switch (node.type) {
+		case "Program":
+			pushArray(node.body);
+			break;
+		case "ExpressionStatement":
+			pushIfNode(node.expression);
+			break;
+		case "FunctionDeclaration":
+		case "FunctionExpression":
+		case "ArrowFunctionExpression":
+			if (node.body) pushIfNode(node.body);
+			break;
+		case "BlockStatement":
+			pushArray(node.body);
+			break;
+		case "ReturnStatement":
+			pushIfNode(node.argument);
+			break;
+		case "IfStatement":
+			pushIfNode(node.consequent);
+			pushIfNode(node.alternate);
+			break;
+		case "SwitchStatement":
+			pushArray(node.cases);
+			break;
+		case "SwitchCase":
+			pushArray(node.consequent);
+			break;
+		case "TryStatement":
+			pushIfNode(node.block);
+			pushIfNode(node.handler);
+			pushIfNode(node.finalizer);
+			break;
+		case "CatchClause":
+			pushIfNode(node.body);
+			break;
+		case "ConditionalExpression":
+			pushIfNode(node.consequent);
+			pushIfNode(node.alternate);
+			break;
+		case "LogicalExpression":
+			pushIfNode(node.left);
+			pushIfNode(node.right);
+			break;
+		case "VariableDeclaration":
+			pushArray(node.declarations);
+			break;
+		case "VariableDeclarator":
+			pushIfNode(node.init);
+			break;
+		case "ForStatement":
+			pushIfNode(node.body);
+			break;
+		case "WhileStatement":
+		case "DoWhileStatement":
+			pushIfNode(node.body);
+			break;
+		default: for (const key of Object.keys(node)) {
+			if (key === "type" || key === "start" || key === "end" || key === "loc" || key === "parent" || key === "range") continue;
+			const val = node[key];
+			if (Array.isArray(val)) pushArray(val);
+			else pushIfNode(val);
+		}
+	}
+	return children;
+}
+
+//#endregion
+//#region src/graph-builder.ts
+const SPECIAL_KEYS = new Set([
+	"_onEnter",
+	"_onExit",
+	"_child"
+]);
+/**
+* Normalize the input to a consistent internal shape.
+* Config objects are passed through; live instances have their
+* public fields extracted.
+*/
+function normalizeInput(input) {
+	if (machina.MACHINA_TYPE in input) {
+		const instance = input;
+		return {
+			id: instance.id,
+			initialState: instance.initialState,
+			states: instance.states
+		};
+	}
+	return input;
+}
+/**
+* Extract transition edges from a single handler value.
+* String shorthands produce one definite edge. Function handlers
+* are analyzed by the acorn-based handler-analyzer.
+*/
+function extractEdges(fromState, inputName, handlerValue) {
+	if (typeof handlerValue === "string") return [{
+		inputName,
+		from: fromState,
+		to: handlerValue,
+		confidence: "definite"
+	}];
+	if (typeof handlerValue === "function") return analyzeHandler(handlerValue).map(({ target, confidence }) => ({
+		inputName,
+		from: fromState,
+		to: target,
+		confidence
+	}));
+	return [];
+}
+/**
+* Detect whether a _child value is a ChildLink wrapper (post-construction)
+* vs a raw FSM instance (pre-construction config path).
+*
+* ChildLink objects have a `canHandle` method and an `instance` field.
+* Raw FSM instances have MACHINA_TYPE stamped on them.
+*/
+function isChildLink(value) {
+	return typeof value === "object" && value !== null && "canHandle" in value && "instance" in value;
+}
+/**
+* Detect a plain config object that looks like an FSM config (has `initialState`
+* and `states`). This covers eval'd user input in the explorer, where _child is
+* a bare object literal rather than a createFsm() instance.
+*/
+function isConfigShaped(value) {
+	return typeof value === "object" && value !== null && "initialState" in value && "states" in value;
+}
+/**
+* Build a StateGraph from an FSM config or live instance.
+* Child FSMs declared via _child are recursively built into child graphs.
+*
+* @param input - A config object or a live Fsm/BehavioralFsm instance
+*/
+function buildStateGraph(input) {
+	const fsm = normalizeInput(input);
+	const nodes = {};
+	const children = {};
+	for (const stateName of Object.keys(fsm.states)) {
+		const stateObj = fsm.states[stateName];
+		const edges = [];
+		for (const key of Object.keys(stateObj)) {
+			const value = stateObj[key];
+			if (key === "_child") {
+				if (isChildLink(value)) children[stateName] = buildStateGraph(value.instance);
+				else if (typeof value === "object" && value !== null && machina.MACHINA_TYPE in value) children[stateName] = buildStateGraph(value);
+				else if (isConfigShaped(value)) children[stateName] = buildStateGraph(value);
+				continue;
+			}
+			if (SPECIAL_KEYS.has(key)) {
+				if (key === "_onEnter" && typeof value === "function") {
+					const targets = analyzeHandler(value);
+					for (const { target, confidence } of targets) edges.push({
+						inputName: "_onEnter",
+						from: stateName,
+						to: target,
+						confidence
+					});
+				}
+				continue;
+			}
+			for (const edge of extractEdges(stateName, key, value)) edges.push(edge);
+		}
+		nodes[stateName] = {
+			name: stateName,
+			edges
+		};
+	}
+	return {
+		fsmId: fsm.id,
+		initialState: fsm.initialState,
+		nodes,
+		children
+	};
+}
+
+//#endregion
+//#region src/checks/unreachable.ts
+/**
+* Check for unreachable states in the graph.
+* BFS from initialState — any unvisited node is a finding.
+* Recurses into child graphs independently.
+*/
+function checkUnreachable(graph, parentState) {
+	const findings = [];
+	findings.push(...findUnreachableInGraph(graph, parentState));
+	for (const [childParentState, childGraph] of Object.entries(graph.children)) findings.push(...checkUnreachable(childGraph, childParentState));
+	return findings;
+}
+function findUnreachableInGraph(graph, parentState) {
+	const { fsmId, initialState, nodes } = graph;
+	const visited = /* @__PURE__ */ new Set();
+	const queue = [];
+	if (initialState in nodes) {
+		queue.push(initialState);
+		visited.add(initialState);
+	}
+	while (queue.length > 0) {
+		const node = nodes[queue.shift()];
+		if (!node) continue;
+		for (const edge of node.edges) if (!visited.has(edge.to) && edge.to in nodes) {
+			visited.add(edge.to);
+			queue.push(edge.to);
+		}
+	}
+	const findings = [];
+	for (const stateName of Object.keys(nodes)) if (!visited.has(stateName)) findings.push({
+		type: "unreachable-state",
+		message: `State "${stateName}" is unreachable from initialState "${initialState}" in FSM "${fsmId}".`,
+		fsmId,
+		states: [stateName],
+		parentState
+	});
+	return findings;
+}
+
+//#endregion
+//#region src/checks/onenter-loop.ts
+/**
+* Check for _onEnter transition loops in the graph.
+* Only reports cycles where every edge is "definite".
+* Recurses into child graphs.
+*/
+function checkOnEnterLoops(graph, parentState) {
+	const findings = [];
+	findings.push(...findOnEnterLoopsInGraph(graph, parentState));
+	for (const [childParentState, childGraph] of Object.entries(graph.children)) findings.push(...checkOnEnterLoops(childGraph, childParentState));
+	return findings;
+}
+function findOnEnterLoopsInGraph(graph, parentState) {
+	const { fsmId, nodes } = graph;
+	const onEnterEdges = {};
+	for (const [stateName, node] of Object.entries(nodes)) {
+		const definiteOnEnterTargets = node.edges.filter((e) => e.inputName === "_onEnter" && e.confidence === "definite" && e.to !== stateName).map((e) => e.to);
+		if (definiteOnEnterTargets.length > 0) onEnterEdges[stateName] = definiteOnEnterTargets;
+	}
+	const WHITE = 0, GRAY = 1, BLACK = 2;
+	const color = {};
+	for (const stateName of Object.keys(nodes)) color[stateName] = WHITE;
+	const findings = [];
+	const reportedCycles = /* @__PURE__ */ new Set();
+	const dfs = (node, stack) => {
+		color[node] = GRAY;
+		stack.push(node);
+		for (const neighbor of onEnterEdges[node] ?? []) if (color[neighbor] === GRAY) {
+			const cycleStart = stack.indexOf(neighbor);
+			const cycle = stack.slice(cycleStart);
+			const cycleKey = [...cycle].sort().join(",");
+			if (!reportedCycles.has(cycleKey)) {
+				reportedCycles.add(cycleKey);
+				findings.push({
+					type: "onenter-loop",
+					message: `Unconditional _onEnter loop detected in FSM "${fsmId}": ` + cycle.join(" → ") + ` → ${neighbor}`,
+					fsmId,
+					states: cycle,
+					parentState
+				});
+			}
+		} else if (color[neighbor] === WHITE) dfs(neighbor, stack);
+		stack.pop();
+		color[node] = BLACK;
+	};
+	for (const stateName of Object.keys(nodes)) if (color[stateName] === WHITE) dfs(stateName, []);
+	return findings;
+}
+
+//#endregion
+//#region src/checks/missing-handler.ts
+const EXCLUDED_INPUTS = new Set([
+	"_onEnter",
+	"_onExit",
+	"*"
+]);
+/**
+* Check for states with missing handlers relative to the FSM's full input set.
+* States with a `*` catch-all edge are skipped entirely.
+* Recurses into child graphs independently.
+*/
+function checkMissingHandlers(graph, parentState) {
+	const findings = [];
+	findings.push(...findMissingHandlersInGraph(graph, parentState));
+	for (const [childParentState, childGraph] of Object.entries(graph.children)) findings.push(...checkMissingHandlers(childGraph, childParentState));
+	return findings;
+}
+function findMissingHandlersInGraph(graph, parentState) {
+	const { fsmId, nodes } = graph;
+	const allInputs = /* @__PURE__ */ new Set();
+	for (const node of Object.values(nodes)) for (const edge of node.edges) if (!EXCLUDED_INPUTS.has(edge.inputName)) allInputs.add(edge.inputName);
+	if (allInputs.size === 0) return [];
+	const findings = [];
+	for (const [stateName, node] of Object.entries(nodes)) {
+		if (node.edges.some((e) => e.inputName === "*")) continue;
+		const stateInputs = /* @__PURE__ */ new Set();
+		for (const edge of node.edges) if (!EXCLUDED_INPUTS.has(edge.inputName)) stateInputs.add(edge.inputName);
+		const missingInputs = [...allInputs].filter((input) => !stateInputs.has(input));
+		if (missingInputs.length > 0) findings.push({
+			type: "missing-handler",
+			message: `State "${stateName}" in FSM "${fsmId}" is missing handlers for: ` + missingInputs.map((i) => `"${i}"`).join(", ") + ".",
+			fsmId,
+			states: [stateName],
+			inputs: missingInputs,
+			parentState
+		});
+	}
+	return findings;
+}
+
+//#endregion
+//#region src/inspect.ts
+/**
+* Build a state graph from the input and run all structural checks.
+* Returns an array of findings — empty means no issues detected.
+*
+* @param input - A config object or a live Fsm/BehavioralFsm instance
+*/
+function inspect(input) {
+	return inspectGraph(buildStateGraph(input));
+}
+/**
+* Run all structural checks against a pre-built state graph.
+* Useful when you've already called buildStateGraph() for another purpose
+* (e.g., diagram export) and want to avoid building it twice.
+*
+* @param graph - A StateGraph produced by buildStateGraph()
+*/
+function inspectGraph(graph) {
+	return [
+		...checkUnreachable(graph),
+		...checkOnEnterLoops(graph),
+		...checkMissingHandlers(graph)
+	];
+}
+
+//#endregion
+exports.analyzeHandler = analyzeHandler;
+exports.buildStateGraph = buildStateGraph;
+exports.inspect = inspect;
+exports.inspectGraph = inspectGraph;
+exports.walkHandlerAst = walkHandlerAst;
+//# sourceMappingURL=index.cjs.map