progress

type ChannelReporter ¶

type ChannelReporter struct {
	// contains filtered or unexported fields
}

ChannelReporter sends progress events to a Go channel for programmatic consumption.

This reporter is designed for building custom UIs, web dashboards, or other tools that need to consume progress events in real-time within a Go program. Events are sent to a buffered channel using non-blocking sends to prevent impacting analysis performance.

Important: Always call Close() when done to release resources and signal completion to consumers.

Example:

ctx, cancel := context.WithCancel(context.Background())
defer cancel()
reporter := progress.NewChannelReporter(ctx)

// Start consuming events in a goroutine
go func() {
    for event := range reporter.Events() {
        fmt.Printf("Progress: %d%%\n", int(event.Percent))
    }
}()

// Use reporter with engine
eng := engine.CreateRuleEngine(ctx, 10, log,
    engine.WithProgressReporter(reporter),
)

func NewChannelReporter(ctx context.Context, opts ...ChannelReporterOption) *ChannelReporter

ctx, cancel := context.WithCancel(context.Background())
defer cancel()
reporter := progress.NewChannelReporter(ctx, progress.WithLogger(log))
// When ctx is cancelled, the channel will automatically close

func (c *ChannelReporter) Close()

reporter.Close()

func (c *ChannelReporter) DroppedEvents() uint64

func (c *ChannelReporter) Events() <-chan ProgressEvent

for event := range reporter.Events() {
    // Process event
}

func (c *ChannelReporter) Report(event ProgressEvent)

type ChannelReporterOption ¶

type ChannelReporterOption func(*ChannelReporter)

ChannelReporterOption is a function that configures a ChannelReporter.

func WithLogger(log logr.Logger) ChannelReporterOption

type JSONReporter ¶

type JSONReporter struct {
	// contains filtered or unexported fields
}

JSONReporter writes progress events as newline-delimited JSON (NDJSON).

Each event is marshaled to JSON and written as a single line, making the output suitable for streaming consumption by other tools. This reporter is thread-safe and suitable for concurrent use.

Example output:

{"timestamp":"2024-10-29T17:06:14Z","stage":"provider_init","message":"Initializing nodejs provider"}
{"timestamp":"2024-10-29T17:06:17Z","stage":"provider_init","message":"Provider nodejs ready"}
{"timestamp":"2024-10-29T17:06:22Z","stage":"rule_execution","current":1,"total":10,"percent":10}

func NewJSONReporter(w io.Writer) *JSONReporter

reporter := progress.NewJSONReporter(os.Stderr)
reporter.Report(progress.ProgressEvent{
    Stage: progress.StageRuleExecution,
    Current: 5,
    Total: 10,
    Percent: 50.0,
})

func (j *JSONReporter) Report(event ProgressEvent)

type NoopReporter ¶

type NoopReporter struct{}

NoopReporter is a no-op implementation of ProgressReporter that discards all events.

This is the default reporter when progress reporting is not explicitly configured, ensuring zero overhead when the feature is disabled. All Report calls are no-ops and will be optimized away by the compiler in many cases.

Example:

// Default behavior - no progress output
reporter := progress.NewNoopReporter()
reporter.Report(event) // Does nothing

func NewNoopReporter() *NoopReporter

func (n *NoopReporter) Report(event ProgressEvent)

type ProgressBarReporter ¶

type ProgressBarReporter struct {
	// contains filtered or unexported fields
}

ProgressBarReporter writes progress as a visual progress bar with real-time updates.

This reporter displays a dynamic progress bar that updates in place using carriage returns. It shows percentage completion, a visual bar, current/total counts, and the current rule being processed.

Example output:

Processing rules  42% |██████████░░░░░░░░░░░░░░░| 99/235  hibernate6-00280

The bar updates in place during rule execution and prints a final newline when complete. This reporter is designed for terminal (TTY) output where ANSI control characters work. For non-TTY output (pipes, files), consider using TextReporter instead.

func NewProgressBarReporter(w io.Writer) *ProgressBarReporter

reporter := progress.NewProgressBarReporter(os.Stderr)
// Progress bar will be displayed during rule execution

func (p *ProgressBarReporter) Report(event ProgressEvent)

type ProgressEvent ¶

