98 lines
4.0 KiB
Markdown
98 lines
4.0 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 [`config.toml`](../crates/john-slop-core/assets/config.toml) and
|
|
[`heuristics.toml`](../crates/john-slop-core/assets/heuristics.toml).
|
|
Ready-to-copy, commented partial layers live in
|
|
[`examples/config`](../examples/config/): `config.toml` demonstrates a user-wide
|
|
base and `editorial.toml` demonstrates a named overlay.
|
|
|
|
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.
|
|
|
|
The built-in matcher names are `exact-phrase`, `regex`, `repeated-regex`,
|
|
`replacement`, `confusable`, and `invisible`. The last three use validated
|
|
sentinel patterns because their implementations are data-backed rather than
|
|
free-form strings: `configured-replacements`, `uts39-ascii-skeleton-v16`, and
|
|
`gitea-invisible-9c715c0`. They remain ordinary rule records, so later layers
|
|
can disable them or adjust severity, weight, occurrence cap, and scope without
|
|
changing code. Confusable and invisible findings never authorize edits.
|
|
|
|
Set `enabled = false` on a known rule or replacement ID to disable it. Because
|
|
records merge by ID, do not copy the full embedded table merely to change one
|
|
field; a later partial record preserves every unspecified value.
|
|
|
|
Replacement `source` values are non-empty Unicode strings containing at least
|
|
one non-ASCII byte; `replacement` values are non-empty ASCII strings. Sources
|
|
must be unique. When enabled sources share a prefix, the longest matching source
|
|
wins at each byte offset, with stable rule ID ordering as the deterministic
|
|
tie-break. Edits always refer to the original UTF-8 snapshot.
|
|
|
|
Each heuristic also configures `severity` as `advice`, `warning`, or `error`.
|
|
Severity controls CLI presentation, LSP severity, and summary counts; the
|
|
evidence score still comes from the independently configured weight and
|
|
aggregation formula. In the LSP, advice is information while warnings and errors
|
|
retain their corresponding levels.
|
|
|
|
## 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.
|