# 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, byte_span: Range, matched_text: String, weight: f64, fix: Option, } struct Analysis { findings: Vec, confidence: Confidence, } struct TextEdit { byte_span: Range, 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/.toml` when a validated config name is selected; 4. an explicit `--config ` 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 test --all-targets --no-default-features cargo doc --no-deps ``` Run `cargo tarpaulin --config tarpaulin.toml` when tests or executable Rust code change. It enforces the intentionally modest 30% line-coverage floor. Refresh the tracked local badges with `rust_autobadges --high-coverage-percent 0.7 --mid-coverage-percent 0.3` after a clean test and coverage run. 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. After every milestone's acceptance criteria and quality gates pass, create an annotated Git tag named `milestone-N` on its completion commit. Never move an existing milestone tag; add a corrective commit and a documented successor tag if a published milestone needs amendment.