report

Documentation

Overview

Package report builds the machine-readable bigo document — the Stage-1 integration contract of the ecosystem spec. Output plumbing only: all verdict logic is consumed from bound/engine/callsummary, never reimplemented.

Stability: SchemaVersion is semver, independent of bigo's release version. Changes within a major are additive-only; no field is ever reinterpreted. The normative artifact is schema/report.schema.json.

Index

• Constants
• func BadgeMain(version string, args []string) int
• func Compat(base, head Document) (string, error)
• func DiffMain(args []string) int
• func FormatMarkdown(fs []Finding, warning string) string
• func FormatText(fs []Finding, warning string) string
• func Main(version string, args []string) int
• type AssumptionJSON
• type BoundJSON
• type BudgetJSON
• type CauseJSON
• type Class
  • func Severity(fs []Finding) (Class, bool)
  • func (c Class) String() string
• type Document
  • func Collect(dir string, patterns []string, opts Options) (Document, error)
• type Endpoint
  • func Badge(doc Document) Endpoint
• type FactorJSON
• type Finding
  • func Diff(base, head Document) ([]Finding, string, error)
• type Function
• type Loaded
  • func LoadModule(dir string, patterns []string) (*Loaded, error)
  • func (l *Loaded) Document(opts Options) (Document, error)
• type Options
• type RecognitionJSON
• type SmellJSON
• type SpaceJSON
• type TrustEntry

Constants

const (
	ProvenanceAssumed = "assumed"            // this function is an assumption's target
	ProvenanceTainted = "assumption-tainted" // an assumed summary is in this bound's support
)

Provenance values. Absence means "inferred" — the field is omitted for every function no assumption influenced, which is what keeps documents byte-identical to 1.1.0 output when no assumption file is supplied.

const CommentMarker = "<!-- bigo-diff -->"

CommentMarker identifies a bigo PR comment so the Action updates one comment in place instead of appending a new one per push. It is an HTML comment and renders invisibly on GitHub.

const SchemaVersion = "1.5.0"

SchemaVersion is the version of the document format. 1.1.0 added the top-level smells array. 1.2.0 added provenance and the top-level assumptions array. 1.3.0 added cause.callee. 1.4.0 added smells[].package. 1.5.0 added the top-level recognitions array (all additive; earlier documents remain valid).

Functions

func BadgeMain

func BadgeMain(version string, args []string) int

BadgeMain runs the `bigo badge` subcommand: it emits the shields.io endpoint badge, either by analyzing the module (default) or by projecting a report document supplied with -i ("-" for stdin). Exit codes match `bigo json`: 0 success (verdicts never affect the exit code), 1 analysis/IO/parse error, 2 flag error.

func Compat

func Compat(base, head Document) (string, error)

Compat decides whether two documents may be compared, and reports a warning when they may be compared but the comparison deserves a caveat.

Hard errors (apples-to-oranges): a different module, or a different schema major. Within a schema major the format is additive-only (document.go:5-7), so a minor difference is safe by construction.

Warning: a bigo version difference. Bounds may then differ because the engine changed rather than because the code changed, and reporting that as a regression would be a false accusation. The envelope carries no analysis configuration today, so the version is the only signal available.

func DiffMain

func DiffMain(args []string) int

DiffMain runs the `bigo diff base.json head.json` subcommand: it compares two report documents and renders the findings. Pure and offline — it analyzes nothing and reads no source.

Exit codes match the other subcommands: 0 success, 1 IO/parse/compatibility error, 2 usage error. Findings affect the exit code only when the caller opts in with -fail-on, which then adds 3 for a policy violation: by default the report describes and the consumer enforces.

func FormatMarkdown

func FormatMarkdown(fs []Finding, warning string) string

FormatMarkdown renders findings as a PR comment body, grouped by class in severity order. Always carries CommentMarker, including the all-clear case.

func FormatText

func FormatText(fs []Finding, warning string) string

FormatText renders findings for a terminal.

func Main

func Main(version string, args []string) int

Main runs the `bigo json` subcommand. Exit codes: 0 success (verdicts never affect the exit code — the report describes, a future diff tool enforces), 1 analysis or IO error, 2 flag error.

