1---
2name: hexcheck
3description: Use when configuring or running hexcheck in a Go repo for hexagonal architecture boundaries, adapter business-logic warnings, and mock discipline.
4---
5
6# Hexcheck
7
8Configure `.hexcheck.yaml` by mapping repo paths to roles. Folder names do not matter; roles do.
9
10Roles:
11- `core`: domain/core business logic
12- `usecase`: application use cases/orchestration
13- `ports`: interfaces/contracts
14- `adapter`: infra, persistence, external services, outbound adapters
15- `entrypoint`: CLI/HTTP/UI/bootstrap
16- `ignore`: generated code, mocks, vendor
17
18Minimal shape:
19
20```yaml
21version: 1
22components:
23  core: { role: core, paths: [internal/domain/**, internal/core/**] }
24  usecases: { role: usecase, paths: [internal/application/usecase/**, internal/application/usecases/**, internal/usecases/**] }
25  ports: { role: ports, paths: [internal/application/port/**, internal/domain/repository/**] }
26  adapters: { role: adapter, paths: [internal/infrastructure/**, internal/adapters/**] }
27  entrypoints: { role: entrypoint, paths: [cmd/**] }
28  generated: { role: ignore, paths: ['**/mocks/**', '**/generated/**', '**/*_templ.go', '**/*_gen.go'] }
29```
30
31For repos using `boundaries`, map by role, e.g. `boundaries/in -> entrypoint`, `boundaries/out -> adapter`, `boundaries/ports -> ports`.
32
33Recommended rules:
34
35```yaml
36rules:
37  no-adapter-imports-in-core: error
38  no-infra-imports-in-usecase: error
39  no-framework-types-in-core: error
40  no-infra-types-in-ports: error
41  no-adapter-to-adapter-imports: warn
42  suspicious-business-logic-in-adapter: warn
43  no-local-fakes-for-ports: warn
44  missing-generated-mock-for-port: warn
45  prefer-generated-mocks: warn
46```
47
48Business-logic mode:
49
50```yaml
51heuristics:
52  businessLogicMode: audit # audit|ci
53  businessLogicMinConfidence: medium # low|medium|high
54```
55
56Use `audit` for refactor discovery. Use `ci` when heuristic findings must stay high-confidence. Prefer tuning confidence before adding broad `excludePaths`.
57
58Mock config:
59
60```yaml
61mocking:
62  generatedMockPaths: [internal/mocks/**, internal/application/mocks/**, internal/application/port/mocks/**]
63  generatedMockNamePatterns: ['Mock{{Interface}}', '{{Interface}}Mock']
64```
65
66Run:
67
68```bash
69hexcheck -hexcheck.config .hexcheck.yaml -hexcheck.root . ./...
70```
71
72Agent checklist: read repo architecture docs, map paths to roles, ignore generated/mocks, configure mock paths, run once, tune `ruleSettings.*.excludePaths` only after inspecting examples.