4.0 KiB
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:
- embedded
assets/config.tomlandassets/heuristics.toml; - the platform user file
config.toml; - a selected user
<config_name>.toml; - an explicit
--config <FILE>; - 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:
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 and
heuristics.toml.
Ready-to-copy, commented partial layers live in
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:
[[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:
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.