goplt/docs/content/adr/0011-code-generation-tools.md

ADR-0011: Code Generation Tools

Status

Accepted

Context

The platform will use code generation for:

• Permission constants from module manifests
• Ent ORM code generation
• Mock generation for testing
• OpenAPI client/server code (future)

We need to decide on tooling and workflow.

Decision

Use standard Go generation tools with go generate:

1. Ent ORM: entgo.io/ent/cmd/ent for schema code generation
2. Mocks: github.com/vektra/mockery/v2 or github.com/golang/mock/mockgen
3. Permissions: Custom scripts/generate-permissions.go
4. OpenAPI: github.com/deepmap/oapi-codegen (future)

Workflow:

• Use //go:generate directives in source files
• Run go generate ./... before commits
• Document in Makefile with make generate target
• CI should verify generated code is up-to-date

Rationale:

• Standard Go tooling, well-supported
• go generate is the idiomatic way to run code generation
• Easy to integrate into CI/CD
• Reduces manual code maintenance

Consequences

Positive

• Automated code generation reduces errors
• Consistent code style
• Easy to maintain
• Standard Go workflow

Negative

• Requires developers to run generation before commits
• Generated code must be committed (or verified in CI)
• Slight learning curve for new developers

Implementation Notes

• Add //go:generate directives where needed
• Create Makefile target: make generate
• Add CI step to verify generated code: go generate ./... && git diff --exit-code
• Document in CONTRIBUTING.md