80 lines
2.6 KiB
Markdown
80 lines
2.6 KiB
Markdown
# Detector output contracts
|
|
|
|
The detector exposes three formats through `--output`. All formats preserve the
|
|
same deterministic document and finding order. Requested paths retain command
|
|
line order, directory entries are sorted by filename, archive order follows the
|
|
container, and findings are sorted by byte span and rule ID.
|
|
|
|
## Human
|
|
|
|
`--output human` is the default. Every finding is rendered as a plain
|
|
`miette` diagnostic with the source name, exact excerpt and primary span,
|
|
severity, stable rule code, message, and remediation help. A final line per
|
|
document reports the confidence score/band and advice, warning, and error
|
|
counts. The narratable renderer deliberately avoids ANSI escapes.
|
|
|
|
## Concise
|
|
|
|
`--output concise` emits one line per finding followed by one summary line. A
|
|
finding line contains the source identity, half-open UTF-8 byte range, severity,
|
|
rule ID, and message. Recoverable input errors go to stderr in human and concise
|
|
modes.
|
|
|
|
## JSON Lines schema version 1
|
|
|
|
`--output json` emits one compact JSON object per line. An analyzed document has
|
|
`kind: "analysis"` and this shape:
|
|
|
|
```json
|
|
{
|
|
"schema_version": 1,
|
|
"kind": "analysis",
|
|
"source": "article.md",
|
|
"summary": {
|
|
"confidence_score": 17,
|
|
"confidence_band": "below-threshold",
|
|
"advice": 1,
|
|
"warnings": 0,
|
|
"errors": 0,
|
|
"total": 1
|
|
},
|
|
"findings": [
|
|
{
|
|
"rule_id": "typography-non-ascii-hyphen",
|
|
"category": "typography",
|
|
"severity": "advice",
|
|
"message": "a configured non-ASCII character has an ASCII replacement",
|
|
"help": "Review the punctuation or apply the configured safe replacement.",
|
|
"byte_span": { "start": 8, "end": 11 },
|
|
"matched_text": "—",
|
|
"weight": 10.0,
|
|
"fix": {
|
|
"byte_span": { "start": 8, "end": 11 },
|
|
"replacement": "-"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
`confidence_band` is `null` when there is no evidence. Spans are zero-based,
|
|
half-open UTF-8 byte offsets into the exact source snapshot, not character or
|
|
UTF-16 positions. `fix` is `null` for findings without a safe configured edit.
|
|
|
|
A recoverable input failure has `kind: "input-error"`:
|
|
|
|
```json
|
|
{
|
|
"schema_version": 1,
|
|
"kind": "input-error",
|
|
"source": "broken.txt",
|
|
"message": "input broken.txt is not valid UTF-8"
|
|
}
|
|
```
|
|
|
|
JSON records are the only stdout content in JSON mode and never contain ANSI
|
|
escapes or logs. Fatal argument/configuration/setup failures can occur before
|
|
the JSON stream starts; they return status 2, leave stdout empty, and report on
|
|
stderr. Additive fields may appear within schema version 1; incompatible changes
|
|
require a new schema version.
|