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
- type ContractHandlerAsset
- type ContractHandlerPlan
- type ContractOwnership
- type ContractPlan
- type ContractReference
- type ContractReferences
- type Declaration
- type DeclarationProjection
- type Declarations
- type EmittedFile
- type EntityAssociation
- type EntityInvariant
- type EntityMethod
- type EntitySupportAsset
- type EntitySupportPlan
- type FactoryLinkPlan
- type Field
- type GeneratedTypePlan
- type GeneratedTypeReference
- type GenerationPolicy
- type Generator
- type GoHandlerAsset
- type GoHandlerPlan
- type HelperType
- type HookScaffoldAsset
- func (a *HookScaffoldAsset) Clone() (*HookScaffoldAsset, error)
- func (a *HookScaffoldAsset) Filename() (string, error)
- func (a *HookScaffoldAsset) ResolveEntityHookTypes(directory string) (*typecatalog.Resolver, error)
- func (a *HookScaffoldAsset) RetainEntityHookEvidence(methods map[string][]xshape.Method) error
- type HookScaffoldContract
- type HookScaffoldPlan
- type Input
- type MutationHandlerAsset
- type MutationHandlerPlan
- type MutationSource
- type PackageOwnership
- type PackagePlan
- type Packages
- type Plan
- func (p *Plan) CanonicalType(packagePath, expression string) (string, error)
- func (p *Plan) HolderName() string
- func (p *Plan) PackageName() string
- func (p *Plan) ValidateDestination(dir string) error
- func (p *Plan) ValidateDestinationEphemeral(dir string) error
- func (p *Plan) ValidateDestinationWithPolicy(dir string, policy GenerationPolicy) error
- func (p *Plan) ViewByType(typeName string) *ViewPlan
- type ReadIndexSource
- type ResourceManifest
- type ResourcePlan
- type Result
- type RoutePlan
- type TypeAlias
- type VeltyHandlerAsset
- type VeltyHandlerPlan
- type ViewBindings
- type ViewOwnership
- type ViewPlan
- type ViewReference
- type ViewReferences
Constants ¶
const RootViewPath = "root"
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ContractHandlerAsset ¶
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 ¶
func (a *ContractHandlerAsset) Clone() (*ContractHandlerAsset, error)
Clone returns an isolated parser-backed copy.
type ContractHandlerPlan ¶
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.
type ContractReference ¶
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 ¶
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 ¶
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 EntityInvariant ¶
type EntityMethod ¶
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 ¶
func (a *EntitySupportAsset) Clone() (*EntitySupportAsset, error)
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 ¶
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 (*Generator) RuntimeInputType ¶
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.
type GoHandlerAsset ¶
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 ¶
GoHandlerPlan is the validated custom handler source emitted with a package.
type HelperType ¶
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 ¶
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 ¶
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 ¶
func (a *MutationHandlerAsset) Clone() (*MutationHandlerAsset, error)
type MutationHandlerPlan ¶
type MutationHandlerPlan struct {
Destination, Factory string
File *ast.File
Support []MutationSource
}
type MutationSource ¶
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 ¶
PackagePlan is a planned component and its component directory.
type Packages ¶
type Packages []PackagePlan
func (Packages) ValidateEphemeral ¶
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 ¶
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 (*Plan) PackageName ¶
PackageName is the Go package name used by the scaffold emission owner.
func (*Plan) ValidateDestination ¶
ValidateDestination checks every package in this component before writing.
func (*Plan) ValidateDestinationEphemeral ¶
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 ¶
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 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 ¶
func (a *VeltyHandlerAsset) Clone() *VeltyHandlerAsset
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 ¶
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.
type ViewReference ¶
type ViewReference struct {
DescriptorKey string
}
ViewReference identifies a package-owned canonical view type.
type ViewReferences ¶
type ViewReferences map[string]*ViewReference
Source Files
¶
- contract_handler.go
- contracts.go
- destination_packages.go
- destinations.go
- doc.go
- emit_input_fields.go
- emit_route_component.go
- emit_scaffold.go
- emit_structs.go
- entity.go
- entity_destinations.go
- entity_methods.go
- factory_link.go
- field_type_resolver.go
- filename_settings.go
- generate.go
- generated_type.go
- generator.go
- go_handler.go
- handler_factory_signature.go
- hook_destinations.go
- hook_scaffold.go
- hook_scaffold_mutation.go
- lifecycle.go
- mutation_handler.go
- mutation_source.go
- package_ownership.go
- package_set.go
- persist.go
- persist_fingerprints.go
- persist_owners.go
- persist_projection_fields.go
- persist_renames.go
- persist_resources.go
- persist_shapes.go
- persist_snapshot.go
- plan.go
- plan_column_tags.go
- plan_field_tags.go
- plan_fields.go
- plan_helper_concretize.go
- plan_helper_types.go
- plan_resolver.go
- plan_set_markers.go
- plan_type_authority.go
- plan_type_resolve.go
- plan_validate.go
- plan_velty_tags.go
- plan_view_casts.go
- plan_views.go
- policy.go
- read_indexes.go
- resources.go
- resources_linked.go
- runtime_input.go
- static.go
- type_name.go
- velty_handler.go