framework

type BlobData struct {
	Commit    *gitlib.Commit
	Index     int
	Changes   gitlib.Changes
	BlobCache map[gitlib.Hash]*gitlib.CachedBlob
	Error     error
}

type BlobPipeline struct {
	SeqWorkerChan  chan<- gitlib.WorkerRequest
	PoolWorkerChan chan<- gitlib.WorkerRequest
	BufferSize     int
	WorkerCount    int
	BlobCache      *cache.LRUBlobCache
	ArenaSize      int

	// Metrics provides per-stage counters for memory triage. Nil-safe.
	Metrics *StageMetrics
	// contains filtered or unexported fields
}

type BudgetSolver func(budgetBytes int64) (CoordinatorConfig, error)

type CheckpointParams struct {
	Enabled   bool
	Dir       string
	Resume    bool
	ClearPrev bool
}

type CommitBatch struct {
	// Commits in this batch.
	Commits []*gitlib.Commit

	// StartIndex is the index of the first commit in the full sequence.
	StartIndex int

	// BatchID identifies this batch for ordering.
	BatchID int
}

type CommitData struct {
	Commit        *gitlib.Commit
	Index         int
	Changes       gitlib.Changes
	BlobCache     map[gitlib.Hash]*gitlib.CachedBlob
	FileDiffs     map[string]plumbing.FileDiffData
	UASTChanges   []uast.Change // Pre-computed UAST changes (nil if not computed).
	UASTSpillPath string        // Path to spilled UAST gob file (empty if in-memory).
	Error         error
}

type CommitStreamer struct {
	// BatchSize is the number of commits per batch.
	BatchSize int

	// Lookahead is the number of batches to prefetch.
	Lookahead int
}

type ConfigParams struct {
	Workers         int
	BufferSize      int
	CommitBatchSize int
	BlobCacheSize   string
	DiffCacheSize   int
	BlobArenaSize   string
	MemoryBudget    string
	GCPercent       int
	BallastSize     string
}

type Coordinator struct {

	// StageMetrics provides per-stage high-watermark counters for memory triage.
	// When non-nil, pipeline stages update counters atomically and the sampler reads them.
	StageMetrics *StageMetrics
	// contains filtered or unexported fields
}

type CoordinatorConfig struct {
	// BatchConfig configures batch sizes for blob and diff operations.
	BatchConfig gitlib.BatchConfig

	// CommitBatchSize is the number of commits to process in each batch.
	CommitBatchSize int

	// Workers is the number of parallel workers for processing.
	Workers int

	// BufferSize is the size of internal channels.
	BufferSize int

	// BlobCacheSize is the maximum size of the global blob cache in bytes.
	// Set to 0 to disable caching.
	BlobCacheSize int64

	// DiffCacheSize is the maximum number of diff results to cache.
	// Set to 0 to disable caching.
	DiffCacheSize int

	// BlobArenaSize is the size of the memory arena for blob loading.
	// Defaults to 16MB if 0.
	BlobArenaSize int

	// UASTPipelineWorkers is the number of goroutines for parallel UAST parsing
	// in the pipeline stage. Set to 0 to disable the UAST pipeline stage.
	UASTPipelineWorkers int

	// LeafWorkers is the number of goroutines for parallel leaf analyzer consumption.
	// Each worker processes a disjoint subset of commits via Fork/Merge.
	// Set to 0 to disable parallel leaf consumption (serial path).
	LeafWorkers int

	// GCPercent controls Go's GC aggressiveness.
	// Set to 0 to use auto mode (200 when system memory > 32 GiB).
	GCPercent int

	// BallastSize reserves bytes in a long-lived slice to smooth GC behavior.
	// Set to 0 to disable ballast allocation.
	BallastSize int64

	// FirstParent indicates whether the history walk is restricted to the first parent.
	FirstParent bool

	// WorkerTimeout is the maximum time to wait for a worker response before
	// considering it stalled. Set to 0 to disable the watchdog.
	WorkerTimeout time.Duration
}

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

type DiffCacheStats struct {
	Hits       int64
	Misses     int64
	BloomSkips int64 // Lookups short-circuited by the Bloom pre-filter.
	Entries    int
	MaxEntries int
}

type DiffKey struct {
	OldHash gitlib.Hash
	NewHash gitlib.Hash
}

type DiffPipeline struct {
	PoolWorkerChan chan<- gitlib.WorkerRequest
	BufferSize     int
	DiffCache      *DiffCache

	// NoBatch disables cross-commit batching. Each diff request fires immediately.
	// Useful for debugging or single-commit analysis.
	NoBatch bool

	// Metrics provides per-stage counters for memory triage. Nil-safe.
	Metrics *StageMetrics
	// contains filtered or unexported fields
}

type FlushableAnalyzer interface {
	Flush()
}

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

type PipelineStats struct {
	BlobDuration time.Duration
	DiffDuration time.Duration
	UASTDuration time.Duration

	BlobCacheHits   int64
	BlobCacheMisses int64
	DiffCacheHits   int64
	DiffCacheMisses int64
}

