# Configuration
Reach reads architecture, change-safety, advisory candidate, and smell policy from `.reach.exs`.
```bash
mix reach.check --arch
mix reach.check --changed
mix reach.check --candidates
mix reach.check --smells
mix reach.inspect TARGET --candidates
```
The file must evaluate to a keyword list. Start from [`examples/reach.exs`](../examples/reach.exs), then tune it to your project.
```elixir
[
layers: [
web: "MyAppWeb.*",
domain: "MyApp.*",
data: ["MyApp.Repo", "MyApp.Schemas.*"]
],
deps: [
forbidden: [
{:domain, :web},
{:data, :web}
]
],
source: [
forbidden_modules: ["MyApp.Legacy.*"],
forbidden_files: ["lib/my_app/legacy/**"]
],
calls: [
forbidden: [
{"MyApp.Domain.*", ["IO.puts", "Jason.encode!"]},
{"MyApp.Workers.*", ["System.cmd"], except: ["MyApp.Workers.Cleanup"]}
]
],
effects: [
allowed: [
{"MyApp.Pure.*", [:pure, :unknown]}
]
],
boundaries: [
public: ["MyApp.Accounts"],
internal: ["MyApp.Accounts.Internal.*"],
internal_callers: [
{"MyApp.Accounts.Internal.*", ["MyApp.Accounts", "MyApp.Accounts.*"]}
]
],
risk: [
changed: [
many_direct_callers: 5,
wide_transitive_callers: 10,
branch_heavy: 8,
high_risk_reason_count: 3
]
],
candidates: [
thresholds: [
mixed_effect_count: 2,
branchy_function_branches: 8,
high_risk_direct_callers: 4
],
limits: [
per_kind: 20,
representative_calls: 10,
representative_calls_per_edge: 3
]
],
clone_analysis: [
provider: :ex_dna,
min_mass: 30,
min_similarity: 1.0,
max_clones: 50
],
smells: [
fixed_shape_map: [
min_keys: 3,
min_occurrences: 3,
evidence_limit: 10
],
behaviour_candidate: [
min_modules: 3,
min_callbacks: 3,
module_display_limit: 8,
callback_display_limit: 8
]
],
tests: [
hints: [
{"lib/my_app/accounts/**", ["test/my_app/accounts_test.exs"]}
]
]
]
```
The `deps`, `source`, `calls`, `effects`, `boundaries`, `risk`, `candidates`, `smells`, and `tests` sections use a uniform grouped shape: the section names the concern, and nested entries name the policy direction or threshold being tuned.
## Keys
### `layers`
Assign modules to architectural layers.
```elixir
layers: [
web: "MyAppWeb.*",
domain: ["MyApp.Accounts", "MyApp.Billing", "MyApp.Catalog"],
data: "MyApp.Repo"
]
```
Patterns are module-name strings with `*` wildcards. A layer may have one pattern or a list of patterns.
### `deps[:forbidden]`
Declare layer-to-layer dependencies that should not exist.
```elixir
deps: [
forbidden: [
{:domain, :web},
{:data, :web}
]
]
```
`mix reach.check --arch` reports `forbidden_dependency` violations with caller, callee, call, file, and line evidence.
### `source[:forbidden_modules]`
Declare module names or namespaces that must not appear in the analyzed source tree. This is useful for making removed architecture impossible to reintroduce.
```elixir
source: [
forbidden_modules: [
"MyApp.Legacy.*",
"MyApp.OldTaskRunner"
]
]
```
`mix reach.check --arch` reports `forbidden_module` violations with module, file, and line evidence.
### `source[:forbidden_files]`
Declare source paths that must not appear in the analyzed source tree.
```elixir
source: [
forbidden_files: [
"lib/my_app/legacy/**",
"lib/my_app/old_task_runner.ex"
]
]
```
Path globs use the same `*` / `**` matching rules as module patterns. `mix reach.check --arch` reports `forbidden_file` violations.
### `calls[:forbidden]`
Declare calls that matching modules must not make. This is useful for enforcing presentation/IO boundaries or other call-level rules that are more precise than layer dependencies.
```elixir
calls: [
forbidden: [
{"MyApp.Domain.*", ["IO.puts", "Jason.encode!"]},
{"MyApp.Workers.*", ["System.cmd", "File.rm"], except: ["MyApp.Workers.Cleanup"]}
]
]
```
Each entry is either:
```elixir
{caller_patterns, call_patterns}
{caller_patterns, call_patterns, except: except_caller_patterns}
```
Patterns use the same module/call glob syntax as layers. Call patterns may include or omit arity:
```elixir
"IO.puts"
"IO.puts/1"
"Reach.CLI.Format.render"
"Jason.encode!"
```
`mix reach.check --arch` reports `forbidden_call` violations with caller module, call, file, and line evidence.
### `effects[:allowed]`
Limit side-effect classes for matching modules.
```elixir
effects: [
allowed: [
{"MyApp.Pure.*", [:pure, :unknown]},
{"MyAppWeb.*", [:pure, :read, :write, :send, :io, :unknown]}
]
]
```
Known effect atoms include:
- `:pure`
- `:io`
- `:read`
- `:write`
- `:send`
- `:receive`
- `:exception`
- `:nif`
- `:unknown`
Use this for architectural boundaries, not style linting. For example, keeping parsers or pure domain modules free from writes is a good fit; replacing Credo rules is not.
### `boundaries[:public]`
Declare top-level public modules that callers should use as boundaries.
```elixir
boundaries: [
public: [
"MyApp.Accounts",
"MyApp.Billing"
]
]
```
If a caller reaches into another module under the same namespace instead of going through the declared public API, `mix reach.check --arch` may report a `public_api_boundary` violation.
### `boundaries[:internal]`
Declare modules that should be treated as internal implementation details.
```elixir
boundaries: [
internal: [
"MyApp.Accounts.Internal.*",
"MyApp.Billing.Calculators.*"
]
]
```
Calls into these modules from outside approved callers produce `internal_boundary` violations.
### `boundaries[:internal_callers]`
Allow specific callers to reach specific internal modules.
```elixir
boundaries: [
internal_callers: [
{"MyApp.Accounts.Internal.*", ["MyApp.Accounts", "MyApp.Accounts.*"]}
]
]
```
Use this to make policy precise instead of making internal modules public.
### `risk[:changed]`
Tune changed-code risk thresholds used by `mix reach.check --changed`.
```elixir
risk: [
changed: [
many_direct_callers: 5,
wide_transitive_callers: 10,
branch_heavy: 8,
high_risk_reason_count: 3
]
]
```
These thresholds control when a changed function is marked with risk reasons such as `many direct callers`, `wide transitive impact`, and `branch-heavy function`.
### `candidates[:thresholds]` and `candidates[:limits]`
Tune advisory refactoring candidate generation used by `mix reach.check --candidates` and `mix reach.inspect TARGET --candidates`.
```elixir
candidates: [
thresholds: [
mixed_effect_count: 2,
branchy_function_branches: 8,
high_risk_direct_callers: 4
],
limits: [
per_kind: 20,
representative_calls: 10,
representative_calls_per_edge: 3
]
]
```
Thresholds decide when Reach reports mixed-effect and branch-heavy extraction candidates. Limits bound candidate evidence and per-kind generation while preserving exact cycle-component detection.
### `clone_analysis`
Configure optional structural clone evidence. Reach uses clone evidence to raise confidence or find consistency drift in semantic checks; it does not emit an `ex_dna` smell by itself.
```elixir
clone_analysis: [
provider: :ex_dna,
min_mass: 30,
min_similarity: 1.0,
max_clones: 50
]
smells: [
fixed_shape_map: [
min_keys: 3,
min_occurrences: 3,
evidence_limit: 10
],
behaviour_candidate: [
min_modules: 3,
min_callbacks: 3,
module_display_limit: 8,
callback_display_limit: 8
]
]
```
Reach runs ExDNA when the package is available; package consumers can disable clone evidence with `provider: false` or tune clone mass/similarity when needed.
### `smells[:fixed_shape_map]` and `smells[:behaviour_candidate]`
Use smell-specific thresholds when a codebase intentionally uses small map contracts, when you want stronger pressure toward structs/contracts, or when behaviour-candidate hints are too noisy for small module families.
### `tests[:hints]`
Suggest tests for changed paths.
```elixir
tests: [
hints: [
{"lib/my_app/accounts/**", ["test/my_app/accounts_test.exs"]},
{"lib/my_app_web/live/**", ["test/my_app_web/live"]}
]
]
```
`mix reach.check --changed` combines these hints with nearby test paths and caller impact data.
## Compatibility aliases
Reach accepts the previous flat keys as compatibility aliases, but new configs should use the grouped form.
| Preferred | Compatibility alias |
| --- | --- |
| `deps[:forbidden]` | `forbidden_deps` |
| `calls[:forbidden]` | `forbidden_calls` |
| `effects[:allowed]` | `allowed_effects` |
| `boundaries[:public]` | `public_api` |
| `boundaries[:internal]` | `internal` |
| `boundaries[:internal_callers]` | `internal_callers` |
| `tests[:hints]` | `test_hints` |
| `source[:forbidden_modules]` | `forbidden_modules` |
| `source[:forbidden_files]` | `forbidden_files` |
## Validation
Reach validates `.reach.exs` shape and reports `config_error` entries for:
- unknown top-level or grouped keys
- invalid `layers`
- invalid `deps[:forbidden]`
- invalid `source[:forbidden_modules]`
- invalid `source[:forbidden_files]`
- invalid `calls[:forbidden]`
- invalid `effects[:allowed]`
- invalid `boundaries[:public]`
- invalid `boundaries[:internal]`
- invalid `boundaries[:internal_callers]`
- invalid `risk[:changed]` thresholds
- invalid `candidates[:thresholds]`
- invalid `candidates[:limits]`
- invalid `smells[:fixed_shape_map]`
- invalid `smells[:behaviour_candidate]`
- invalid `clone_analysis`
- invalid `tests[:hints]`
## Practical guidance
Start permissive and tighten gradually:
1. Define broad layers.
2. Add only the forbidden dependencies you are confident about.
3. Add boundary policies for namespaces with clear public/internal modules.
4. Add effect policies for modules that should stay pure or effect-limited.
5. Tune `risk[:changed]`, `candidates`, and `smells` thresholds to match your repository size and tolerance for advisory output.
6. Run `mix reach.check --arch --format json` in CI once the policy is stable.
Refactoring candidates are advisory. They include `confidence`, `actionability`, and `proof` fields. Treat those fields as preconditions for editing, especially for cycle and extraction candidates.
