john-slop/AGENTS.md

249 lines
12 KiB
Markdown

# John Slop contributor guide
## Mission and product boundaries
John Slop is a transparent, local-first heuristic linter for low-effort or
insufficiently reviewed text and source code. It reports concrete signals that
are often associated with careless AI-assisted work. It must not claim to prove
that a person used AI, identify a model, or infer authorship from writing style.
Treat a score as **confidence that configured signals are present**, not as the
probability that content is AI-generated. User-facing language must say
"suspicious", "low-care signal", or "needs review" rather than making an
accusation. A result must always be explainable from the findings that produced
it.
The initial formatter and LSP scope is deliberately narrow: detect configured
Unicode characters that have safe ASCII replacements, expose those replacements
as edits, and reuse the same library implementation in every binary. Do not add
prose rewriting, generative inference, or destructive archive editing without a
separate design decision.
## Required architecture
Keep domain logic in a library and binaries as thin adapters. The intended
layout is:
```text
src/
lib.rs public library facade
config.rs typed loading, validation, and provenance
diagnostic.rs miette conversion and presentation-neutral spans
input/ files, directories, archives, and ignore policy
detection/ engine, score aggregation, and rule implementations
replacement.rs pure replacement/edit generation
bin/
john-slop.rs command-line detector
john-slop-fmt.rs replacement formatter
john-slop-lsp.rs stdio language server
assets/
config.toml embedded replacement defaults
heuristics.toml embedded detection rules
tests/
fixtures/ small, reviewed input/output fixtures
```
Names can evolve when Rust conventions demand it, but preserve these boundaries:
- `input` acquires text and never scores or changes it.
- `detection` is pure over text plus validated rules.
- `replacement` returns non-overlapping edits and does no I/O.
- `diagnostic` renders findings but does not discover them.
- the CLI, formatter, and LSP call the same config, detector, and replacement APIs.
- filesystem writes are confined to explicit adapter methods.
Do not retain the current all-files-in-memory iterator design as the core API.
Prefer a streaming iterator of per-file results so one unreadable or binary file
does not erase findings from unrelated files. Preserve the outer archive path and
inner member name as separate fields. Reject unsafe archive paths and apply size,
entry-count, and nesting limits before extraction or decompression.
## Core data contracts
Use typed, presentation-neutral domain values. The exact names may change, but
the model must express at least:
```rust
struct Finding {
rule_id: RuleId,
category: Category,
message: String,
help: Option<String>,
byte_span: Range<usize>,
matched_text: String,
weight: f64,
fix: Option<TextEdit>,
}
struct Analysis {
findings: Vec<Finding>,
confidence: Confidence,
}
struct TextEdit {
byte_span: Range<usize>,
replacement: String,
}
```
All internal spans are zero-based UTF-8 byte ranges into the exact source
snapshot that was analyzed. Validate boundaries before slicing. Convert spans at
the edge: `miette::SourceSpan` for terminal output and UTF-16 line/column ranges
for LSP. Keep an indexed line map per document so LSP conversions are tested and
not repeatedly O(n).
Rule IDs are stable, unique, lowercase kebab-case identifiers. Findings are
sorted by source identity, span start, then rule ID so output is deterministic.
Never use a hash-map iteration order as output order.
## Heuristics and confidence
Store data-driven heuristic definitions in `assets/heuristics.toml`, separately
from replacement configuration. Compile and validate rules once at startup.
Invalid regular expressions, duplicate IDs, negative/non-finite weights, invalid
thresholds, and unsafe empty matches are configuration errors—not ignored rules.
Each rule needs an ID, category, rationale/message, help text, matcher type,
weight, and optional applicability filters such as prose/source-code extensions.
Start with high-precision, independently testable signals:
- copied assistant disclaimers or knowledge-cutoff phrases;
- prompt/response scaffolding accidentally left in a document;
- templated filler and repeated conclusion/transition phrases;
- suspicious Unicode/confusable punctuation when the configured corpus expects
ASCII;
- source-code placeholders, tutorial residue, fabricated references, or comments
that merely narrate obvious code, using conservative language-specific rules.
Avoid weak demographic, dialect, spelling, grammar, vocabulary, or
English-fluency proxies. Repetition alone must not trigger a high-confidence
verdict. Give users a per-rule disable/weight override and path/language scopes.
Scoring must be documented and deterministic. Use bounded weighted evidence,
apply a per-rule occurrence cap, and damp correlated findings from the same rule
or family. Map the aggregate onto `0..=100` and named bands such as `low`,
`medium`, and `high`; keep thresholds configurable. Tests must pin the formula,
caps, threshold edges, and empty-input result. Never label the numeric result an
accuracy or probability unless it has been independently calibrated against a
published, representative corpus.
Every terminal finding must become a `miette::Diagnostic` with named source,
precise label, stable diagnostic code (the rule ID), severity, message, and help.
A summary score supplements findings; it never replaces their evidence. Machine
output must offer a versioned JSON schema and must not include ANSI escapes.
## Configuration contract
Use `figment` with its TOML support and Serde for typed layered configuration.
Its providers allow embedded serialized defaults and later TOML providers to
override individual values while retaining source metadata for useful errors.
Use `directories` (or an equivalent platform-aware crate) to resolve the user
configuration directory; do not hand-build it from `HOME`.
The precedence from lowest to highest is:
1. embedded `assets/config.toml` and `assets/heuristics.toml`;
2. user base config at `$XDG_CONFIG_HOME/john_slop/config.toml`, conventionally
`~/.config/john_slop/config.toml` on Linux;
3. named user config at `$XDG_CONFIG_HOME/john_slop/<config_name>.toml` when a
validated config name is selected;
4. an explicit `--config <path>` file;
5. explicit CLI flags for the current invocation.
Missing optional files are allowed; malformed files are fatal and identify their
origin. A config name accepts only ASCII letters, digits, `_`, and `-`; it cannot
contain separators, `.` segments, or an extension. Decide array behavior per
field: replacement/rule tables merge by stable ID, while ignore globs and file
extensions replace as complete arrays unless the schema explicitly says
otherwise. Do not rely on a library's default array-merge semantics implicitly.
`assets/config.toml` is the canonical, documented replacement catalog. Each
entry has an ID, Unicode source string/code point, ASCII replacement, rationale,
and enabled flag. Reject duplicate sources, empty sources, non-ASCII targets,
and conflicting edits. Longer sources win matching precedence. Provide a command
that prints the resolved configuration with secrets/redacted fields if secrets
are ever introduced.
Configuration schema changes require a `schema_version`, migration notes, and
tests for precedence. Embed assets with `include_str!` so installed binaries do
not depend on the source tree or current working directory.
## CLI, formatter, and LSP behavior
Use explicit Cargo binaries named `john-slop`, `john-slop-fmt`, and
`john-slop-lsp`.
- The detector reads files/directories/stdin, reports findings, and exits `0`
below the selected threshold, `1` when findings cross it, and `2` for usage or
operational/configuration errors.
- The formatter supports stdin/stdout, `--check`, and an explicit `--write`.
Default behavior must not rewrite a file. Writes must be atomic where the
platform permits, preserve original bytes when no edit applies, preserve line
endings, and be idempotent.
- The LSP communicates only over stdin/stdout; logs go to stderr. Initially it
publishes replacement diagnostics and exposes quick-fix/code-action edits for
open documents. It must honor document versions, clear diagnostics on close,
handle invalid URIs without panicking, and never write editor-owned files.
Replacement edits are generated from the original snapshot, sorted, checked for
overlap, then applied from the end of the buffer toward the beginning. The
formatter and LSP must produce byte-for-byte equivalent results for the same
source and resolved config.
## Errors, safety, and observability
- Libraries return typed errors with `thiserror`; application boundaries attach
path/rule context and render with `miette`.
- Do not use `unwrap`, `expect`, `panic!`, `todo!`, or `unreachable!` on
user-controlled input. An `expect` is acceptable only for an invariant proved
during construction and explained in a comment.
- Treat invalid UTF-8 and binary content as explicit skipped-input diagnostics
according to policy; do not silently truncate or lossily rewrite it.
- Do not follow symlinks by default. Respect ignore configuration and establish
file-size, archive-size, archive-entry, and recursion limits.
- Do not make network calls during analysis. Results should be reproducible and
private by default.
- Structured logs go to stderr and are disabled or quiet by default. Never mix
logs with JSON, formatter stdout, or the LSP protocol stream.
## Testing and quality gates
Each behavior change requires tests at the lowest useful layer plus an
integration test when it crosses a binary boundary. Include positive,
near-miss/negative, Unicode, empty, large-input, malformed-config, and ordering
cases. Regression fixtures must state why they should or should not match.
Before considering a task complete, run:
```text
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets --all-features
cargo doc --no-deps
```
Also run focused CLI golden tests and LSP protocol tests once those binaries
exist. Favor property tests for replacement idempotence/non-overlap and fuzz
targets for config parsing, span conversion, archives, and replacement planning.
Benchmarks should cover a representative large document and directory; optimize
only from measured results.
## Change discipline
Keep commits and patches small enough to review. Do not combine a structural
move with new detection behavior unless the new behavior requires it. Preserve
public behavior during refactors or document the deliberate break. Update sample
configuration, schema/version notes, CLI help, and tests together.
When implementing `tasks.md`, work in dependency order, mark only verified items
complete, and add newly discovered work under the relevant milestone. Record a
short decision note in the task file when changing configuration precedence,
the score formula, a public data contract, or safety limits.
After completing and verifying each individual task, create a dedicated commit
before starting the next task. Stage only the files that belong to that task;
never include unrelated or pre-existing user changes. Use a concise conventional
commit message that describes the completed behavior. If a task cannot be
verified or committed, leave it unchecked and report the blocker instead of
combining it with later work.