john-slop/docs/configuration.md

205 lines
8.0 KiB
Markdown

# 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:
```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.
## Generate a project configuration
Create the embedded, commented base configuration as `./config.toml`:
```sh
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:
```sh
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:
```sh
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`](../crates/john-slop-core/assets/config.toml),
[`heuristics.toml`](../crates/john-slop-core/assets/heuristics.toml), and the
generated [`unicode.toml`](../crates/john-slop-core/assets/unicode.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
[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:
```toml
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:
```toml
[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 ten curated
punctuation 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 mapping IDs use `uts39-u<lowercase-codepoint>`, so an individual
entry can still 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:
```sh
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:
```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.