service

package
v0.1.0-preview.8 Latest Latest
Warning

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

 Go to latest Published: Aug 13, 2026 License: Apache-2.0 Imports: 50 Imported by: 0

Documentation

Overview

Package service exposes Spice's typed compiler pipeline as an isolated, overlay-aware analysis service for commands and editor integrations.

@NamedInterface("service")

Index

Constants

This section is empty.

Variables

View Source 
var ErrStaleAnalysis = errors.New("spice analysis request is stale")

ErrStaleAnalysis reports that a newer sequenced request superseded a result.

Functions

This section is empty.

Types

type AnalysisMode 

type AnalysisMode uint8

AnalysisMode controls whether a successful analysis also selects and renders one application target. The zero value preserves generation behavior. 

const (
	// AnalysisGenerate builds the complete application IR and a generation plan.
	AnalysisGenerate AnalysisMode = iota
	// AnalysisValidate builds and validates the complete application IR without
	// requiring an @Application target or rendering generated files.
	AnalysisValidate
)

type Annotation 

type Annotation struct {
	Name              string
	Spelling          string
	Raw               string
	Target            annotation.Target
	Declaration       string
	SymbolID          string
	PackagePath       string
	DefinitionPackage string
	DefinitionSymbol  string
	Location          diagnostic.Location
}

Annotation is one resolved declaration annotation summary.

type AnnotationArgument 

type AnnotationArgument struct {
	Name             string
	Kinds            []annotation.Kind
	ListElementKinds []annotation.Kind
	ValueDomain      sdk.ValueDomain
	AllowedStrings   []string
	Description      string
	Default          string
	Required         bool
	Positional       bool
	Variadic         bool
}

AnnotationArgument describes one completion-safe annotation argument.

type AnnotationCompatibility 

type AnnotationCompatibility struct {
	Since        string
	MinimumSpice string
}

AnnotationCompatibility records the declared lifecycle of one descriptor.

type AnnotationDefinition 

type AnnotationDefinition struct {
	Name                  string
	Summary               string
	Documentation         string
	DescriptorPackage     string
	DescriptorSymbol      string
	DescriptorLocation    diagnostic.Location
	HasDescriptorLocation bool
	Targets               []annotation.Target
	Repeatable            bool
	Arguments             []AnnotationArgument
	Examples              []AnnotationExample
	Compatibility         AnnotationCompatibility
	Implementation        AnnotationImplementation
	Provenance            AnnotationProvenance
}

AnnotationDefinition is one available built-in or selected extension.

type AnnotationExample 

type AnnotationExample struct {
	Title string
	Code  string
}

AnnotationExample is one descriptor-owned editor example.

type AnnotationImplementation 

type AnnotationImplementation struct {
	Tool               string
	Handler            string
	Protocol           string
	Authorized         bool
	AuthorizationKnown bool
	Package            string
	Symbol             string
	Location           diagnostic.Location
	HasLocation        bool
}

AnnotationImplementation identifies the trusted Go tool handler and its inspectable implementation symbol.

type AnnotationProvenance 

type AnnotationProvenance struct {
	Module             string
	Version            string
	ReplacementModule  string
	ReplacementVersion string
	ReplacementDir     string
	LocalReplacement   bool
}

AnnotationProvenance is the exact Go-selected descriptor module identity.

type ApplicationScope 

type ApplicationScope struct {
	BuildSelection      string
	PackagePath         string
	GeneratedEntrypoint bool
}

ApplicationScope identifies one independently validated application composition under one exact configured Go build selection.

type AutoConfiguration 

type AutoConfiguration struct {
	PackagePath     string                           `json:"package"`
	Factory         string                           `json:"factory"`
	OutputTypeID    string                           `json:"output"`
	Status          provider.AutoConfigurationStatus `json:"status"`
	Reason          string                           `json:"reason"`
	ModulePath      string                           `json:"module"`
	ModuleVersion   string                           `json:"version"`
	ReplacementPath string                           `json:"replacement,omitempty"`
	Review          string                           `json:"review"`
}

AutoConfiguration is one imported library default and its compiler-owned activation decision.

type Config 

type Config struct {
	Loader               Loader
	ModuleVersions       ModuleVersionLoader
	LoadOptions          load.Options
	Registry             annotation.Registry
	StarterCatalog       compilerstarter.Catalog
	BootstrapDefinitions []compilerbootstrap.Definition
	ProviderEntrypoints  []provider.Entrypoint
	CacheNamespace       string
	MaxCacheEntries      int
	MaxOverlayFiles      int
	MaxOverlayBytes      int
	// SpiceVersion is sent during annotation-tool compatibility negotiation.
	SpiceVersion string
}

Config constructs one isolated service instance.

type Configuration 

