starter

Documentation

Overview

Package starter defines deterministic compatibility and annotation metadata for opt-in Spice integrations.

Index

• Constants
• type Activation
• type ActivationMode
• type AnnotationSpec
• type ArgumentSpec
• type Dependency
• type EntryPoint
• type FeatureSpec
• type Manifest
  • func Must(spec Spec) Manifest
  • func New(spec Spec) (Manifest, error)
  • func Parse(content []byte) (Manifest, error)
  • func (manifest Manifest) Compatible(spiceAPI, goVersion string) error
  • func (manifest Manifest) Definitions() []annotation.Definition
  • func (manifest Manifest) JSON() ([]byte, error)
  • func (manifest Manifest) MarshalJSON() ([]byte, error)
  • func (manifest Manifest) Spec() Spec
• type OptionSpec
• type Spec

Constants

const (
	// Schema is the current starter manifest wire schema.
	Schema = "spice.starter/v1"
	// APIVersion is the compiler/runtime contract implemented by this Spice line.
	APIVersion = "v1alpha1"
)

Types

type Activation

type Activation struct {
	Mode        ActivationMode `json:"mode"`
	EntryPoints []EntryPoint   `json:"entry_points"`
}

Activation declares the only supported explicit activation paths.

type ActivationMode

type ActivationMode string

ActivationMode identifies how application code deliberately enables a starter. Dependency presence is never an activation mode.

const (
	// ActivationExplicitConstructor requires application or generated code to
	// call a declared constructor.
	ActivationExplicitConstructor ActivationMode = "explicit-constructor"
	// ActivationExplicitAnnotation requires a declared qualified annotation and
	// compiler selection of its declared entrypoints.
	ActivationExplicitAnnotation ActivationMode = "explicit-annotation"
)

type AnnotationSpec

type AnnotationSpec struct {
	Name       string              `json:"name"`
	Targets    []annotation.Target `json:"targets"`
	Repeatable bool                `json:"repeatable,omitempty"`
	Arguments  []ArgumentSpec      `json:"arguments,omitempty"`
}

AnnotationSpec is one qualified annotation contributed by a starter.

type ArgumentSpec

type ArgumentSpec struct {
	Name             string            `json:"name"`
	Kinds            []annotation.Kind `json:"kinds"`
	ListElementKinds []annotation.Kind `json:"list_element_kinds,omitempty"`
	Required         bool              `json:"required,omitempty"`
	Positional       bool              `json:"positional,omitempty"`
}

ArgumentSpec is the portable annotation-argument definition used by starter manifests.

type Dependency

type Dependency struct {
	Module  string `json:"module"`
	Version string `json:"version"`
	License string `json:"license"`
}

Dependency records one reviewed direct third-party module.

type EntryPoint

type EntryPoint struct {
	Package string `json:"package"`
	Symbol  string `json:"symbol"`
}

EntryPoint identifies one exported Go constructor or factory.

type FeatureSpec

type FeatureSpec struct {
	Annotation   string       `json:"annotation"`
	Capability   string       `json:"capability"`
	EntryPoints  []EntryPoint `json:"entry_points"`
	Options      []OptionSpec `json:"options,omitempty"`
	Requirements []string     `json:"requirements,omitempty"`
}

FeatureSpec maps a contributed application annotation to an immutable capability and its runtime requirements.

type Manifest

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

Manifest is an immutable, validated starter compatibility record.

func Must

func Must(spec Spec) Manifest

Must constructs a manifest or panics for package-owned invalid metadata.

func New

func New(spec Spec) (Manifest, error)

New validates and deterministically normalizes a starter specification.

func Parse

func Parse(content []byte) (Manifest, error)

Parse strictly decodes and validates one starter manifest.

func (Manifest) Compatible

func (manifest Manifest) Compatible(spiceAPI, goVersion string) error

Compatible verifies the exact Spice API and minimum Go version contract.

func (Manifest) Definitions

func (manifest Manifest) Definitions() []annotation.Definition

Definitions returns defensive annotation definitions suitable for an explicitly composed compiler registry.

func (Manifest) JSON

func (manifest Manifest) JSON() ([]byte, error)

JSON returns canonical indented JSON with a final newline.

func (Manifest) MarshalJSON

func (manifest Manifest) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler using the normalized wire spec.

func (Manifest) Spec

func (manifest Manifest) Spec() Spec

Spec returns a defensive copy of the normalized portable specification.

type OptionSpec

type OptionSpec struct {
	Name           string            `json:"name"`
	Kind           annotation.Kind   `json:"kind"`
	ListItemKinds  []annotation.Kind `json:"list_item_kinds,omitempty"`
	AllowedStrings []string          `json:"allowed_strings,omitempty"`
	Required       bool              `json:"required,omitempty"`
	UniqueItems    bool              `json:"unique_items,omitempty"`
	MinimumItems   int               `json:"minimum_items,omitempty"`
	SortItems      bool              `json:"sort_items,omitempty"`
}

OptionSpec defines deterministic semantic validation for one application feature option.

type Spec

type Spec struct {
	Schema              string           `json:"schema"`
	ID                  string           `json:"id"`
	Version             string           `json:"version"`
	Module              string           `json:"module"`
	SpiceAPI            string           `json:"spice_api"`
	MinimumGo           string           `json:"minimum_go"`
	License             string           `json:"license"`
	Review              string           `json:"review"`
	Activation          Activation       `json:"activation"`
	Capabilities        []string         `json:"capabilities"`
	Dependencies        []Dependency     `json:"dependencies,omitempty"`
	Annotations         []AnnotationSpec `json:"annotations,omitempty"`
	ApplicationFeatures []FeatureSpec    `json:"application_features,omitempty"`
}

Spec is the portable input used to construct or decode a Manifest.