analysis

Documentation

Overview

Package analysis implements BatchWeaver's static discovery and analysis foundation: it loads real Go programs, builds canonical identities, discovers operation declarations, constructs SSA and a conservative call graph, summarizes observable effects, indexes scalar-operation call sites, and produces a deterministic, versioned analysis snapshot.

The analysis never modifies source, never executes analyzed application code, and never claims that a discovered call is safe to transform. Unknown facts are represented explicitly as unknown, ambiguous, or deferred. Everything here is internal; no unstable go/types or SSA value is exposed as a public API.

Index

• Constants
• func RenderJSON(w io.Writer, snap *Snapshot) error
• func RenderText(w io.Writer, snap *Snapshot) error
• type BuildContext
• type CallEdge
• type CallSite
• type Candidate
• type DeclarationSource
• type Diag
• type EffectSummary
• type Operation
• type Package
• type Request
• type Snapshot
  • func Analyze(ctx context.Context, req Request) (*Snapshot, error)
  • func (snap *Snapshot) HasErrors() bool
  • func (snap *Snapshot) HasWarnings() bool
  • func (snap *Snapshot) LoadFailed() bool

Constants

const (
	// KeyStructural means the key derives only from parameters, constants,
	// fields, induction/range values, and pure computations over them. Such a
	// key can be evaluated without observing mutable state or a prior result.
	KeyStructural = "structural"
	// KeyResultDependent means the key transitively depends on the result of a
	// scalar-operation call, i.e. it is loop-carried through the operation
	// result. Such a key must not be evaluated ahead of the operation.
	KeyResultDependent = "result-dependent"
	// KeyCallDerived means the key is produced by calling another function or by
	// reading mutable global state, so its evaluation is observable or its
	// independence cannot be established without a contract.
	KeyCallDerived = "call-derived"
	// KeyUnknown means the key is computed by SSA the classifier does not model
	// conservatively enough to trust.
	KeyUnknown = "unknown"
)

Key dependency classifications. They describe how a call site's key argument is computed, which a later proof stage uses to reason about whether the key may be evaluated before the operation's scalar calls.

const (
	ClassApplication     = "application"
	ClassApplicationTest = "application-test"
	ClassDependency      = "dependency"
	ClassStandardLibrary = "standard-library"
	ClassCommand         = "command"
	ClassUnsupported     = "unsupported"
)

Package classifications.

const (
	DispatchDirect    = "direct"
	DispatchInterface = "interface"
	DispatchClosure   = "closure"
	DispatchUnknown   = "unknown"
)

Dispatch kinds for call sites and edges.

const (
	StateDirectIsolated     = "direct_isolated"
	StatePotentialLoop      = "potential_loop"
	StatePotentialSiblings  = "potential_siblings"
	StatePotentialFanout    = "potential_fanout"
	StateAmbiguousTarget    = "ambiguous_target"
	StateDisabledOperation  = "disabled_operation"
	StateInvalidDeclaration = "invalid_declaration"
)

Candidate states. Discovery never asserts transformation safety.

const SchemaVersion = "batchweaver.analysis/v1alpha1"

SchemaVersion identifies the analysis snapshot schema. It is deliberately an alpha version because the analysis model is not yet a stable public contract.

Functions

func RenderJSON

func RenderJSON(w io.Writer, snap *Snapshot) error

RenderJSON writes the snapshot as deterministic, indented JSON with a trailing newline. In reproducible mode the caller must have built the snapshot without volatile fields.

func RenderText

func RenderText(w io.Writer, snap *Snapshot) error

RenderText writes a concise, human-readable analysis summary. It never claims that any discovered structure is safe to transform.

Types

type BuildContext

type BuildContext struct {
	// GOOS is the target operating system; empty means the current GOOS.
	GOOS string
	// GOARCH is the target architecture; empty means the current GOARCH.
	GOARCH string
	// CGOEnabled reports whether cgo is enabled.
	CGOEnabled bool
	// Tags are additional build tags.
	Tags []string
	// Tests reports whether test variants are loaded.
	Tests bool
}

BuildContext describes the build configuration under which packages are loaded. Its zero value is completed from the current Go environment; the analysis never silently changes a user's configuration and always reports the effective context.

type CallEdge

type CallEdge struct {
	Caller    string `json:"caller"`
	Callee    string `json:"callee"`
	Dispatch  string `json:"dispatch"`
	Algorithm string `json:"algorithm"`
}

CallEdge is a normalized call graph edge.

type CallSite

type CallSite struct {
	ID                string `json:"id"`
	Operation         string `json:"operation"`
	Location          string `json:"location"`
	EnclosingFunction string `json:"enclosing_function"`
	// EnclosingFunctionID joins a call site to the effect summary of its
	// enclosing function (EffectSummary.Function). It lets a later analysis
	// stage reason about the observable effects surrounding a call without
	// rebuilding SSA.
	EnclosingFunctionID string `json:"enclosing_function_id,omitempty"`
	Dispatch            string `json:"dispatch"`
	Structural          string `json:"structural"`
	LoopDepth           int    `json:"loop_depth,omitempty"`
	InGoroutine         bool   `json:"in_goroutine,omitempty"`
	Targets             int    `json:"targets"`
	ContextArg          string `json:"context_arg,omitempty"`
	KeyArg              string `json:"key_arg,omitempty"`
	// KeyDependency classifies how the key argument is computed (structural,
	// result-dependent, call-derived, or unknown). See keydep.go.
	KeyDependency string `json:"key_dependency,omitempty"`
	Receiver      string `json:"receiver,omitempty"`
}

