Documentation
¶
Overview ¶
Package report renders a gate's progress and a CLI's console output. NewFromConfig builds one ExecutionObserver from config: line (a status line per phase, the failures and a one-line summary, with an interactive layout that ticks each step), table (a result table per phase), gh-actions (GitHub Actions workflow commands), json (one machine-readable report) or quiet (nothing, the default); Composite fans one run out to several. Console is a CLI's whole console: verbosity levels, a leveled Logger, a command hook, coded-error formatting with exit codes, and the observer a run should use.
Index ¶
- func ActionableLines(output []byte, limit int) []string
- func Composite(obs ...interfaces.ExecutionObserver) interfaces.ExecutionObserver
- func ExitCode(code apperr.ErrorCode) int
- func IsNoiseLine(line string) bool
- func NewFromConfig(cfg Config, streams types.Streams) (interfaces.ExecutionObserver, error)
- func WriteStepSummary(w io.Writer, results types.StepResults, total time.Duration) error
- type Config
- type Console
- func (c *Console) CommandHook() interfaces.CmdHook
- func (c *Console) Debugf(format string, a ...any)
- func (c *Console) EndGroup()
- func (c *Console) Errorf(format string, a ...any)
- func (c *Console) FormatError(err error) int
- func (c *Console) Groupf(format string, a ...any)
- func (c *Console) Infof(format string, a ...any)
- func (c *Console) Level() Level
- func (c *Console) Logger() interfaces.Logger
- func (c *Console) Observer() interfaces.ExecutionObserver
- func (c *Console) SetLevel(l Level)
- func (c *Console) Successf(format string, a ...any)
- func (c *Console) Warnf(format string, a ...any)
- type ConsoleConfig
- type Hint
- type Kind
- type Level
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ActionableLines ¶ added in v0.0.19
ActionableLines condenses a failed step's captured output to at most limit lines an operator can act on. It keeps the decisive lines first (Go test failures, file:line compiler and linter errors, pytest FAILED lines, the files a diff touches, govulncheck findings); when there are none it keeps the first lines that are not noise (see IsNoiseLine). Each line is trimmed and capped at 200 characters.
func Composite ¶
func Composite(obs ...interfaces.ExecutionObserver) interfaces.ExecutionObserver
Composite returns an observer that forwards every event to obs, in order.
func ExitCode ¶ added in v0.0.19
ExitCode maps an error code to a process exit code: 2 for a failure the operator can act on (invalid input, not found, quality failed), 3 for an unavailable operation, and 1 otherwise.
func IsNoiseLine ¶ added in v0.0.19
IsNoiseLine reports whether a trimmed output line carries nothing actionable: a bare PASS/FAIL, runner decoration, Go test boilerplate, structured-log and timestamp lines, tool chatter, diff hunks and govulncheck's explanatory lines.
func NewFromConfig ¶
func NewFromConfig( cfg Config, streams types.Streams, ) (interfaces.ExecutionObserver, error)
NewFromConfig builds the reporter cfg.Kind selects over streams. An unknown kind, or streams missing a writer, is CodeInvalidInput.
func WriteStepSummary ¶ added in v0.0.19
WriteStepSummary writes a gate's verdict as GitHub step-summary markdown: one line when every step passed, otherwise a count heading and a table of the steps that did not pass. The heading names the first result's group ("Results" when it has none). A write error is CodeInternal.
Types ¶
type Config ¶
type Config struct {
// Kind selects the reporter; empty means KindQuiet.
Kind Kind `yaml:"kind" mapstructure:"kind"`
// Hints are the remediation hints the failure block prints under a matching step
// (line and table).
Hints []Hint `yaml:"hints" mapstructure:"hints"`
// Verbose reports at LevelVerbose rather than LevelNormal (line and table).
Verbose bool `yaml:"verbose" mapstructure:"verbose"`
// Interactive turns on the line reporter's interactive layout: the gate and phase
// headers, a tick per step and a table of unticked steps. Leave it off in CI.
Interactive bool `yaml:"interactive" mapstructure:"interactive"`
// Color styles line and table output with ANSI color.
Color bool `yaml:"color" mapstructure:"color"`
}
Config selects and tunes a reporter.
type Console ¶ added in v0.0.19
type Console struct {
// contains filtered or unexported fields
}
Console is a CLI's console on one error stream: a verbosity level, a leveled Logger, a command hook, coded-error formatting, and the observer a gate run reports through. One Console is built at the composition root and shared; SetLevel may change its verbosity after the reporters it built exist.
func NewConsole ¶ added in v0.0.19
func NewConsole(streams types.Streams, cfg ConsoleConfig) (*Console, error)
NewConsole returns a Console writing to streams.Err at LevelNormal. Streams missing a writer are CodeInvalidInput.
func (*Console) CommandHook ¶ added in v0.0.19
func (c *Console) CommandHook() interfaces.CmdHook
CommandHook returns a CmdHook that echoes each command the runner starts, and its outcome, at the verbose level.
func (*Console) EndGroup ¶ added in v0.0.19
func (c *Console) EndGroup()
EndGroup closes the section Groupf opened; outside GitHub Actions it prints nothing.
func (*Console) FormatError ¶ added in v0.0.19
FormatError prints err and returns the process exit code for it: a coded error prints as "<CODE>: <message>" (with its cause when verbose) and exits with ExitCode(code); any other error prints as "Error: <err>" and exits 1.
func (*Console) Groupf ¶ added in v0.0.19
Groupf opens a section titled by format: a collapsible log group under GitHub Actions, otherwise a bold header at the verbose level only (the line reporter's phase lines already title a normal run).
func (*Console) Logger ¶ added in v0.0.19
func (c *Console) Logger() interfaces.Logger
Logger returns an interfaces.Logger that prints through the console: Debug at the verbose level, Info and Warn at the normal level, Error always. Key-value pairs are appended to the message as " key=value".
func (*Console) Observer ¶ added in v0.0.19
func (c *Console) Observer() interfaces.ExecutionObserver
Observer returns the reporter a gate run should use at the console's current level: the table when verbose, the line reporter with GitHub Actions annotations in CI, and the interactive line reporter otherwise. With a step summary path set, the run's verdict is also appended there.
type ConsoleConfig ¶ added in v0.0.19
type ConsoleConfig struct {
// StepSummaryPath is the GitHub step summary file a run's verdict is appended to
// when its gate completes; empty writes none.
StepSummaryPath string `yaml:"step_summary_path" mapstructure:"step_summary_path"`
// Hints are the failure block's remediation hints.
Hints []Hint `yaml:"hints" mapstructure:"hints"`
// Color styles the output with ANSI color.
Color bool `yaml:"color" mapstructure:"color"`
// CI marks a CI run: the line reporter drops its interactive layout and GitHub
// Actions annotations join it.
CI bool `yaml:"ci" mapstructure:"ci"`
// GitHubActions marks a run inside GitHub Actions: Groupf opens a collapsible log
// group there.
GitHubActions bool `yaml:"github_actions" mapstructure:"github_actions"`
}
ConsoleConfig tunes a Console. A composition root resolves it from the environment (a TTY, NO_COLOR, CI, GITHUB_STEP_SUMMARY); the console itself reads nothing.
type Hint ¶ added in v0.0.19
type Hint struct {
// Group is the step group the hint applies to.
Group string `yaml:"group" mapstructure:"group"`
// Substr narrows the hint to steps whose name contains it; empty matches every step
// in the group.
Substr string `yaml:"substr" mapstructure:"substr"`
// Text is the hint line, typically the command that reproduces or fixes the step.
Text string `yaml:"text" mapstructure:"text"`
}
Hint is one remediation hint: the failure block prints Text under a failed or warned step whose Group equals Group and whose name contains Substr (empty matches any).
type Kind ¶
type Kind string
Kind selects a reporter.
const ( // KindQuiet reports nothing (the default). KindQuiet Kind = "quiet" // KindLine prints a status line per phase on Err and ends with the failures and a // one-line summary; Config.Interactive adds a tick per step. KindLine Kind = "line" // KindTable prints a result table per phase and for the gate on Err. KindTable Kind = "table" // KindGHActions writes GitHub Actions log groups and annotations on Out. KindGHActions Kind = "gh-actions" // KindJSON writes one JSON report of the gate on Out. KindJSON Kind = "json" )
Source Files