analyze

Documentation

Overview

Package analyze provides combined API style analysis.

This package orchestrates both deterministic linting (via vacuum) and LLM-based evaluation (via judge) to produce comprehensive API quality assessments.

Key concepts:

• Analyzer: Orchestrates lint and evaluate operations
• AnalysisReport: Combined results from all analysis types
• Decision: GO/NO-GO recommendation based on configured thresholds

Usage:

spec, _ := profile.Load("azure")
analyzer := analyze.New(spec, provider)
report, err := analyzer.Analyze(ctx, openAPISpec, opts)
if report.Decision == analyze.DecisionNoGo {
    // Handle blocking issues
}

The analyzer can run lint-only, evaluate-only, or combined analysis based on the options provided.

Index

• type AnalysisMetadata
• type AnalysisReport
• type Analyzer
  • func New(spec *types.APIStyleSpec, provider judge.Provider) *Analyzer
  • func (a *Analyzer) Analyze(ctx context.Context, specBytes []byte, opts *Options) (*AnalysisReport, error)
  • func (a *Analyzer) Evaluate(ctx context.Context, specBytes []byte, opts *Options) (*judge.EvaluationReport, error)
  • func (a *Analyzer) HasEvaluator() bool
  • func (a *Analyzer) Lint(ctx context.Context, specBytes []byte, opts *Options) (*types.LintReport, error)
• type Decision
• type Options
  • func DefaultOptions() *Options

Types

type AnalysisMetadata

type AnalysisMetadata struct {
	// FileName is the analyzed spec file.
	FileName string `json:"fileName,omitempty"`

	// ProfileName is the style profile used.
	ProfileName string `json:"profileName,omitempty"`

	// Duration is the total analysis time.
	Duration string `json:"duration"`

	// Timestamp is when analysis was performed.
	Timestamp string `json:"timestamp"`

	// LintEnabled indicates if linting was performed.
	LintEnabled bool `json:"lintEnabled"`

	// EvaluateEnabled indicates if LLM evaluation was performed.
	EvaluateEnabled bool `json:"evaluateEnabled"`

	// ToolVersion is the api-style-spec version.
	ToolVersion string `json:"toolVersion,omitempty"`
}

AnalysisMetadata contains context about the analysis run.

type AnalysisReport

type AnalysisReport struct {
	// Decision is the GO/NO-GO recommendation.
	Decision Decision `json:"decision"`

	// Summary provides a human-readable overview.
	Summary string `json:"summary"`

	// LintReport contains deterministic linting results.
	LintReport *types.LintReport `json:"lintReport,omitempty"`

	// EvaluationReport contains LLM evaluation results.
	EvaluationReport *judge.EvaluationReport `json:"evaluationReport,omitempty"`

	// ConformanceLevel is the achieved conformance level.
	ConformanceLevel string `json:"conformanceLevel,omitempty"`

	// OverallScore is the combined score (0.0-1.0).
	OverallScore float64 `json:"overallScore"`

	// Metadata contains analysis context.
	Metadata AnalysisMetadata `json:"metadata"`
}

AnalysisReport contains the combined results of all analysis types.

type Analyzer

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

Analyzer orchestrates lint and LLM evaluation of API specifications.

func New

func New(spec *types.APIStyleSpec, provider judge.Provider) *Analyzer

New creates a new Analyzer with the given style spec and optional LLM provider. If provider is nil, LLM evaluation is disabled.

func (*Analyzer) Analyze

func (a *Analyzer) Analyze(ctx context.Context, specBytes []byte, opts *Options) (*AnalysisReport, error)

Analyze performs the full analysis of an API specification.

func (*Analyzer) Evaluate

func (a *Analyzer) Evaluate(ctx context.Context, specBytes []byte, opts *Options) (*judge.EvaluationReport, error)

Evaluate performs only LLM evaluation.

func (*Analyzer) HasEvaluator

func (a *Analyzer) HasEvaluator() bool

HasEvaluator returns true if an LLM evaluator is configured.

func (*Analyzer) Lint

func (a *Analyzer) Lint(ctx context.Context, specBytes []byte, opts *Options) (*types.LintReport, error)

Lint performs only deterministic linting.

type Decision

type Decision string

Decision represents the GO/NO-GO recommendation.

const (
	// DecisionGo means the API spec passes quality gates.
	DecisionGo Decision = "GO"
	// DecisionNoGo means the API spec has blocking issues.
	DecisionNoGo Decision = "NO-GO"
	// DecisionWarning means non-blocking issues were found.
	DecisionWarning Decision = "WARNING"
)

type Options

type Options struct {
	// FileName is the name of the spec file (for reporting).
	FileName string

	// EnableLint enables deterministic linting (default: true).
	EnableLint bool

	// EnableEvaluate enables LLM evaluation (default: false).
	EnableEvaluate bool

	// ConformanceLevel is the target level (bronze, silver, gold).
	ConformanceLevel string

	// LintOptions are passed to the linter.
	LintOptions *lint.Options

	// EvaluateOptions are passed to the evaluator.
	EvaluateOptions *judge.Options

	// FailOnWarnings makes warnings cause NO-GO decision.
	FailOnWarnings bool

	// MinScore is the minimum overall score required for GO (0.0-1.0).
	// Only applies when EnableEvaluate is true.
	MinScore float64
}

Options configures the analysis behavior.

func DefaultOptions

func DefaultOptions() *Options

DefaultOptions returns options with sensible defaults.