resolve

Documentation

Overview

Package resolve associates parsed Spice annotations with declarations in an already loaded, type-checked Go program.

@NamedInterface("resolve")

Index

• type DefinitionIndex
• type Diagnostic
  • func (d Diagnostic) Error() string
• type Occurrence
  • func (occurrence Occurrence) Contribution(kind sdk.ContributionKind) (sdk.Contribution, bool)
  • func (occurrence Occurrence) DescriptorContribution(kind sdk.ContributionKind) (sdk.Contribution, bool)
  • func (occurrence Occurrence) HasContribution(kind sdk.ContributionKind) bool
• type Result
  • func Annotations(program *load.Program) Result
  • func AnnotationsWithDefinitions(program *load.Program, definitions DefinitionIndex) Result
  • func (result Result) WithContributions(index int, values []sdk.Contribution) (Result, error)

Types

type DefinitionIndex

type DefinitionIndex map[annotation.DefinitionReference]string

DefinitionIndex maps an explicitly imported descriptor source to the canonical annotation name contributed by that descriptor.

type Diagnostic

type Diagnostic struct {
	Position         token.Position
	PhysicalFile     string
	PhysicalOffset   int
	PhysicalPosition token.Position
	Annotation       string
	Kind             string
	Message          string
	// contains filtered or unexported fields
}

Diagnostic is one deterministic source-positioned resolution failure.

func (Diagnostic) Error

func (d Diagnostic) Error() string

Error formats a compiler-style diagnostic.

type Occurrence

type Occurrence struct {
	Annotation                annotation.Annotation
	Spelling                  string
	Definition                annotation.DefinitionReference
	Target                    annotation.Target
	Name                      string
	SymbolID                  string
	PackagePath               string
	PhysicalFile              string
	PhysicalOffset            int
	PhysicalPosition          token.Position
	DisplayPosition           token.Position
	Contributions             []sdk.Contribution
	ParameterIndex            int
	ParameterName             string
	ParameterPosition         token.Position
	ParameterPhysicalPosition token.Position
}

Occurrence associates one parsed annotation with the exact declaration from the supplied typed Program. DisplayPosition is developer-facing and may be adjusted by //line directives; PhysicalPosition remains the deterministic loaded source identity. PhysicalFile and PhysicalOffset are retained for compatibility.

func (Occurrence) Contribution

func (occurrence Occurrence) Contribution(
	kind sdk.ContributionKind,
) (sdk.Contribution, bool)

Contribution returns a defensive typed contribution by kind.

func (Occurrence) DescriptorContribution

func (occurrence Occurrence) DescriptorContribution(
	kind sdk.ContributionKind,
) (sdk.Contribution, bool)

DescriptorContribution returns a contribution only when its invocation was resolved through an explicit descriptor import. Compiler consumers use this accessor for payload metadata so unbound parser fixtures cannot impersonate an authorized annotation tool.

func (Occurrence) HasContribution

func (occurrence Occurrence) HasContribution(
	kind sdk.ContributionKind,
) bool

HasContribution reports whether a validated tool contribution is attached to this invocation.

type Result

type Result struct {
	Files       int
	Occurrences []Occurrence
	Diagnostics []Diagnostic
}

Result is the immutable-by-convention output of resolving annotations from one loaded Program.

func Annotations

func Annotations(program *load.Program) Result

Annotations associates raw declaration-comment annotations with typed symbols without assigning descriptor identity or semantics. It exists for parser and model unit tests; product analysis must use AnnotationsWithDefinitions so imports fail closed.

func AnnotationsWithDefinitions

func AnnotationsWithDefinitions(
	program *load.Program,
	definitions DefinitionIndex,
) Result

AnnotationsWithDefinitions resolves explicit file-scoped imports against descriptors decoded from the same typed program. Every invocation must be imported and descriptor-backed; there is no built-in spelling fallback.

func (Result) WithContributions

func (result Result) WithContributions(
	index int,
	values []sdk.Contribution,
) (Result, error)

WithContributions returns a defensive result whose occurrence at index owns the supplied validated contributions.