view

Documentation

Overview

Strategy: extend BulletItem with optional *ClusterRender (per Task 0 orient).

Package view defines the eight ViewSpec variants that sit between the canonical report.Report and the paint primitives. A ViewSpec carries the data its variant needs and is rendered by Render. Selection logic (pickView) lives in a separate package.

ViewSpec is a closed sum-type: only this package can satisfy the unexported isViewSpec marker. Adding a ninth variant means adding a case to render.go's type switch — by design.

Index

• Constants
• func NewExpandSet(values []string) expandSet
• func Render(spec ViewSpec, t theme.Theme, width int) string
• func RenderMetricsHuman(w io.Writer, tool string, rows []MetricRow) error
• func RenderMetricsLLM(w io.Writer, tool string, rows []MetricRow) error
• func RenderReport(w io.Writer, r report.Report, t theme.Theme, width int) error
• func RenderReportMode(w io.Writer, r report.Report, t theme.Theme, width int, mode Mode) error
• func RenderReportModeWithExpand(w io.Writer, r report.Report, t theme.Theme, width int, mode Mode, ...) error
• func RenderSceneHuman(w io.Writer, s scene.Scene) error
• func RenderSceneLLM(w io.Writer, s scene.Scene) error
• func RenderStatusHuman(w io.Writer, tool string, rows []StatusRow) error
• func RenderStatusLLM(w io.Writer, tool string, rows []StatusRow) error
• func RenderStream(ctx context.Context, w io.Writer, ch <-chan report.Report, t theme.Theme, ...) error
• func RenderStreamMode(ctx context.Context, w io.Writer, ch <-chan report.Report, t theme.Theme, ...) error
• type Alert
• type Bullet
• type BulletItem
• type Clean
• type ClusterRender
• type Counter
• type Delta
• type DeltaBucket
• type Grouped
• type GroupedSection
• type Headline
• type LbRow
• type Leaderboard
• type MetricRow
• type Mode
• type MultipleCell
• type SmallMultiples
• type StatusRow
• type ViewSpec
  • func PickView(r report.Report) ViewSpec
  • func PickViewMode(r report.Report, mode Mode) ViewSpec
  • func PickViewModeWithExpand(r report.Report, mode Mode, expand expandSet) ViewSpec

Constants

const DefaultWidth = 80

DefaultWidth is used when the caller passes width <= 0.

Functions

func NewExpandSet

func NewExpandSet(values []string) expandSet

NewExpandSet exposes expandSet construction to cmd/fo and external tests.

func Render

func Render(spec ViewSpec, t theme.Theme, width int) string

Render paints a ViewSpec to a string using the supplied theme. Width is the available terminal column count; variants that need it (Leaderboard bars, SmallMultiples grid) consume it, others ignore. Width <= 0 falls back to DefaultWidth.

The type switch is the closed-set check: adding a variant means adding a case here. An unknown variant returns a placeholder marker rather than panicking, to keep the renderer fail-soft for callers composing dynamic specs.

func RenderMetricsHuman

func RenderMetricsHuman(w io.Writer, tool string, rows []MetricRow) error

func RenderMetricsLLM

func RenderMetricsLLM(w io.Writer, tool string, rows []MetricRow) error

func RenderReport

func RenderReport(w io.Writer, r report.Report, t theme.Theme, width int) error

RenderReport picks a view from r and writes the rendered string to w. Batch arrival mode: caller has the complete Report.

func RenderReportMode

func RenderReportMode(w io.Writer, r report.Report, t theme.Theme, width int, mode Mode) error

RenderReportMode is RenderReport with an explicit audience mode.

func RenderReportModeWithExpand

func RenderReportModeWithExpand(w io.Writer, r report.Report, t theme.Theme, width int, mode Mode, expand expandSet) error

RenderReportModeWithExpand is RenderReportMode plus an --expand set. LLM mode ignores the set (clusters always render fully).

func RenderSceneHuman

func RenderSceneHuman(w io.Writer, s scene.Scene) error

