generate

package
v0.5.3 Latest Latest
Warning

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

Go to latest
Published: Nov 3, 2026 License: MIT Imports: 48 Imported by: 0

Documentation

Overview

Package generate owns declaration analysis and deterministic Go generation.

Index

Constants

View Source
const ArtifactHeader = generatedHeader

ArtifactHeader is shared with language renderers. JSON outputs are identified by the versioned ownership manifest and digest, without invalid JSON comments.

View Source
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.

View Source
const MaxDistributionBytes = 32 << 20
View Source
const MaxDistributionDirectories = 256
View Source
const MaxDistributionFileBytes = 8 << 20
View Source
const MaxDistributionFiles = 1024
View Source
const MaxScaffoldEnumCases = 64

MaxScaffoldEnumCases bounds the cases of one enum scaffold.

Variables

This section is empty.

Functions

func DistributionPath

func DistributionPath(name string) bool

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

func SnapshotDistribution(outputs map[string][]byte) (map[string][]byte, error)

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.

func Recover

func Recover(ctx context.Context, dir string) (Recovery, error)

Recover acquires the package's process guard, validates every journal target, and keeps a fully published set or restores an interrupted set. It never replaces a target that differs from both recorded states.

type Report

type Report struct {
	Written, Removed []string
	// Stale explains each difference found by a check, without file contents.
	Stale []StaleFile
}

func Generate

func Generate(ctx context.Context, options Options) (Report, error)

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"
)

Jump to

Keyboard shortcuts

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