Documentation
¶
Overview ¶
Package generate owns declaration analysis and deterministic Go generation.
Index ¶
- Constants
- func DistributionPath(name string) bool
- func FrameworkHTTPDependencies(ctx context.Context, dir string) (map[string]bool, error)
- func Scaffold(ctx context.Context, options ScaffoldOptions) (string, error)
- func SnapshotDistribution(outputs map[string][]byte) (map[string][]byte, error)
- func ValidateScaffold(options ScaffoldOptions) error
- type AnalysisPackage
- type Options
- type Recovery
- type Report
- type RetiredJournalError
- type ScaffoldKind
- type ScaffoldOptions
- type StaleFile
- type StaleReason
- type TransportDeclaration
Constants ¶
const ArtifactHeader = generatedHeader
ArtifactHeader is shared with language renderers. JSON outputs are identified by the versioned ownership manifest and digest, without invalid JSON comments.
const MaxArtifactBytes = 48 << 20
MaxArtifactBytes bounds one published client artifact. A client embeds a manifest of up to 16 MiB plus its declarations, so it exceeds the Go limit.
const MaxDistributionBytes = 32 << 20
const MaxDistributionDirectories = 256
const MaxDistributionFileBytes = 8 << 20
const MaxDistributionFiles = 1024
const MaxScaffoldEnumCases = 64
MaxScaffoldEnumCases bounds the cases of one enum scaffold.
Variables ¶
This section is empty.
Functions ¶
func DistributionPath ¶
DistributionPath is shared by plugin rendering and publication. Names are portable relative paths with no hidden files, framework ownership paths, directory traversal or platform-specific separators/device names.
func FrameworkHTTPDependencies ¶ added in v0.45.0
FrameworkHTTPDependencies uses the same source import graph as generation. It is also used by the external migration before any annotation is written.
func Scaffold ¶
func Scaffold(ctx context.Context, options ScaffoldOptions) (string, error)
Scaffold checks the consumer package with the proposed declaration in memory, then creates one new file through the shared guarded publication/recovery path. The file is handwritten from that point onward and never manifest-owned.
func SnapshotDistribution ¶
SnapshotDistribution validates the complete path set and returns owned bytes. Case-insensitive aliases and file/directory prefix collisions fail on all OSes.
func ValidateScaffold ¶
func ValidateScaffold(options ScaffoldOptions) error
ValidateScaffold checks options without loading packages or touching files.
Types ¶
type AnalysisPackage ¶ added in v0.45.0
type AnalysisPackage struct {
Types *types.Package
TypesInfo *types.Info
Fset *token.FileSet
Syntax []*ast.File
HTTPDependencies map[string]bool
Declarations map[string]TransportDeclaration
}
AnalysisPackage retains complete function bodies for read-only source tooling. Generation's declaration-only pass remains independent of this check.
func LoadAnalysis ¶ added in v0.45.0
func LoadAnalysis(ctx context.Context, dir string, patterns []string) (result []*AnalysisPackage, resultErr error)
LoadAnalysis reuses the generator's Go listing, module selection and export importer. Test variants use their own import remapping and type-check context.
type Options ¶
type Options struct {
Dir string
Check bool
Recursive bool
// Framework identifies the framework release rendering output, normally the
// running tool's build. A known version that differs from the consumer's
// selected framework fails before any file is written. Leave it empty in
// development builds, where no release version is available.
Framework frameworkinfo.Build
// contains filtered or unexported fields
}
Options targets an existing consumer Go package or a recursive package tree. Check validates output without creating locks, stage directories, or modifying any project file.
type Recovery ¶
type Recovery struct{ Found, Kept, RolledBack bool }
Recovery reports whether a interrupted publication was kept or rolled back.
type Report ¶
type Report struct {
Written, Removed []string
// Stale explains each difference found by a check, without file contents.
Stale []StaleFile
}
func Generate ¶
Generate analyzes declarations, renders deterministic output and type-checks the complete package overlay before publishing any generated source.
func PublishArtifacts ¶
func PublishArtifacts(ctx context.Context, dir string, outputs map[string][]byte, check bool) (Report, error)
PublishArtifacts reuses the Go publisher's planning, ownership, read-only checks, guarded publication, rollback and crash recovery. It neither loads Go packages nor invokes a compiler. The existing output directory belongs to one artifact family; Go-owned and client-owned manifests cannot be mixed.
func PublishDistribution ¶
func PublishDistribution(ctx context.Context, dir string, owner pluginmanifest.Distribution, outputs map[string][]byte, check bool) (Report, error)
PublishDistribution uses the same ownership planner, process guards, staged publication and recovery as generated Go/client files. The selected existing root belongs to one distribution. Its new parents may be created; empty directories are retained after rollback to avoid deleting user-created data.
type RetiredJournalError ¶ added in v0.24.0
type RetiredJournalError struct{ Version int }
RetiredJournalError identifies a source-edit journal that this generator cannot recover. Its staging must be reconciled with the matching older generator before retrying.
func (*RetiredJournalError) Error ¶ added in v0.24.0
func (e *RetiredJournalError) Error() string
type ScaffoldKind ¶
type ScaffoldKind string
const ( MigrationScaffold ScaffoldKind = "migration" SeederScaffold ScaffoldKind = "seeder" ModelScaffold ScaffoldKind = "model" DTOScaffold ScaffoldKind = "dto" JobScaffold ScaffoldKind = "job" CommandScaffold ScaffoldKind = "command" // EndpointScaffold creates request/response DTOs, generates their codecs, // then creates the typed route, endpoint and handler stub. EndpointScaffold ScaffoldKind = "endpoint" EnumScaffold ScaffoldKind = "enum" MiddlewareScaffold ScaffoldKind = "middleware" RuleScaffold ScaffoldKind = "rule" EventScaffold ScaffoldKind = "event" ListenerScaffold ScaffoldKind = "listener" PolicyScaffold ScaffoldKind = "policy" NotificationScaffold ScaffoldKind = "notification" )
func ScaffoldKinds ¶
func ScaffoldKinds() []ScaffoldKind
ScaffoldKinds lists every supported kind in documentation order.
type ScaffoldOptions ¶
type ScaffoldOptions struct {
// HTTP selects body, response or both for a DTO; empty emits no helper.
HTTP string
// Role selects response-only DTO validation semantics independently of HTTP.
Role string
Dir string
Kind ScaffoldKind
Name string
ID string
Origin string
Version string
Table string
Queue string
Create string
Method string
Path string
Cases []string
Event string
Subject string
Resource string
// Model extension slots: the Go field names of each slot kind, and the
// storage disk ID that attachment slots use.
Translated []string
Attachment []string
Attachments []string
Metadata []string
Disk string
// Framework identifies the release used by scaffold generation.
Framework frameworkinfo.Build
// contains filtered or unexported fields
}
ScaffoldOptions creates a consumer-owned declaration in an existing Go package. Explicit identities make output deterministic; no clock, SQL schema inspection, automatic registration or application bootstrap is involved.
Kind-specific fields: Table (model); Queue (job); Origin, Version and the optional Create table (migration); Method and a static Path (endpoint); Cases (enum); Event payload type (listener); Subject and Resource types (policy). Type names refer to exported types of the same package.
type StaleFile ¶
type StaleFile struct {
Path string
Reason StaleReason
}
StaleFile is one generation-owned or managed target that differs.
type StaleReason ¶
type StaleReason string
StaleReason distinguishes absent/obsolete output from content, comment and layout-only differences and ownership manifests.
const ( StaleMissing StaleReason = "missing" StaleObsolete StaleReason = "obsolete" StaleContent StaleReason = "content differs" StaleComments StaleReason = "comments differ" StaleFormatting StaleReason = "formatting differs" StaleManifest StaleReason = "ownership manifest differs" )
type TransportDeclaration ¶ added in v0.45.0
type TransportDeclaration struct {
Key, Name, Kind, Role, HTTP string
Position, Directive token.Position
Comment string
Generic bool
}
TransportDeclaration exposes existing directive metadata to read-only source tools and the external migration. It does not create a second wire schema.
func TransportDeclarations ¶ added in v0.45.0
Source Files
¶
- analysis.go
- artifacts.go
- batch.go
- declarations.go
- discover.go
- discover_config.go
- discover_dto.go
- discover_enum.go
- discover_message.go
- discover_multipart.go
- discover_path.go
- discover_query.go
- discover_transport_fields.go
- discover_union.go
- distribution.go
- distribution_recovery.go
- dto_custom_codec.go
- dto_identity.go
- dto_instantiation.go
- dto_map_key.go
- emit.go
- emit_config.go
- emit_diagnostics.go
- emit_dto.go
- emit_dto_generic.go
- emit_dto_validation.go
- emit_enum_codec.go
- emit_json_paths.go
- emit_multipart.go
- emit_path.go
- emit_query.go
- emit_union.go
- generate.go
- generated_names.go
- graph.go
- guard_unix.go
- http_helpers.go
- json_shape.go
- load.go
- module_scope.go
- persistence_models.go
- presentation.go
- publication_json.go
- recover.go
- scaffold.go
- scaffold_components.go
- scaffold_contracts.go
- scaffold_developer.go
- scaffold_model.go
- scaffold_model_names.go
- scaffold_model_slots.go
- source_documentation.go
- test_symbols.go
- transport_declarations.go
- url_scalar.go
- write.go