feat: add arazzo graph command for Mermaid and DOT workflow diagrams
Stacked on #315 (which is stacked on #306 and #305). Review those first; this PR's diff is against feat/arazzo-lint.
Why
An Arazzo document is hard to follow once workflows have more than a few steps. The flow is spread across step order, onSuccess/onFailure actions (some inherited from the workflow or pulled in from components), dependsOn lists and steps that run other workflows. There was no way to see that flow other than reading the YAML.
What changed
openapi arazzo graph <file> [output-file] renders the workflows as a Mermaid flowchart (default) or a Graphviz DOT digraph.
--format mermaid|dot. When the flag isn't given,.dotand.gvoutput files get DOT.--workflow <id>renders a single workflow.--direction TB|LRsets the layout.- Stdin is supported, and output goes to stdout unless an output file is given.
Each workflow is a group with a start node and its steps. Each step shows its operationId, operationPath, channelPath or workflow. Edges:
| Edge | Mermaid | DOT |
|---|---|---|
| Step following on to the next step | solid | solid |
Success goto | green | green |
Failure goto or retry (self-loop) | dashed red | dashed red |
Workflow or step dependsOn | dashed grey | dotted grey |
| Step running another workflow | thick | bold |
Workflows and steps outside the diagram, such as $sourceDescriptions.shared.audit or workflows left out by --workflow, are drawn as dashed external nodes.
The library is arazzo/graph. Build(doc, Options) returns an exported model (workflows, steps, external nodes, typed edges), so other renderers can use it. Write, WriteMermaid and WriteDOT do the rendering.
The success and failure action resolution that the lint's semantic-unreachable-step rule used now lives in arazzo/internal/actions and is shared by both. It resolves components references, with step actions overriding workflow actions by name.
Review notes
- Fall-through follows the same reading as the unreachable-step rule. Actions apply in order and the first match wins, so an action without
criteriaalways applies. Later actions aren't drawn, and the step only follows on to the next step if none of its success actions apply unconditionally. - Conditional
endactions aren't drawn. The step still falls through, which is what the diagram shows. - The graph doesn't validate the document (
WithSkipValidation), so it still draws work-in-progress documents. DuplicateworkflowIds orstepIds are all drawn, and references resolve to the first. - The golden files
arazzo/testdata/graph/workflows.{mmd,dot}were checked by rendering them with mermaid 11 and@hpcc-js/wasm-graphviz: 13 edges and 2 clusters each, labels escaped correctly.test-clidiffs the CLI output against them. - The CLI README has a worked example in a
mermaidblock, so GitHub renders it. - Patch coverage measured locally: 160/161 blocks in the library and 24/28 in the CLI. The CLI gaps are
runGraph's os-stream wiring and two error branches the earlier format and nil checks make unreachable.
Summary by cubic
Adds openapi arazzo graph, bootstrap, and explore commands, plus the library code behind them.
graph renders an Arazzo document's workflows as a Mermaid flowchart or Graphviz DOT digraph, so control flow across steps, actions, dependencies, and sub-workflows is visible without reading the YAML.
- Each workflow is a cluster with a start node and steps; edges show step order, success/failure
gotoandretryactions,dependsOnentries, and steps running other workflows, with distinct colors and line styles per format. - Supports
--format mermaid|dot,--workflow,--direction TB|LR, stdin, and stdout output;.dot/.gvoutput files default to DOT. - Success/failure action resolution (including
componentsreferences) moved toarazzo/internal/actionsand shared with the lint unreachable-step rule. - The graph skips validation so work-in-progress documents still render; missing workflows, unknown directions, and unknown formats return targeted errors.
bootstrap generates starter workflows from an OpenAPI document, one per tag, with steps wired together by the document's links and targeting operations by operationId or operationPath.
explore launches an interactive terminal UI for browsing a document's workflows and steps.