application

Documentation

Overview

Package application assembles the immutable Spice application model from one resolved, type-aware compiler program.

@NamedInterface("application")

Index

• type BuildOptions
• type Diagnostic
  • func (d Diagnostic) Error() string
• type Model
  • func Build(program *load.Program, resolution resolve.Result) Model
  • func BuildWithOptions(program *load.Program, resolution resolve.Result, options BuildOptions) Model
  • func (m Model) AsyncTasks() []compilerasync.Task
  • func (m Model) Caches() []compilercache.Boundary
  • func (m Model) Components() []lifecycle.Component
  • func (m Model) Configurations() []configuration.Type
  • func (m Model) Controllers() []controller.Controller
  • func (m Model) Diagnostics() []Diagnostic
  • func (m Model) Edges() []graph.Edge
  • func (m Model) Enums() []compilerenum.Type
  • func (m Model) Events() []compilerevent.Topic
  • func (m Model) Jobs() []compilerschedule.Job
  • func (m Model) ModuleCycles() []modulith.Cycle
  • func (m Model) ModuleEdges() []modulith.Edge
  • func (m Model) Modules() []modulith.Module
  • func (m Model) Policies() []compilerpolicy.Service
  • func (m Model) Providers() []provider.Provider
  • func (m Model) Targets() []Target
  • func (m Model) Transactions() []compilertransaction.Boundary
  • func (m Model) UnassignedPackages() []modulith.Package
• type Root
• type Stage
• type Target
  • func (t Target) AutomaticDiscovery() bool
  • func (t Target) Bootstrap() compilerbootstrap.Metadata
  • func (t Target) Roots() []Root

Types

type BuildOptions

type BuildOptions struct {
	BootstrapDefinitions []compilerbootstrap.Definition
	ProviderCatalogs     []provider.Catalog
	// PrimaryProviderCatalog reuses a catalog already built from this exact
	// Program and resolution. It lets compiler services expose partial,
	// type-safe authoring metadata without rebuilding provider semantics.
	PrimaryProviderCatalog *provider.Catalog
}

BuildOptions supplies explicitly composed compiler extensions. The caller remains responsible for validating annotations with a registry containing matching definitions before building the application model.

type Diagnostic

type Diagnostic struct {
	Stage            Stage
	Position         token.Position
	PhysicalPosition token.Position
	SymbolID         string
	Kind             string
	Message          string
	Fixes            []provider.SuggestedFix
}

Diagnostic is one deterministic source-positioned application-model failure.

func (Diagnostic) Error

func (d Diagnostic) Error() string

Error renders a compiler-style diagnostic.

type Model

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

Model is the immutable-by-convention application IR assembled from one loaded Program and one resolved annotation result.

func Build

func Build(program *load.Program, resolution resolve.Result) Model

Build assembles provider, graph, lifecycle, and application-root metadata from the existing single-program pipeline. It never reloads source, reparses files, reflects on declarations, or executes application/provider bodies.

func BuildWithOptions

func BuildWithOptions(
	program *load.Program,
	resolution resolve.Result,
	options BuildOptions,
) Model

BuildWithOptions assembles an application model with explicitly supplied bootstrap feature definitions in addition to Spice's built-in definitions.

func (Model) AsyncTasks

func (m Model) AsyncTasks() []compilerasync.Task

AsyncTasks returns immutable provider-owned asynchronous method metadata in stable method identity order.

func (Model) Caches

func (m Model) Caches() []compilercache.Boundary

Caches returns immutable generated HTTP cache boundaries in stable route identity order.

func (Model) Components

func (m Model) Components() []lifecycle.Component

Components returns lifecycle components in provider construction order.

func (Model) Configurations

func (m Model) Configurations() []configuration.Type

Configurations returns validated typed configuration declarations in stable symbol order.

func (Model) Controllers

func (m Model) Controllers() []controller.Controller

Controllers returns validated provider-owned HTTP controllers in stable symbol order.

func (Model) Diagnostics

func (m Model) Diagnostics() []Diagnostic

Diagnostics returns deterministic diagnostics. A model with diagnostics must not be used for generation.

func (Model) Edges

func (m Model) Edges() []graph.Edge

Edges returns exact-type provider graph edges in stable consumer and parameter order.

