Documentation
¶
Index ¶
- Constants
- func Cards(w io.Writer, p Payload) error
- func CountFiles(findings []Finding) int
- func JSON(w io.Writer, p Payload) error
- func Markdown(w io.Writer, p Payload) error
- func TemplateFuncs() template.FuncMap
- func Terminal(w io.Writer, p Payload) error
- func ValidateOutputTemplate(content string) error
- func VerboseFooter(m Meta) string
- type Finding
- type Format
- type Meta
- type Payload
- type Severity
- type SeverityGroup
- type Summary
- type TemplateData
Constants ¶
const SchemaVersion = 1
SchemaVersion is the integer in the "schema" field of every JSON document we emit. Consumers should refuse to parse if SchemaVersion is higher than what they expect.
Versioning policy (see docs/json-schema.md):
- v1 (current): top-level shape locked at {schema, content, findings, summary, meta}. `findings` is populated from the parsed LLM response under ADR-0014. `summary` and `content` remain in the schema for backwards compatibility:
- `content` is populated only on graceful degrade (LLM produced unparseable output); empty on the happy path.
- `summary` is reserved for a future LLM-authored prose summary; v1 always emits it as `{}`.
- Additive changes (new optional fields in `meta`, new keys in `summary`, new fields on a Finding) are NOT a version bump. Consumers MUST ignore unknown fields.
- Renaming, removing, or changing the type of any documented field IS a breaking change and requires bumping SchemaVersion to 2.
Variables ¶
This section is empty.
Functions ¶
func Cards ¶ added in v0.6.0
Cards is the rich terminal renderer that frames the review with a styled header, a pre-body status line, one bordered panel per finding (severity- colored), and a one-line summary footer. It is the default Format when stdout is a TTY and neither --markdown nor --json is set.
Under ADR-0014 the LLM emits a JSON document parsed into Payload.Findings before render. If Findings is nil (graceful degrade — parse failed) the renderer falls back to a Stage A glamour-rendered body of Payload.Content so the user still sees something rather than a stack trace. Color resolution is delegated to lipgloss; NO_COLOR=1 and non-TTY stdout both downgrade automatically.
func CountFiles ¶ added in v0.6.0
CountFiles returns the number of distinct files referenced across the given findings.
func Markdown ¶
Markdown writes a plain-markdown rendering of the review. Under ADR-0014 the renderer runs the user's OUTPUT.md as a Go text/template against the parsed Findings; it never sees the system prompt or any LLM-side formatting. Graceful degrade paths:
- p.Findings == nil → emit p.Content verbatim (parse failed upstream).
- p.OutputTemplate == "" → emit p.Content verbatim (no template loaded).
- template execute fails → return the error; pre-send validation (ADR-0014 §5) should have caught this, so if we land here a regression occurred and the caller deserves to see it rather than silently render half-formed output.
func TemplateFuncs ¶ added in v0.6.0
TemplateFuncs is the function map registered on every OUTPUT.md template the renderer parses. The set is the public template contract (ADR-0014 §2); additions are allowed in v1.x but removals require a schema bump.
func ValidateOutputTemplate ¶ added in v0.6.0
ValidateOutputTemplate is the pre-send guard from ADR-0014 §5. It runs three checks against a template body so a malformed user OUTPUT.md fails before any provider round-trip:
- Parse — text/template syntax check.
- Empty-findings execute — does the template crash on the empty case?
- Sample-findings execute — does the template crash with two findings (critical + info) populated, covering both branches of any severity-based conditional logic.
Returns the first failure verbatim, wrapped with a stable prefix the CLI uses to format an i18n'd error message. Returns nil on success.
func VerboseFooter ¶
VerboseFooter returns the multi-line footer appended after a review when --verbose is in effect. Format is stable: tokens, cost, latency, provider, model — each on its own line, aligned. Cached results get a `(cached)` marker on the tokens line so users see why a fast result was free.
Types ¶
type Finding ¶ added in v0.6.0
type Finding struct {
Severity Severity `json:"severity"`
File string `json:"file"`
Line int `json:"line"`
Title string `json:"title"`
Description string `json:"description"`
Language string `json:"language,omitempty"`
Snippet string `json:"snippet,omitempty"`
}
Finding is one review item the LLM returned. See ADR-0014 §1 for the full contract, including which fields are required.
func ParseFindings ¶ added in v0.6.0
ParseFindings decodes the LLM-emitted JSON payload into a slice. The returned slice may be empty (a clean review) but is non-nil on success. Errors trigger graceful degrade at the caller (ADR-0014 §4) — the pipeline never crashes on a malformed response.
type Meta ¶
type Meta struct {
Provider string
Model string
Lang string
Usage provider.Usage
Cost float64
Latency time.Duration
Cached bool
Timestamp time.Time
// Stats describing what went into this review. Used by the Cards
// renderer for its pre-body status line; zero values cause the line
// to be omitted. Markdown / JSON / verbose-footer renderers ignore
// these fields, so adding more here is backwards-compatible.
Files int // post-filter file count
LinesAdded int // total `+` lines in the reviewed diff
LinesRemoved int // total `-` lines in the reviewed diff
RulesLoaded bool // a non-default COMMITBRIEF.md was loaded
}
type Payload ¶
type Payload struct {
// Content is the raw provider response — under ADR-0014 a JSON string
// matching the findings schema; on graceful degrade it may be free-form
// markdown left over from a malformed JSON response. Cached as-is.
Content string
// Findings is the parsed structured response from the LLM. A non-nil
// empty slice means "no review-worthy issues"; a nil slice signals
// graceful degrade — the JSON parse failed and renderers must fall
// back to rendering Content directly (Stage A behavior).
Findings []Finding
// OutputTemplate is the loaded OUTPUT.md template body, consumed by the
// Markdown renderer. Empty string falls back to emitting Content
// unchanged (also the path used during degrade).
OutputTemplate string
Meta Meta
Verbose bool
}
type Severity ¶ added in v0.6.0
type Severity string
Severity ranks how urgently a finding should be addressed. The vocabulary is the wire contract with the LLM (ADR-0014 §1) and is intentionally English-only; UI strings around it are i18n-able at the renderer layer.
type SeverityGroup ¶ added in v0.6.0
SeverityGroup is the value type produced by GroupBySeverity for template consumption. Items preserve the order they appeared in the source slice.
func GroupBySeverity ¶ added in v0.6.0
func GroupBySeverity(findings []Finding) []SeverityGroup
GroupBySeverity returns findings grouped by severity, ordered critical → info. Empty buckets are omitted so templates can iterate without a presence check.
type TemplateData ¶ added in v0.6.0
type TemplateData struct {
Findings []Finding
}
TemplateData is the value passed to a parsed OUTPUT.md template at execution time. Keeping the struct named (rather than a bare slice) lets templates write `{{ range .Findings }}` and gives future fields a stable home.
Source Files