linter

package
v1.27.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 17, 2026 License: MIT Imports: 4 Imported by: 0

README

Arazzo Linter

The Arazzo linter checks Arazzo workflow documents for semantic issues, style and security concerns beyond what arazzo.Validate reports, such as steps that can never run, dependency cycles and unused components.

It uses the same engine, configuration format and output formats as the OpenAPI linter.

Quick Start

CLI
# Lint an Arazzo document, checking it against the documents its sourceDescriptions reference
openapi arazzo lint workflow.arazzo.yaml

# Only lint the document itself, without loading its sources
openapi arazzo lint --skip-sources workflow.arazzo.yaml

# Output as JSON
openapi arazzo lint --format json workflow.arazzo.yaml

# Use the recommended ruleset, and disable specific rules
openapi arazzo lint --ruleset recommended --disable style-step-success-criteria workflow.arazzo.yaml

# Apply the fixes that don't need input, or preview them first
openapi arazzo lint --fix workflow.arazzo.yaml
openapi arazzo lint --fix --dry-run workflow.arazzo.yaml

# Also be prompted for the fixes that need input
openapi arazzo lint --fix-interactive workflow.arazzo.yaml

# List the available rules
openapi arazzo list-rules
Go API
import (
    "context"
    "fmt"
    "os"

    "github.com/speakeasy-api/openapi/arazzo"
    arazzoLinter "github.com/speakeasy-api/openapi/arazzo/linter"
    "github.com/speakeasy-api/openapi/linter"
)

func main() {
    ctx := context.Background()

    f, err := os.Open("workflow.arazzo.yaml")
    if err != nil {
        panic(err)
    }
    defer f.Close()

    doc, validationErrors, err := arazzo.Unmarshal(ctx, f)
    if err != nil {
        panic(err)
    }

    // Optionally load the sourceDescriptions, so findings can be checked against them and fixes can use them
    sources, loadErrors := arazzo.LoadSourceDescriptions(ctx, doc, arazzo.LoadSourcesOptions{DocumentLocation: "workflow.arazzo.yaml"})
    validationErrors = append(validationErrors, loadErrors...)
    validationErrors = append(validationErrors, doc.ValidateSources(ctx, sources)...)
    ctx = arazzoLinter.WithSourceDocuments(ctx, sources)

    lint := arazzoLinter.NewLinter(linter.NewConfig())
    output, err := lint.Lint(ctx, linter.NewDocumentInfo(doc, "workflow.arazzo.yaml"), validationErrors, nil)
    if err != nil {
        panic(err)
    }

    fmt.Println(output.FormatText())
}

Fixes can be applied with the shared fix engine's ProcessDocumentErrors, then the document written back with arazzo.Marshal.

Available Rules

Rule Severity Description
security-source-description-https warning Source descriptions should be loaded over HTTPS. A document fetched over plain HTTP can be modified in transit, which can redirect a workflow's steps to different operations or servers. Local addresses (localhost and loopback IPs) are not reported.
semantic-dependency-cycle error Workflows and steps must not depend on each other in a cycle. A workflow or step only runs once everything in its dependsOn has completed, so none of the workflows or steps in a cycle can ever run.
semantic-unreachable-step warning Every step should be reachable. Steps run in order unless a success or failure action ends the workflow or goes to another step, so a step is unreachable when every path to it is cut off by an unconditional end or goto and no action goes to it. Unreachable steps are usually left over from a refactor, or a sign that an action's criteria are missing.
semantic-unused-component warning Components that are never referenced should be removed. Inputs are referenced with $ref: '#/components/inputs/<name>', and parameters and actions with reference: $components.<type>.<name>. A component only referenced by itself is unused.
semantic-unused-step-output hint Step outputs should be used. A step's outputs can only be read within its workflow, by later steps or by the workflow's outputs, so an output that is never read has no effect.
semantic-unused-workflow-input warning Workflow inputs should be used. An input is only available to a workflow through $inputs expressions, so an input that is never read either isn't needed, or a step is missing the parameter or payload value that should use it.
style-info-description warning The info section should include a description that explains what the workflows in the document do and when to use them, so readers don't have to infer it from the individual steps.
style-retry-after hint Retry failure actions should set retryAfter. Without it the step is retried immediately, which rarely helps with the transient failures retries are meant for (rate limits, eventual consistency) and adds load to a struggling API.
style-source-description-type warning Source descriptions should declare their type. Without it, tools have to load the document to know whether it is an OpenAPI, AsyncAPI or Arazzo document, and some checks (such as which steps may use channelPath or action) can't be made from the Arazzo document alone.
style-step-success-criteria warning Steps that call an operation or channel should declare successCriteria. Without them, any response is treated as success, so a workflow can carry on after an error response and fail later in a way that is harder to diagnose. Steps that run another workflow are not checked, as their success is decided by that workflow.
style-workflow-description hint Workflows should have a summary or description that explains the outcome they achieve. Workflow IDs are often terse, and a short explanation helps people and tools pick the right workflow.

