docs: record core analysis contracts

This commit is contained in:
Dandaedre 2026-09-29 12:10:54 +02:00
parent 4d142d60ed
commit 7b5e6b330f
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
3 changed files with 59 additions and 1 deletions

View File

@ -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

View File

@ -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.

View File

@ -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