type Runner struct {
	Repo      *gitlib.Repository
	RepoPath  string
	Analyzers []analyze.HistoryAnalyzer
	Config    CoordinatorConfig

	// Tracer is the OTel tracer for creating pipeline spans.
	// When nil, falls back to otel.Tracer("codefang").
	Tracer trace.Tracer

	// CoreCount is the number of leading analyzers in the Analyzers slice that are
	// core (plumbing) analyzers. These run sequentially. Analyzers after CoreCount
	// are leaf analyzers that can be parallelized via Fork/Merge.
	// Set to 0 to disable parallel leaf consumption.
	CoreCount int

	// MemBudget is the user's memory budget in bytes. When positive, overrides
	// the system-RAM-based debug.SetMemoryLimit with a budget-aligned value.
	MemBudget int64

	// TCSink, when set, receives every non-nil TC as commits are consumed.
	// Used by NDJSON streaming output. When set, aggregators are not created
	// and FinalizeWithAggregators is not called.
	TCSink analyze.TCSink

	// AggSpillBudget is the maximum bytes of aggregator state to keep in memory
	// before spilling to disk. Computed by ComputeSchedule from the memory budget.
	// Zero means no limit (unlimited budget or budget too small to decompose).
	AggSpillBudget int64

	// TmpDir is the parent directory for temporary spill files.
	// Empty means os.TempDir() (system default).
	TmpDir string

	// StageMetrics provides per-stage counters for memory triage.
	// When non-nil, passed to Coordinator and updated by pipeline stages.
	StageMetrics *StageMetrics
	// contains filtered or unexported fields
}

type SamplerConfig struct {
	Logger       *slog.Logger
	Metrics      *StageMetrics
	DumpDir      string
	ChunkIndex   int
	MemBudget    int64
	ProfileAtRSS int64 // RSS in bytes at which to capture t1 profile. 0 = disabled.
}

type StageMetrics struct {
	// Blob pipeline metrics.
	BlobChangesInFlight atomic.Int64 // Number of file changes being processed.
	BlobBytesLoaded     atomic.Int64 // Total blob bytes loaded in current batch.
	BlobCacheEntries    atomic.Int64 // Current global blob cache entry count.
	BlobCacheBytes      atomic.Int64 // Current global blob cache byte size.

	// Diff pipeline metrics.
	DiffItemsQueued  atomic.Int64 // Diff requests pending in batcher.
	DiffCacheEntries atomic.Int64 // Current diff cache entry count.

	// UAST pipeline metrics.
	UASTItemsQueued atomic.Int64 // UAST parse jobs pending.

	// Runner / aggregator metrics.
	AggregatorBytes  atomic.Int64 // Estimated aggregator state size.
	CommitsProcessed atomic.Int64 // Commits processed in current chunk.
	LastChangeCount  atomic.Int64 // File changes in most recent commit.

	// High-watermarks (updated by Record* methods, never decrease within a chunk).
	PeakBlobChanges atomic.Int64 // Max changes seen in any single commit.
	PeakBlobBytes   atomic.Int64 // Max blob bytes loaded in any single batch.
	PeakDiffQueued  atomic.Int64 // Max diff items queued at any point.
}

type StageMetricsSnapshot struct {
	BlobChangesInFlight int64
	BlobBytesLoaded     int64
	BlobCacheEntries    int64
	BlobCacheBytes      int64
	DiffItemsQueued     int64
	DiffCacheEntries    int64
	UASTItemsQueued     int64
	AggregatorBytes     int64
	CommitsProcessed    int64
	LastChangeCount     int64
	PeakBlobChanges     int64
	PeakBlobBytes       int64
	PeakDiffQueued      int64
}

type StreamingConfig struct {
	MemBudget     int64
	Checkpoint    CheckpointParams
	RepoPath      string
	AnalyzerNames []string

	// Logger is the structured logger for streaming operations.
	// When nil, a discard logger is used.
	Logger *slog.Logger

	// DebugTrace enables 100% trace sampling for debugging.
	DebugTrace bool

	// AnalysisMetrics records analysis-specific OTel metrics (commits, chunks,
	// cache stats). Nil-safe: when nil, no metrics are recorded.
	AnalysisMetrics *observability.AnalysisMetrics

	// TCSink, when set, receives every non-nil TC as commits are consumed.
	// Used by NDJSON streaming output. When set, aggregators are not created
	// and FinalizeWithAggregators is not called — results are nil.
	TCSink analyze.TCSink

	// AggSpillBudget is the maximum bytes of aggregator state to keep in memory
	// before spilling to disk. Computed by ComputeSchedule. Zero means no limit.
	AggSpillBudget int64

	// OnChunkComplete, when set, is called after each chunk finishes processing.
	// Used by streaming timeseries NDJSON to drain per-commit data from aggregators
	// between chunks, keeping memory bounded by chunk size.
	OnChunkComplete func(runner *Runner) error

	// SkipFinalize, when true, causes RunStreaming/RunStreamingFromIterator to
	// return empty reports instead of calling FinalizeWithAggregators. Used when
	// OnChunkComplete already handles output (e.g. streaming timeseries NDJSON).
	SkipFinalize bool

	// ReportStore, when set, causes finalization to write results one-at-a-time
	// to the store via FinalizeToStore instead of materializing all reports in
	// memory via FinalizeWithAggregators. Returns empty reports map.
	ReportStore analyze.ReportStore

	// TmpDir is the parent directory for temporary spill files.
	// Empty means os.TempDir() (system default).
	TmpDir string
}

type UASTPipeline struct {
	Parser     *uast.Parser
	Workers    int
	BufferSize int
	PathFilter *pathfilter.Filter
}