Types

type AssumptionJSON

type AssumptionJSON struct {
	Key   string `json:"key"`
	Bound string `json:"bound"`
}

AssumptionJSON is one external assumption in force during the run.

type BoundJSON

type BoundJSON struct {
	Top   bool                    `json:"top,omitempty"`
	Str   string                  `json:"str,omitempty"`
	Terms []map[string]FactorJSON `json:"terms,omitempty"`
}

BoundJSON is an asymptotic bound: top (unverifiable), or a canonical string plus the antichain of poly-log monomials. A monomial maps each size variable to its exponents; the empty object is O(1).

type BudgetJSON

type BudgetJSON struct {
	Raw     string     `json:"raw"`             // the directive as written
	Bound   *BoundJSON `json:"bound,omitempty"` // normalized budget; nil when invalid
	Verdict string     `json:"verdict"`
}

BudgetJSON is a declared budget and its verdict. Verdict vocabulary: within | exceeds | unverifiable | invalid (budget failed to normalize).

type CauseJSON

type CauseJSON struct {
	Kind   string `json:"kind"` // engine.CauseKind string: call, defer, go, loop, irreducible, nobody
	Detail string `json:"detail"`
	File   string `json:"file,omitempty"`
	Line   int    `json:"line,omitempty"`

	// Callee is the cost-table key of the blocking callee, when it has one:
	// package-qualified, receiver-qualified for methods, generic instantiations
	// resolved to their origin. It is the vocabulary a trust file is written in.
	//
	// Absent for loops, goroutines, interface dispatch and function values —
	// and that absence is the signal that no trust-file entry can address this
	// blocker. Detail is prose for humans and is never a substitute: the two
	// render a callee differently. Added in schema 1.3.0.
	Callee string `json:"callee,omitempty"`
}

CauseJSON is one reason a bound is unverifiable (engine.Cause, serialized).

type Class

type Class int

Class is a finding's severity class, in the ecosystem spec's §5 order. Lower is more severe; Improvement is last because it is good news.

const (
	// BudgetBreak - a declared budget went from within to exceeds
	BudgetBreak Class = iota
	// ProvenRegression - both sides proven, head is asymptotically worse
	ProvenRegression
	// NewTop - a proven bound became unverifiable
	NewTop
	// NewFuncBreak - a function was added already exceeding its budget
	NewFuncBreak
	// Improvement - exceeds→within, a tightened bound, or ⊤→proven
	Improvement
	// TrustChanged - the verdict moved under a CHANGED TRUST SURFACE and this
	// function's bound rests on an assertion. Never an improvement and never a
	// regression: a trusted bound is the user's claim, so attributing its
	// effect to the code would be exactly the conflation this class prevents.
	//
	// Appended last on purpose: the values above are compared in tests and
	// rendered by name, so inserting would renumber them.
	TrustChanged
)

func Severity

func Severity(fs []Finding) (Class, bool)

Severity reports the worst non-improvement class present, and whether any exists. Improvements are never severe: a change that only makes things better must never trip an exit-code policy.

func (Class) String

func (c Class) String() string

type Document

type Document struct {
	SchemaVersion string       `json:"schema_version"`
	BigoVersion   string       `json:"bigo_version"`
	Module        string       `json:"module"`
	Generated     string       `json:"generated"` // RFC 3339, UTC
	Functions     []Function   `json:"functions"`
	Trusted       []TrustEntry `json:"trusted,omitempty"`

	// Assumptions are the external assumptions in force during the run — the
	// assumption analog of Trusted: any entry may have influenced any verdict.
	// Present since schema 1.2.0.
	Assumptions []AssumptionJSON `json:"assumptions,omitempty"`

	// Smells are advisory findings, deliberately a top-level array rather than
	// a field on Function: the document mirrors the engine's firewall, where a
	// smell can never influence a verdict. Present since schema 1.1.0.
	Smells []SmellJSON `json:"smells,omitempty"`

	// Recognitions are advisory bounds from matched algorithmic shapes: the
	// conventional bound for a named pattern, with the assumption it rests on.
	// Top level for the same reason Smells are — the document mirrors the
	// engine's firewall, where an advisory finding can never influence a
	// verdict. Present since schema 1.5.0.
	Recognitions []RecognitionJSON `json:"recognitions,omitempty"`
}