type ProgressEvent struct {
	// Timestamp is when the event occurred. If not set by the caller,
	// reporters will populate it automatically.
	Timestamp time.Time `json:"timestamp"`

	// Stage indicates which phase of analysis this event relates to.
	Stage Stage `json:"stage"`

	// Message provides human-readable context (e.g., rule ID, provider name).
	Message string `json:"message,omitempty"`

	// Current is the number of items completed so far (e.g., rules processed).
	Current int `json:"current,omitempty"`

	// Total is the total number of items to process.
	Total int `json:"total,omitempty"`

	// Percent is the completion percentage (0-100).
	// This field is automatically calculated from Current and Total if not set.
	Percent float64 `json:"percent,omitempty"`

	// Metadata contains additional stage-specific information.
	// For example, error details for failed providers.
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

ProgressEvent represents a progress update at a specific point in time.

Events are emitted at key points during analysis:

• Provider initialization (start and completion)
• Rule parsing (total count discovered)
• Rule execution (per-rule completion with percentage)
• Analysis completion

Not all fields are populated for all events. For example, init events may only have Stage and Message, while rule execution events include Current, Total, and Percent.

type ProgressReporter ¶

type ProgressReporter interface {
	// Report emits a progress event. This method may be called concurrently
	// and should not block. Implementations should handle errors internally
	// to avoid disrupting the analysis.
	Report(event ProgressEvent)
}

ProgressReporter is the interface for reporting analysis progress.

Implementations must be safe for concurrent use. The Report method should not block to avoid impacting analysis performance.

type Stage ¶

type Stage string

Stage represents a phase of the analysis process.

Stages occur in a typical sequence:

1. StageInit - Analysis starting
2. StageProviderInit - Initializing language providers
3. StageRuleParsing - Loading and parsing rules
4. StageRuleExecution - Processing rules
5. StageComplete - Analysis finished

const (
	// StageInit indicates analysis initialization.
	StageInit Stage = "init"

	// StageProviderInit indicates provider initialization.
	// Events include provider name and readiness status.
	StageProviderInit Stage = "provider_init"

	// StageProviderPrepare indicates provider Prepare() phase (symbol cache population).
	// Events include provider name, files processed, and total files.
	StageProviderPrepare Stage = "provider_prepare"

	// StageDependencyResolution indicates dependencies resolution (list).
	// Events include the total number of dependencies discovered.
	StageDependencyResolution Stage = "dependency_resolution"

	// StageRuleParsing indicates rule loading and parsing.
	// Events include the total number of rules discovered.
	StageRuleParsing Stage = "rule_parsing"

	// StageRuleExecution indicates rule processing.
	// Events include current/total counts and percentage completion.
	StageRuleExecution Stage = "rule_execution"

	// StageDependencyAnalysis indicates dependency analysis (future).
	StageDependencyAnalysis Stage = "dependency_analysis"

	// StageComplete indicates analysis completion.
	StageComplete Stage = "complete"
)

type TextReporter ¶

type TextReporter struct {
	// contains filtered or unexported fields
}

TextReporter writes progress events as human-readable text with timestamps.

Each event is formatted with a timestamp prefix and stage-appropriate message. This reporter is ideal for terminal output and log files where human readability is important. It is thread-safe and suitable for concurrent use.

Example output:

[17:06:14] Provider: Initializing nodejs provider
[17:06:17] Provider: Provider nodejs ready
[17:06:22] Rule: Starting rule execution: 10 rules to process
[17:06:22] Rule: patternfly-v5-to-v6-charts-00000
[17:06:26] Analysis complete!

func NewTextReporter(w io.Writer) *TextReporter

reporter := progress.NewTextReporter(os.Stderr)
reporter.Report(progress.ProgressEvent{
    Stage: progress.StageRuleExecution,
    Message: "Processing rule-001",
})

func (t *TextReporter) Report(event ProgressEvent)

type ThrottledReporter ¶

type ThrottledReporter struct {
	// contains filtered or unexported fields
}

ThrottledReporter wraps a ProgressReporter with intelligent throttling and optional streaming.

It ensures progress updates don't overwhelm the reporting system by:

• Throttling updates to a configured interval (default 500ms)
• Always reporting first and last events regardless of timing
• Optionally streaming events to a channel for real-time consumers

This reporter is designed to be reused across different providers and contexts. It's safe for concurrent use.

Example usage:

baseReporter := progress.NewTextReporter(os.Stderr)
throttled := progress.NewThrottledReporter("java", baseReporter)

// Optional: enable streaming for gRPC or other consumers
eventChan := make(chan ProgressEvent, 100)
throttled.EnableStreaming(eventChan)

// Report progress - automatically throttled
for i := 0; i < total; i++ {
    throttled.Report(ProgressEvent{
        Stage: StageProviderPrepare,
        Current: i,
        Total: total,
    })
}

func NewThrottledReporter(stageName string, reporter ProgressReporter) *ThrottledReporter

func NewThrottledReporterWithInterval(stageName string, reporter ProgressReporter, interval time.Duration) *ThrottledReporter

func (t *ThrottledReporter) DisableStreaming()

func (t *ThrottledReporter) EnableStreaming(ch chan<- ProgressEvent)

eventChan := make(chan ProgressEvent, 100)
reporter.EnableStreaming(eventChan)

go func() {
    for event := range eventChan {
        // Process event
    }
}()

// When done:
reporter.DisableStreaming()  // Must be called before close!
close(eventChan)

func (t *ThrottledReporter) Report(event ProgressEvent)

func (t *ThrottledReporter) Reset()