Documentation
¶
Overview ¶
Package featurize converts a layered project's per-resource source files into the feature-package shape:
app/models/<snake>.model.go → app/<snake>/model.go app/dtos/<snake>.dtos.go → app/<snake>/dtos.go app/repositories/<snake>.repository.go → app/<snake>/repository.go app/repositories/interfaces/<snake>_repository.go → app/<snake>/repository_iface.go app/services/<snake>.service.go → app/<snake>/service.go app/services/interfaces/<snake>_service.go → app/<snake>/service_iface.go app/services/<snake>_errors.go → app/<snake>/errors.go app/services/<snake>_inputs.go → app/<snake>/inputs.go app/rest/controllers/<snake>.controller.go → app/<snake>/controller.go app/rest/routes/<snake>.routes.go → app/<snake>/routes.go app/validators/<snake>.validators.go → app/<snake>/validators.go app/di/providers/<snake>.go → app/<snake>/wire.go
Plus cross-cutting per-layout files (container.go, wire.go, index.routes.go, di/providers/core.go) whose import shape changes.
AST-based transformation ¶
The transformer uses github.com/dave/dst (decorated syntax tree) rather than regex so that:
- aliased imports (`alias "path"`) round-trip correctly
- SelectorExpr collapse is identifier-aware (won't rewrite a constant string that happens to contain "models.User")
- external test packages (`package controllers_test`) are recognized by their syntax shape, not a fragile regex
- the rendered output is gofmt-clean
The transformer operates on RENDERED Go source — text/template placeholders must be resolved by the caller before passing the bytes in. `gofasta new --layout=feature` renders the .tmpl file with ProjectData first, then routes the resulting source through here.
Phase D's `gofasta refactor feature-package` command reuses this same engine on a user's project source. The transformations are identical — only the input source path / output destination differ.
File map ¶
featurize.go — public types (Resource, Options) and package doc
paths.go — path-mapping tables (PerResourceMapping etc.)
forward.go — TransformPerResource (layered → feature)
reverse.go — TransformPerResourceReverse (feature → layered)
crosscutting.go — Transform{Container,Wire,IndexRoutes,Mock,…} +
the shared transformCrossCutting engine
ast.go — generic dst utilities: imports, walker, rewrite
Package featurize — GraphQL resolver-file transformations.
GraphQL files never MOVE between layouts: app/graphql/ is a shared directory in both the layered and the feature shape (gqlgen owns the resolver directory and generates every `{name}.resolvers.go` into it, so splitting the files across feature packages would fight the generator). What changes between layouts is where the symbols the resolvers reference live:
- per-resource DTOs, service interfaces, domain inputs/filters and error sentinels move into `app/<snake>/` (package <snake>)
- shared dtos aliases and gqlgen-generated model types move from `app/dtos` to `app/shared/dtos` (package name stays `dtos`)
So the transform is a re-qualification, not a relocation: every `.go` file under app/graphql/resolvers/ keeps `package resolvers` and its path, and only its selectors + imports are rewritten. The files must NOT go through TransformPerResource — that transform collapses selectors to bare identifiers, which is only correct for files that move INTO the feature package.
Index ¶
- func EnsureGqlgenAutobind(src []byte, mod, snake string) []byte
- func ExpectedResourceSymbols(r Resource) map[string]bool
- func FixDtosImportPath(src []byte, mod string) ([]byte, error)
- func FixSharedDtosImportPathReverse(src []byte, mod string) ([]byte, error)
- func ReversePerResourceMapping(snake string) []struct{ ... }
- func RewriteGqlgenConfig(src []byte, mod string, resources []Resource) []byte
- func RewriteGqlgenConfigReverse(src []byte, mod string, resources []Resource) []byte
- func TransformContainer(src []byte, mod string, resources []Resource) ([]byte, error)
- func TransformContainerReverse(src []byte, mod string, resources []Resource) ([]byte, error)
- func TransformCoreProviders(src []byte, mod string, resources []Resource) ([]byte, error)
- func TransformCoreProvidersReverse(src []byte, mod string, resources []Resource) ([]byte, error)
- func TransformGraphQL(src []byte, mod string, resources []Resource) ([]byte, error)
- func TransformGraphQLReverse(src []byte, mod string, resources []Resource) ([]byte, error)
- func TransformIndexRoutes(src []byte, mod string, resources []Resource) ([]byte, error)
- func TransformIndexRoutesReverse(src []byte, mod string, resources []Resource) ([]byte, error)
- func TransformMock(src []byte, mod string, resource Resource) ([]byte, error)
- func TransformMockReverse(src []byte, mod string, resource Resource) ([]byte, error)
- func TransformPerResource(src []byte, opts Options) ([]byte, error)
- func TransformPerResourceReverse(src []byte, dest LayeredDestination, opts Options) ([]byte, error)
- func TransformWire(src []byte, mod string, resources []Resource) ([]byte, error)
- func TransformWireReverse(src []byte, mod string, resources []Resource) ([]byte, error)
- type LayeredDestination
- type Options
- type PathPair
- type Resource
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EnsureGqlgenAutobind ¶
EnsureGqlgenAutobind inserts `- "<mod>/app/<snake>"` into the autobind list of a FEATURE-shaped gqlgen.yml, anchored right after the `<mod>/app/shared/dtos` entry. Used by `gofasta g` when scaffolding a new resource into a feature-layout GraphQL project.
No-op (returns src unchanged) when the entry is already present or when the shared-dtos anchor is missing — callers detect "nothing changed" by comparing the returned bytes with the input.
func ExpectedResourceSymbols ¶
ExpectedResourceSymbols returns the exported identifiers the scaffold generates for one resource — the surface the migration engines recognize and re-qualify. Derived from buildReverseSymbolMap (the reverse transformer's recognition table) plus the routes function names, which the transformers handle by rename rather than by re-qualification. The refactor preflight diffs a project's actual exports against this set to detect renamed scaffold types, which the migrations would silently fail to rewrite.
func FixDtosImportPath ¶
FixDtosImportPath rewrites a file's `<mod>/app/dtos` import to `<mod>/app/shared/dtos`. No-op if the file doesn't import dtos. Used by shared infra files (app/validators/app_validator.go, app/rest/controllers/validator.go, etc.) that stay in their layered location but reference the shared dtos package which has moved.
func FixSharedDtosImportPathReverse ¶
FixSharedDtosImportPathReverse flips `<mod>/app/shared/dtos` back to `<mod>/app/dtos` in shared infra files (app_validator.go, validator.go, resolver.go) — inverse of FixDtosImportPath.
func ReversePerResourceMapping ¶
func ReversePerResourceMapping(snake string) []struct { Feature string Dest LayeredDestination }
ReversePerResourceMapping returns the (feature_path → layered_path) pairs for unwinding one resource back to layered. Inverse of PerResourceMapping. The PackageName field tells the reverse transformer which `package X` decl to write.
func RewriteGqlgenConfig ¶
RewriteGqlgenConfig rewrites gqlgen.yml from the layered to the feature shape:
- model.filename: app/dtos/… → app/shared/dtos/…
- autobind: `- "<mod>/app/dtos"` → `- "<mod>/app/shared/dtos"`, followed by one `- "<mod>/app/<snake>"` entry per resource.
Idempotent: running it twice produces the same bytes as running it once. Everything not targeted (comments, indentation, the exec / resolver / models sections) is preserved verbatim.
func RewriteGqlgenConfigReverse ¶
RewriteGqlgenConfigReverse rewrites gqlgen.yml from the feature shape back to layered — the exact inverse of RewriteGqlgenConfig: the model.filename flips back, the shared dtos autobind entry becomes app/dtos again, and every per-resource autobind entry is removed.
func TransformContainer ¶
TransformContainer rewrites app/di/container.go: replaces the layered cross-package imports (repoInterfaces, svcInterfaces, controllers) with per-feature alias imports, and rewrites every resource's field types to point at the feature packages.
func TransformContainerReverse ¶
TransformContainerReverse rewrites app/di/container.go from feature layout (per-feature alias imports) back to layered (repoInterfaces, svcInterfaces, controllers).
func TransformCoreProviders ¶
TransformCoreProviders rewrites app/di/providers/core.go: replaces the `app/services` import + `services.NewDefaultPasswordGenerator` reference with the user feature's equivalent. PasswordGenerator follows the user feature (only consumer in the bootstrap scaffold).
func TransformCoreProvidersReverse ¶
TransformCoreProvidersReverse rewrites app/di/providers/core.go back to layered. `userpkg.NewDefaultPasswordGenerator` → `services.NewDefaultPasswordGenerator` (PasswordGenerator moves back to app/services/).
func TransformGraphQL ¶
TransformGraphQL rewrites one `.go` file under app/graphql/resolvers/ from the layered to the feature shape. The file keeps its path and `package resolvers`; only selectors and imports change:
- Per-resource references re-qualify to the feature package: `dtos.TCreateUserDto` → `userpkg.TCreateUserDto`, `services.ErrUserNotFound` → `userpkg.ErrUserNotFound`, `svcInterfaces.UserServiceInterface` → `userpkg.UserServiceInterface`.
- Surviving `dtos.X` references (shared aliases and gqlgen-generated types) keep their qualifier; the `<mod>/app/dtos` import flips to `<mod>/app/shared/dtos`.
- Imports for the emptied layered packages (`app/services`, `app/services/interfaces`, and a fully-requalified `app/dtos`) drop when no reference survives; one `<snake>pkg "<mod>/app/<snake>"` import is added per resource that is actually referenced.
func TransformGraphQLReverse ¶
TransformGraphQLReverse rewrites one `.go` file under app/graphql/resolvers/ from the feature shape back to layered — the exact inverse of TransformGraphQL.
func TransformIndexRoutes ¶
TransformIndexRoutes rewrites app/rest/routes/index.routes.go: replaces `<R>Routes(api, ...)` with `<snake>pkg.RegisterRoutes(api, ...)` and updates the controller field types in RouteConfig.
func TransformIndexRoutesReverse ¶
TransformIndexRoutesReverse rewrites app/rest/routes/index.routes.go back to layered. `<snake>pkg.RegisterRoutes(...)` becomes `<Name>Routes(...)`, and `*<snake>pkg.UserController` fields become `*controllers.UserController`.
func TransformMock ¶
TransformMock rewrites a testutil/mocks/<snake>_*_mock.go file: the mock stays in `package mocks` but the imports flip from the layered `<mod>/app/models` + `<mod>/app/repositories/interfaces` (or `<mod>/app/services/interfaces`) to a single per-feature alias import `<snake>pkg "<mod>/app/<snake>"`, and every selector referencing the layered packages is rewritten to point at the feature package.
The mock impl is in a separate package from the feature it mocks (testify/mock convention), so the references stay as SelectorExprs — only the X identifier changes.
func TransformMockReverse ¶
TransformMockReverse rewrites a testutil/mocks/<snake>_*_mock.go file from feature-package back to layered: the `<snake>pkg` import + qualifier flip to `repoInterfaces` / `svcInterfaces` / `services`.
func TransformPerResource ¶
TransformPerResource rewrites a single per-resource layered Go source file into its feature-package equivalent. Returns the rewritten source as bytes (gofmt'd).
Operations:
Package declaration: `package <layered>` → `package <snake>`. Also handles external test packages: `package <layered>_test` → `package <snake>_test`.
Selector collapse: `X.Y` where X resolves to one of the collapsable layered packages becomes just `Y`.
Drop imports that are no longer referenced after the collapse.
The transformer is package-aware via the import block — it doesn't guess which identifier means what. An aliased import like `repoInterfaces "<mod>/app/repositories/interfaces"` correctly collapses every `repoInterfaces.X` reference, regardless of name.
func TransformPerResourceReverse ¶
func TransformPerResourceReverse(src []byte, dest LayeredDestination, opts Options) ([]byte, error)
TransformPerResourceReverse migrates a single per-resource source file from feature-package layout back to its layered location. It's the inverse of TransformPerResource:
- Package decl: `package <snake>` → `package <layered>` (or `package <layered>_test` for external test files).
- Bare refs to in-feature symbols that belong to OTHER layered packages get qualified — e.g. `UserRepositoryInterface` → `repoInterfaces.UserRepositoryInterface`. Required imports auto-added.
- Refs already qualified by package decl (e.g. `controllers.Validator` when the destination is `package controllers`) shed the redundant self-qualifier.
- `dtos.X` for shared aliases (TPaginationObjectDto etc.) collapses to bare `X` because the destination is `package dtos`. The `<mod>/app/shared/dtos` import flips back to `<mod>/app/dtos`.
- `RegisterRoutes` in routes files renames back to `<R>Routes`.
Caveat: the reverse direction assumes the feature project follows scaffold-shaped conventions. Heavy hand-edits (renamed types, custom files, alternate folder layouts) may not unwind cleanly — in those cases the user should split the migration into smaller pieces or manually adjust the result.
func TransformWire ¶
TransformWire rewrites app/di/wire.go: replaces `providers.<R>Set` with `<snake>pkg.<R>Set` and updates the import.
func TransformWireReverse ¶
TransformWireReverse rewrites app/di/wire.go back to layered: `<snake>pkg.UserSet` → `providers.UserSet`. The providers import is added (or kept — it might already be there for CoreSet).
Types ¶
type LayeredDestination ¶
type LayeredDestination struct {
Path string // layered path (e.g. "app/services/user.service.go")
PackageName string // target package decl ("services", "interfaces", "controllers", ...)
}
LayeredDestination describes where a feature file belongs in the layered layout, plus the package name its package decl must take.
type Options ¶
type Options struct {
ModulePath string // "github.com/acme/myapp"
Resource Resource // the resource this file belongs to
}
Options describes the transformation's environment.
type PathPair ¶
PathPair maps a layered path to its feature equivalent.
func PerResourceMapping ¶
PerResourceMapping returns the (sourcePath, destPath) pairs for a given resource — i.e. which layered files become which feature files. Used by both `gofasta new --layout=feature` (to know which layered templates to transform) and Phase D's refactor command.
func SharedRelocations ¶
func SharedRelocations() []PathPair
SharedRelocations returns the (layered, feature) path pairs for files that simply move location in feature mode without any source-level rewriting. Per Option B:
- app/dtos/aliases.go → app/shared/dtos/aliases.go (package stays `dtos`, but the import path callers use becomes `<mod>/app/shared/dtos` — featurize handles that rewrite on the caller side via rewriteDtosImportPath).
- app/dtos/generated-types.dtos.go → app/shared/dtos/ — gqlgen's generated models file (GraphQL projects only; absent in REST-only projects, and relocation callers stat-gate each pair). Package stays `dtos`; its only intra-project references are same-package, so it moves without rewriting. gqlgen.yml's model.filename is rewritten in step with this move (see gqlgenconfig.go).
func SharedRelocationsReverse ¶
func SharedRelocationsReverse() []PathPair
SharedRelocationsReverse mirrors SharedRelocations but inverted: app/shared/dtos/aliases.go → app/dtos/aliases.go.