// Package engine provides a mode-agnostic scan engine that can be used
// independently of any UI layer. This file defines the progress reporting
// interface that decouples the engine from any specific display implementation.
package engine

import "time"

// ProgressUpdate contains information about a target's scan progress.
// Sent via ProgressReporter.OnProgress for each status change.
type ProgressUpdate struct {
	// Target is the domain being scanned.
	Target string

	// Status is the current state of this target's scan.
	Status TargetStatus

	// PathsChecked is the number of paths scanned so far for this target.
	PathsChecked int

	// PathsTotal is the total number of paths to scan for this target.
	PathsTotal int

	// FindingsCount is the number of exposures found so far for this target.
	FindingsCount int

	// Elapsed is the time spent scanning this target so far.
	Elapsed time.Duration

	// EstRemaining is the estimated time remaining for this target.
	// May be zero if not computed or not applicable.
	EstRemaining time.Duration
}

// ErrorInfo contains information about an error that occurred during scanning.
// Errors are reported separately from progress via ProgressReporter.OnError.
type ErrorInfo struct {
	// Target is the domain where the error occurred.
	Target string

	// Path is the specific path being scanned when the error occurred.
	// May be empty if the error is not path-specific.
	Path string

	// Err is the underlying error.
	Err error

	// At is the timestamp when the error occurred.
	At time.Time
}

// ProgressReporter is the interface for receiving scan progress, errors, and findings.
// Implementations must be safe for concurrent use, as callbacks may be called
// from multiple worker goroutines simultaneously.
//
// The engine guarantees:
//   - OnProgress is called when a target's status changes
//   - OnError is called for each error (separate from progress stream)
//   - OnFinding is called immediately when an exposure is discovered
//
// Callbacks should return quickly to avoid blocking scan workers.
// For slow consumers, consider using buffered channels internally.
type ProgressReporter interface {
	// OnProgress is called when a target's scan status changes.
	// Called from worker goroutines; must be safe for concurrent use.
	OnProgress(update ProgressUpdate)

	// OnError is called when an error occurs during scanning.
	// Errors are reported separately from progress per design decision.
	// Called from worker goroutines; must be safe for concurrent use.
	OnError(err ErrorInfo)

	// OnFinding is called immediately when an exposure is discovered.
	// This allows the display layer to show findings in real-time.
	// Called from worker goroutines; must be safe for concurrent use.
	OnFinding(finding Finding)
}