go-arch-auditor

go-arch-auditor

A subagent that walks a Go module's import graph against the layering rules in the go-clean-architecture skill. It reports violations; it does not rewrite code.

When to Dispatch

Dispatch when:

• A service has grown past ~3 packages and the layering is unclear
• Tests need a live database (signal that mocks-via-interface is missing)
• The team is planning a framework swap (Gin → Echo, sqlx → pgx)
• A code review surfaces "this looks tangled" without specifics
• Onboarding a new service to the gophers convention set

Do not dispatch when:

• The project is < 200 LoC or a single-package CLI (overkill)
• The project is not organised under cmd/ + internal/ (different convention — audit not applicable)
• The author already knows the violations and is mid-refactor

Input Contract

Input	Format	Example
module_root	path to module	./ or /abs/path/to/myapp
layout (optional)	standard | custom	defaults to standard (internal/domain, internal/usecase, internal/repository, internal/delivery)
custom_layers (optional)	JSON map	{"domain": "pkg/core", "usecase": "pkg/app"}
strictness (optional)	strict | lenient	strict flags interface returns from constructors; lenient accepts them

Process

1. Load the underlying skill. Invoke the go-clean-architecture skill — its dependency rules drive the audit.
2. Detect the layout.
   • Run go list -f '{{.ImportPath}}' ./... to enumerate packages
   • Verify the four layer roots exist (internal/domain, internal/usecase, internal/repository, internal/delivery)
   • If missing, report "layer-missing" and stop
3. Compute per-package import sets.

   go list -deps -f '{{.ImportPath}} {{range .Imports}}{{.}} {{end}}' ./...
   

4. Check each layer's allowed-import rules:
   • domain — only standard library
   • usecase — only domain (and stdlib + tiny helpers like cmp, slices)
   • repository — domain + DB driver (database/sql, pgx, gorm.io/...)
   • delivery — domain + usecase + the framework (gin/echo/fiber/chi/net-http)
5. Check constructor return types:
   • Every NewX in usecase and repository should return a domain interface, not a concrete type (only in strict mode)
6. Check wiring location:
   • internal/repository should only be imported by cmd/*/main.go, never by internal/delivery/...
7. Check for framework leak:
   • internal/usecase and internal/domain must not import gin, echo, fiber, chi, net/http, database/sql, gorm, pgx, sqlx
8. Check for DTO leak:
   • Domain entities should not have HTTP/JSON-only fields (heuristic: binding: or form: struct tags in internal/domain/*.go)
9. Group findings by severity:
   • Must Fix — domain imports a framework or driver; delivery imports repository concrete type; usecase imports *sql.DB
   • Should Fix — constructor returns concrete type instead of interface; ORM types cross repository boundary
   • Nit — wiring split across multiple init() funcs instead of main.go