codegen

package
v1.7.0 Latest Latest
Warning

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

 Go to latest Published: Sep 7, 2026 License: MIT Imports: 29 Imported by: 0

Documentation

Overview

Decorator-argument literal extractors shared by the validator, OpenAPI, transport, and routes emitters.

Resolution of value-bearing decorators (`@default`, `@example`) to the wire value the OpenAPI document and the transport pre-fill both use.

Cross-cutting decorator utilities: presence checks and string-argument extraction shared across the transport, types, and OpenAPI emitters.

The flattened field view of a type: mixins expanded and generic arguments substituted, with each field's dedup-resolved Go name.

OpenAPI codegen uses `github.com/getkin/kin-openapi` to build a strongly- typed openapi3.T document and `sigs.k8s.io/yaml` to render it as YAML. The library handles spec compliance, default ordering, and the small quirks of OpenAPI 3.1; we only translate craftgo's AST into its types.

Field-level decorator -> schema metadata mapping.

Multi-package merge + clone/rewrite helpers for the OpenAPI document builder.

Operation assembly: buildOperation, parameters, errors, tags, security.

Path + per-operation request/response schemas + response headers.

Top-level component schemas: types, enums, scalars, errors.

OpenAPI security scheme components emission + manifest scheme validation.

TypeRef -> SchemaRef conversion + generic instantiation.

Resolved field/type IR: the single, fully-resolved view of a type's fields that every codegen stage consumes - so no stage re-walks the AST and re-derives a field fact (is-on-wire, is-required, is-pointer, wire name, default value) differently from another and drifts.

[resolveFields] computes each fact ONCE, so a consumer that reads a ResolvedField gets a value that cannot disagree with another consumer's.

Transport: path/query/header/cookie/form/response binding collection.

Transport: @default literal rendering + Go pre-fill code generation.

Wire-bind rendering: the per-source (query/header/cookie/path/form) binding descriptors, the primitive parse table, and the Go-source generator for one field's bind line.

Package codegen turns a validated semantic.Package into Go source files.

Each generator function in this package is responsible for one artefact (currently only types.go; handler/routes/logic scaffolds and OpenAPI/client generators land in subsequent slices). Output files are formatted with `go/format` before being written so that diffs in version control are minimal and the generated code passes `gofmt`.

Small ordering and string helpers shared by every emitter.

Array / file validators: @minItems/@maxItems/@uniqueItems/@maxSize/@mimeTypes.

Cross-field validators: @requiresOneOf / @mutuallyExclusive emission and the field presence / absence expressions they build on.

Nested / enum / type-param validator dispatch.

Numeric validators: @gt/@gte/@lt/@lte/@range/@positive/@negative/@multipleOf.

Required-presence validators emitted onto the generated Validate() chain.

String validators: @length, @minLength, @maxLength, @pattern, @format dispatcher.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Generate added in v1.7.0 

func Generate(proj *semantic.Project, cfg *config.Config, projectRoot string) error

Generate runs the whole codegen pipeline for proj under projectRoot: the pre-flight checks that reject a design before any file is written, then per package the type artefacts (types, enums, errors, validators), the middleware scaffolds, per package the service artefacts (transport, service stubs, routes), and finally the project-wide files (routes umbrella, runtime scaffolds, main.go, openapi.yaml).

func GenerateEnums 

func GenerateEnums(pkg *semantic.Package, outDir string) error

GenerateEnums writes enums.go under outDir/<pkg.Name>/ with a Go type alias and const block per enum. No-op when pkg has no enums.

The Go base type is `int` for int-valued enums, `string` otherwise. Constants are named `<EnumName><PascalCase(ValueName)>`; bare values use the value name as the string payload.

func GenerateErrors 

func GenerateErrors(pkg *semantic.Package, outDir string, r *ProjectResolver) error

GenerateErrors emits a single `errors.go` file under outDir/<pkg.Name>/ declaring one struct + constructor + Error()/HTTPStatus() methods + SCREAMING_SNAKE error-code constant for every ast.ErrorDecl in pkg. When pkg has no errors the function is a no-op.

