Help us shape the future of Go! Take the 2026 Go Developer Survey

contracts

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Oct 11, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package contracts checks explicitly declared contracts with bounded schema support.

Index

Constants

View Source 
const ManifestPath = ".radar/contracts.json"

ManifestPath is the committed location of explicit contract bindings.

Variables

This section is empty.

Functions

func DecodeDocument 

func DecodeDocument(data []byte) (map[string]any, error)

DecodeDocument decodes a JSON contract document.

func DecodeDocumentAt 

func DecodeDocumentAt(p string, data []byte) (map[string]any, error)

DecodeDocumentAt decodes JSON, or YAML when the path ends in .yaml/.yml. YAML is normalized through JSON so both formats compare identically.

func FieldOverlaps 

func FieldOverlaps(declared, changed string) bool

FieldOverlaps reports whether a declared consumer field depends on a changed schema field: the same field, a nested field of it, or an enclosing object.

func MissingConsumerFields 

func MissingConsumerFields(content []byte, fields []string) []string

MissingConsumerFields returns declared fields whose final name does not occur as an identifier in the consumer source. This lexical check flags declarations that may be stale; presence does not prove runtime use.

func Pointer 

func Pointer(doc map[string]any, pointer string) (map[string]any, error)

Pointer resolves an object inside a contract document.

func ReadSchema 

func ReadSchema(ctx context.Context, root, ref, path string) (map[string]any, error)

ReadSchema reads a JSON or YAML contract document at ref.

Types

type Binding 

type Binding struct {
	ID        string   `json:"id"`
	Schema    string   `json:"schema"`
	Pointer   string   `json:"pointer"`
	Producer  string   `json:"producer"`
	Consumer  string   `json:"consumer"`
	Fields    []string `json:"fields"`
	Direction string   `json:"direction,omitempty"`
}

type BindingCheck 

type BindingCheck struct {
	ID     string       `json:"id"`
	Status model.Status `json:"status"`
	Issues []string     `json:"issues"`
	Notes  []string     `json:"notes,omitempty"`
}

BindingCheck reports whether one binding can be analyzed and still matches the files it declares.

type CellResult 

type CellResult struct {
	Producer string          `json:"producer"`
	Consumer string          `json:"consumer"`
	Status   model.Status    `json:"status"`
	Findings []model.Finding `json:"findings"`
	Reason   string          `json:"reason,omitempty"`
}

type Change 

type Change struct {
	BeforeType  string   `json:"before_type,omitempty"`
	AfterType   string   `json:"after_type,omitempty"`
	Field       string   `json:"field"`
	Kind        string   `json:"kind"`
	Values      []string `json:"values,omitempty"`
	Explanation string   `json:"explanation"`
}

func Compare 

func Compare(before, after map[string]any, pointer string) ([]Change, error)

Compare reports supported differences between two schema objects. Unsupported constructs that differ are reported as changes of kind "unanalyzed".

type LinkInput 

type LinkInput struct {
	ID                     string         `json:"id"`
	Direction              string         `json:"direction,omitempty"`
	Pointer                string         `json:"pointer"`
	ProducerBase           map[string]any `json:"producer_base"`
	ProducerCandidate      map[string]any `json:"producer_candidate"`
	ProducerBaseErr        error          `json:"-"`
	ProducerCandidateErr   error          `json:"-"`
	ConsumerBase           []string       `json:"consumer_base"`
	ConsumerCandidate      []string       `json:"consumer_candidate"`
	ConsumerBaseState      string         `json:"consumer_base_state"`
	ConsumerCandidateState string         `json:"consumer_candidate_state"`
	LinkBaseState          string         `json:"link_base_state,omitempty"`
	LinkCandidateState     string         `json:"link_candidate_state,omitempty"`
	Retirements            []Retirement   `json:"retirements,omitempty"`
}

LinkInput contains committed documents and explicit consumer declarations. Empty link states mean present, for callers that have no declaration delta. Retirements are the reviewed declarations the caller accepts for this delta. Because repositories merge independently, workspace links pass the candidate team file's retirements, including those already on its base.

type LinkResult 

type LinkResult struct {
	ID    string        `json:"id"`
	Cells [4]CellResult `json:"cells"`
	// Status uses candidate+candidate only; intermediate failures are rollout hints.
	Status      model.Status       `json:"status"`
	Obligations []ObligationChange `json:"obligations,omitempty"`
}
func CheckLink(in LinkInput) LinkResult

