generate

package
v1.0.0 Latest Latest
Warning

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

Go to latest
Published: Sep 22, 2026 License: Apache-2.0 Imports: 40 Imported by: 0

Documentation

Overview

Package generate emits Go package artifacts from resolved transcribe products and type authority. It does not parse authored DQL or infer runtime behavior. Its location under transcribe makes that lifecycle ownership explicit.

Index

Constants

View Source
const RootViewPath = "root"

Variables

This section is empty.

Functions

This section is empty.

Types

type ContractHandlerAsset

type ContractHandlerAsset struct {
	Destination string
	Factory     string
	File        *ast.File
}

ContractHandlerAsset is generated binder-aware Go handler source accepted from the transcribe Go target. Supplied simple Go functions remain GoHandlerAsset; the two products have different public contracts.

func (*ContractHandlerAsset) Clone

Clone returns an isolated parser-backed copy.

type ContractHandlerPlan

type ContractHandlerPlan struct {
	Destination string
	Factory     string
	File        *ast.File
}

ContractHandlerPlan is one validated manifest-owned generated Go handler.

type ContractOwnership

type ContractOwnership string
const (
	ContractGenerated ContractOwnership = "generated"
	ContractLinked    ContractOwnership = "linked"
)

type ContractPlan

type ContractPlan struct {
	Package       string
	Type          string
	Destination   string
	Fields        []Field
	Ownership     ContractOwnership
	DescriptorKey string
}

ContractPlan keeps one input/output contract's type, destination, fields, and ownership together so emission cannot mix linked and generated state.

func (*ContractPlan) Field

func (p *ContractPlan) Field(name string) (Field, bool)

Field returns a contract field by its generated Go name.

type ContractReference

type ContractReference struct {
	Expression    string
	DescriptorKey string
}

type ContractReferences

type ContractReferences struct {
	Input  *ContractReference
	Output *ContractReference
}

type Declaration

type Declaration struct {
	Projection       []DeclarationProjection
	NestedChildField string
	DataType         string
}

Declaration contains parser-derived facts required by code generation. Transcribe owns parsing; generation consumes only this normalized product.

type DeclarationProjection

type DeclarationProjection struct {
	Name      string
	Source    string
	Aggregate bool
}

DeclarationProjection is one typed StructQL result field produced by the transcribe parser. Generation never reparses declaration SQL.

type Declarations

type Declarations map[string]Declaration

type EmittedFile

type EmittedFile struct {
	Path    string
	Content string
}

func EmitScaffold

func EmitScaffold(dir string, plan *Plan) ([]EmittedFile, error)

func EmitScaffoldEphemeral

func EmitScaffoldEphemeral(dir string, plan *Plan) ([]EmittedFile, error)

EmitScaffoldEphemeral emits a staging package without any ownership sidecar.

func EmitScaffoldWithPolicy

func EmitScaffoldWithPolicy(dir string, plan *Plan, policy GenerationPolicy) ([]EmittedFile, error)

type EntityAssociation

type EntityAssociation struct {
	Identity                           string
	Path                               []string
	Field                              string
	StateType, KeyType, KeyAdapterType string
	CurrentKeyFunction                 string
}

type EntityInvariant

type EntityInvariant struct {
	Identity                string
	Path                    []string
	Group, BackfillFunction string
}

type EntityMethod

type EntityMethod struct {
	Receiver, Name, ValueType string
	Getter                    bool
	Signature                 string
}

type EntitySupportAsset

type EntitySupportAsset struct {
	File                                      *ast.File
	Role                                      string
	CaptureFunction                           string
	Methods                                   []EntityMethod
	SnapshotType, SyncContextType, SyncMethod string
	Associations                              []EntityAssociation
	Invariants                                []EntityInvariant
}

EntitySupportAsset is Go source shared by generated Go and Velty adapters. It contains typed accessors and an invocation-local original-input capturer.

func (*EntitySupportAsset) Clone

type EntitySupportPlan

type EntitySupportPlan struct {
	File                                      *ast.File
	Role                                      string
	Destination, CaptureFunction              string
	Methods                                   []EntityMethod
	SnapshotType, SyncContextType, SyncMethod string
	Associations                              []EntityAssociation
	Invariants                                []EntityInvariant
}

type FactoryLinkPlan

type FactoryLinkPlan struct{ Name, Destination, PackagePath, Factory, Adapter string }

FactoryLinkPlan is compiled-Go registration wiring, separate from the runtime-free public policy source. It registers only in a supplied x.Registry.

type Field

