Documentation
¶
Overview ¶
Package progress renders a CLI progress display: a live region of per-step lines, each animating its own spinner and bubbles-rendered progress bar, plus a stream of completed steps that get promoted in place (rewritten as a past-tense title with their child tree) and scroll into history as new steps start.
Progress satisfies the engine.ProgressReporter interface (StartStage / AdvanceStage / CompleteStage) so the pipeline can drive coarse progress events, while command code can also open finer-grained step handles via Start / StartWithDoneLabel.
Index ¶
- Constants
- type Child
- type Progress
- func (p *Progress) Advance(label string)
- func (p *Progress) AdvanceStage(label string, completed, total int)
- func (p *Progress) CompleteStage(label string, total int)
- func (p *Progress) CompleteStep(doneLabel string, children []Child)
- func (p *Progress) Detail(label, detail string)
- func (p *Progress) Fail(label string)
- func (p *Progress) SeparateReport()
- func (p *Progress) Stage(text string)
- func (p *Progress) Start(id, activeLabel string) *Step
- func (p *Progress) StartStage(label string, total int)
- func (p *Progress) StartWithDoneLabel(id, activeLabel, doneLabel string) *Step
- func (p *Progress) Stop()
- func (p *Progress) Success(label string)
- func (p *Progress) SuccessWithChildren(label string, children []Child)
- type Step
Constants ¶
const ( CheckMark = "✔" CrossMark = "✘" WarningMark = "⚠" )
Visual marks rendered before completed-step / child labels.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Child ¶
type Child struct {
Icon string // e.g. CheckMark, CrossMark, WarningMark, or "" for a plain item
Label string // e.g. "Maven Detector", "subproject-a"
Detail string // e.g. "[59 packages]"
}
Child describes one sub-item rendered beneath a completed task.
type Progress ¶
type Progress struct {
// contains filtered or unexported fields
}
Progress renders the live region. Safe for concurrent use.
func New ¶
New creates a Progress instance. When enabled is false, all methods are no-ops. A non-empty initial label opens an implicit step that disappears silently once any explicit Start / StartStage is called.
func (*Progress) Advance ¶
Advance flushes any prior implicit/in-flight steps and starts a new labeled step. Preserves the legacy single-spinner API for callers like scan_cmd's "Writing SBOM output" transition. Each silently-promoted prior step gets its own hold (sequential, so the user sees each one transition).
func (*Progress) AdvanceStage ¶
func (*Progress) CompleteStage ¶
func (*Progress) CompleteStep ¶
CompleteStep finalises the step matching doneLabel (or the most-recent stepActive / stepFinishing step) with the supplied children. Blocks for p.minStepDuration after the state transition (see holdAfterDone) so each step has its own visible ✔ window before the next CLI operation proceeds.
func (*Progress) Detail ¶
Detail updates the hint on the step keyed by activeLabel. Implements the engine's DetailProgressReporter interface.
func (*Progress) Fail ¶
Fail promotes the most-recent active step with a ✘ icon and stops the renderer.
func (*Progress) SeparateReport ¶
func (p *Progress) SeparateReport()
SeparateReport writes a blank line between the progress output and any human-readable report that follows on stdout.
func (*Progress) Stage ¶
Stage updates the hint on the most-recent active step. Kept for backwards-compatibility with the legacy single-spinner API.
func (*Progress) StartStage ¶
StartStage / AdvanceStage / CompleteStage satisfy engine.ProgressReporter. They route engine-emitted stage events through the label-keyed shim so the CLI can later supply a past-tense label + children via CompleteStep.
func (*Progress) StartWithDoneLabel ¶
StartWithDoneLabel opens a new step and pre-registers its past-tense label so subsequent CompleteStep(doneLabel, …) finds the same step.
func (*Progress) Stop ¶
func (p *Progress) Stop()
Stop halts the renderer without writing a final line. Cursor visibility is restored. Subsequent calls are no-ops.
func (*Progress) Success ¶
Success promotes the most-recent active step (or the step matching label via pastToID) and stops the renderer. Subsequent calls are no-ops.
func (*Progress) SuccessWithChildren ¶
SuccessWithChildren promotes the most-recent active step with children and stops the renderer.
type Step ¶
type Step struct {
// contains filtered or unexported fields
}
Step is the handle for one line in the live region. It is returned by Start / StartWithDoneLabel and used by callers that want to drive a dedicated progress line directly (rather than via the label-keyed shim).
func (*Step) Complete ¶
Complete marks the step as succeeded with the supplied past-tense label and child tree. The renderer holds the line for p.minStepDuration after this call (via the doneAt stamp) and the call itself blocks for the same hold, so each step has its own visible ✔ window before the next operation proceeds.
func (*Step) Fail ¶
Fail marks the step as failed with the supplied past-tense label. Blocks for p.minStepDuration after the state transition (same hold semantics as Complete) so failures stay readable.
func (*Step) SetDetail ¶
SetDetail updates the hint text shown to the right of the bar on this step.
func (*Step) SetProgress ¶
SetProgress replaces completed/total atomically.
Source Files