## vary.toml

Every Vary project can have a `vary.toml` file at its root. The compiler searches upward from the current directory to find it. If no config file exists, defaults are used for everything.

Create one with:

```bash
vary init
```

Or view the active configuration with:

```bash
vary config --verbose
```

## Minimal example

Most projects only need a few lines:

```toml
[project]
name = "my-app"
version = "0.1.0"

[source]
directories = ["src"]
test_directories = ["tests"]
```

## Full reference

### [project]

Project metadata. Used in build output and artifact naming.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `name` | Str | `"unnamed"` | Project name |
| `version` | Str | `"0.1.0"` | Version string (available as `__project_version__` in code) |
| `description` | Str | `""` | Short description |

### [source]

Where the compiler looks for `.vary` files.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `directories` | Array | `["src"]` | Source code directories |
| `test_directories` | Array | `["tests"]` | Test file directories |
| `excludes` | Array | `[]` | Patterns to skip during compilation |

`roots` is accepted as an alias for `directories`.

### [compiler]

Controls how code is compiled.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `target` | Str | `"17"` | JVM target version (e.g. `"17"`, `"21"`) |
| `stdlib` | Str | null | Custom path to stdlib (rarely needed) |
| `output_dir` | Str | `"build"` | Where compiled output goes |
| `warnings_as_errors` | Bool | `false` | Treat warnings as errors |
| `verbose` | Bool | `false` | Verbose compiler output |
| `optimization` | Int | `0` | Optimization level: 0 = none, 1 = basic, 2 = aggressive |
| `debug_info` | Bool | `true` | Include debug info in bytecode |
| `strict_null_checks` | Bool | `true` | Enforce null safety |

### [test]

Test execution settings.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `parallel` | Int | `1` | Number of parallel test runners |
| `coverage` | Bool | `false` | Enable coverage tracking |
| `coverage_threshold` | Int | `0` | Minimum coverage percentage (0 = no gate) |
| `timeout` | Int | `300` | Test timeout in seconds |

### [mutation]

Mutation testing settings used by `vary mutate`.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `operators` | Str | `"all"` | Which mutation operators to apply, comma-separated or `"all"` |
| `quick_limit` | Int | `20` | Maximum mutants in `--quick` mode |
| `timeout` | Int | `5000` | Per-mutant timeout in milliseconds |
| `report_format` | Str | `"text"` | Output format: `"text"`, `"html"`, or `"json"` |
| `report_dir` | Str | `"mutation-reports"` | Where reports are written |
| `min_score` | Float | `0.0` | Minimum mutation score (0-100), fails the run if not met |
| `fail_on_decrease` | Bool | `false` | Fail if mutation score dropped since last run |
| `max_survivors` | Int | unlimited | Maximum allowed surviving mutants |
| `pairing_mode` | Str | `"fallback_all_tests"` | How mutants are paired with tests: `"fallback_all_tests"` or `"strict"` |
| `emit_manifest` | Bool | `true` | Emit mutation manifest (`.vary/mutation-manifest.json`) during builds |
| `max_pure_survivors` | Int | unlimited | Maximum surviving mutants in `pure def` regions |
| `require_contracts_in_pure` | Bool | `false` | Require contracts on pure functions touched by mutants |
| `min_contract_kills` | Int | `0` | Minimum contract kills (PRE+POST+INVARIANT) required |
| `min_contract_adequacy` | Float | `0.0` | Minimum contract adequacy score (0-100) |
| `allow_no_oracle_tests` | Bool | `false` | Allow tests without oracles (otherwise warned/errored) |
| `min_integrity` | Float | `0.0` | Minimum integrity score gate (0-100) |

### [validate]

Settings for `vary validate`.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `contracts` | Bool | `false` | Enable structured contract violation reporting in test output |

When `contracts` is `true`, contract violations detected during test execution are reported in a structured block showing the violation kind, function name, source location, and failing expression.

### [format]

Code formatting settings used by `vary fmt`.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `indent_size` | Int | `4` | Spaces per indent level |
| `max_line_length` | Int | `100` | Maximum line length |
| `use_spaces` | Bool | `true` | Spaces instead of tabs |
| `trailing_newline` | Bool | `true` | Ensure files end with a newline |
| `sort_imports` | Bool | `true` | Sort and group import statements |

