john-slop/docs/configuration.md

8.2 KiB

Configuration

John Slop embeds schema-versioned base, heuristic, and Unicode 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 optional platform user diagnostic catalog diagnostics.toml, followed by explicitly selected diagnostic catalogs in declaration order;
  3. the platform user file config.toml;
  4. a selected user <config_name>.toml;
  5. an explicit --config <FILE>;
  6. configuration flags for the current invocation.

Diagnostic catalogs load before normal configuration so a base, named, or explicit configuration can tune or disable a catalog rule by stable ID. A catalog accepts only schema_version and [[rules]]; unrelated settings are a configuration error rather than being silently applied from the wrong file.

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.

Generate a project configuration

Create the embedded, commented base configuration as ./config.toml:

john-slop config init

The command refuses to overwrite an existing file. Use john-slop config init --force only when replacing that file is intentional. config generate is an alias for config init. Load a project-local file with john-slop --config config.toml path/to/input or inspect it with the command shown below.

Generate a dedicated runtime diagnostic catalog separately:

john-slop config init-diagnostics

Place the result at the user_diagnostics path printed by config paths for automatic loading, or select one or more project/team catalogs explicitly:

john-slop --diagnostics team.toml --diagnostics project.toml article.md
john-slop-lsp --diagnostics project.toml

Explicit catalogs are applied in command-line order. All catalogs load before config.toml, named configuration, and --config, allowing those normal layers to override their rules.

Schema

The current schema_version is 1. The complete defaults live in config.toml, heuristics.toml, and the generated unicode.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:

[diagnostics.categories]
# Disable every style diagnostic as one family.
style = false

[[replacements]]
id = "em-dash"
enabled = false

[[rules]]
id = "templated-conclusion"
# An individual rule switch is independent of the category switch.
enabled = false

The category keys are typography, style, prompt-leakage, and source-code. A diagnostic runs only when its category switch and its individual [[rules]] enabled field are both true. Consequently, enabling a category does not silently re-enable a rule that another layer disabled individually; set that rule's enabled = true explicitly when that is intended. Later files override earlier category values using the normal precedence above.

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, and invisible. The last two use validated sentinel patterns because their implementations are data-backed rather than free-form strings: configured-replacements 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. Invisible findings never authorize edits; generated confusable mappings follow the bulk policy below.

Runtime diagnostic catalog

diagnostics.toml supports new data-driven diagnostics without recompilation. Every new rule must provide the complete rule shape:

schema_version = 1

[[rules]]
id = "custom-review-marker"
category = "style"
severity = "warning"
matcher = "exact-phrase"
pattern = "REVIEW BEFORE PUBLISHING"
weight = 8.0
message = "a project review marker remains"
help = "Resolve or remove the marker before publishing."
occurrence_cap = 1
enabled = true
scope = { content = ["prose", "source-code"], extensions = [] }

Runtime rules may select exact-phrase, regex, or repeated-regex. replacement and invisible are code-backed catalog sentinels and cannot define new matching behavior. Categories remain the four stable values listed above. Unknown fields, invalid or empty-match regular expressions, duplicate IDs within one catalog, incomplete new rules, and missing explicit catalogs are fatal. These constraints keep startup deterministic and prevent a configuration file from executing code.

The generated UTS #39 mappings have one bulk policy:

[unicode]
confusables = "review" # replace (default), review, or off

replace enables diagnostics and edits, review retains diagnostics without formatter/LSP edits, and off suppresses generated lookalikes. The reviewed punctuation and width-folding replacements and invisible/control diagnostics are unaffected.

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.

Generated confusable IDs use uts39-u<lowercase-codepoint>. New fullwidth mappings use fullwidth-u<lowercase-codepoint>; mappings shipped previously retain their uts39-* or fullwidth-hyphen-minus IDs for compatibility, while ideographic space uses ideographic-space. Every entry can be disabled or overridden through normal merge-by-ID behavior. Maintain the embedded list by editing crates/john-slop-core/examples/generate_unicode_catalog.rs and running:

cargo run -p john-slop-core --example generate_unicode_catalog \
  > crates/john-slop-core/assets/unicode.toml

The exhaustive catalog test walks every Unicode scalar and rejects drift from the pinned Unicode 16.0 tables.

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.