Skip to content

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.

npm install machina-inspect
# or
pnpm add machina-inspect

machina >= 7.0.1 is a peer dependency.

import { inspect } from "machina-inspect";

const findings = inspect({
    id: "traffic-light",
    initialState: "green",
    states: {
        green: { timeout: "yellow" },
        yellow: { timeout: "red" },
        red: { timeout: "green" },
        broken: {}, // unreachable — no transitions lead here
    },
});

// findings: [{ type: "unreachable-state", states: ["broken"], ... }]

inspect() accepts a config object or a live Fsm / BehavioralFsm instance.

machina-inspect runs three structural checks:

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.

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.

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.

Sometimes the graph IR is itself an output, for visualization or custom analysis. Build it once with buildStateGraph() and run the checks separately:

import { buildStateGraph, inspectGraph } from "machina-inspect";

const graph = buildStateGraph(config);

// Use the graph for diagram generation, export, etc.
// Then run checks against it
const findings = inspectGraph(graph);

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.

Downstream tools consume the StateGraph, the intermediate representation:

interface StateGraph {
    fsmId: string;
    initialState: string;
    nodes: Record<string, StateNode>;
    children: Record<string, StateGraph>;
}

interface StateNode {
    name: string;
    edges: TransitionEdge[];
}

interface TransitionEdge {
    inputName: string;
    from: string;
    to: string;
    confidence: "definite" | "possible";
}
  • "definite": an unconditional transition. String shorthands (timeout: "yellow") and functions with one top-level return.
  • "possible": a conditional transition. Returns inside if, switch, ternary, logical expressions, or try blocks.

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 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.