type Field struct {
	// Implementation fields are private generated support, never binding or shape placeholders.
	Implementation bool
	// ExplicitType authorizes only this field's exact planned CAST type during shape persistence.
	ExplicitType bool
	// RelationHolder carries canonical relation cardinality authority. Persistence
	// may change only a proven, unedited generated holder between *T and []*T.
	RelationHolder bool
	Name           string
	Type           string
	Tag            string
	Source         string
	Anonymous      bool
}

type GeneratedTypePlan

type GeneratedTypePlan struct {
	Name        string
	Destination string
	Declaration string
	Imports     []spec.ImportSpec
}

GeneratedTypePlan is immutable source material for one package-owned type.

type GeneratedTypeReference

type GeneratedTypeReference struct {
	DescriptorKey string
	Destination   string
}

GeneratedTypeReference selects one synthetic catalog descriptor for package-owned named type emission.

type GenerationPolicy

type GenerationPolicy string

GenerationPolicy controls how persistent generated artifacts are reconciled. Merge preserves the existing structural shape-merge behavior. Overwrite replaces manifest-owned generated files from the new generator proposal after fingerprint validation, without parsing the previous generated source.

const (
	GenerationPolicyMerge     GenerationPolicy = ""
	GenerationPolicyOverwrite GenerationPolicy = "overwrite"
)

type Generator

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

func New

func New(input Input) *Generator

func (*Generator) Generate

func (g *Generator) Generate(dir string) (*Result, error)

func (*Generator) Plan

func (g *Generator) Plan() (*Plan, error)

func (*Generator) RuntimeInputType

func (g *Generator) RuntimeInputType() (reflect.Type, error)

RuntimeInputType materializes the generated input contract used before the generated package itself exists. Linked contracts should use their compiled reflect.Type directly; this method is the generated-contract counterpart.

func (*Generator) RuntimeOutputType

func (g *Generator) RuntimeOutputType() (reflect.Type, error)

RuntimeOutputType materializes the generated output contract used before a generated package exists. It mirrors RuntimeInputType for dynamic readers.

type GoHandlerAsset

type GoHandlerAsset struct {
	Destination string
	Entry       string
	File        *ast.File
}

GoHandlerAsset is accepted custom Go source supplied by transcription. Canonical component metadata stores only Entry; the AST remains a generation concern and is cloned at every ownership boundary.

func (*GoHandlerAsset) Clone

func (a *GoHandlerAsset) Clone() (*GoHandlerAsset, error)

Clone returns an isolated parser-backed copy of the handler asset.

type GoHandlerPlan

type GoHandlerPlan struct {
	Destination string
	Entry       string
	File        *ast.File
}

GoHandlerPlan is the validated custom handler source emitted with a package.

type HelperType

type HelperType struct {
	Package string
	Name    string
	Fields  []Field
}

type HookScaffoldAsset

type HookScaffoldAsset struct {
	Destination string
	File        *ast.File
	PackagePath string
	EntityHooks []HookScaffoldContract
	Catalog     *typecatalog.Catalog
	// contains filtered or unexported fields
}

HookScaffoldAsset is an optional create-once, user-owned lifecycle file. It is emitted by the existing package transaction but never enters the generated-file manifest.

func (*HookScaffoldAsset) Clone

func (a *HookScaffoldAsset) Clone() (*HookScaffoldAsset, error)

Clone returns an isolated parser-backed copy.

func (*HookScaffoldAsset) Filename

func (a *HookScaffoldAsset) Filename() (string, error)

Filename resolves the create-once destination without requiring emission.

func (*HookScaffoldAsset) ResolveEntityHookTypes

func (a *HookScaffoldAsset) ResolveEntityHookTypes(directory string) (*typecatalog.Resolver, error)

ResolveEntityHookTypes loads the actual create-once file when it exists, or its proposed source otherwise. The detached native package preserves the real canonical identity for the orchestration owner's hook compilation.

func (*HookScaffoldAsset) RetainEntityHookEvidence

func (a *HookScaffoldAsset) RetainEntityHookEvidence(methods map[string][]xshape.Method) error

RetainEntityHookEvidence snapshots canonical native method sets after the orchestration owner has approved them with EntityHookCompiler. This method does not establish SDK compatibility. It must receive independent compiled results, never signatures inferred from an unvalidated mutable proposal.

type HookScaffoldContract

type HookScaffoldContract struct {
	Type     string
	Identity string
	Path     []string
	Required []string
}

HookScaffoldContract identifies one lowered role, its source type and mandatory methods. Compiler-approved native signatures are retained separately from this mutable metadata and the proposal AST.

