john-slop/docs/configuration.md

2.4 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:

  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:

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 and assets/heuristics.toml.

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.

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.