type Configuration struct {
	SymbolID    string
	Name        string
	PackagePath string
	TypeID      string
	Prefix      string
	Module      string
	Fields      []ConfigurationField
}

Configuration is one generated typed configuration declaration.

type ConfigurationField 

type ConfigurationField struct {
	Name        string
	Key         string
	TypeID      string
	Environment string
	Default     string
	HasDefault  bool
	Required    bool
	Secret      bool
}

ConfigurationField is one generated configuration property.

type Document 

type Document struct {
	Version int
	Content []byte
}

Document is one versioned in-memory source overlay.

type Enum 

type Enum struct {
	SymbolID    string
	Name        string
	PackagePath string
	TypeID      string
	Underlying  string
	Location    diagnostic.Location
	Members     []EnumMember
}

Enum is one validated closed enum declaration.

type EnumMember 

type EnumMember struct {
	Name  string
	Value string
}

EnumMember is one declared member of a closed enum.

type GoInterface 

type GoInterface struct {
	Name           string
	PackageName    string
	PackagePath    string
	TypeID         string
	TypeParameters []string
	Methods        []GoInterfaceMethod
	Exported       bool
	Location       diagnostic.Location
	HasLocation    bool
}

GoInterface is one compiler-resolved named runtime interface available to annotation arguments whose SDK value domain is ValueDomainGoInterface.

type GoInterfaceCatalog 

type GoInterfaceCatalog struct {
	Packages []GoInterfacePackage
}

GoInterfaceCatalog is the immutable type-aware interface view produced by the same loaded Go program used for diagnostics, DI, and generation.

type GoInterfaceMethod 

type GoInterfaceMethod struct {
	Name      string
	Signature string
}

GoInterfaceMethod is one method in the complete method set of a named runtime Go interface.

type GoInterfacePackage 

type GoInterfacePackage struct {
	Name       string
	Path       string
	Files      []string
	Interfaces []GoInterface
}

GoInterfacePackage groups interfaces by their exact Go package identity and records the physical files that establish same-package visibility.

type Loader 

type Loader func(
	context.Context,
	load.Options,
	...string,
) (*load.Program, error)

Loader is the cancellable typed-program loading boundary.

type Module 

type Module struct {
	ID                  string
	RootPackage         string
	Packages            []string
	NamedInterfaces     []NamedInterface
	AllowedDependencies []ModuleDependency
}

Module is one compile-time application-module summary.

type ModuleDependency 

type ModuleDependency struct {
	ModuleID string
	API      string
}

ModuleDependency is one explicitly allowed module API.

type ModuleEdge 

type ModuleEdge struct {
	FromModule  string
	ToModule    string
	FromPackage string
	ToPackage   string
	API         string
	Exported    bool
	Allowed     bool
}

ModuleEdge is one observed cross-module import edge.

type ModuleGraph 

type ModuleGraph struct {
	Modules            []Module
	Edges              []ModuleEdge
	UnassignedPackages []string
}

ModuleGraph is the immutable module architecture summary.

type ModuleVersionLoader 

type ModuleVersionLoader func(
	context.Context,
	load.Options,
) ([]compilerstarter.ModuleVersion, error)

ModuleVersionLoader returns the selected Go module graph used to enforce exact reviewed starter dependencies.

type NamedInterface 

type NamedInterface struct {
	Name        string
	PackagePath string
}

NamedInterface is one explicitly exposed module descendant.

type Provider 

type Provider struct {
	ID             string
	Name           string
	ExplicitName   bool
	PackagePath    string
	OutputTypeID   string
	Source         provider.Source
	Aliases        []string
	Qualifiers     []string
	Primary        bool
	Fallback       bool
	Order          int64
	Scope          sdk.BeanScope
	Dependencies   []ProviderDependency
	ReturnsCleanup bool
	ReturnsError   bool
}

Provider is one dependency-first provider summary.

type ProviderDependency 

type ProviderDependency struct {
	Index         int
	Name          string
	TypeID        string
	Kind          provider.DependencyKind
	ElementTypeID string
	Qualifiers    []string
}

ProviderDependency is one exact provider input.

type ProviderEdge 

type ProviderEdge struct {
	ConsumerID      string
	DependencyID    string
	RequiredTypeID  string
	ParameterIndex  int
	ParameterName   string
	DependencyKind  provider.DependencyKind
	CollectionIndex int
}

ProviderEdge is one exact-type provider dependency edge.

type ProviderGraph 

type ProviderGraph struct {
	Providers []Provider
	Edges     []ProviderEdge
}

ProviderGraph is the immutable exact-type construction graph.

type Request 