r supplies the cross-package import paths for body fields (an error in `tasks` whose body carries a `users.UserRef`) and the scalar / enum resolution needed to format a non-string `@header` / `@cookie` error field (`cost shared.Cents`). A nil resolver resolves local names only.

func GenerateProjectMain 

func GenerateProjectMain(proj *semantic.Project, cfg *config.Config, projectRoot string) error

GenerateProjectMain scaffolds the project's main.go (`output.main`) using the union of services and middlewares from every package. The single shared umbrella `routes.RegisterAll` (emitted by GenerateProjectRoutesUmbrella) is the one-call wire-up so the template doesn't have to import per-package routes packages.

The file is gen-once: written when missing, skipped on subsequent gen runs so user-written boot code (extra middlewares, config loading, OTel SDK setup, etc.) survives regeneration.

Setting `output.main: "-"` in the manifest opts the project out of scaffolding entirely - useful for test fixtures that ship their own httptest server and would collide with a generated `package main`.

func GenerateProjectMiddlewares 

func GenerateProjectMiddlewares(proj *semantic.Project, cfg *config.Config, projectRoot string) error

GenerateProjectMiddlewares emits the unified `svccontext/middlewares.go` + per-middleware scaffolds for every package in the project. Middleware names are global (the project resolver enforces uniqueness), so a single Middlewares struct embeds every declaration regardless of which package it lives in. Run ONCE per `craftgo gen` instead of per-package.

Two artefacts per `middleware Name` block:

  1. The IMPLEMENTATION at `<output.middleware>/<kebab-name>-middleware.go`. Scaffold-only - gen-once; existing files are left alone.
  2. The TYPE declaration list at `<svccontext-dir>/middlewares.go`. Always overwritten - derived purely from the DSL.

Users embed the generated `Middlewares` struct into their own ServiceContext, then assign each field to a concrete impl in main.go. Routes consume the middleware via the embedded fields directly, so no runtime name registry lookup is needed.

func GenerateProjectOpenAPI 

func GenerateProjectOpenAPI(proj *semantic.Project, cfg *config.Config, projectRoot string) error

GenerateProjectOpenAPI merges every package's types/enums/errors/ scalars/services into a single OpenAPI 3.1 document written to `output.openapi`. When two packages declare a same-named entity, the second-and-subsequent occurrences get renamed to `<PascalPkg><Name>` (e.g. two packages each declaring `User` produce `User` for the first-seen and `AuthUser` / `SharedUser` for collisions). Non-conflicting names stay bare so simple projects keep readable schema names.

func GenerateProjectRoutesUmbrella 

func GenerateProjectRoutesUmbrella(proj *semantic.Project, cfg *config.Config, projectRoot string) error

GenerateProjectRoutesUmbrella emits the top-level `<output.routes>/routes.go` that exposes `RegisterAll(srv, svcCtx)`, aggregating every service from every DSL package in the project. When no package declares a service the file is skipped - calling `RegisterAll` from main.go would also be a no-op.

func GenerateRoutes 

func GenerateRoutes(pkg *semantic.Package, cfg *config.Config, projectRoot string) error

GenerateRoutes emits the per-directory `routes.go` files for pkg's services under `<output.routes>/`. The project-wide umbrella that wires every directory into one `RegisterAll` is GenerateProjectRoutesUmbrella.

The unit of emission is the OUTPUT DIRECTORY, not the service: only one `routes.go` can live in a folder, and `@group` deliberately lets several services share one. Every service landing in a directory contributes its methods to that directory's single RegisterRoutes.

func GenerateRuntimeConfig 

func GenerateRuntimeConfig(cfg *config.Config, projectRoot string) error

GenerateRuntimeConfig scaffolds the project's `config/` package (`config.go` + `config.yaml` + `example.config.yaml`) under `cfg.Output.Config`. Every file is gen-once: written when missing, left untouched when present. main.go reads `<Config>/config.yaml` at boot and hands the loaded `*config.Config` to `svccontext.NewServiceContext`.

Skipped when `cfg.Output.Main == "-"` - projects opting out of the generated main.go (test fixtures, library-style modules) don't need the runtime config package; emitting it would only add a stray import and force the module to track yaml.v3.

