cargo-statum-graph

cargo-statum-graph is the zero-touch CLI package for exact Statum workspace export and the Statum Inspector TUI.

It materializes a stable generated runner under the target workspace's target/statum-graph/runner/<key>/, links the selected crate inside that workspace context, and writes the combined exact workspace graph as Mermaid, DOT, PlantUML, and JSON, including declared validator-entry nodes from compiled #[validators] impls. inspect and export reuse that cached runner home across invocations, and suggest now uses that same cached runner path too, but CodebaseDoc::linked() still executes fresh at runtime on every run. It can also launch an inspector TUI over that same linked compiled CodebaseDoc surface, with composition machines as the primary workspace flow surface and a separate heuristic lane for broader source-scanned machine coupling hints.

Install

cargo install cargo-statum-graph

Export

cargo statum-graph export \
  /path/to/workspace

That writes:

• /path/to/workspace/codebase.mmd
• /path/to/workspace/codebase.dot
• /path/to/workspace/codebase.puml
• /path/to/workspace/codebase.json

If you want a different output directory:

cargo statum-graph export \
  /path/to/workspace \
  --out-dir /tmp/codebase-graph

If you want to narrow export to one library package inside a multi-package workspace:

cargo statum-graph export \
  /path/to/workspace \
  --package app

codebase still works as a compatibility alias in this release, but export is now the primary command name.

For local development against an unreleased Statum checkout, add --patch-statum-root /path/to/statum.

Inspect

cargo statum-graph inspect \
  /path/to/workspace

That launches the inspector TUI for the selected workspace. The current surface shows:

• workspace sections for Composition, Machines, and Gaps
• composition-first home view when any #[machine(role = composition)] machines exist
• composition view with the selected flow’s states, transitions, validators, summary edges, and a bottom-pane path explorer
• path explorer that prefers composition-owned routes, then raw exact graph routes, then heuristic fallback when the current lane allows it
• gap view that surfaces composition warnings and heuristic-only suggestions together with the best currently visible path to the suggested target
• machine view with states, transitions, validator entries, and summary edges for leaf protocol drilldown
• composition machines surfaced from #[machine(role = composition)], with composition-owned direct child-machine edges labeled as composition refs instead of generic exact references
• relation pane with inbound and outbound exact relations plus optional heuristic machine-to-machine coupling hints
• explicit empty-state guidance when the selected state or transition has no direct relations but the machine does
• search plus exact relation-kind filters and current relation-basis filters for direct-type and declared-reference relations
• heuristic evidence filters for type-surface and body matches
• exact-only, heuristic-only, and mixed lane toggles
• detail pane explaining the current selection, including #[present(description = ...)] text and source rustdoc (///) when available. For #[via(...)] relations, the detail pane also shows the attested route, producer machine, producer source state, and producer transition. Composition-owned exact relations also show their composition semantics and source/target machine roles. Summary and exact relation cards now prefer those composition-owned explanations. Machine detail also shows composition diagnostics when a protocol machine still looks like a composition candidate.

If composition machines exist, the inspector opens on Composition first. If none exist, it falls back to Machines.

inspect requires an interactive terminal on stdin and stdout.

Suggest

cargo statum-graph suggest \
  /path/to/workspace

That prints composition diagnostics without launching the TUI.

• warning means a protocol machine already exposes exact typed cross-machine orchestration and should likely be marked #[machine(role = composition)].
• suggestion means the coupling is still only visible through the heuristic lane, so the next step is to model it in typed composition state or transition surfaces or promote a detached handoff into the exact lane.
• The report also prints heuristic collector status so a quiet suggestion list does not hide partial or unavailable source scanning.

Keybindings:

• tab / shift-tab: move focus between panes
• w: cycle available workspace sections
• h / l: switch machine tabs or toggle relation direction in Machines
• j / k: move within the focused list
• /: enter search mode
• enter / esc: leave search mode
• m: cycle exact, heuristic, and mixed lanes
• 1 / 2 / 3: toggle payload, field, and param relation filters
• 4 / 5: toggle direct-type and declared-reference relation-basis filters
• 6 / 7: toggle heuristic type-surface and body evidence filters
• 0: clear relation filters
• q: quit

Exact lane:

• consumes the linked compiled CodebaseDoc surface directly
• is the only lane backed by Mermaid, DOT, PlantUML, and JSON export
• drives the composition home view and path explorer before any heuristic fallback is considered
• is where #[via(...)] relations appear with exact producer-route detail
• is where direct child-machine references on #[machine(role = composition)] machines appear as composition-owned exact relations
• fails closed on malformed exact relation inventories instead of writing a partial graph bundle or inspector view

Heuristic lane:

• is TUI-only
• scans raw source from the selected packages' reachable library module trees
• supports #[path = ...] mod ...; module edges while walking those trees
• scans state payload types, local payload structs reachable from those states, transition signatures and bodies, and non-transition impl Machine<State> method signatures
• resolves only to already-known exact machines
• stays machine-first in v1, so it does not claim heuristic target states or transitions
• hides heuristic relations in mixed mode when the exact lane already covers the same source machine/state-or-transition and target machine

The heuristic lane is useful but non-authoritative. It does not change export output. Runtime replay and snapshot inspection are still future work.

If you are moving a workspace from loose cross-machine coupling into typed composition flow, start with docs/composition-migration.md and the composition example in statum-examples/src/toy_demos/example_18_composition_machine.rs.

If a cross-flow artifact or handoff type is stable enough to count as exact, promote it with #[machine_ref(...)] on the nominal type once instead of depending on the heuristic lane. Target the earliest stable producer state for that artifact.

For concise labels and descriptions in the inspector, use #[present(...)]. For fuller detail-pane docs that also show up in rustdoc, use outer rustdoc comments on the machine, state variants, transition methods, and #[validators] impls.