Document is one `bigo json` run over one module.

func Collect

func Collect(dir string, patterns []string, opts Options) (Document, error)

Collect analyzes the module at dir (patterns as for `go build`, default ./...) and returns the report document. Analysis is the same InferTop / SpaceOf pipeline the analyzer runs; Collect adds no inference of its own.

type Endpoint

type Endpoint struct {
	SchemaVersion int    `json:"schemaVersion"`
	Label         string `json:"label"`
	Message       string `json:"message"`
	Color         string `json:"color"`
}

Endpoint is a shields.io endpoint-badge document. SchemaVersion is shields' own contract (always 1), unrelated to the report Document's SchemaVersion. bigo writes this JSON; a repo commits or publishes it and points shields.io at it as a static endpoint (https://shields.io/badges/endpoint-badge).

func Badge

func Badge(doc Document) Endpoint

Badge projects a report Document into the budget badge — the honest anti-rating (spec §6). It claims only that the functions this module chose to budget are verified within those budgets; unverifiable and invalid budgets are counted in the message, never hidden. Every declared budget counts once: a function with both a //bigo:max and a //bigo:space contributes two. Verdicts are read verbatim off the document — the badge reinterprets nothing.

type FactorJSON

type FactorJSON struct {
	Pow int `json:"pow,omitempty"`
	Log int `json:"log,omitempty"`
}

FactorJSON is one variable's exponents within a monomial: v^pow · (log v)^log.

type Finding

type Finding struct {
	Class   Class
	Key     string // the join identity from keysOf: package.(receiver).func, plus #ordinal when the name repeats in its package
	File    string
	Line    int
	Message string
}

Finding is one reportable difference.

func Diff

func Diff(base, head Document) ([]Finding, string, error)

Diff compares two report documents and returns findings ordered by severity then key, plus any compatibility warning.

Silence is the default and is load-bearing: ⊤→⊤, unchanged bounds, removed functions, and pre-existing breaks all produce nothing. Only differences this diff can attribute to the change between base and head are reported.

type Function

type Function struct {
	Package  string      `json:"package"`
	Func     string      `json:"func"`
	Receiver string      `json:"receiver,omitempty"` // e.g. "*Tree"; empty for plain functions
	File     string      `json:"file"`               // module-relative, forward slashes
	Line     int         `json:"line"`
	Time     BoundJSON   `json:"time"`
	Causes   []CauseJSON `json:"causes,omitempty"` // present exactly when time.top
	Budget   *BudgetJSON `json:"budget,omitempty"` // //bigo:max, when declared
	Space    *SpaceJSON  `json:"space,omitempty"`  // //bigo:space, when declared
	Trust    []string    `json:"trust,omitempty"`  // raw //bigo:cost / //bigo:ignore on this decl

	// Provenance marks assumption influence: ProvenanceAssumed on an
	// assumption's own target, ProvenanceTainted downstream. Absent when no
	// assumption touched this entry (i.e. inferred). Since schema 1.2.0.
	Provenance string `json:"provenance,omitempty"`
}

Function is one analyzed function or method.

type Loaded

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

Loaded is a parsed, type-checked, SSA-built module, ready to produce documents. Splitting the load from the analysis lets a multi-pass consumer (the what-if harness) build SSA once per target and run Document once per candidate assumption set.

Every piece of per-Document state — resolvers, warning dedup, the document itself — is constructed inside Document. The only mutable state shared across Document calls is costtable's stability memo, which is safe: field stability is a pure CFG fact, independent of assumptions.

func LoadModule

func LoadModule(dir string, patterns []string) (*Loaded, error)

LoadModule loads and builds the module at dir (patterns as for `go build`, default ./...).

func (*Loaded) Document

func (l *Loaded) Document(opts Options) (Document, error)

Document runs the analysis pipeline over the loaded module and returns one report document.

type Options

type Options struct {
	Version string
	Now     func() time.Time

	// Assume is an external assumption set (spec 2026-07-24). Validated
	// against the whole loaded program before analysis; nil disables the
	// mechanism entirely.
	Assume *assume.Set
	// Warn receives shadowing warnings (deduplicated); nil drops them.
	Warn func(string)

	// Overlay is a cost-model overlay that OUTRANKS the curated cost table,
	// the mechanism the -kata profile uses. It is separate from Assume because
	// the two answer different questions: an assumption is a claim about code
	// bigo cannot see, while an overlay REPLACES an answer bigo already has
	// with the one a different cost model gives. `strings.Compare` is
	// O(len(a)) because that is true, and O(1) because one record comparison
	// is one element operation; both are correct, for different questions.
	//
	// SpaceOverlay is the same mechanism on the heap axis, and is deliberately
	// a SEPARATE field rather than a second column on Overlay: what a call
	// costs and what it allocates are two assertions, and one field asserting
	// both would leave half of every entry unreasoned.
	//
	// A consumer applying a cost model must set BOTH, or the document carries
	// one axis under the chosen model and the other under the default.
	Overlay      *assume.Set
	SpaceOverlay *assume.Set

	// AssumeUnmatchedKeys, when non-nil, receives the assumption keys that
	// matched no function in THIS module instead of failing the run. Only a
	// multi-module consumer may set it: over one module an unmatched key is a
	// typo and must stay loud, but across a population a key absent from one
	// module contributes zero to it by arithmetic. The sweep sets this and then
	// requires every key to match somewhere, which is the same protection.
	AssumeUnmatchedKeys func([]string)
}

Options configures a Collect run. Version fills the envelope's bigo_version; Now is injectable for deterministic goldens and defaults to time.Now.

type RecognitionJSON

type RecognitionJSON struct {
	Package    string `json:"package,omitempty"`
	Func       string `json:"func"`
	Pattern    string `json:"pattern"`
	Kind       string `json:"kind"` // worst | amortized | expected
	Bound      string `json:"bound"`
	Assumption string `json:"assumption"`
	File       string `json:"file"` // module-relative, forward slashes
	Line       int    `json:"line"`
}

RecognitionJSON is one advisory recognized shape. Like SmellJSON this is carried in a TOP-LEVEL array rather than on Function, because a recognition can never influence a verdict and the document is built to make that structural rather than a convention.

Bound is rendered text, not a serialized bound: it may name a quantity the bound algebra cannot express, such as the number of nodes reachable from a pointer. Assumption states the preconditions the bound rests on, including any bigo cannot itself verify, and is what makes the claim honest rather than merely unproved. Present since schema 1.5.0.

type SmellJSON

type SmellJSON struct {
	Package string `json:"package,omitempty"`
	Rule    string `json:"rule"`
	Message string `json:"message"`
	File    string `json:"file"` // module-relative, forward slashes
	Line    int    `json:"line"`
}

SmellJSON is one advisory smell finding (internal/smell.Finding, serialized). Rule is the canonical ID (SM1..SM8); Message carries no "smell(SMn):" prefix — that is the analyzer's diagnostic presentation, not part of the data.

Package is present since schema 1.4.0 and exists so consumers can apply frontier.FirstParty: File alone cannot distinguish this module's code from a dependency's, which put third-party findings into the survey's triage queue.

type SpaceJSON

type SpaceJSON struct {
	Heap   BoundJSON   `json:"heap"`
	Stack  BoundJSON   `json:"stack"`
	Budget *BudgetJSON `json:"budget,omitempty"`
}

SpaceJSON is the //bigo:space picture: heap (total-allocation upper bound, proves Within only) and stack (true peak depth, proves both).

type TrustEntry

type TrustEntry struct {
	Package   string `json:"package"`
	Func      string `json:"func"`
	Receiver  string `json:"receiver,omitempty"`
	Directive string `json:"directive"` // the directive as written
}

TrustEntry is one //bigo:cost or //bigo:ignore assertion — the document's trust surface. Any entry may have influenced any verdict in the document.