### [cache]

Controls the content-addressed artifact cache in `.vary/artifacts/`.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | Bool | `true` | Enable caching |
| `directory` | Str | `".vary/artifacts"` | Cache directory path |
| `max_size_mb` | Int | `500` | Maximum cache size in MB |
| `max_age_days` | Int | `30` | Evict artifacts older than this |
| `eviction_policy` | Str | `"lru"` | `"lru"` (least recently used), `"lfu"` (least frequently used), or `"none"` |
| `auto_gc` | Bool | `true` | Run garbage collection automatically |
| `validate_on_load` | Bool | `true` | Validate artifacts before using them |

### [check]

Settings for `vary check` diagnostics.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `profile` | Str | `"local"` | Check profile: `"local"` (default) or `"ci"` (JSON output, warnings as errors) |
| `warnings` | Str | `"all"` | Warning mode: `"all"`, `"none"`, or `"error"` |

#### [check.analysis]

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `broad_effects_threshold` | Int | `3` | Warn if a function produces more than this many distinct effect classes |

#### [check.effects]

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `deny` | Array | `[]` | Effect classes to forbid (e.g. `["PROCESS", "NETWORK"]`). Functions producing denied effects are flagged as errors. |

Available effect classes: `IO`, `NETWORK`, `FILESYSTEM`, `PROCESS`, `STATE`, `CONCURRENCY`, `TIME`, `RANDOM`.

### [lsp]

Language server configuration.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | Bool | `true` | Enable the LSP server |
| `port` | Int | `0` | TCP port (0 = use stdio mode) |
| `log_file` | Str | null | Optional path for LSP logs |

### [services]

Network host restrictions for `service` declarations (typed HTTP clients).

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `allowed_hosts` | Array | `[]` | Hosts the project may connect to (empty = all allowed) |
| `denied_hosts` | Array | `[]` | Hosts explicitly blocked |

Host patterns support wildcard subdomains: `*.example.com` matches `api.example.com` and `foo.bar.example.com`.

```toml
[services]
allowed_hosts = ["api.example.com", "*.internal.example.com"]
denied_hosts = ["untrusted.com"]
```

When `allowed_hosts` is non-empty, any service targeting a host not in the list is flagged by `VCS008`. Hosts in `denied_hosts` are always blocked.

### [profiles.*]

Custom validation profiles for `vary validate --profile <name>`. Each profile defines which checks to run and their thresholds.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `checks` | Array | `[]` | Stages to run (e.g., `"check"`, `"test"`, `"mutation"`) |
| `timeout` | Int | `300` | Timeout in seconds |

Thresholds are nested under `[profiles.<name>.thresholds]`:

```toml
[profiles.local]
checks = ["check", "test"]

[profiles.local.thresholds]
coverage = 70

[profiles.ci]
checks = ["check", "test", "mutation"]

[profiles.ci.thresholds]
coverage = 80
mutation = 80

[profiles.nightly]
checks = ["check", "test", "mutation"]
timeout = 600

[profiles.nightly.thresholds]
coverage = 90
mutation = 90
```

### [dependencies]

Dependencies use a different format from other sections. Each dependency is a key-value pair where the key is the dependency name:

```toml
[dependencies]
my-lib = "1.0.0"
local-lib = { version = "2.0.0", path = "./libs/local-lib" }
```

The `path` form points to a local directory containing another Vary project with its own `vary.toml`.

## Bigger example

A project that gates on mutation score and runs tests in parallel:

```toml
[project]
name = "my-api"
version = "0.2.0"
description = "Order management API"

[source]
directories = ["src"]
test_directories = ["tests"]
excludes = ["src/scratch"]

[compiler]
target = "21"
warnings_as_errors = true
optimization = 1

[test]
parallel = 4
timeout = 60

[mutation]
min_score = 75.0
fail_on_decrease = true
max_survivors = 10
timeout = 3000

[validate]
contracts = true

[cache]
max_size_mb = 200
max_age_days = 7
```