RenderSceneHuman renders a parsed Scene for a TTY: horizontal-rule act headers, dimmed narration, accent-colored actor prompts, and monospace command output. Exit zero is suppressed; non-zero is rendered in the error color.

func RenderSceneLLM

func RenderSceneLLM(w io.Writer, s scene.Scene) error

RenderSceneLLM emits a scene in the canonical `# fo:scene` text form. Output is plain text with no ANSI; structure is preserved so the result round-trips through scene.Parse.

func RenderStatusHuman

func RenderStatusHuman(w io.Writer, tool string, rows []StatusRow) error

RenderStatusHuman emits a banner + counts header followed by the LLM table body. Mono-only first cut; theme routing comes later.

func RenderStatusLLM

func RenderStatusLLM(w io.Writer, tool string, rows []StatusRow) error

RenderStatusLLM emits one row per line: aligned state token, label, optional value, optional note. Token-dense; no decoration.

func RenderStream

func RenderStream(ctx context.Context, w io.Writer, ch <-chan report.Report, t theme.Theme, width int) error

RenderStream consumes successive Report snapshots from ch and emits a fresh PickView+Render per snapshot, separated by blank lines. The final snapshot received before ch closes IS the final summary — same renderer, same code path as batch. No footer, no terminal-state machinery: live mode is just batch repeated.

The choice of report.Report (whole-snapshot) over a per-event channel is deliberate: PickView's thresholds are total-driven, so the renderer would otherwise re-implement parser accumulation. Parsers stream snapshots at natural boundaries (per-package finish for testjson, per-run for sarif).

Returns when ch is closed or ctx is cancelled. The caller owns ch.

func RenderStreamMode

func RenderStreamMode(ctx context.Context, w io.Writer, ch <-chan report.Report, t theme.Theme, width int, mode Mode) error

RenderStreamMode is RenderStream with an explicit audience mode.

Clean snapshots (no findings, no failures) are heartbeats, not changes: a passing package in a passing run flattens the signal the reader is scanning for (fo-58k). They are deferred and emitted at most once — at end-of-stream, only if no non-clean snapshot ever rendered. Any non-clean snapshot discards a pending Clean heartbeat.

Types

type Alert

type Alert struct {
	Severity report.Severity // drives the prefix color
	Prefix   string          // short label, e.g. "ERRORS"
	Value    string          // the metric, e.g. "47"
	Detail   string          // optional muted suffix
}

Alert — colored bold prefix + value, single line. Used when one metric breaches a threshold and demands attention without dominating.

type Bullet

type Bullet struct {
	Items []BulletItem
}

Bullet — flat list of rows, glyph + label + value per row. Used when the count is small and items don't share a meaningful grouping.

FixCommand on a row, when non-empty, is rendered as a copy-pastable suggestion line beneath the row.

type BulletItem

type BulletItem struct {
	Severity   report.Severity // optional — drives glyph + color
	Outcome    report.TestOutcome
	Label      string
	Value      string // free-form right-side detail (e.g. file:line)
	FixCommand string // optional copy-pastable suggestion
	Cluster    *ClusterRender
}

BulletItem is one row in a Bullet or Grouped view. When Cluster != nil, this item represents a cluster block (header + visible members) and the singleton fields (Severity/Outcome/Label/Value/FixCommand) are ignored.

type Clean

type Clean struct {
	// Message is the affirming line (e.g. "no findings"). Required.
	Message string
}

Clean — the empty-state view. count == 0 case.

type ClusterRender

type ClusterRender struct {
	ID            string
	Header        string              // formatted via clusterHeader
	Members       []report.TestResult // visible — 1 (collapsed) or all (expanded)
	Total         int                 // total member count (for "K tests" display)
	SharedOutput  string              // non-empty only in LLM Shape A
	UsesSharedRow bool                // true → Shape A; false → Shape B (LLM mode only)
	LLMMode       bool                // true → LLM Shape A/B; false → human header+rep
}

ClusterRender carries the formatted cluster header and the visible members (collapsed: 1 rep; expanded: all members). Singletons stay in Bullet.Items with Cluster == nil and the existing fields populated.