CallSite is a discovered call to a declared scalar operation.

type Candidate

type Candidate struct {
	ID                string   `json:"id"`
	Operation         string   `json:"operation"`
	State             string   `json:"state"`
	StructuralContext string   `json:"structural_context"`
	CallSites         []string `json:"call_sites"`
	Evidence          []string `json:"evidence,omitempty"`
}

Candidate is a discovered potential batching structure. It never asserts safety.

type DeclarationSource

type DeclarationSource struct {
	Kind     string `json:"kind"` // typed | configuration | directive
	Location string `json:"location"`
}

DeclarationSource records where a declaration field came from.

type Diag

type Diag struct {
	Code        string `json:"code"`
	Severity    string `json:"severity"`
	Message     string `json:"message"`
	Location    string `json:"location,omitempty"`
	Fingerprint string `json:"fingerprint"`
	Phase       string `json:"phase,omitempty"`
}

Diag is an analysis diagnostic (a portable projection of the diagnostics model).

type EffectSummary

type EffectSummary struct {
	Function string   `json:"function"`
	Effects  []string `json:"effects"`
	Complete bool     `json:"complete"`
}

EffectSummary is a conservative summary of a function's observable effects.

type Operation

type Operation struct {
	ID            string              `json:"id"`
	Sources       []DeclarationSource `json:"sources"`
	ScalarSymbol  string              `json:"scalar_symbol,omitempty"`
	BatchSymbol   string              `json:"batch_symbol,omitempty"`
	Kind          string              `json:"kind,omitempty"`
	Compatibility string              `json:"compatibility"` // valid | unresolved | invalid
	Disabled      bool                `json:"disabled,omitempty"`
	CallSiteIDs   []string            `json:"call_site_ids,omitempty"`
}

Operation is a discovered, resolved BatchWeaver operation.

type Package

type Package struct {
	ID         string   `json:"id"`
	ImportPath string   `json:"import_path"`
	Name       string   `json:"name"`
	Module     string   `json:"module,omitempty"`
	Class      string   `json:"class"`
	Files      []string `json:"files"`
	Generated  bool     `json:"generated,omitempty"`
	HasErrors  bool     `json:"has_errors,omitempty"`
	Errors     []string `json:"errors,omitempty"`
}

Package is a portable record of a loaded Go package.

type Request

type Request struct {
	// Patterns are Go package patterns (for example "./...").
	Patterns []string
	// BuildContext selects the build configuration.
	BuildContext BuildContext
	// Reproducible omits volatile fields (timestamps) for byte-stable output.
	Reproducible bool
	// ToolVersion is the BatchWeaver version recorded in the snapshot.
	ToolVersion string
	// Dir is the working directory used to resolve patterns; empty means the
	// process working directory.
	Dir string
	// Overlay maps absolute file paths to in-memory contents, used to analyze
	// unsaved editor buffers without writing them to disk. It is passed through to
	// go/packages unchanged; a nil map analyzes on-disk content.
	Overlay map[string][]byte
}

Request describes an analysis to perform.

type Snapshot

type Snapshot struct {
	SchemaVersion       string          `json:"schema_version"`
	ToolVersion         string          `json:"tool_version"`
	GoVersion           string          `json:"go_version"`
	Timestamp           string          `json:"timestamp,omitempty"`
	Workspace           string          `json:"workspace"`
	ConfigDigest        string          `json:"config_digest,omitempty"`
	BuildDigest         string          `json:"build_digest"`
	PackagesLoaded      int             `json:"packages_loaded"`
	ApplicationPackages int             `json:"application_packages"`
	TestVariants        int             `json:"test_variants"`
	SSAFunctions        int             `json:"ssa_functions"`
	CallGraphEdges      int             `json:"call_graph_edges"`
	Incomplete          bool            `json:"incomplete,omitempty"`
	Packages            []Package       `json:"packages"`
	Operations          []Operation     `json:"operations"`
	CallSites           []CallSite      `json:"call_sites"`
	Edges               []CallEdge      `json:"call_edges"`
	Effects             []EffectSummary `json:"effect_summaries"`
	Candidates          []Candidate     `json:"candidates"`
	Diagnostics         []Diag          `json:"diagnostics"`
}

Snapshot is the immutable, deterministic result of an analysis. Volatile fields (Timestamp) are omitted in reproducible mode.

func Analyze

func Analyze(ctx context.Context, req Request) (*Snapshot, error)

Analyze loads the requested packages, discovers operations, builds SSA and a conservative call graph, summarizes effects, indexes scalar-operation call sites, inventories candidates, and returns a deterministic, immutable snapshot. A non-nil error is returned only when package loading cannot be performed at all; ordinary package and analysis problems are reported as diagnostics in the snapshot.

func (*Snapshot) HasErrors

func (snap *Snapshot) HasErrors() bool

HasErrors reports whether the snapshot has any error-severity diagnostic.

func (*Snapshot) HasWarnings

func (snap *Snapshot) HasWarnings() bool

HasWarnings reports whether the snapshot has any warning-severity diagnostic.

func (*Snapshot) LoadFailed

func (snap *Snapshot) LoadFailed() bool

LoadFailed reports whether any package-loading diagnostic is present.