Documentation
¶
Overview ¶
Package render formats check findings for stdout — either as human-readable text (default) or as a structured JSON envelope (--format=json).
JSON envelope contract ¶
Every aiwf invocation that emits JSON writes a single object with these slots:
tool // always "aiwf"
version // the binary's reported version
status // "ok" | "findings" | "error" — overall outcome
findings // []Finding — validation outcomes, cross-cutting; may
// be present on any verb that runs the validators.
// Empty when the run produced none.
result // verb-specific payload. Different shape per verb:
// - check → omitted (findings is the result)
// - history → { id, events: [...] }
// - future verbs → their own shape
metadata // counts, timing, root path, correlation_id when
// present — auxiliary data, not load-bearing
findings vs result is the load-bearing distinction: findings is always the same shape across verbs (so a CI script can grep one thing), result is whatever the verb returns (so each verb can model its own output without compromise). Downstream tooling that touches both reads findings the same way everywhere and switches on the verb name to interpret result.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func JSON ¶
JSON writes the envelope to w as a single JSON object. Pretty enables indented output for human reading; the default (non-indented) is what CI and downstream tooling consume.
func StatusFor ¶
StatusFor returns the canonical envelope status string for a given findings list. "ok" if empty, "findings" if anything was reported. Internal-error envelopes are constructed directly by callers.
func Text ¶
Text writes one finding per line in linter-style format:
{path}:{line}: {severity} {code}[/{subcode}]: {message} — hint: {hint}
followed by a one-line summary. The `:line` is omitted when the finding has no line (load-errors that fail before parsing). The `— hint: ...` suffix is omitted when the finding has no hint. Findings without a path are still rendered (the path:line prefix is dropped but the rest of the line is unchanged).
func TextSummary ¶ added in v0.8.0
TextSummary writes the default-mode text rendering of findings used by `aiwf check` (without --verbose). Errors are rendered per instance — identical to the full per-instance shape produced by Text — because each error is per-instance-actionable. Warnings are collapsed into a per-code summary:
<code> (warning) × N — <representative message>
where N is the count of findings sharing that Code and the representative message is the Message of the first finding in the input slice with that code (per M-0089 *Constraints*: "the first finding's Message field, verbatim").
Summary lines are sorted by count descending, with ties broken alphabetically by code (also pinned in *Constraints* — pinned here so the golden files in the test suite don't drift).
The footer line ("N findings (E errors, W warnings)") is unchanged and reflects raw instance counts, not summary-line counts.
Types ¶
type Envelope ¶
type Envelope struct {
Tool string `json:"tool"`
Version string `json:"version"`
Status string `json:"status"`
Findings []check.Finding `json:"findings"`
Result any `json:"result,omitempty"`
Metadata map[string]any `json:"metadata,omitempty"`
}
Envelope is the JSON shape every aiwf invocation writes when invoked with --format=json. Status is one of "ok", "findings", "error". Result carries the verb's payload (nil for `aiwf check`). Metadata carries timing, counts, correlation_id, etc.
Source Files