The template body lives in `internal/codegen/templates/`. Edit those files to change the shape of the scaffolded artefact - per-project overrides are out of scope here (the runtime config is meant to be edited freely after the first gen).

func GenerateService 

func GenerateService(pkg *semantic.Package, cfg *config.Config, projectRoot string, r *ProjectResolver) error

GenerateService scaffolds one `<method>.go` per method per service under `<output.service>/<servicePackage>/`. Unlike the other generators this one runs in **scaffold** mode: existing files are left untouched so user-written business logic is never overwritten. r lets the scaffold render `*foo.Cred` for a cross-package request/response type; a nil resolver resolves local names only.

func GenerateSvccontext 

func GenerateSvccontext(cfg *config.Config, projectRoot string) error

GenerateSvccontext scaffolds `svccontext.go` at the location pointed to by `cfg.Output.Svccontext`. The file accepts a `*config.Config` in its constructor and embeds the codegen-managed `Middlewares` struct (which is regenerated next to it on every gen run).

Gen-once: existing svccontext.go is left untouched so user-added fields (database handles, caches, ...) survive regeneration. The adjacent `middlewares.go` IS regenerated; splitting the two keeps the auto-managed struct from colliding with hand-edited code.

Skipped when `cfg.Output.Main == "-"` - same rationale as GenerateRuntimeConfig: opting out of main.go means the project doesn't want the framework's runtime scaffolding in its module.

func GenerateTransport 

func GenerateTransport(pkg *semantic.Package, cfg *config.Config, projectRoot string, r *ProjectResolver) error

GenerateTransport emits one `<method>_handler.go` per method per service under `<output.handler>/<servicePackage>/`. Each file contains a single exported `<Method>Handler(svcCtx) http.HandlerFunc` constructor that decodes the request, calls the user's logic, and writes the response.

projectRoot is prepended to `cfg.Output.Transport` so the function can be called with paths relative to the manifest's directory. r supplies every project-wide lookup the handler emit chain consults - scalar inheritance, cross-package enum/type resolution for binding casts, and the Go import paths for qualified identifiers. A nil resolver resolves local names only.

func GenerateTypes 

func GenerateTypes(pkg *semantic.Package, outDir string, r *ProjectResolver) error

GenerateTypes emits a `types.go` file under outDir/<pkg.Name>/ containing Go struct definitions for every concrete (non-generic) ast.TypeDecl in pkg. Generic declarations (those with ast.TypeDecl.TypeParams) are skipped - their concrete instances are emitted at the call site once generic instantiation lands.

outDir is the configured `output.types` directory; the package name segment is appended so that types live alongside the rest of the service-scoped artefacts. r supplies the Go imports for cross-package field types and mixin refs; a nil resolver resolves local names only.

func GenerateValidators 

func GenerateValidators(pkg *semantic.Package, outDir string, r *ProjectResolver) error

GenerateValidators writes `validate.go` next to `types.go`. The file adds a `Validate() error` method to every concrete TypeDecl. Types without any constraints get an empty stub so handlers can call `req.Validate()` uniformly.

r carries every cross-package lookup the validator emit chain needs - scalar inheritance, generic Validate dispatch, cross-pkg enum value-set checks, and the matching Go import registrations. A nil resolver resolves local names only.

func GoFieldName 

func GoFieldName(name string) string

GoFieldName converts a DSL field name (which is allowed to be lowercase, snake_case, or camelCase) into an exported Go identifier applying the common-initialism rule. The DSL field name is preserved verbatim as the JSON tag - see [jsonTag]. Implementation lives in internal/idents so the semantic analyser can detect collisions using the same conversion rule that codegen emits.

func GoTypeRef 

func GoTypeRef(t *ast.TypeRef) string

GoTypeRef converts an ast.TypeRef into the corresponding Go type expression. The optional suffix (`?`) prepends `*` only when the underlying Go type isn't already nilable: slices, maps, channels, interfaces, and pointer-shaped builtins (`file` → `*multipart.FileHeader`) already use `nil` as their zero value, so wrapping them in another pointer would just produce `**T` / `*[]T` for no semantic gain. Value types (`string`, `int`, user structs) still receive `*` so the generated field can distinguish "absent" from the zero value.

