feat: add arazzo graph command for Mermaid and DOT workflow diagrams

Merged
TR
4d ago
+5817-81

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, .dot and .gv output files get DOT.
  • --workflow <id> renders a single workflow. --direction TB|LR sets 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:

EdgeMermaidDOT
Step following on to the next stepsolidsolid
Success gotogreengreen
Failure goto or retry (self-loop)dashed reddashed red
Workflow or step dependsOndashed greydotted grey
Step running another workflowthickbold

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 criteria always 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 end actions 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. Duplicate workflowIds or stepIds 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-cli diffs the CLI output against them.
  • The CLI README has a worked example in a mermaid block, 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 goto and retry actions, dependsOn entries, 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/.gv output files default to DOT.
  • Success/failure action resolution (including components references) moved to arazzo/internal/actions and 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.