diff

Documentation

Overview

Package diff compares two versioned contracts and classifies each change as non-breaking, potentially breaking, or breaking to downstream consumers. A deterministic rule table drives classification across service identity, interfaces, configuration, policies, dependencies, runtime, and embedded OpenAPI and SBOM artifacts, so the same change always classifies the same way.

Index

• type Change
• type ChangeType
  • func (t ChangeType) MarshalJSON() ([]byte, error)
  • func (t ChangeType) String() string
• type Classification
  • func (c Classification) MarshalJSON() ([]byte, error)
  • func (c Classification) String() string
• type Result
  • func Compare(old, new *contract.Contract, oldFS, newFS fs.FS) *Result

Types

type Change

type Change struct {
	Path           string         `json:"path"`
	Type           ChangeType     `json:"type"`
	OldValue       any            `json:"oldValue,omitempty"`
	NewValue       any            `json:"newValue,omitempty"`
	Classification Classification `json:"classification"`
	Reason         string         `json:"reason"`
}

Change represents a single detected change between two contracts.

type ChangeType

type ChangeType int

ChangeType describes how a field changed.

const (
	Added ChangeType = iota
	Removed
	Modified
)

func (ChangeType) MarshalJSON

func (t ChangeType) MarshalJSON() ([]byte, error)

MarshalJSON serializes the ChangeType as its lowercase String form (e.g. "added").

func (ChangeType) String

func (t ChangeType) String() string

String returns the lowercase name: "added", "removed", "modified", or "unknown".

type Classification

type Classification int

Classification represents the severity of a change.

const (
	NonBreaking       Classification = iota // Consumers are not affected.
	PotentialBreaking                       // Consumers may be affected.
	Breaking                                // Consumers are definitely affected.
)

func (Classification) MarshalJSON

func (c Classification) MarshalJSON() ([]byte, error)

MarshalJSON serializes the Classification as its String form (e.g. "BREAKING").

func (Classification) String

func (c Classification) String() string

String returns the upper-snake-case name: "NON_BREAKING", "POTENTIAL_BREAKING", "BREAKING", or "UNKNOWN".

type Result

type Result struct {
	Classification Classification `json:"classification"`
	Changes        []Change       `json:"changes"`
	SBOMDiff       *sbom.Result   `json:"sbomDiff,omitempty"`
}

Result holds the output of comparing two contracts.

func Compare

func Compare(old, new *contract.Contract, oldFS, newFS fs.FS) *Result

Compare compares two contracts and produces a classified diff result. oldFS and newFS provide access to referenced files (OpenAPI specs, JSON Schemas) within each contract's bundle. Either may be nil if file-level diffs are not needed.