func ServiceDir 

func ServiceDir(svcName, style string) string

ServiceDir returns the directory name for a service under the naming case selected by `output.fileCase` (style). Used for filesystem paths and import segments - with the default kebab case `UserService` becomes `user-service` (snake `user_service`, camel `userService`). The Go package declaration inside the directory is derived separately so the source remains compilable regardless of the directory case.

func ServicePackage 

func ServicePackage(svcName string) string

ServicePackage returns the fallback Go package name derived from a service name ("UserService" -> "userservice"), used only when a service's DSL package has no name (a single-file design with no `package` declaration). Kept for the import-alias uniqueness suffix, which must stay per-service.

func ServicePkgName added in v1.5.0 

func ServicePkgName(pkgName, svcName string) string

ServicePkgName is the Go package declaration for a service's generated handler / transport / routes files. It reuses the DSL package name, so the handlers land in the same package identifier as their types (`project` service code alongside the `project` types), matching what the author wrote. Multiple services in one DSL package therefore share a package name across their separate directories - legal in Go, and the route hub imports them under distinct per-service aliases. Falls back to the service-derived name for an unnamed (single-file) package.

func ValidateProjectOpenAPI added in v1.1.0 

func ValidateProjectOpenAPI(proj *semantic.Project, cfg *config.Config) error

ValidateProjectOpenAPI runs every OpenAPI-level uniqueness check (operationId + component-schema names) against the merged project WITHOUT writing anything. The CLI calls it as a pre-flight before any codegen step touches disk, so a name collision fails the whole run up front instead of after types/transport are already written.

func ValidateSecuritySchemes added in v1.7.0 

func ValidateSecuritySchemes(cfg *config.Config) []string

ValidateSecuritySchemes checks the manifest's declared `openapi.securitySchemes` definitions. An oauth2 scheme without a `flows` object (with at least one flow) emits an OpenAPI document that violates the spec and crashes downstream client generators, so it is rejected with a clear message. `@security(...)` references are resolved against the same declared set by the semantic analyser.

Types

type Binding added in v1.2.0 

type Binding int

Binding is where a field's value rides on the wire, derived from its explicit binding decorator (auto-@path / auto-@query are method-context dependent and applied by the request-binding stage, not here). 

const (
	BindBody Binding = iota // JSON request/response body (the default)
	BindPath
	BindQuery
	BindHeader
	BindCookie
	BindForm
	BindSensitive // @sensitive: server-only, json:"-", excluded everywhere
)

func (Binding) String added in v1.2.0 

func (b Binding) String() string

String renders the OpenAPI `in` value for the wire bindings; body and sensitive have no `in`.

type CrossPkg 

type CrossPkg map[string]string

