feat: add arazzo lint and list-rules commands
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-sourcesto lint offline. - Config lives at
~/.openapi/arazzo-lint.yaml, separate fromlint.yamlbecause the rules and rulesets don't overlap. It's the same format. --fix,--fix-interactiveand--dry-runapply fixes and write the file back witharazzo.Marshal
openapi arazzo list-rules lists the rules, with --category, --ruleset and --format json filters.
| Rule | Severity | Fix |
|---|---|---|
semantic-unreachable-step | warning | |
semantic-dependency-cycle | error | |
semantic-unused-component | warning | removes it (and empty sections) |
semantic-unused-workflow-input | warning | |
semantic-unused-step-output | hint | |
style-step-success-criteria | warning | |
style-source-description-type | warning | sets type from the loaded document, or asks |
style-info-description | warning | asks for one |
style-workflow-description | hint | |
style-retry-after | hint | |
security-source-description-https | warning |
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: addsEngine.ProcessDocumentErrors(ctx, doc any, errs)so the fix engine can apply fixes to non-OpenAPI documents.ProcessErrorsis unchanged. Node-level fixes are still OpenAPI only, and on other documents they fall back toApply.marshaller: fixes an existing bug where an optional field with a non-pointer scalar type (Arazzo'ssourceDescription.typeandcriterion.type) was written out astype: ""when unset. A field taggedrequired:"false"whose value is the zero scalar is now removed instead of written. This also affectedarazzo upgradeoutput for untyped sources, and it's what made thetypefix's output clean.
Review notes
- Reachability (
semantic-unreachable-step) is deliberately conservative. Agotomakes its target reachable, and only an unconditionalendorgotostops 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.xor$steps.s.outputs.xmention 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_rulesin 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.ProcessDocumentErrorstolinter/fixso fixes apply to non-OpenAPI documents; node-level fixes fall back toApply. - 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 astype: ""when unset. This also cleans uparazzo upgradeoutput for untyped sources.