john-slop/docs/configuration.md

75 lines
2.6 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 arrays replace the prior array as a
whole. A rule scope can select `prose` or `source-code`, restrict lowercase
extensions, and use `include`/`exclude` path globs. The `skip_generated`,
`skip_vendor`, and `skip_minified` switches default to `true`; set one to
`false` only when those paths are intentionally in scope. Archive rules match
the inner member path. Unknown keys, malformed TOML, duplicate IDs within one
layer, invalid regular expressions or globs, unsafe matchers, non-ASCII
replacement targets, and invalid thresholds are fatal configuration
diagnostics.
Each heuristic also configures `severity` as `advice`, `warning`, or `error`.
Severity controls diagnostic presentation and summary counts; confidence still
comes from the independently configured weight and evidence formula.
## 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.