type Request struct {
	WorkspaceRoot string
	Target        string
	Patterns      []string
	Overlay       map[string]Document
	Mode          AnalysisMode
	Profile       compilerstyle.Profile
	// StyleConfiguration is the shared immutable schema-two policy consumed by
	// structural and typed validation. Profile remains available for legacy
	// profile-only callers that do not select configuration enforcement.
	StyleConfiguration *compilerstyle.Configuration
	// ContentHash is a caller-owned hash of all relevant workspace and overlay
	// content. Caching is disabled when it is empty, preventing stale disk
	// results from being reused without a complete content identity.
	ContentHash string
	// Sequence enables per-workspace stale-result rejection. Zero disables
	// sequencing for one-shot command callers.
	Sequence uint64
}

Request describes one read-only compiler analysis.

type Result 

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

Result is an immutable-by-construction compiler analysis result.

func (Result) AnnotationDefinitions 

func (result Result) AnnotationDefinitions() []AnnotationDefinition

AnnotationDefinitions returns completion-safe available definitions.

func (Result) Annotations 

func (result Result) Annotations() []Annotation

Annotations returns defensive resolved annotation summaries.

func (Result) ApplicationModel 

func (result Result) ApplicationModel() application.Model

ApplicationModel returns the immutable application IR assembled from the same typed program. Its public accessors return defensive metadata copies.

func (Result) ApplicationScopes 

func (result Result) ApplicationScopes() []ApplicationScope

ApplicationScopes returns the deterministic application compositions that were independently validated for configured analysis.

func (Result) AutoConfigurations 

func (result Result) AutoConfigurations() []AutoConfiguration

AutoConfigurations returns imported library-default activation decisions.

func (Result) CodeActions 

func (result Result) CodeActions() []diagnostic.SuggestedFix

CodeActions returns version-aware safe fixes carried by diagnostics.

func (Result) Configurations 

func (result Result) Configurations() []Configuration

Configurations returns deep defensive configuration metadata.

func (Result) Diagnostics 

func (result Result) Diagnostics() diagnostic.Set

Diagnostics returns the immutable shared diagnostic set.

func (Result) Enums 

func (result Result) Enums() []Enum

Enums returns deep defensive closed enum metadata.

func (Result) Files 

func (result Result) Files() int

Files returns the number of primary Go files scanned for annotations.

func (Result) GenerationPlan 

func (result Result) GenerationPlan() (generate.Plan, bool)

GenerationPlan returns the immutable pure plan when analysis succeeded.

func (Result) GenerationReady 

func (result Result) GenerationReady() bool

GenerationReady reports whether a pure guarded generation plan is available.

func (Result) GoInterfaces 

func (result Result) GoInterfaces() GoInterfaceCatalog

GoInterfaces returns the compiler-owned named runtime interface catalog used by LSP completion and navigation. Editors do not independently decide which Go types are valid Spice interface bindings.

func (Result) ModuleGraph 

func (result Result) ModuleGraph() ModuleGraph

ModuleGraph returns a deep defensive module summary.

func (Result) ModuleModel 

func (result Result) ModuleModel() modulith.Model

ModuleModel returns the immutable application-module model used by CLI and editor projections. Its public accessors return defensive values.

func (Result) ProviderGraph 

func (result Result) ProviderGraph() ProviderGraph

ProviderGraph returns a deep defensive graph summary.

func (Result) Sequence 

func (result Result) Sequence() uint64

Sequence returns the caller-supplied request sequence.

func (Result) TargetName 

func (result Result) TargetName() string

TargetName returns the selected application's stable developer-facing name. It is empty when analysis did not reach target selection.

func (Result) WorkspaceRoot 

func (result Result) WorkspaceRoot() string

WorkspaceRoot returns the normalized absolute analysis root.

type Service 

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

Service owns bounded analysis state for independent workspaces.

func New 

func New(config Config) (*Service, error)

New creates an isolated bounded compiler service.

func (*Service) Analyze 

func (service *Service) Analyze(
	ctx context.Context,
	request Request,
) (Result, error)

Analyze executes one read-only typed compiler analysis.

func (*Service) AnnotationCatalog 

func (service *Service) AnnotationCatalog(
	ctx context.Context,
	workspaceRoot string,
) ([]AnnotationDefinition, error)

AnnotationCatalog returns statically discoverable descriptors from source already present in the target application's offline Go module graph. It does not load packages, execute tools, download modules, or mutate module files.

func (*Service) Close 

func (service *Service) Close(ctx context.Context) error

Close gracefully terminates annotation-tool processes owned by the service.

func (*Service) InvalidateAnnotationCatalog 

func (service *Service) InvalidateAnnotationCatalog(
	workspaceRoot string,
) error

InvalidateAnnotationCatalog drops a workspace's brief completion cache after an explicitly confirmed module-file change.

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.