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. Start with `hexcheck init`, which writes a starter config from detected folders, then refine it.
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-usecase-imports-in-core: error
39  no-infra-imports-in-usecase: error
40  no-infra-imports-in-ports: error
41  no-entrypoint-imports-in-adapter: error
42  no-framework-types-in-core: error
43  no-infra-types-in-ports: error
44  no-adapter-to-adapter-imports: warn
45  suspicious-business-logic-in-adapter: warn
46  no-local-fakes-for-ports: warn
47  missing-generated-mock-for-port: warn
48  prefer-generated-mocks: warn
49```
50
51Business-logic mode:
52
53```yaml
54heuristics:
55  businessLogicMode: audit # audit|ci
56  businessLogicMinConfidence: medium # low|medium|high
57```
58
59Use `audit` for refactor discovery. Use `ci` when heuristic findings must stay high-confidence. Prefer tuning confidence before adding broad `excludePaths`.
60
61Mock config:
62
63```yaml
64mocking:
65  generatedMockPaths: [internal/mocks/**, internal/application/mocks/**, internal/application/port/mocks/**]
66  generatedMockNamePatterns: ['Mock{{Interface}}', '{{Interface}}Mock']
67```
68
69Run:
70
71```bash
72hexcheck -config .hexcheck.yaml -root . ./...   # exit 3 on error-level findings
73hexcheck -fail-on warn ./...                     # also fail on warn-level findings
74```
75
76The config is strict: unknown keys or rule names fail the run. For a single justified exception, use an inline directive with a reason: `//hexcheck:ignore <rule>[,<rule>] <reason>`.
77
78Agent checklist: read repo architecture docs, map paths to roles, ignore generated/mocks, configure mock paths, run once, tune `ruleSettings.*.excludePaths` only after inspecting examples, and prefer `allow` entries or inline directives with reasons over turning rules off.