type Counter

type Counter struct {
	Severity report.Severity // optional — drives color
	Label    string
	Value    int
}

Counter is a labeled small integer used inside a MultipleCell.

type Delta

type Delta struct {
	Inner    ViewSpec
	Buckets  []DeltaBucket
	Headline string // "N new · N resolved · N persistent" — omitted when empty
}

Delta wraps another view with a strip of arrow buckets summarising change versus a prior run. Inner is rendered first, then the bucket strip below.

By convention Inner is one of Bullet, Leaderboard, or SmallMultiples — the three views where row-level deltas carry meaning. The type system does not enforce this; pickView is responsible for picking a sane Inner.

type DeltaBucket

type DeltaBucket struct {
	Label     string
	Count     int
	Direction int
}

DeltaBucket is one comparison cell: a labeled count with direction vs prior. Direction values: +1 up, -1 down, 0 same.

type Grouped

type Grouped struct {
	Sections []GroupedSection
}

Grouped — flat list with section labels. Used when count is larger and items naturally cluster (e.g. by severity or package). Sections render in the order given; empty sections are skipped.

type GroupedSection

type GroupedSection struct {
	Label string
	Items []BulletItem
}

GroupedSection is a labeled cluster of BulletItems.

type Headline

type Headline struct {
	Title  string
	Detail string   // optional sub-line, rendered muted under Title
	Body   []string // extra lines (panic message, build error, user-code frame)
}

Headline — single dominant message in heading typography. Used for PANIC, build-error-only runs, or one overwhelming signal.

type LbRow

type LbRow struct {
	Label string
	Value float64
}

LbRow is one ranked entry in a Leaderboard.

type Leaderboard

type Leaderboard struct {
	Rows  []LbRow
	Total float64 // value used to scale bars; rows sum to <= Total
}

Leaderboard — ranked items with bars. Used when a small head holds a large fraction of the total impact. Total scales every bar.

type MetricRow

type MetricRow struct {
	Key   string
	Value float64
	Unit  string
	Delta float64 // 0 if New, or genuinely unchanged
	New   bool    // true when no prior sample matched — render "(new)"
}

type Mode

type Mode int

Mode hints the audience for the picked view. ModeHuman (default) may pick visual aggregates (Leaderboard, SmallMultiples) that condense many findings into a chart. ModeLLM skips those — an LLM consumer needs file:line per finding, not a bar chart — and falls through to Grouped or Bullet, which carry the full data.

const (
	ModeHuman Mode = iota
	ModeLLM
)

type MultipleCell

type MultipleCell struct {
	Label    string
	Sparks   []float64 // optional sparkline series
	Counters []Counter // 0..n labeled counts, rendered inline
}

MultipleCell is one tile in a SmallMultiples grid.

type SmallMultiples

type SmallMultiples struct {
	Cells []MultipleCell
}

SmallMultiples — Swiss grid of repeated mini-bullets. Used for per-package or per-module summaries where the same shape repeats. Cells are laid out in a column-aligned grid; whitespace alone makes the grid visible.

type StatusRow

type StatusRow struct {
	State string
	Label string
	Value string
	Note  string
}

type ViewSpec

type ViewSpec interface {
	// contains filtered or unexported methods
}

ViewSpec is the closed sum of render variants. The isViewSpec marker is unexported so external packages cannot extend the set; the type switch in Render is the canonical exhaustive handler.

func PickView

func PickView(r report.Report) ViewSpec

PickView selects a ViewSpec from a Report. Pure and deterministic: branches are evaluated in fixed priority order so the same Report always yields the same shape. Delta wraps the inner pick when Diff is present and at least one severity bucket moved.

func PickViewMode

func PickViewMode(r report.Report, mode Mode) ViewSpec

PickViewMode is PickView with an explicit audience mode.

func PickViewModeWithExpand

func PickViewModeWithExpand(r report.Report, mode Mode, expand expandSet) ViewSpec

PickViewModeWithExpand is PickViewMode plus an --expand set that controls cluster collapse/expand in human mode. LLM mode always shows full members.