2.6 KiB
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:
{
"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":
{
"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.