Pipecircuit visualization

pipecircuit-visualization derives reviewable architecture diagrams from a crate's Rust source. It walks the crate's module tree, finds every explicit StateMachine and StepInputOf implementation, follows imports, and expands each outcome enum into its variants.

No diagram-specific step list is maintained:

use pipecircuit_visualization::{CrateArchitecture, DiagramTarget};

let architecture = CrateArchitecture::read(env!("CARGO_MANIFEST_DIR"))?;
let players = architecture.state_machine("Players")?;
let snapshot = players.render(DiagramTarget::TextTree);

The uncolored text tree is intended for expect tests and redirected output. AnsiTextTree gives its role markers a terminal-safe lime treatment. The same graph can be projected to MermaidFlowchart for Markdown and browser tooling or GraphvizDot for Graphviz, SVG, and image generation.

The separately installable pipecircuit-cli package exposes the interactive surface:

pipec diagram Players

It selects ANSI text only for an interactive terminal and honors NO_COLOR.

Generation fails when a referenced local type, module, state machine, input, or outcome cannot be resolved. Procedural macros that generate StepInputOf implementations are not source-visible on stable Rust and are not currently supported; step implementations themselves must remain ordinary Rust. This keeps incomplete diagrams from masquerading as complete ones.

Behavior expectations

Keep a behavior.rs snapshot module beside a machine's tests and architecture expectation. Its inventory discovers the compiled tests automatically:

use expect_test::expect;
use pipecircuit_visualization::{BehaviorError, BehaviorInventory};

#[test]
fn behavior_remains_reviewable() -> Result<(), BehaviorError> {
    expect![[r#"
        - Equal sentences retain their distinct code locations
        - Listing order does not change the inventory
    "#]]
    .assert_eq(&BehaviorInventory::for_snapshot(module_path!())?.render());
    Ok(())
}

Register this dedicated child module with #[cfg(test)] mod behavior;. The inventory includes tests below its parent module and excludes its own module. Renaming, adding, or removing a check changes the expectation. Review the diff, then accept it with UPDATE_EXPECT=1 cargo test behavior_remains_reviewable.

Discovery asks the current test executable for its list; it neither reruns the checks nor starts Cargo. Macro-generated tests, including property tests, are included. Names become alphabetically sorted sentence bullets; duplicate sentences retain their code locations, and ignored tests carry [ignored].

This is a review aid, not evidence that a named claim passed. The ordinary verification run supplies that evidence. Discovery covers only the current libtest target and compiled features: other test targets, doctests, and Kani proof harnesses are not included. No production dependency or runtime instrumentation is needed in a consuming application's semantic core; use this library as a dev-dependency.