Documentation
¶
Overview ¶
Package generate implements `gombit generate`: it regenerates a gombit application's model-first resource files (the generator-owned *.gen.go DTOs and handler) from the app's real compiled GORM models, and, with Check, verifies they are up to date without mutating anything.
Model-first generation must read the ACTUAL current model — the one the developer may have edited — so it cannot work off the make-resource CLI grammar or off source it just wrote. Like migrations (ADR-012), it uses Program Mode: a throwaway `main` is written into the app module and `go run`, importing the app's model packages and calling resourcegen.RenderResource on each. That loader is a pure function — it emits the artifacts (path, bytes, ownership) as JSON and has no write access to the app tree. This package (the parent) owns all filesystem policy: which files are overwritten, which are seeded once, and what --check compares.
Index ¶
- Variables
- func Generate(ctx context.Context, opts Options) error
- func PlanResource(ctx context.Context, opts Options, pend resourcegen.Pending) ([]resourcegen.GeneratedArtifact, error)
- func ValidateResource(ctx context.Context, opts Options, pend resourcegen.Pending, ...) error
- type LoaderError
- type Options
- type StaleFile
Constants ¶
This section is empty.
Variables ¶
var ErrStale = errors.New("generate: generated files are stale")
ErrStale is the error Generate wraps, with Check, when a generated file differs from what the models produce (or is missing).
Functions ¶
func PlanResource ¶
func PlanResource(ctx context.Context, opts Options, pend resourcegen.Pending) ([]resourcegen.GeneratedArtifact, error)
PlanResource runs the Program-Mode phase-2 render for a single pending (not-yet-written) resource and returns its generator-owned + seed artifacts WITHOUT writing anything. The pending model is compiled through a Go build overlay (pend.Overlay) that isolates it from the stale generated files this run replaces, so the loader can reflect the new model while the real app tree stays untouched and local replace directives keep their meaning — go run executes from the real module root. This renders the artifacts; ValidateResource then compiles the whole committed package (including preserved human-owned files) against them.
func ValidateResource ¶
func ValidateResource(ctx context.Context, opts Options, pend resourcegen.Pending, overlay map[string][]byte) error
ValidateResource compiles the resource package exactly as make resource will commit it — the new model, the freshly rendered *.gen.go, and every preserved human-owned file (hooks and any hand-written code, read from disk) — via an overlay of the final tree, WITHOUT writing anything. It is the second half of the phase-2 preflight: PlanResource renders against an isolated model, but the customization the commit keeps (a hooks.go that reads a model field, say) is only exercised here, so a resource whose preserved code no longer matches the regenerated model fails closed before any file changes. overlay stages just the files this run will write; kept and hand-written files come from disk.
Types ¶
type LoaderError ¶ added in v0.8.0
type LoaderError struct {
Err error
}
LoaderError is a failure to run the resource loader: the go run, inside the application's module, that compiles its models and renders their files. After an upgrade with breaking changes the models may not compile yet; every other error of Stale and Update is about the application's layout or files.
func (*LoaderError) Error ¶ added in v0.8.0
func (e *LoaderError) Error() string
func (*LoaderError) Unwrap ¶ added in v0.8.0
func (e *LoaderError) Unwrap() error
type Options ¶
type Options struct {
WorkDir string
// Check renders in temp space and compares against the committed
// generator-owned files instead of writing; it fails on any difference and
// never mutates the tree (a CI drift gate). Seed-once files are ignored.
Check bool
// DryRun prints what a write run would do without writing.
DryRun bool
Stdout io.Writer
Stderr io.Writer
// contains filtered or unexported fields
}
Options configures a generate run.
type StaleFile ¶ added in v0.8.0
type StaleFile struct {
// Path is relative to the application directory, with forward slashes.
Path string `json:"path"`
Missing bool `json:"missing,omitempty"`
}
StaleFile is a generator-owned file that differs from what the models produce, or is missing.
func Stale ¶ added in v0.8.0
Stale reports the generator-owned resource files that are stale (what Generate with Check fails on), and how many model-first resources the application has. It renders exactly as Generate does, through a loader run inside the application's module (so with the framework version its go.mod requires), and never writes.
func Update ¶ added in v0.8.0
Update renders the resource files once, as Stale does, and writes only the stale generator-owned ones: never a seed-once file (hooks.go), which Stale does not check either. Seeding one where the resource declares its hooks in another file would redeclare them. It returns the files it wrote, and how many resources the application has; when a write fails, the ones written before it, with the error.
Source Files