94 lines
3.3 KiB
Markdown
94 lines
3.3 KiB
Markdown
# Detector output contracts
|
|
|
|
The detector exposes four 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` renders every finding 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 low-care
|
|
evidence score/band and advice, warning, and error counts. The narratable renderer
|
|
deliberately avoids ANSI escapes.
|
|
|
|
## Miette
|
|
|
|
`--output miette` is the default. It renders the same typed diagnostics with
|
|
Miette's graphical Unicode source annotations and ANSI severity colors,
|
|
followed by the same summary. Each diagnostic starts with a `◆`-marked rule-code
|
|
title immediately followed by its severity/message, and ends with an empty line
|
|
that separates it from the next diagnostic or summary. This mode requires the
|
|
default `fancy-diagnostics` Cargo feature; builds made with
|
|
`--no-default-features`
|
|
accept the option but fall back to the plain human renderer. Select `human`,
|
|
`concise`, or `json` when ANSI escapes are not appropriate.
|
|
|
|
## 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 2
|
|
|
|
`--output json` emits one compact JSON object per line. An analyzed document has
|
|
`kind: "analysis"` and this shape:
|
|
|
|
```json
|
|
{
|
|
"schema_version": 2,
|
|
"kind": "analysis",
|
|
"source": "article.md",
|
|
"summary": {
|
|
"evidence_score": 17,
|
|
"evidence_band": "below-threshold",
|
|
"advice": 1,
|
|
"warnings": 0,
|
|
"errors": 0,
|
|
"total": 1
|
|
},
|
|
"findings": [
|
|
{
|
|
"rule_id": "unicode-ascii-replacement",
|
|
"category": "typography",
|
|
"severity": "advice",
|
|
"message": "a Unicode character or sequence has a configured ASCII replacement",
|
|
"help": "Review the character or apply the configured ASCII replacement.",
|
|
"byte_span": { "start": 8, "end": 11 },
|
|
"matched_text": "—",
|
|
"weight": 10.0,
|
|
"fix": {
|
|
"byte_span": { "start": 8, "end": 11 },
|
|
"replacement": "-"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
`evidence_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": 2,
|
|
"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 2; incompatible changes
|
|
require a new schema version. Schema version 2 renamed the version 1 summary
|
|
fields `confidence_score` and `confidence_band` to `evidence_score` and
|
|
`evidence_band`; version 1 records are no longer emitted.
|