john-slop/docs/output.md

3.3 KiB

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:

{
  "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":

{
  "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.