machina-inspect 1.0.0

package/LICENSE

@@ -0,0 +1,69 @@
+Copyright (c) 2011-2023 Jim Cowart (MIT License)
+
+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.
+
+See http://opensource.org/licenses/MIT for more details.
+
+--------------------------------------------------------------------
+Also available under GPL 2.0
+Copyright (c) 2011-2015 Jim Cowart (GPL-2.0 License)
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or (at
+your option) any later version.
+
+This program is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+General Public License for more details.
+
+See http://opensource.org/licenses/GPL-2.0 for more details
+
+--------------------------------------------------------------------
+
+The extend function included in machina was very heavily borrowed
+from the backbone.js project, which can be found at http://backbonejs.org.
+Due to its origin, the backbone license is included below as well.
+
+Copyright (c) 2010-2012 Jeremy Ashkenas, DocumentCloud
+
+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,185 @@
+# machina-inspect
+
+Static analysis for [machina](https://machina-js.org) FSM configs. Catches structural bugs — unreachable states, infinite `_onEnter` loops, missing handlers — without running the machine.
+
+Parses your FSM config (or a live instance) into a directed graph IR, then runs checks against it. The graph is a first-class export, so other tools (diagram generators, linters, [eslint-plugin-machina](https://www.npmjs.com/package/eslint-plugin-machina)) can build on the same representation.
+
+## Install
+
+```bash
+npm install machina-inspect
+# or
+pnpm add machina-inspect
+```
+
+`machina` >= 6.0.0 is a peer dependency.
+
+## Quick Start
+
+```ts
+import { createFsm } from "machina";
+import { inspect } from "machina-inspect";
+
+const config = {
+    id: "traffic-light",
+    initialState: "green",
+    states: {
+        green: { timeout: "yellow" },
+        yellow: { timeout: "red" },
+        red: { timeout: "green" },
+        broken: {}, // unreachable — no transitions lead here
+    },
+};
+
+const findings = inspect(config);
+// [{ type: "unreachable-state", states: ["broken"], ... }]
+```
+
+Works with live instances too:
+
+```ts
+const fsm = createFsm(config);
+const findings = inspect(fsm);
+```
+
+## API
+
+### `inspect(input): Finding[]`
+
+Build a state graph and run all checks. Returns an array of findings — empty means no issues.
+
+`input` is either a config object (`{ id, initialState, states }`) or a live `Fsm` / `BehavioralFsm` instance.
+
+### `buildStateGraph(input): StateGraph`
+
+Build the graph IR without running checks. Use this when you want the graph for other purposes (visualization, custom analysis) and want to avoid building it twice.
+
+### `inspectGraph(graph): Finding[]`
+
+Run all checks against a pre-built `StateGraph`. Pair with `buildStateGraph()` when you need both the graph and the findings.
+
+```ts
+import { buildStateGraph, inspectGraph } from "machina-inspect";
+
+const graph = buildStateGraph(config);
+// use `graph` for diagram export, etc.
+const findings = inspectGraph(graph);
+```
+
+### `analyzeHandler(handler): HandlerTarget[]`
+
+Parse a handler function for transition targets via acorn AST analysis of `handler.toString()`. Returns `{ target, confidence }` pairs.
+
+```ts
+import { analyzeHandler } from "machina-inspect";
+
+const targets = analyzeHandler(({ ctx }) => {
+    if (ctx.ready) {
+        return "active";
+    }
+});
+// [{ target: "active", confidence: "possible" }]
+```
+
+### `walkHandlerAst(node): HandlerTarget[]`
+
+Walk a pre-parsed ESTree/acorn function AST node to extract transition targets. This is the shared core used by both the runtime path (`analyzeHandler`) and the ESLint plugin. Accepts `AstFunctionNode` — a union of `FunctionDeclaration`, `FunctionExpression`, and `ArrowFunctionExpression`.
+
+```ts
+import { walkHandlerAst } from "machina-inspect";
+import type { AstFunctionNode } from "machina-inspect";
+
+// Use with a pre-parsed AST node (e.g., from ESLint or acorn)
+const targets = walkHandlerAst(functionNode as AstFunctionNode);
+```
+
+## Checks
+
+### Unreachable States
+
+BFS from `initialState`. Any state with no inbound path is reported. Both `"definite"` and `"possible"` edges count — if there's any path, the state is reachable.
+
+### `_onEnter` Loops
+
+DFS cycle detection on the subgraph of `_onEnter` transitions. Only reports cycles where **every** edge is `"definite"` (unconditional). Conditional bounces like `if (ctx.error) return "failed"` are intentional patterns, not bugs.
+
+Same-state self-loops are excluded — the machina runtime ignores same-state transitions, so they're no-ops.
+
+### Missing Handlers
+
+Collects the union of all input names across all states in the FSM. States that don't handle inputs present elsewhere are flagged. This is a best-effort check — only inputs visible as graph edges (string shorthand or statically extractable function returns) are included.
+
+States with a `*` catch-all handler are excluded (they implicitly handle everything). `_onEnter`, `_onExit`, and `*` are excluded from the input union. Child graphs are checked independently with their own input sets.
+
+## Graph IR
+
+The `StateGraph` is designed to be consumed by downstream tools:
+
+```ts
+interface StateGraph {
+    fsmId: string;
+    initialState: string;
+    nodes: Record<string, StateNode>;
+    children: Record<string, StateGraph>; // child FSMs, keyed by parent state
+}
+
+interface StateNode {
+    name: string;
+    edges: TransitionEdge[];
+}
+
+interface TransitionEdge {
+    inputName: string; // handler name, "_onEnter", or "*"
+    from: string;
+    to: string;
+    confidence: "definite" | "possible";
+}
+```
+
+### Confidence Levels
+
+- **`"definite"`** — Unconditional transition. String shorthands (`timeout: "yellow"`) and functions with a single top-level return.
+- **`"possible"`** — Conditional transition. Returns inside `if`, `switch`, ternary, logical expressions, or `try` blocks. Also applies when a function has multiple return statements.
+
+Function handlers are analyzed via [acorn](https://github.com/acornjs/acorn) (AST parsing of `handler.toString()`). Non-string returns, template literals, and variable returns are ignored — the analysis is best-effort, not exhaustive.
+
+## Child FSMs
+
+`_child` declarations are followed recursively. The resulting child graphs appear in `StateGraph.children`, keyed by the parent state name. Each child graph is analyzed independently (its own `initialState`, its own reachability).
+
+## Findings
+
+Findings are a discriminated union — narrow on `finding.type` to access type-specific fields.
+
+```ts
+interface BaseFinding {
+    message: string;
+    fsmId: string;
+    states: string[];
+    parentState?: string; // set for child FSM findings
+}
+
+interface UnreachableFinding extends BaseFinding {
+    type: "unreachable-state";
+}
+
+interface OnEnterLoopFinding extends BaseFinding {
+    type: "onenter-loop";
+}
+
+interface MissingHandlerFinding extends BaseFinding {
+    type: "missing-handler";
+    inputs: string[]; // the input names this state is missing
+}
+
+type Finding = UnreachableFinding | OnEnterLoopFinding | MissingHandlerFinding;
+```
+
+## See also
+
+- [eslint-plugin-machina](https://www.npmjs.com/package/eslint-plugin-machina) — get these checks inline in your editor via ESLint
+- [machina-explorer](https://machina-js.org/examples/machina-explorer/) — browser-based paste-and-analyze UI built on machina-inspect
+
+## License
+
+MIT