feat: add arazzo lint and list-rules commands

Merged
TR
4d ago
+10412-80

Stacked on #306 (which is stacked on #305). Review those first; this PR's diff is against feat/arazzo-source-validation.

Why

openapi arazzo validate tells you whether a workflow document is spec-compliant and, since #306, whether it matches the OpenAPI and Arazzo documents it references. It doesn't catch documents that are valid but wrong or sloppy: steps that can never run, dependsOn cycles, components nobody references, inputs and outputs nothing reads, retries with no backoff, sources pulled over plain HTTP. The OpenAPI side already has openapi spec lint for this kind of thing. Arazzo had nothing equivalent.

What changed

openapi arazzo lint reports everything validate does, plus 11 lint rules. It mirrors openapi spec lint:

  • --ruleset all|recommended, --disable, --format text|json, --summary, and stdin support
  • Source descriptions are loaded and checked by default, same as validate. Use --skip-sources to lint offline.
  • Config lives at ~/.openapi/arazzo-lint.yaml, separate from lint.yaml because the rules and rulesets don't overlap. It's the same format.
  • --fix, --fix-interactive and --dry-run apply fixes and write the file back with arazzo.Marshal

openapi arazzo list-rules lists the rules, with --category, --ruleset and --format json filters.

RuleSeverityFix
semantic-unreachable-stepwarning
semantic-dependency-cycleerror
semantic-unused-componentwarningremoves it (and empty sections)
semantic-unused-workflow-inputwarning
semantic-unused-step-outputhint
style-step-success-criteriawarning
style-source-description-typewarningsets type from the loaded document, or asks
style-info-descriptionwarningasks for one
style-workflow-descriptionhint
style-retry-afterhint
security-source-description-httpswarning

recommended is all minus the three hint rules.

The library lives in arazzo/linter (NewLinter, Lint, WithSourceDocuments) and arazzo/linter/rules, built on the shared linter engine so config, severity overrides, match filters and output formats behave the same as the OpenAPI linter. cmd/update-lint-docs now generates the rule table in arazzo/linter/README.md as well.

Two changes outside arazzo/:

  • linter/fix: adds Engine.ProcessDocumentErrors(ctx, doc any, errs) so the fix engine can apply fixes to non-OpenAPI documents. ProcessErrors is unchanged. Node-level fixes are still OpenAPI only, and on other documents they fall back to Apply.
  • marshaller: fixes an existing bug where an optional field with a non-pointer scalar type (Arazzo's sourceDescription.type and criterion.type) was written out as type: "" when unset. A field tagged required:"false" whose value is the zero scalar is now removed instead of written. This also affected arazzo upgrade output for untyped sources, and it's what made the type fix's output clean.

Review notes

  • Reachability (semantic-unreachable-step) is deliberately conservative. A goto makes its target reachable, and only an unconditional end or goto stops fall-through to the next step. A failed step ends the workflow unless a failure action jumps somewhere. Workflow-level actions apply to every step unless a step action with the same name overrides them.
  • The unused-input and unused-output rules work on the raw YAML, so any $inputs.x or $steps.s.outputs.x mention anywhere in the workflow counts as a use. Dotted names are matched by prefix, because names can contain dots.
  • Custom (JS) rules aren't wired up for Arazzo, so custom_rules in the Arazzo config is ignored. That's documented in the README.
  • Patch coverage is about 98% locally. The gaps are file I/O error paths in the CLI.

Summary by cubic

Adds five new arazzo CLI commands — lint, list-rules, graph, bootstrap, and explore — and the libraries behind them. Stacked on #305 and #306; the diff is against feat/arazzo-source-validation.

openapi arazzo lint reports everything validate does plus 11 rules for semantic issues, style, and security: unreachable steps, dependsOn cycles, unused components/inputs/outputs, missing successCriteria, retries without retryAfter, untyped or plain-HTTP source descriptions, and missing descriptions. It supports --ruleset, --disable, --format, --summary, stdin, and offline linting with --skip-sources. --fix, --fix-interactive and --dry-run write fixes back with arazzo.Marshal. Config lives at ~/.openapi/arazzo-lint.yaml, and recommended is all minus the three hint rules. openapi arazzo list-rules lists rules with --category, --ruleset, and --format json filters. The linter is a new library in arazzo/linter and arazzo/linter/rules, built on the shared linter engine so config, severity overrides, and output formats behave like the OpenAPI linter.

openapi arazzo graph renders the document's workflows as a Mermaid flowchart or Graphviz DOT digraph, showing step order, success and failure gotos and retries, dependsOn edges, and workflow-runner steps. openapi arazzo bootstrap writes a new Arazzo document, either a best-practice template or starter workflows generated from an OpenAPI document's tagged operations, with steps wired by its links. openapi arazzo explore provides an interactive terminal browser for workflows and steps.

Outside arazzo/

  • Adds Engine.ProcessDocumentErrors to linter/fix so fixes apply to non-OpenAPI documents; node-level fixes fall back to Apply.
  • Extracts fix-result reporting into cmdutil.ReportFixResults, shared by the OpenAPI and Arazzo lint commands.
  • Fixes a marshaller bug where optional scalar fields (sourceDescription.type, criterion.type) were written as type: "" when unset. This also cleans up arazzo upgrade output for untyped sources.