type HookScaffoldPlan

type HookScaffoldPlan struct {
	Destination string
	File        *ast.File
	PackagePath string
	EntityHooks []HookScaffoldContract
	Catalog     *typecatalog.Catalog
	// contains filtered or unexported fields
}

HookScaffoldPlan is a validated create-once user-owned file.

type Input

type Input struct {
	Resources          *resource.Store
	Component          *spec.Component
	Declarations       Declarations
	TypeResolver       *typecatalog.Resolver
	TargetPackage      string
	PackageName        string
	ProjectRoot        string
	Contracts          ContractReferences
	Views              ViewReferences
	ViewBindings       ViewBindings
	GeneratedTypes     []GeneratedTypeReference
	SetMarkerViews     map[string]bool
	GoHandler          *GoHandlerAsset
	ContractHandler    *ContractHandlerAsset
	MutationHandler    *MutationHandlerAsset
	ReadIndexes        *ReadIndexSource
	HookScaffold       *HookScaffoldAsset
	VeltyHandler       *VeltyHandlerAsset
	SQLResources       bool
	EntitySupport      *EntitySupportAsset
	EphemeralOwnership bool
	GenerationPolicy   GenerationPolicy
}

func (*Input) ValidateLifecycleTarget

func (input *Input) ValidateLifecycleTarget(mutation bool) error

ValidateLifecycleTarget checks dispatch ownership before artifact generation. Intermediate shape planning may precede mutation lowering; emitting an unsupported target must never silently retain an inert lifecycle declaration.

type MutationHandlerAsset

type MutationHandlerAsset struct {
	ReadIndexes          *ReadIndexSource
	Destination, Factory string
	File                 *ast.File
	Support              []MutationSource
}

MutationHandlerAsset is an explicitly supplied generated policy product. Its factory returns public mutation.Definition[I,O], not a custom Contract or runtime handler. The linking application uses runtime mutation.New.

func (*MutationHandlerAsset) Clone

type MutationHandlerPlan

type MutationHandlerPlan struct {
	Destination, Factory string
	File                 *ast.File
	Support              []MutationSource
}

type MutationSource

type MutationSource struct {
	Role        string
	Destination string
	File        *ast.File
}

MutationSource keeps generated policy support concerns in separate, package-local files under the same ownership and persistence transaction.

type PackageOwnership

type PackageOwnership struct{ Directory string }

PackageOwnership reads the destination recorded by generation for a package component. Type lookup context alone does not establish a destination.

func (PackageOwnership) Destination

func (p PackageOwnership) Destination(key spec.Key) (string, error)

type PackagePlan

type PackagePlan struct {
	Plan      *Plan
	Directory string
}

PackagePlan is a planned component and its component directory.

type Packages

type Packages []PackagePlan

func (Packages) Validate

func (p Packages) Validate() error

func (Packages) ValidateEphemeral

func (p Packages) ValidateEphemeral() error

ValidateEphemeral validates the generated package layout without treating existing generated artifacts as user-owned merely because no persistence sidecar is present. It is deliberately limited to read-only validation.

func (Packages) ValidateWithPolicy

func (p Packages) ValidateWithPolicy(policy GenerationPolicy) error

type Plan

type Plan struct {
	Generation       *spec.GenerationSettings
	OwnerIdentity    string
	ComponentPackage string
	Destinations     map[string]string
	Aliases          []TypeAlias
	Package          string
	GoPackage        string
	Holder           string
	ProjectRoot      string
	ShapePackages    []*Plan
	ShapesOnly       bool
	Documentation    xdocs.Source
	Static           *spec.StaticContent
	ComponentName    string
	Description      string
	Example          string
	Handler          string
	Routes           []RoutePlan
	Connector        string
	Report           *spec.ReportSettings
	Settings         dtag.Settings
	Imports          []spec.ImportSpec
	LifecycleTypes   []string

	ViewDest     string
	RouterDest   string
	RootViewName string
	RootViewType string
	RootSource   string
	Views        []ViewPlan

	Input  ContractPlan
	Output ContractPlan

	HelperTypes     []HelperType
	GeneratedTypes  []GeneratedTypePlan
	GoHandler       *GoHandlerPlan
	ContractHandler *ContractHandlerPlan
	MutationHandler *MutationHandlerPlan
	ReadIndexes     *ReadIndexSource
	FactoryLink     *FactoryLinkPlan
	HookScaffold    *HookScaffoldPlan
	VeltyHandler    *VeltyHandlerPlan
	Resources       *ResourcePlan
	EntitySupport   *EntitySupportPlan
	// contains filtered or unexported fields
}

