From 7b5e6b330f435eb74aeaec4e7bd4b27fb955734d Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Tue, 29 Sep 2026 12:10:54 +0200 Subject: [PATCH] docs: record core analysis contracts --- README.md | 3 + .../decisions/0001-core-analysis-contracts.md | 55 +++++++++++++++++++ tasks.md | 2 +- 3 files changed, 59 insertions(+), 1 deletion(-) create mode 100644 docs/decisions/0001-core-analysis-contracts.md diff --git a/README.md b/README.md index 4c7a93d..4abf303 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,9 @@ The repository currently contains proof-of-concept code that: The implementation is being restructured into a reusable library plus detector, formatter, and LSP binaries. See [tasks.md](tasks.md) for the ordered backlog and [AGENTS.md](AGENTS.md) for the design and contribution rules. +Architecture and product choices are recorded under +[`docs/decisions`](docs/decisions/), beginning with the +[core analysis contracts](docs/decisions/0001-core-analysis-contracts.md). ## Development diff --git a/docs/decisions/0001-core-analysis-contracts.md b/docs/decisions/0001-core-analysis-contracts.md new file mode 100644 index 0000000..96cffc8 --- /dev/null +++ b/docs/decisions/0001-core-analysis-contracts.md @@ -0,0 +1,55 @@ +# ADR 0001: Core analysis contracts + +- Status: accepted +- Date: 2026-09-29 + +## Context + +John Slop needs stable semantics before its proof-of-concept modules are split +into a library, CLI, formatter, and language server. In particular, consumers +need to know what a confidence score means, how source locations are represented, +whether formatting is destructive by default, and whether archive members can +be rewritten. + +## Decision + +### Confidence represents evidence, not authorship + +The detector reports confidence that configured, observable low-care signals are +present. It does not report the probability that content is AI-generated and +must not present a score as an authorship determination. Every score must be +decomposable into source-labelled findings from stable rule IDs. + +### UTF-8 byte spans are canonical + +Internal source spans are zero-based, half-open UTF-8 byte ranges into the exact +source snapshot analyzed. This matches Rust string and regex offsets and avoids +lossy conversions inside the detection engine. Presentation adapters validate +boundaries and convert to their required representation: `miette::SourceSpan` +for terminal diagnostics and UTF-16 line/character positions for LSP. + +### Formatter writes are opt-in + +The formatter's default file behavior is read-only. It may print transformed +text or a diff, while an explicit `--write` is required to mutate files. +`--check` only reports whether an edit would be made. A failed analysis, +configuration load, or edit validation must leave the original file untouched. + +### Archive mutation is deferred + +The first formatter release may inspect text members in supported ZIP-based +containers, but it will not rewrite archives, DOCX, XLSX, or PPTX files. In-place +archive editing has additional integrity, metadata-preservation, atomicity, and +decompression-safety concerns. It requires a separate decision record and test +plan before implementation. + +## Consequences + +- User-facing terminology must describe evidence and request review rather than + accuse an author. +- The domain model stores byte ranges, while the LSP owns a tested UTF-16 mapping + layer tied to document versions. +- Replacement planning remains a pure operation; filesystem mutation lives in + an explicit formatter adapter. +- Archive inputs can produce findings but an attempted archive write produces a + clear unsupported-operation diagnostic. diff --git a/tasks.md b/tasks.md index bd4900f..45903b7 100644 --- a/tasks.md +++ b/tasks.md @@ -28,7 +28,7 @@ audit in CI. matching. - [x] Fix the misleading Unicode tests/comments (UTF-8 byte lengths and grapheme terminology) so test names reflect what is actually asserted. -- [ ] Record initial decisions in `docs/decisions/`: evidence confidence is not +- [x] Record initial decisions in `docs/decisions/`: evidence confidence is not authorship probability; UTF-8 byte spans are canonical; formatter writes are opt-in; no archive mutation in the first formatter release. - [ ] Define supported inputs and limits: extensions/MIME policy, maximum file