Rulesets

Ruleset Rules
all Every rule (the default)
recommended Every rule except the hint level rules (semantic-unused-step-output, style-workflow-description and style-retry-after), which are useful while authoring but noisier

Configuration

The CLI looks for a configuration file at ~/.openapi/arazzo-lint.yaml, separate from the OpenAPI linter's ~/.openapi/lint.yaml as the rules and rulesets differ. Use --config to use a different file.

extends: recommended

rules:
  # Change severity
  - id: style-step-success-criteria
    severity: error

  # Disable a rule
  - id: semantic-unused-step-output
    disabled: true

  # Filter by message pattern
  - id: security-source-description-https
    match: ".*internal.example.com.*"
    disabled: true

categories:
  # Disable an entire category
  style:
    enabled: false

Custom rules are not supported for Arazzo documents yet, so custom_rules is ignored.

Documentation

Overview

Package linter lints Arazzo documents for semantic issues, style and security concerns beyond what arazzo.Validate reports, using the shared linter engine, configuration and output formats.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func WithSourceDocuments

func WithSourceDocuments(ctx context.Context, sources *arazzo.SourceDocuments) context.Context

WithSourceDocuments returns a context carrying the documents loaded for the Arazzo document's sourceDescriptions (see arazzo.LoadSourceDescriptions), which rules use to improve their findings and fixes.

Types

type Linter

type Linter struct {
	// contains filtered or unexported fields
}

Linter lints Arazzo documents.

func NewLinter

func NewLinter(config *baseLinter.Config, opts ...NewLinterOption) *Linter

NewLinter creates a new Arazzo linter. By default all built-in rules and rulesets are registered.

func (*Linter) FilterErrors

func (l *Linter) FilterErrors(errs []error) []error

FilterErrors applies rule-level overrides and match filters to arbitrary errors, such as validation errors collected separately from Lint.

func (*Linter) Lint

func (l *Linter) Lint(ctx context.Context, docInfo *baseLinter.DocumentInfo[*arazzo.Arazzo], preExistingErrors []error, opts *baseLinter.LintOptions) (*baseLinter.Output, error)

Lint runs the configured rules against the document. preExistingErrors, such as the errors returned by arazzo.Unmarshal and (*arazzo.Arazzo).ValidateSources, are included in the output after severity overrides and filters are applied.

Rules can make use of the documents loaded for the document's sourceDescriptions when they are provided with WithSourceDocuments.

Rules check the version the document declares themselves, so opts.VersionFilter isn't needed.

func (*Linter) Registry

func (l *Linter) Registry() *baseLinter.Registry[*arazzo.Arazzo]

Registry returns the rule registry, for registering rules and generating documentation.

type NewLinterOption

type NewLinterOption func(*newLinterOpts)

NewLinterOption configures NewLinter.

func WithoutDefaultRules

func WithoutDefaultRules() NewLinterOption

WithoutDefaultRules creates a linter with no rules registered, so specific rules can be registered with Registry().Register().

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL