john-slop/docs/configuration.md

66 lines
2.1 KiB
Markdown

# Configuration
John Slop embeds schema-versioned replacement and heuristic catalogs in every
binary. Installed binaries therefore work without a source checkout or external
default files.
## Precedence
Configuration layers are applied from lowest to highest priority:
1. embedded `assets/config.toml` and `assets/heuristics.toml`;
2. the platform user file `config.toml`;
3. a selected user `<config_name>.toml`;
4. an explicit `--config <FILE>`;
5. configuration flags for the current invocation.
On Linux, the user directory conventionally resolves to
`~/.config/john_slop`. John Slop uses operating-system APIs rather than reading
`HOME` directly, so Windows and macOS receive their native application config
directories. Run this to inspect the exact paths on the current machine:
```sh
john-slop config paths
```
Named configurations accept only ASCII letters, digits, `_`, and `-`. Do not
include a directory, dot component, or `.toml` extension. Missing user and named
files are optional; a selected explicit file must exist.
## Schema
The current `schema_version` is `1`. The complete defaults and documented record
examples live in [`assets/config.toml`](../assets/config.toml) and
[`assets/heuristics.toml`](../assets/heuristics.toml).
Replacement and heuristic arrays merge by stable `id`. A partial record changes
only the supplied fields:
```toml
[[replacements]]
id = "em-dash"
enabled = false
[[rules]]
id = "templated-conclusion"
weight = 2.5
```
A new ID must provide every field. Scope extension arrays replace the prior
array as a whole. Unknown keys, malformed TOML, duplicate IDs within one layer,
invalid regular expressions, unsafe matchers, non-ASCII replacement targets,
and invalid thresholds are fatal configuration diagnostics.
## Inspection
Print the fully layered and validated model as deterministic TOML:
```sh
john-slop config show
john-slop config show --config project.toml
john-slop config show --config-name strict
```
The output contains no secrets in schema version 1. If secret-bearing fields are
introduced later, inspection output must redact them by default.