docs: record core analysis contracts
This commit is contained in:
parent
4d142d60ed
commit
7b5e6b330f
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
2
tasks.md
2
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
|
||||
|
|
|
|||
Loading…
Reference in New Issue