CrossPkg maps a DSL package name (the target's `package X` declaration) to the Go import path under `<modulePath>/<typesOutputDir>/<X>`. Generators look up multi-part DSL refs (`shared.User`) by their first segment to decide which Go import statement to add.

A nil or empty CrossPkg indicates no cross-package context - the generators emit only the standard-library imports they have always emitted.

func BuildCrossPkg 

func BuildCrossPkg(proj *semantic.Project, cfg *config.Config, currentPkgName string) CrossPkg

BuildCrossPkg returns a fully-populated lookup table for every non-current package in the project. The current package is excluded so a self-reference (`design.Foo` inside `package design`) renders as bare `Foo` without dragging in a redundant Go import.

Caller passes `currentPkgName` = the package being generated; passing "" returns the entire project mapping (useful for tools that don't know the destination yet).

type EnumTable 

type EnumTable map[string]*ast.EnumDecl

EnumTable is the per-target-package lookup of EnumDecls reachable from the package being generated. Local enums are keyed bare (`Color`); cross-package enums by qualified DSL form (`shared.Color`). The validator codegen consults this so a field typed `color shared.Color` emits the switch-case validity check for a qualified ref the local-only `pkg.Enums` lookup misses.

func BuildEnumTable 

func BuildEnumTable(proj *semantic.Project, currentPkgName string) EnumTable

BuildEnumTable returns the lookup table for `currentPkgName`. Every enum declared anywhere in the project is included once.

type ErrorTable 

type ErrorTable map[string]*ast.ErrorDecl

ErrorTable is the per-target-package lookup of ErrorDecls reachable from the package being generated. Mirrors TypeTable: local errors keyed bare (`NotFoundErr`), cross-package errors by qualified DSL form (`shared.NotFoundErr`). The OpenAPI emitter needs this to resolve `@errors(shared.NotFoundErr)` references against the right per-error response schema and to register the error body component.

func BuildErrorTable 

func BuildErrorTable(proj *semantic.Project, currentPkgName string) ErrorTable

BuildErrorTable returns the lookup table for `currentPkgName`. Mirrors BuildTypeTable / BuildEnumTable.

type MiddlewareTable 

type MiddlewareTable map[string]*ast.MiddlewareDecl

MiddlewareTable is the per-target-package lookup of MiddlewareDecls reachable from the package being generated. Same keying contract as the other tables, included for symmetry with the codegen-side lookups so a cross-pkg middleware rule has the same plumbed lookup as everything else.

func BuildMiddlewareTable 

func BuildMiddlewareTable(proj *semantic.Project, currentPkgName string) MiddlewareTable

BuildMiddlewareTable returns the lookup table for `currentPkgName`.

type ProjectResolver 

type ProjectResolver struct {
	// Proj is the analysed project the tables were built from; the
	// semantic field IR resolves names against it.
	Proj        *semantic.Project
	Types       TypeTable
	Enums       EnumTable
	Scalars     ScalarTable
	Errors      ErrorTable
	Middlewares MiddlewareTable
	CrossPkg    CrossPkg
}

ProjectResolver bundles every per-package-target lookup table the codegen layer needs to resolve qualified cross-package references. One resolver per generated package; built by BuildProjectResolver from a semantic.Project + config.Config.

Pass it as a single parameter instead of plumbing 4-5 separate tables. Lookup methods are nil-tolerant - `(*ProjectResolver)(nil)` is a usable zero value that always misses, matching the legacy behaviour every callsite already handles for `nil` maps.

func BuildProjectResolver 

func BuildProjectResolver(proj *semantic.Project, cfg *config.Config, currentPkgName string) *ProjectResolver

BuildProjectResolver assembles every table the codegen layer needs for `currentPkgName`. Returns a non-nil resolver with empty tables when proj is nil so callers don't have to nil-check before use.

func (*ProjectResolver) ImportPath 

func (r *ProjectResolver) ImportPath(pkgAlias string) string

ImportPath returns the Go import path for the DSL package alias, or "" when the alias isn't in the cross-package map. Used by emit sites that need to register an import when they output a qualified Go identifier like `shared.ColorRed`.

func (*ProjectResolver) LookupEnum 

func (r *ProjectResolver) LookupEnum(name string) *ast.EnumDecl

LookupEnum is the enum counterpart of [LookupType].

func (*ProjectResolver) LookupError 

func (r *ProjectResolver) LookupError(name string) *ast.ErrorDecl

LookupError is the error counterpart of [LookupType].

func (*ProjectResolver) LookupMiddleware 

func (r *ProjectResolver) LookupMiddleware(name string) *ast.MiddlewareDecl

LookupMiddleware is the middleware counterpart of [LookupType].

func (*ProjectResolver) LookupScalar 

func (r *ProjectResolver) LookupScalar(name string) *ast.ScalarDecl

LookupScalar is the scalar counterpart of [LookupType].

func (*ProjectResolver) LookupType 

func (r *ProjectResolver) LookupType(name string) *ast.TypeDecl

LookupType returns the type decl bound to name (bare for local, qualified `pkg.Name` for cross-package), or nil when no match.

func (*ProjectResolver) QualifierFor 

func (r *ProjectResolver) QualifierFor(n *ast.NamedTypeRef) (string, string)

QualifierFor inspects a named ref and returns (goPrefix, importPath):

  • goPrefix is the Go package qualifier WITH trailing dot (e.g. `"shared."`) for cross-pkg refs, empty for local
  • importPath is the Go import path to register on the generated file when the prefix is non-empty

Returns ("", "") for nil receiver / nil ref / bare ref so callers can use the result unconditionally: 

prefix, path := r.QualifierFor(n)
if path != "" { uses[path] = true }
emit(prefix + ed.Name + ...)

type ResolvedField added in v1.2.0 

type ResolvedField struct {
	semantic.ResolvedField

	GoName string // exported Go field identifier
	GoType string // final Go type, including any *T nullable wrap

	Binding    Binding // wire placement (after request auto-binding, if any)
	OnWireBody bool    // appears as a property in the JSON body schema/struct
	// AutoBound is true when resolveRequestFields promoted an un-decorated
	// field to @path / @query (vs an explicit binding). Stages use it to
	// distinguish an explicit binding that fails to lower (a hard error)
	// from an auto-promoted field that merely can't ride the wire (skipped
	// silently). Always false for response/explicit fields.
	AutoBound bool

	IsPointer     bool // generated Go type is a pointer: a wrapped optional / @nullable field, or a file
	NeedsNilGuard bool // a constraint check must nil-guard before len()/deref: optional or @nullable

	HasDefault  bool // carries @default
	DefaultWire any  // resolved OpenAPI default value (enum member -> wire), nil if none
	HasDefValue bool // a default value was resolved

	// SpecRequired: the field belongs in the OpenAPI required[] (not
	// optional, no @default). RuntimeEnforced: the validator emits a
	// presence check for it (not optional, not @nullable - pointer-backed
	// fields are presence-checked via nil). Stored side-by-side so the
	// schema/param/validate stages read ONE answer each, and a test can
	// assert their relationship as a single visible invariant rather than
	// an emergent property of separate predicates. They differ by design on
	// @default (excluded from SpecRequired) and @nullable (excluded from
	// RuntimeEnforced) - the test pins exactly where.
	SpecRequired    bool
	RuntimeEnforced bool
}

ResolvedField is the resolved view of one field after mixin flattening and generic-argument substitution: the layer-agnostic facts from the semantic IR (category, primitive, home package, nilability) plus the Go rendering derived from them. Every value is computed from the canonical helper, so the field is the single source of truth a stage reads instead of recomputing.

func (ResolvedField) WireName added in v1.2.0 

func (rf ResolvedField) WireName() string

WireName returns the field's wire parameter name for its explicit binding (the decorator's name arg, or the field name). Empty for a body or sensitive field.

type ScalarTable 

type ScalarTable map[string]*ast.ScalarDecl

ScalarTable is the per-target-package lookup of scalar declarations reachable from the package being generated. Local scalars are keyed by bare name (`OrderID`); cross-package scalars use the qualified DSL form (`shared.NonEmptyID`). The codegen consults the table when a field's declared type is a scalar so the scalar's decorators (e.g. `@format(email)` on `scalar Email`) inherit into the field's effective validator chain.

Empty / nil table disables inheritance and the generated validators only honour the field's own decorator list - the legacy single-package behaviour.

func BuildScalarTable 

func BuildScalarTable(proj *semantic.Project, currentPkgName string) ScalarTable

BuildScalarTable returns the lookup table for `currentPkgName`. Every scalar declared anywhere in the project is included once; scalars from other packages are keyed by their qualified DSL form so a field typed `shared.NonEmptyID` resolves cleanly.

Returns nil when proj is nil - callers can still pass the result straight into [GenerateValidatorsPackage] without a guard.

type TypeTable 

type TypeTable map[string]*ast.TypeDecl

TypeTable is the per-target-package lookup of TypeDecls reachable from the package being generated. Mirrors ScalarTable but for struct-shaped types: local types are keyed by bare name (`Order`), cross-package types by qualified form (`shared.Page`). The codegen consults the table to decide whether a field type carries its own `Validate()` method, so a qualified ref like `shared.Page<T>` (which the local-only `pkg.Types` lookup misses) still emits its recursive validate call.

func BuildTypeTable 

func BuildTypeTable(proj *semantic.Project, currentPkgName string) TypeTable

BuildTypeTable returns the lookup table for `currentPkgName`. Every type declared anywhere in the project is included once, qualified for cross-package entries the same way scalars are.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.