func (Model) Enums

func (m Model) Enums() []compilerenum.Type

Enums returns validated closed enum declarations in stable symbol order.

func (Model) Events

func (m Model) Events() []compilerevent.Topic

Events returns generated typed event topics in stable marker identity order.

func (Model) Jobs

func (m Model) Jobs() []compilerschedule.Job

Jobs returns immutable provider-owned scheduling metadata in stable method identity order.

func (Model) ModuleCycles

func (m Model) ModuleCycles() []modulith.Cycle

ModuleCycles returns deterministic strongly connected module components.

func (Model) ModuleEdges

func (m Model) ModuleEdges() []modulith.Edge

ModuleEdges returns distinct cross-module Go import edges.

func (Model) Modules

func (m Model) Modules() []modulith.Module

Modules returns discovered application modules in stable import-path order.

func (Model) Policies

func (m Model) Policies() []compilerpolicy.Service

Policies returns immutable generated service-method decorator metadata in stable provider identity order.

func (Model) Providers

func (m Model) Providers() []provider.Provider

Providers returns providers in deterministic dependency-first construction order. Cleanup capabilities remain attached to each provider record.

func (Model) Targets

func (m Model) Targets() []Target

Targets returns validated application targets in stable symbol order.

func (Model) Transactions

func (m Model) Transactions() []compilertransaction.Boundary

Transactions returns immutable generated transaction boundaries in stable route identity order.

func (Model) UnassignedPackages

func (m Model) UnassignedPackages() []modulith.Package

UnassignedPackages returns selected packages not owned by any module root.

type Root

type Root struct {
	Index            int
	Name             string
	Type             types.Type
	TypeID           string
	ProviderID       string
	Position         token.Position
	PhysicalPosition token.Position
}

Root identifies one exact provider type requested by an @Application marker.

type Stage

type Stage string

Stage identifies the compiler phase that produced a model diagnostic.

const (
	// StageResolution identifies invalid resolved annotation input.
	StageResolution Stage = "resolution"
	// StageProvider identifies provider catalog validation.
	StageProvider Stage = "provider"
	// StageGraph identifies provider graph validation.
	StageGraph Stage = "graph"
	// StageLifecycle identifies lifecycle hook validation.
	StageLifecycle Stage = "lifecycle"
	// StageSchedule identifies scheduled-method validation.
	StageSchedule Stage = "schedule"
	// StageAsync identifies asynchronous-method validation.
	StageAsync Stage = "async"
	// StagePolicy identifies generated service-method policy validation.
	StagePolicy Stage = "policy"
	// StageTransaction identifies generated transaction-boundary validation.
	StageTransaction Stage = "transaction"
	// StageEvent identifies typed event topic and listener validation.
	StageEvent Stage = "event"
	// StageEnum identifies closed enum declaration validation.
	StageEnum Stage = "enum"
	// StageModule identifies application-module architecture validation.
	StageModule Stage = "module"
	// StageConfiguration identifies typed configuration validation.
	StageConfiguration Stage = "configuration"
	// StageController identifies typed HTTP controller validation.
	StageController Stage = "controller"
	// StageCache identifies generated HTTP cache-boundary validation.
	StageCache Stage = "cache"
	// StageBootstrap identifies application-platform feature validation.
	StageBootstrap Stage = "bootstrap"
	// StageApplication identifies application marker and root validation.
	StageApplication Stage = "application"
)

type Target

type Target struct {
	Symbol           load.Symbol
	SymbolID         string
	Name             string
	PackagePath      string
	Position         token.Position
	PhysicalPosition token.Position
	// contains filtered or unexported fields
}

Target describes one validated @Application marker. The marker function is compile-time metadata only; Spice never invokes its body during analysis.

func (Target) AutomaticDiscovery

func (t Target) AutomaticDiscovery() bool

AutomaticDiscovery reports whether this is the preferred package-main marker whose application graph is discovered from the selected local module scope rather than enumerated as marker parameters.

func (Target) Bootstrap

func (t Target) Bootstrap() compilerbootstrap.Metadata

Bootstrap returns immutable, typed application-platform feature metadata.

func (Target) Roots

func (t Target) Roots() []Root

Roots returns the target's roots in function-parameter order.