func (*Plan) CanonicalType

func (p *Plan) CanonicalType(packagePath, expression string) (string, error)

CanonicalType resolves a generated field expression under the artifact's package/import authority. Implicit aliases follow the same generation policy used when allocating and emitting these imports; native shape owns syntax.

func (*Plan) HolderName

func (p *Plan) HolderName() string

func (*Plan) PackageName

func (p *Plan) PackageName() string

PackageName is the Go package name used by the scaffold emission owner.

func (*Plan) ValidateDestination

func (p *Plan) ValidateDestination(dir string) error

ValidateDestination checks every package in this component before writing.

func (*Plan) ValidateDestinationEphemeral

func (p *Plan) ValidateDestinationEphemeral(dir string) error

ValidateDestinationEphemeral validates a prospective generated layout and imports without applying persistence ownership checks. It is for read-only project validation; real transcription still calls ValidateDestination.

func (*Plan) ValidateDestinationWithPolicy

func (p *Plan) ValidateDestinationWithPolicy(dir string, policy GenerationPolicy) error

func (*Plan) ViewByType

func (p *Plan) ViewByType(typeName string) *ViewPlan

ViewByType returns the final view plan that owns typeName.

type ReadIndexSource

type ReadIndexSource struct {
	Package              string
	TypeName, CacheField string
	Source               MutationSource
}

ReadIndexSource is generated application support owned by the input package. Keeping it there lets Input.Init use typed indexes without importing its handler package. Linked contracts use a component-owned free accessor.

type ResourceManifest

type ResourceManifest = packageasset.Resources

ResourceManifest is persisted beside generated package ownership metadata. Paths are relative to the generated package directory.

type ResourcePlan

type ResourcePlan struct {
	Namespace   string
	Destination string
	Symbol      string
	Files       []EmittedFile
	// contains filtered or unexported fields
}

ResourcePlan keeps regenerable package assets separate from append-only Go field metadata. The emitted FS is registered explicitly with Bindly.

type Result

type Result struct {
	Plan        *Plan
	Files       []EmittedFile
	Diagnostics []spec.Diagnostic
}

func (*Result) RegisterPackage

func (r *Result) RegisterPackage(catalog *typecatalog.Catalog, pkg *smodel.Package, dir string) error

RegisterPackage publishes generated declarations under manifest ownership and preserves authored declarations that share the same Go package.

type RoutePlan

type RoutePlan struct {
	Name         string
	Path         string
	Method       string
	Marshaller   string
	APIKeyHeader string
	APIKeyValue  string
	MCP          []*spec.MCPExposure
}

RoutePlan is the route-specific metadata emitted on one typed component holder field. Handler identity remains component-wide on Plan.

type TypeAlias

type TypeAlias struct{ Name, Type string }

type VeltyHandlerAsset

type VeltyHandlerAsset struct {
	Template            string
	Factory             string
	GoDestination       string
	ResourceDestination string
}

VeltyHandlerAsset is an explicitly accepted Velty template and its managed package destinations. It carries no compiled program or runtime capability.

func (*VeltyHandlerAsset) Clone

Clone returns an isolated value copy of the handler asset.

type VeltyHandlerPlan

type VeltyHandlerPlan struct {
	Template            string
	Factory             string
	GoDestination       string
	ResourceDestination string
}

VeltyHandlerPlan is the validated template/factory pair emitted with a generated package.

type ViewBindings

type ViewBindings map[string]string

ViewBindings maps one effective parameter identity to the exact canonical independent-view identity selected during transcribe/load assembly.

type ViewOwnership

type ViewOwnership string
const (
	ViewGenerated ViewOwnership = "generated"
	ViewLinked    ViewOwnership = "linked"
)

type ViewPlan

type ViewPlan struct {
	Package         string
	Identity        string
	Name            string
	Type            string
	Destination     string
	Fields          []Field
	SetMarkerFields []string
	Ownership       ViewOwnership
	DescriptorKey   string
}

ViewPlan is one generated canonical view type. Relations reference another ViewPlan by its local type name rather than creating a parallel graph.

func (*ViewPlan) Field

func (p *ViewPlan) Field(name string) (Field, bool)

Field returns a generated view field by its Go name.

type ViewReference

type ViewReference struct {
	DescriptorKey string
}

ViewReference identifies a package-owned canonical view type.

type ViewReferences

type ViewReferences map[string]*ViewReference

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL