Documentation
¶
Overview ¶
Package generate owns declaration analysis and deterministic Go generation.
Index ¶
- Constants
- func DistributionPath(name string) bool
- 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 Options
- type Recovery
- type Report
- type ScaffoldKind
- type ScaffoldOptions
- type StaleFile
- type StaleReason
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 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 Options ¶
type Options struct {
Dir string
Check bool
Recursive bool
// FieldDocumentation removes obsolete managed "Foundry field behavior"
// notes from handwritten model files. Without this option, generation leaves
// handwritten files and existing notes unchanged.
FieldDocumentation 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
}
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 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 {
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
// FieldDocumentation and Framework apply to the generation a scaffold runs
// (a model with slots, an endpoint or a notification), as they do to
// foundry generate.
FieldDocumentation bool
Framework frameworkinfo.Build
}
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, managed field notes and ownership manifests.
const ( StaleMissing StaleReason = "missing" StaleObsolete StaleReason = "obsolete" StaleContent StaleReason = "content differs" StaleComments StaleReason = "comments differ" StaleFormatting StaleReason = "formatting differs" StaleFieldNotes StaleReason = "managed field notes differ" StaleManifest StaleReason = "ownership manifest differs" )
Source Files
¶
- 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
- field_documentation.go
- field_documentation_write.go
- generate.go
- generated_names.go
- graph.go
- guard_unix.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
- url_scalar.go
- write.go