CheckLink checks the four producer/consumer combinations without executing repository code. A field declaration is structural evidence, not runtime usage.

type LintReport 

type LintReport struct {
	Status   model.Status   `json:"status"`
	Revision string         `json:"revision"`
	Bindings []BindingCheck `json:"bindings"`
	Error    string         `json:"error,omitempty"`
}

LintReport summarizes `radar contracts`.

func Lint 

func Lint(ctx context.Context, root, ref string) LintReport

Lint checks the manifest at ref: schema analyzability, pointers, declared files, declared fields against the schema, and lexical consumer drift.

type Manifest 

type Manifest struct {
	Version  int          `json:"version"`
	Bindings []Binding    `json:"bindings"`
	Retired  []Retirement `json:"retired,omitempty"`
}

func LoadManifest 

func LoadManifest(ctx context.Context, root, ref string) (Manifest, error)

type ObligationChange 

type ObligationChange struct {
	Binding string `json:"binding"`
	Head    string `json:"head"`
	// Kind is removed, narrowed, moved, retired, consumer_removed or invalid.
	Kind        string `json:"kind"`
	Explanation string `json:"explanation"`
}

ObligationChange records how a binding declared at base differs at a head.

type Report 

type Report struct {
	Status      model.Status       `json:"status"`
	Checkpoint  string             `json:"checkpoint"`
	Base        string             `json:"base"`
	Heads       []string           `json:"heads"`
	Bindings    int                `json:"bindings"`
	Analyzed    int                `json:"analyzed"`
	Findings    []model.Finding    `json:"findings"`
	Diagnostics []model.Diagnostic `json:"diagnostics"`
	// Obligations lists base declarations removed, narrowed, moved or retired.
	Obligations []ObligationChange `json:"obligation_changes"`
	// Unverified lists reasons no-breaking-contracts cannot be established.
	Unverified []string `json:"unverified_obligations"`
}

Report is the outcome of a committed or working-tree contract comparison. Status is "incomplete" when a binding could not be analyzed, so a clean finding list never hides skipped contracts.

func Impact 

func Impact(ctx context.Context, root, base, head string, approved ...Retirement) (Report, error)

Impact compares declared obligations at base with head. approved lists retirements reviewed outside the manifest (an approved plan's removal delta); they apply in addition to "retired" entries the head manifest introduces.

func Scan 

func Scan(ctx context.Context, root, base string, branches []string) (Report, error)

func (Report) Unestablished 

func (r Report) Unestablished() []string

Unestablished returns every reason the report cannot support a passing no-breaking-contracts verdict, independent of the finding list.

type Retirement 

type Retirement struct {
	ID     string   `json:"id"`
	Fields []string `json:"fields,omitempty"`
	Reason string   `json:"reason"`
}

Retirement explicitly withdraws a previously declared obligation, or some of its fields, so its removal is a reviewable manifest change rather than a silent loss of verification coverage. Radar records but cannot verify who reviewed it; protect .radar/ with code ownership where that matters.

type Schema 

type Schema struct {
	Types       []string // sorted; nil means unconstrained
	Properties  map[string]*Schema
	Required    []string
	Items       *Schema
	Enum        []string // canonical JSON values; nil means no enum
	Constraints string   // canonical JSON of validation keywords
	Opaque      string   // reason this subtree is not analyzed
	Raw         string   // canonical expanded form of an opaque subtree
	Ignored     []string // unrecognized keywords
}

Schema is the normalized subset of JSON Schema/OpenAPI Radar compares. Annotations are dropped, validation keywords are summarized, and constructs Radar cannot reason about are kept as opaque subtrees.

func Analyzable 

func Analyzable(doc map[string]any, pointer string) (*Schema, error)

Analyzable reports whether the object at pointer can be normalized.

func Normalize 

func Normalize(doc, schema map[string]any) (*Schema, error)

Normalize resolves local references and reduces a schema object.

func (*Schema) Field 

func (s *Schema) Field(field string) (*Schema, bool)

Field resolves a dotted field path ("a.b", "items[].id") in a normalized schema, descending into array items when needed.

func (*Schema) Notes 

func (s *Schema) Notes(field string) []string

Notes lists unsupported subtrees and ignored keywords below a schema, for diagnostics.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.