Skip to content

ESLint Plugin

eslint-plugin-machina reports machina-inspect findings inline in your editor, with three rules and one import to set up. ESLint 9 flat config only.

npm install --save-dev eslint-plugin-machina
# or
pnpm add -D eslint-plugin-machina

machina-inspect is pulled in automatically. For TypeScript files, you also need @typescript-eslint/parser:

npm install --save-dev @typescript-eslint/parser
// eslint.config.mjs
import machina from "eslint-plugin-machina";

export default [machina.configs.recommended];
// eslint.config.mjs
import tsParser from "@typescript-eslint/parser";
import machina from "eslint-plugin-machina";

export default [
    {
        files: ["src/**/*.ts"],
        languageOptions: { parser: tsParser },
    },
    machina.configs.recommended,
];
Rule Default Type Description
machina/unreachable-state "warn" problem States with no inbound path from initialState
machina/onenter-loop "error" problem Unconditional _onEnter transition cycles
machina/missing-handler "off" suggestion States missing handlers for inputs other states handle

The rule reports states that the machine cannot enter from initialState. Unreachable states are dead code.

createFsm({
    id: "traffic-light",
    initialState: "green",
    states: {
        green: { timeout: "yellow" },
        yellow: { timeout: "red" },
        red: { timeout: "green" },
        broken: {}, // warning: unreachable from "green"
    },
});

Detects unconditional _onEnter transition cycles that will infinite-loop the runtime. Conditional bounces are intentional patterns and are not flagged.

createFsm({
    id: "bouncy",
    initialState: "a",
    states: {
        a: { _onEnter: () => "b" },
        b: { _onEnter: () => "a" }, // error: a -> b -> a
    },
});

Flags states that don’t handle inputs handled by other states. Off by default because many FSMs have asymmetric handlers by design. States with a * catch-all are excluded.

createFsm({
    id: "player",
    initialState: "idle",
    states: {
        idle: { start: "running" },
        running: { stop: "idle", pause: "paused" },
        paused: { resume: "running", stop: "idle" },
        // idle is missing "stop" and "pause"
    },
});

The plugin listens for createFsm() and createBehavioralFsm() call expressions, builds a StateGraph from the ESLint AST using machina-inspect’s graph IR, then runs the structural checks. Findings are reported as ESLint diagnostics at the call site.

The plugin resolves a _child reference when it is an inline createFsm() call or a const identifier bound to such a call in the same module. The plugin silently skips cross-module imports and let/var bindings. A skipped child goes unanalyzed, which avoids false positives from guessing.