load

Documentation

Overview

Package load provides Spice's single type-aware Go package loading boundary.

@NamedInterface("load")

Index

• func DiscoverGeneratedApplicationEntrypoints(options Options, patterns ...string) ([]GeneratedApplicationEntrypoint, []Diagnostic, error)
• func IsGeneratedApplicationEntrypoint(program *Program, symbol Symbol) bool
• type Diagnostic
  • func (d Diagnostic) String() string
• type GeneratedApplicationEntrypoint
• type LoadError
  • func (e *LoadError) Error() string
• type Options
• type Package
• type Program
  • func Load(ctx context.Context, options Options, patterns ...string) (*Program, error)
  • func (p *Program) Diagnostics() []Diagnostic
  • func (p *Program) Packages() []Package
  • func (p *Program) PrimaryPackages() []Package
  • func (p *Program) PrimarySymbols() []Symbol
  • func (p *Program) Symbols() []Symbol
• type SourceFile
• type Symbol
• type SymbolKind

Functions

func DiscoverGeneratedApplicationEntrypoints

func DiscoverGeneratedApplicationEntrypoints(
	options Options,
	patterns ...string,
) ([]GeneratedApplicationEntrypoint, []Diagnostic, error)

DiscoverGeneratedApplicationEntrypoints reports only entrypoints reachable through patterns under options' exact Go build context. It shares the same parser and body validation as Load's generated-package preparation.

func IsGeneratedApplicationEntrypoint

func IsGeneratedApplicationEntrypoint(program *Program, symbol Symbol) bool

IsGeneratedApplicationEntrypoint reports whether symbol is the exact compiler-owned spice_generate bridge shape accepted by generated-package preparation. It does not accept ordinary application functions.

Types

type Diagnostic

type Diagnostic struct {
	PackagePath string
	Position    string
	Filename    string
	Line        int
	Column      int
	Kind        string
	Message     string
}

Diagnostic is a normalized package-list, parse, or type-checking diagnostic. Position remains the familiar rendered Go position. Filename, Line, and Column retain its structured components so deterministic ordering is numeric.

func (Diagnostic) String

func (d Diagnostic) String() string

String returns a deterministic, human-readable diagnostic.

type GeneratedApplicationEntrypoint

type GeneratedApplicationEntrypoint struct {
	PackagePath          string
	GeneratedPackagePath string
	Filename             string
}

GeneratedApplicationEntrypoint identifies one compiler-validated spice_generate application bridge selected by an exact Go build context. PackagePath is the handwritten package-main target; GeneratedPackagePath is the analysis-only package supplied through the loader overlay.

type LoadError

type LoadError struct {
	Diagnostics []Diagnostic
}

LoadError reports that one or more requested root packages could not be safely used for semantic generation.

func (*LoadError) Error

func (e *LoadError) Error() string

type Options

type Options struct {
	Dir               string
	Env               []string
	BuildFlags        []string
	Overlay           map[string][]byte
	AuxiliaryPackages []string
	// PrepareGeneratedApplicationEntrypoints supplies a bounded in-memory
	// generated-package stub while the spice_generate build tag excludes stale
	// committed output. The physical application source remains unchanged.
	PrepareGeneratedApplicationEntrypoints bool
	// PromoteApplicationDependencies admits same-module packages transitively
	// imported by an exact application root into the primary typed program.
	// Compiler-scoped analysis uses this to retain local module declarations
	// without widening to unrelated application roots.
	PromoteApplicationDependencies bool
	// Tests is reserved for a future test-package model. The bootstrap loader
	// rejects true because go/packages test variants can duplicate logical
	// package and symbol identities.
	Tests bool
}

Options configures one isolated package-loading operation.

type Package

type Package struct {
	ID              string
	Path            string
	Name            string
	Dir             string
	ModulePath      string
	Auxiliary       bool
	Files           []SourceFile
	CompiledGoFiles []string
	IllTyped        bool
	Types           *types.Package
	TypesInfo       *types.Info
	Syntax          []*ast.File
	Raw             *packages.Package
}

Package is one root package selected by the standard Go package driver. Auxiliary packages share the Program's type universe but are excluded from primary annotation and application-module discovery.

type Program

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

Program is the immutable-by-convention result of one Load call. Its methods return copies of ordered record slices. Live type and syntax references must never be combined with values from another Program.

func Load

func Load(ctx context.Context, options Options, patterns ...string) (*Program, error)

Load asks the standard Go package driver to load the requested root package patterns, then builds deterministic package, symbol, and diagnostic records from that shared type universe. Exact application loads repeat the request with discovered same-module dependencies as roots so every promoted package is syntax- and type-information complete.

func (*Program) Diagnostics

func (p *Program) Diagnostics() []Diagnostic

Diagnostics returns deterministically ordered load diagnostics.

func (*Program) Packages

func (p *Program) Packages() []Package

Packages returns deterministically ordered root package records.

func (*Program) PrimaryPackages

func (p *Program) PrimaryPackages() []Package

PrimaryPackages returns roots selected for application annotation and module analysis, excluding auxiliary compiler-extension packages.

func (*Program) PrimarySymbols

func (p *Program) PrimarySymbols() []Symbol

PrimarySymbols returns declarations owned by primary application roots.

func (*Program) Symbols

func (p *Program) Symbols() []Symbol

Symbols returns deterministically ordered declaration records.

type SourceFile

type SourceFile struct {
	PhysicalPath string
	Syntax       *ast.File
}

SourceFile pairs one deterministic compiled-file identity with its syntax tree. Syntax may be nil when the package driver reports a compiled file for which go/packages could not retain an AST.

type Symbol

type Symbol struct {
	ID               string
	DisplayLabel     string
	Kind             SymbolKind
	Name             string
	PackagePath      string
	Receiver         string
	Position         token.Position
	PhysicalPosition token.Position
	Object           types.Object
	Node             ast.Node
	Signature        *types.Signature
}

Symbol is a stable logical declaration record backed by live go/types and AST references from one Program instance. ID is the canonical machine key; DisplayLabel is a concise human label and must not be used as an identity key. Position is developer-facing and //line-adjusted; PhysicalPosition identifies the loaded Go file.

type SymbolKind

type SymbolKind string

SymbolKind identifies a declaration kind in a loaded program.

const (
	SymbolPackage  SymbolKind = "package"
	SymbolType     SymbolKind = "type"
	SymbolFunction SymbolKind = "function"
	SymbolMethod   SymbolKind = "method"
	SymbolVariable SymbolKind = "variable"
	SymbolConstant SymbolKind = "constant"
)