feat(generate): gombit generate + --check (Program Mode) — RESGEN-1 slice 5a (#352)

[leo-aa88]

Summary

Adds gombit generate — regenerate a gombit app's model-first resource files (*.gen.go) from its real compiled GORM models, with --check verifying they're current without mutating anything (a drift gate). This is ADR-016's synchronization mechanism: regeneration, not inspection.

• resourcegen.RenderResource(model, pkg) — the shared generation primitive both gombit generate (now) and make resource (slice 5b) will call, so a resource's files are only ever derived one way. Returns []GeneratedArtifact{Path, Content, Ownership}: DTOs + handler are GeneratorOwned (*.gen.go), the hooks file is SeedOnce (human-owned).
• generate package — Program Mode, mirroring migrations (ADR-012): discover the app's model-first resources by an explicit marker (resourcegen.ResourceMarkerFile = .gombit-resource, written by make resource in 5b) — not by AutoMigrate membership (AutoMigrate means "persisted", which a join table/audit model also is). Each marked package is paired with its one AutoMigrate model (exactly one, or fail closed). It writes a throwaway loader main into the app module and go runs it; the loader imports resourcegen + the model packages, calls RenderResource per model, and emits the artifacts as JSON. The loader is a pure function with no write access to the app tree — the parent owns all filesystem policy.
• cli: gombit generate [--check] [--dry-run].

Related #352

Ownership policy (the three constraints from review direction)

• --check compares only generator-owned .gen.go. The hooks file is SeedOnce: written only when absent, never overwritten, and never drift-checked — it's the human-owned customization surface.
• Fail closed on the legacy layout. A resource that still has the human-owned handler.go is refused before the loader runs or anything is written, so the old and new layouts never coexist half-migrated.
• One authoritative derivation. generate and (later) make resource both go through RenderResource; the loader answers "what should exist?", the parent decides how the tree changes.

Acceptance criteria (epic #352)

• Drift becomes staleness checked by regeneration (generate --check), not AST inspection.
• Changing a model + policy needs no manual cross-artifact sync — generate re-derives DTOs/mappers/handler from the model.
• Editing generated plumbing is unsupported (.gen.go overwritten); customization is the seed-once hooks file (never clobbered).

Scope notes

• Slice 5b (next): rewire make resource to bootstrap this layout (model + seed-once hooks + register) and invoke RenderResource, dropping the legacy human-owned handler.go, updating goldentest/frontend/routes. The CI generate --check job lands there too — there is no in-repo example app using the new layout yet, so there's nothing for a CI gate to check until make resource emits it.
• Slice 6: remove resourcecheck + the breaking-change migration guide.

Validation

• go test ./generate/ ./resourcegen/ ./cli/ — pass, incl. a real Program-Mode end-to-end test (go run a loader in a temp app: --check clean when fresh, fails after the model gains a column, clean again after regenerating)
• go build ./..., go vet, golangci-lint run ./generate/ ./cli/ ./resourcegen/ — clean (the two createsuperuser.go gosec G115 are pre-existing and unflagged by CI)

Working agreement checklist

• New behavior has tests — fake-runner unit tests for all parent policy paths + a real go run integration test; the executed DB-independent (schema parsing only)
• Stable features ship docs and appear in an example app — N/A until make resource emits the layout (5b); docs + migration guide in slice 6
• Extraction preserves contracts — additive; the legacy make-resource path is untouched, and generate refuses to run against it
• Generators are idempotent/additive, AST-safe, never overwrite user-owned files — .gen.go regenerable, hooks seed-once/never-clobbered; deterministic output
• API changes regenerate OpenAPI + TS client — N/A (no API change)
• No secrets in generated frontend source — N/A
• Scope stays inside its milestone — post-v0.1 epic [RESGEN-1] Model-derived, generator-owned resource contracts (supersedes contract-drift in #218) #352
• This PR links its issue and states which acceptance criteria it satisfies

[leo-aa88]

REQUEST CHANGES

Program Mode itself is done right: the loader is a genuinely pure function (no filesystem access, emits JSON to stdout), all write/overwrite/seed-once policy lives in the parent, the legacy-layout guard runs before the loader touches anything, and TestGenerateProgramModeEndToEnd actually runs go run against a real temp app through three real states (fresh/stale/regenerated) rather than mocking it away. That's the right shape for a command whose whole job is keeping generated code trustworthy.

But the destination package name this whole pipeline writes files under is derived the same way PR #359 spent three review rounds proving is unsafe for referencing types — and here it's unsafe for something worse: it decides what package clause a brand-new file on disk declares. Confirmed by direct reproduction, not just reasoning — see inline comment. gombit generate (write mode) can silently leave an app not compiling and still print success.

Also one architectural question, not a defect: QUESTION — appResourceModels treats every AutoMigrate'd model under <module>/internal/… as a model-first CRUD resource, with no apparent way to mark one as "persisted but not a generated-API resource" (a join table, an audit-log model, a token/session model). Is that intentional for this framework's conventions (every model gets a generated CRUD surface unless removed from AutoMigrate entirely), or is an opt-out coming in a later slice? Worth confirming before make resource (5b) makes this the default path apps are built on, since retrofitting an exclusion mechanism after real apps depend on "every model is a resource" is more disruptive than deciding it now.

VERDICT

The missing piece is the same one PR #359's own code comments already promised: buildModelResource's doc says cross-checking the destination package against "the package clause already on disk beside model.go" is deferred to "the caller, once a real destination file exists." This is that caller — the first slice in the epic with real filesystem access — and the check still isn't there. The fix is small (read the package clause of an existing file in the target directory, or of model.go specifically, and fail closed on a mismatch before running the loader) and the failure mode without it is exactly the kind of silent, mistrust-the-tool outcome this whole epic exists to eliminate.

[leo-aa88]

BLOCKING — confirmed by reproduction, not just reasoning.

path.Base(m.ImportPath) is the directory's basename, not the actual package clause of the files already in that directory. RenderResource uses it verbatim as the package line of the new dto.gen.go / handler.gen.go / hooks.go it writes (resourcegen/render.go: dir := "internal/" + pkg, and renderModelDTOs/renderModelHandler/renderModelHooks all emit package " + r.Package). Nothing anywhere in this PR reads the package clause of an existing file in that directory to confirm they'd agree.

This is the exact class of bug PR #359 spent three review rounds closing for the model's own referenced types ("reflect.Type.PkgPath is an import path, not the package's declared name, and the two can differ") — and buildModelResource's own doc comment explicitly flags this exact gap for the destination package too: "Cross-checking it against the package clause already on disk beside model.go — the stronger guarantee once a real destination file exists — is [the future filesystem-writing caller]'s job: this pure emitter never touches a filesystem." This PR is that caller, and the cross-check still isn't here.

I reproduced it: a temp app with internal/book/book.go declaring package books (directory book, clause books — a plausible state after a hand-rename that didn't touch every file, or a copy-paste into a differently-named directory) registered in database.go. Running Generate in write mode:

• returns err == nil — reports success.
• writes internal/book/dto.gen.go with package book (from path.Base) alongside the existing book.go's package books.
• the app then fails go build ./... with: found packages books (book.go) and book (dto.gen.go) in .../internal/book.

So the tool whose entire purpose is "regeneration keeps the app in sync and buildable" can itself put the app into a state that doesn't build, and tell the developer it succeeded. The same path.Base(m.ImportPath) pattern is used for the legacy-layout check too (line ~160, pkg := path.Base(m.ImportPath) in ensureNoLegacyLayout) — that one only affects which directory gets stat'd, so it's lower-stakes, but it's the same unvalidated assumption.

Fix: before running the loader (same place ensureNoLegacyLayout already fails closed), parse the package clause of an existing .go file in each resource's target directory (e.g. go/parser.ParseFile in PackageClauseOnly mode is cheap) and compare it against the derived pkg; fail closed with a clear error naming the mismatch instead of silently writing a file under the wrong package name.

[leo-aa88]

APPROVE

Both points from the previous round are addressed, and the second one better than I expected.

The BLOCKING finding (package/directory mismatch) is fixed with ensurePackageMatchesDir (553a279): it parses the actual package clause of every non-test .go file already in each resource directory (go/parser in PackageClauseOnly mode — cheap, no function bodies) and fails closed, before the loader runs or anything is written, if it disagrees with the directory basename. I re-ran my exact original reproduction (internal/book/book.go declaring package books) against this commit and it now fails closed with a clear, actionable error instead of silently writing a broken dto.gen.go and reporting success:

generate: internal/book/book.go declares package "books", but model-first generation writes files as package "book" (the directory name); rename the package to match the directory before regenerating

TestFailsClosedOnPackageMismatch covers the same scenario directly, and asserts both that the loader never ran and that nothing was written — not just that an error came back.

The QUESTION (is every AutoMigrate'd model treated as a CRUD resource) got a real answer, not just a reply: 993e801 replaces AutoMigrate-membership discovery with an explicit ResourceMarkerFile (.gombit-resource) that make resource will write at bootstrap (slice 5b) and generate only reads. This is the right fix, not a patch — it cleanly separates "persisted" from "generated API surface" (a join table or audit-log model stays out of discovery entirely), and it closes the ambiguity case I hadn't even asked about: a marked package must resolve to exactly one AutoMigrate model, failing closed with a clear diagnostic on zero or several. The reasoning for making the marker a durable sentinel rather than inferring resource-ness from a .gen.go file's presence is exactly right too: a missing .gen.go needs to read as drift (caught by --check), not make the resource silently disappear from discovery.

Verified independently: checked out 993e801badd436a380f3c8c3263ac53bbcd5425f in a worktree, ran go build ./..., go vet, and the full generate/cli/resourcegen test suites (no -short, so the real Program-Mode end-to-end test executes) — all clean. Re-ran my original repro against the new code and confirmed it now fails closed as shown above.

VERDICT

Both issues closed with real fixes and real tests, and the second one turned into a better design than what I asked a question about, not just a bolted-on flag. Good to merge.