205 lines
8.0 KiB
Markdown
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.
|