Documentation
¶
Overview ¶
Package report turns a reconcile's failures into a compact, styled end-of-run summary: the real (primary) errors shown once, every cascaded failure folded under the root that caused it, and any deferred log lines in a quiet footer. It exists so a single missing or failed dependency reads as one root cause with a list of what it blocked — not a wall of nested, repeated "dependencies failed: A: dependencies failed: B: …" chains.
The model is built from orchestrator data (Result.Failed + Result.Blocked) and is pure/deterministic; rendering is gated on a color bool so it is plain and testable off a TTY. Styling reuses internal/style, the vocabulary the live status bar and `flate test` report already speak.
Index ¶
- func Document(blocks ...string) string
- func MessageLines(s string) []string
- func NotesBlock(notes []Note, color bool) string
- func Roots(blocked map[manifest.NamedResource][]manifest.NamedResource) map[manifest.NamedResource][]manifest.NamedResource
- func RootsOf(id manifest.NamedResource, ...) []manifest.NamedResource
- func Verdict(color bool, glyph string, paintGlyph func(string, bool) string, ...) string
- func WarningsBlock(warnings []manifest.Warning, color bool) string
- type Count
- type Missing
- type Model
- type Note
- type Primary
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Document ¶ added in v0.4.6
Document assembles a footer from section blocks: a leading blank line parts it from preceding output, a single blank line separates each non-empty block, and it ends with a newline. Returns "" when every block is empty, so the caller writes nothing. Blocks carry no blank lines of their own — spacing lives here, in one place, so there's no per-section newline bookkeeping to drift. Shared by the build/diff failure report and the `flate test` roster.
func MessageLines ¶
MessageLines splits a stored failure message into trimmed, non-empty lines. Shared with the test runner so a multi-line build/template diagnostic renders the same way on both surfaces.
func NotesBlock ¶ added in v0.4.6
NotesBlock renders the operational-log section: a header counting the notes, then one dim line each (collapsed identical lines carry a ×N suffix), or "" when there are none. Shared by every footer-bearing surface.
func Roots ¶
func Roots(blocked map[manifest.NamedResource][]manifest.NamedResource) map[manifest.NamedResource][]manifest.NamedResource
Roots inverts a blocked graph into root cause → the resources that trace to it. blocked maps each derived failure to the immediate dependencies that blocked it; a root is any id reached by walking those blockers that is not itself blocked (a primary failure, or a dependency missing from the graph). Shared by Build and the test runner so both fold a cascade under the same root with identical walk semantics.
func RootsOf ¶ added in v0.4.6
func RootsOf(id manifest.NamedResource, blocked map[manifest.NamedResource][]manifest.NamedResource) []manifest.NamedResource
RootsOf resolves the root cause(s) of a blocked id by walking its blockers to a primary failure or a missing id, returning a fresh slice. Cycle-safe via a visited set: a victim whose blockers form a closed cycle (no escape to a primary/missing root) yields nil — callers that must account for every victim fall back to its immediate blockers.
func Verdict ¶ added in v0.4.6
func Verdict(color bool, glyph string, paintGlyph func(string, bool) string, elapsed time.Duration, counts ...Count) string
Verdict renders a one-line run summary: the lead glyph, then each count as "<N> <Label>" joined by " · ", then a dim elapsed clock (omitted when zero). The first count always shows (even at zero, e.g. "0 passed"); later counts show only when non-zero. Returns "" when given no counts. Shared by the build/diff failure report and the `flate test` roster so both speak one verdict grammar.
func WarningsBlock ¶ added in v0.4.6
WarningsBlock renders the advisory section: a header counting the warnings, then one attributed line each (with an indented detail line when present), or "" when there are none. Exported so the build/diff report and the `flate test` roster surface advisories identically.
Types ¶
type Count ¶ added in v0.4.6
Count is one labeled tally in a Verdict line: N items, a noun, and the paint that colors "<N> <Label>" (e.g. style.Fail for "failed").
type Missing ¶
type Missing struct {
ID manifest.NamedResource
RequiredBy []manifest.NamedResource
}
Missing is a dependency that never rendered (absent from the store) yet was required by one or more resources — the other kind of root cause. RequiredBy lists the resources blocked on it (sorted).
type Model ¶
type Model struct {
Primary []Primary
Missing []Missing
// Warnings are non-fatal render advisories (Result.Warnings) — rendered in
// their own footer section above operational Notes. Distinct from failures
// (the render succeeded) and from Notes (operational slog lines).
Warnings []manifest.Warning
Notes []Note
// Blocked is the count of distinct derived (cascaded) failures. It is the
// verdict's "N blocked" figure — distinct resources, not the sum of the
// per-root Blocks/RequiredBy lists, which can overlap when one resource
// traces to more than one root (e.g. a failed parent AND a missing dep).
Blocked int
}
Model is the partitioned, deterministic view the renderer consumes.
func Build ¶
func Build(failed map[manifest.NamedResource]store.StatusInfo, blocked map[manifest.NamedResource][]manifest.NamedResource, warnings []manifest.Warning, notes []Note) Model
Build partitions failures into primary errors and root-grouped cascades. failed is Result.Failed (sentinel-trimmed messages); blocked is Result.Blocked (a failed id → the immediate deps that blocked it, empty for primaries); notes are the deferred log lines for the footer.
A blocked resource is folded into the root(s) it traces to: walking its blockers until reaching a primary failure (a failed id that is not itself blocked) or a missing id (absent from failed). Cascaded resources never get their own line — they appear only in a root's Blocks / RequiredBy list.
type Note ¶
Note is one deferred log line for the footer, collapsed by identical text with a repeat count.
type Primary ¶
type Primary struct {
ID manifest.NamedResource
Msg string
Blocks []manifest.NamedResource
}
Primary is a resource that failed on its own — a real render/template/build error. Blocks lists the resources whose failure cascaded from it (sorted).
Source Files