machina-inspect
machina-inspect parses your FSM config (or a live instance) into a directed graph IR, then runs structural checks against it. It’s the engine behind both the ESLint plugin and machina-explorer. It is also a standalone tool for programmatic use.
Install
Section titled “Install”machina >= 7.0.1 is a peer dependency.
Quick start
Section titled “Quick start”inspect() accepts a config object or a live Fsm / BehavioralFsm instance.
Checks
Section titled “Checks”machina-inspect runs three structural checks:
Unreachable states
Section titled “Unreachable states”The unreachable check reports each state that the machine cannot enter from initialState. Both "definite" and "possible" edges count, because any path at all makes a state reachable. The search is a breadth-first traversal from initialState.
_onEnter loops
Section titled “_onEnter loops”The loop check runs a depth-first cycle search over the subgraph of _onEnter transitions and reports only cycles in which each edge is unconditional. A conditional bounce like if (ctx.error) { return "failed"; } is an intentional pattern, and the check skips it.
Missing handlers
Section titled “Missing handlers”The missing-handler check collects the input names that appear anywhere in the FSM, then reports the states that leave some of those inputs unhandled. A state with a * catch-all is exempt. The check is best-effort: only inputs visible as graph edges enter the set.
Two-step usage
Section titled “Two-step usage”Sometimes the graph IR is itself an output, for visualization or custom analysis. Build it once with buildStateGraph() and run the checks separately:
This is the pattern machina-explorer uses: it builds the graph once, then feeds it to both the check runner and the mermaid diagram generator.
Graph IR
Section titled “Graph IR”Downstream tools consume the StateGraph, the intermediate representation:
Confidence levels
Section titled “Confidence levels”"definite": an unconditional transition. String shorthands (timeout: "yellow") and functions with one top-level return."possible": a conditional transition. Returns insideif,switch, ternary, logical expressions, ortryblocks.
machina-inspect parses handler.toString() with acorn to find transition targets in function handlers. Non-string returns, template literals, and variable references are ignored. The analysis is best-effort.
Child FSMs
Section titled “Child FSMs”_child declarations are followed recursively. Child graphs appear in StateGraph.children, keyed by the parent state name. Each child is analyzed independently with its own initialState and reachability scope.
See also
Section titled “See also”- machina-test, Jest and Vitest matchers built on machina-inspect’s graph analysis
- ESLint plugin, the same checks inline in your editor
- machina-explorer, a paste-and-analyze browser UI