go-arch-auditor

name: go-arch-auditor
description: "Dispatch when a Go service needs a clean-architecture audit. Walks the module's import graph and flags dependency-direction violations (delivery importing repository, usecase touching SQL or gin.Context), framework leaks into the domain, and ORM types crossing layer boundaries — with file:line citations and a refactor sequence. Use before a refactor sprint, when onboarding a service, or when tests require a live database."
tools: Read, Glob, Grep, Bash
model: opus
license: MIT
metadata:
  author: muratmirgun
  version: "0.1.0"
  homepage: https://github.com/muratmirgun/gophers
  emoji: "🏛️"
  skill: go-clean-architecture

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`

Output Contract

Return a single markdown block with this exact shape:

## Architecture Audit — <module_path>

**Layout:** standard (cmd/, internal/{domain,usecase,repository,delivery})
**Skill:** go-clean-architecture v0.1.0
**Packages scanned:** 17

### Dependency Direction Check

| Layer | Allowed | Violations |
|---|---|---|
| domain | stdlib | ✅ 0 |
| usecase | domain + stdlib | ❌ 2 (see below) |
| repository | domain + driver | ✅ 0 |
| delivery | domain + usecase + framework | ⚠️ 1 |

### Must Fix

- `internal/usecase/user.go:14` — **[domain-purity]** `usecase` imports `github.com/jmoiron/sqlx`. SQL belongs only in `internal/repository`. The repository should expose a `domain.UserRepository` interface; the usecase depends on the interface.
- `internal/delivery/http/user_handler.go:9` — **[skip-usecase]** Handler imports `internal/repository/postgres` directly, bypassing `internal/usecase`. Inject `domain.UserService` (the usecase contract) instead of `*postgres.UserRepo`.

### Should Fix

- `internal/usecase/user.go:33` — **[constructor-interface]** `NewUserUsecase` returns `*userUsecase` (concrete). Return `domain.UserService` so callers depend on the contract, not the implementation.
- `internal/repository/order.go:88` — **[orm-leak]** Method `(*orderRepo).FindAll` returns `[]*gorm.Tx` instead of `[]*domain.Order`. Translate to domain entities before crossing the boundary.

### Nit

- `internal/delivery/http/init.go:5` — **[wiring-in-init]** DI happens in `init()`. Move to `cmd/api/main.go` so the wiring graph is in one file.

### Test-Surface Check

- `internal/usecase/*_test.go` import `database/sql` → tests require a live DB. After fixing the Must-Fix items, in-memory fakes will compile.

### Summary

| Severity | Count | Notes |
|---|---|---|
| Must Fix | 2 | Both reachable from `cmd/api/main.go` |
| Should Fix | 2 | Constructor + ORM leak |
| Nit | 1 | DI in init() |

**Verdict:** ❌ Layer boundaries are leaky. Resolve Must Fix items first; the suggested refactor sequence is in the appendix.

### Suggested Refactor Sequence

1. Move SQL out of `internal/usecase/user.go` → into `internal/repository/