analyze

type AggregationMode int

type AggregationModeAware interface {
	SetAggregationMode(mode AggregationMode)
}

type Aggregator interface {
	// Add ingests a single per-commit result.
	Add(tc TC) error

	// FlushTick finalizes and returns the aggregated result for the
	// given tick. Precondition: tick >= 0.
	FlushTick(tick int) (TICK, error)

	// FlushAllTicks returns TICKs for all ticks that have accumulated data.
	// For per-tick aggregators (byTick map), ticks are sorted ascending.
	// For cumulative aggregators, returns a single TICK with all state.
	// Returns nil, nil when the aggregator has no data.
	FlushAllTicks() ([]TICK, error)

	// Spill writes accumulated state to disk to free memory.
	// Returns the number of bytes freed. A SpillBudget of 0 in
	// AggregatorOptions means no spill limit (keep everything in memory).
	Spill() (int64, error)

	// Collect reloads previously spilled state back into memory.
	Collect() error

	// EstimatedStateSize returns the current in-memory footprint
	// of the aggregator's accumulated state in bytes.
	EstimatedStateSize() int64

	// SpillState returns the current on-disk spill state for checkpoint persistence.
	SpillState() AggregatorSpillInfo

	// RestoreSpillState points the aggregator at a previously-saved spill directory.
	// Called on checkpoint resume before any Add() calls.
	RestoreSpillState(info AggregatorSpillInfo)

	// Close releases all resources. Idempotent.
	Close() error
}

type AggregatorFunc func(opts AggregatorOptions) (Aggregator, error)

type AggregatorOptions struct {
	// SpillBudget is the maximum bytes of aggregator state to keep
	// in memory before spilling to disk. Zero means no limit.
	SpillBudget int64

	// SpillDir is the directory for spill files. Empty means the
	// system default temporary directory.
	SpillDir string

	// Sampling is the commit sampling rate. Zero means no sampling
	// (process every commit).
	Sampling int

	// Granularity is the tick granularity in hours. Zero means the
	// pipeline default.
	Granularity int
}

type AggregatorSpillInfo struct {
	// Dir is the directory containing spill files. Empty if no spills occurred.
	Dir string `json:"dir,omitempty"`

	// Count is the number of spill files written.
	Count int `json:"count,omitempty"`
}

type AnalysisVisitor interface {
	NodeVisitor
	GetReport() Report
}

type Analyzer interface {
	Name() string
	Flag() string
	Descriptor() Descriptor

	// Configuration.
	ListConfigurationOptions() []pipeline.ConfigurationOption
	Configure(facts map[string]any) error
}

type AnalyzerData struct {
	Flag string
	Data map[string]any
}

type AnalyzerMode string

type AnalyzerResult struct {
	ID     string       `json:"id"     yaml:"id"`
	Mode   AnalyzerMode `json:"mode"   yaml:"mode"`
	Report Report       `json:"report" yaml:"report"`
}

type BaseHistoryAnalyzer[M any] struct {
	Desc               Descriptor
	Sequential         bool
	CPUHeavyFlag       bool
	EstimatedStateSize int64
	EstimatedTCSize    int64
	ConfigOptions      []pipeline.ConfigurationOption

	// Hooks.
	ComputeMetricsFn MetricComputer[M]
	TicksToReportFn  func(ctx context.Context, ticks []TICK) Report
	AggregatorFn     func(opts AggregatorOptions) Aggregator

	// Custom format hooks — set these to handle FormatText and FormatPlot
	// without overriding Serialize/SerializeTICKs. When set, the base
	// dispatch checks them before falling through to JSON/YAML/Binary.
	SerializeTextFn func(result Report, writer io.Writer) error
	SerializePlotFn func(result Report, writer io.Writer) error
}

type BaseReportSection struct {
	Title      string
	Message    string
	ScoreValue float64
}

type CommitIdentity interface {
	Hash() gitlib.Hash
	Author() gitlib.Signature
	Committer() gitlib.Signature
	Message() string
}

type CommitLike interface {
	CommitIdentity
	CommitParents
	Tree() (*gitlib.Tree, error)
	Files() (*gitlib.FileIter, error)
	File(path string) (*gitlib.File, error)
}

type CommitMeta struct {
	Hash      string `json:"hash"`
	Timestamp string `json:"timestamp"`
	Author    string `json:"author"`
	Tick      int    `json:"tick"`
}

type CommitParents interface {
	NumParents() int
	Parent(n int) (*gitlib.Commit, error)
}

type CommitStatsDrainer interface {
	// DrainCommitStats returns per-commit summary data and per-tick commit
	// ordering, then clears these maps from the aggregator. Cumulative state
	// (coupling matrices, burndown histories, etc.) remains intact.
	//
	// The returned commitData maps commit hash (hex) to a JSON-serializable
	// summary (same shape as ExtractCommitTimeSeries output for this analyzer).
	DrainCommitStats() (commitData map[string]any, commitsByTick map[int][]gitlib.Hash)
}

type CommitTimeSeriesProvider interface {
	// ExtractCommitTimeSeries extracts per-commit data from a finalized report.
	// Returns a map of commit hash (hex string) to a JSON-serializable value.
	// Returns nil if no per-commit data is available.
	ExtractCommitTimeSeries(report Report) map[string]any
}

type Context struct {
	Time    time.Time
	Commit  CommitLike
	Index   int
	IsMerge bool

	// Changes contains the tree diff changes for this commit.
	Changes gitlib.Changes

	// BlobCache maps blob hashes to cached blobs.
	// Populated by the runtime pipeline for efficient blob access.
	BlobCache map[gitlib.Hash]*gitlib.CachedBlob

	// FileDiffs maps file paths to diff data for modified files.
	// Populated by the runtime pipeline using native C diff computation.
	FileDiffs map[string]plumbing.FileDiffData

	// UASTChanges contains pre-computed UAST changes for this commit.
	// Populated by the UAST pipeline stage when enabled.
	UASTChanges []uast.Change

	// UASTSpillPath is the path to a spilled UAST gob file for large commits.
	// When set, UASTChanges is nil and the changes must be deserialized from disk.
	UASTSpillPath string
}

type Descriptor struct {
	ID          string
	Description string
	Mode        AnalyzerMode
}

type DirectStoreWriter interface {
	WriteToStoreFromAggregator(ctx context.Context, agg Aggregator, w ReportWriter) error
}

type DistributionItem struct {
	Label   string  // Category label (e.g., "Simple (1-5)").
	Percent float64 // Percentage as 0-1.
	Count   int     // Absolute count.
}

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

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

type GenericAggregator[S any, T any] struct {
	Opts       AggregatorOptions
	ByTick     map[int]S
	SpillStore *spillstore.SpillStore[S]

	// Delegate Hooks.
	ExtractTCFn  func(TC, map[int]S) error
	MergeStateFn func(S, S) S
	SizeStateFn  func(S) int64
	BuildTickFn  func(int, S) (TICK, error)

	// DrainCommitDataFn extracts and clears per-commit data from a tick
	// accumulator state. Returns summarized per-commit data and commit ordering.
	// When nil, DrainCommitStats returns nil (CommitStatsDrainer not satisfied).
	DrainCommitDataFn func(S) (map[string]any, map[int][]gitlib.Hash)
}

type HistoryAnalyzer interface {
	Analyzer

	// Core analysis methods.
	Initialize(repository *gitlib.Repository) error

	// Consumption. Returns a TC with per-commit result data.
	// Plumbing analyzers return zero-value TC (Data: nil).
	Consume(ctx context.Context, ac *Context) (TC, error)

	// Memory sizing for the planner.
	// WorkingStateSize returns the estimated bytes of analyzer-internal
	// working state accumulated per commit (maps, treaps, matrices).
	WorkingStateSize() int64
	// AvgTCSize returns the estimated bytes of TC payload emitted per commit.
	AvgTCSize() int64

	// Aggregation. NewAggregator creates a per-analyzer aggregator that
	// collects TCs into TICKs. Returns nil when no aggregator is available.
	NewAggregator(opts AggregatorOptions) Aggregator
	// SerializeTICKs writes aggregated TICKs in the given format.
	// Returns ErrNotImplemented when not yet wired.
	SerializeTICKs(ticks []TICK, format string, writer io.Writer) error

	// ReportFromTICKs converts aggregated TICKs into a Report.
	// Returns ErrNotImplemented for analyzers without aggregators.
	// ctx is used for cancellation and tracing (e.g. tree.Files() I/O).
	ReportFromTICKs(ctx context.Context, ticks []TICK) (Report, error)

	// Branching support.
	Fork(n int) []HistoryAnalyzer
	Merge(branches []HistoryAnalyzer)

	// Formatting/Serialization.
	// Format can be: "yaml", "json", or "binary" (protobuf).
	Serialize(result Report, format string, writer io.Writer) error
}

type Issue struct {
	Name     string // Item name (e.g., function name).
	Location string // File location (e.g., "pkg/foo/bar.go:42").
	Value    string // Metric value (e.g., "12").
	Severity string // "good", "fair", "poor", or "info".
}

type ItemConverter func(items any, sourceFile string) []map[string]any

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

type MergedCommitData struct {
	Hash      string         `json:"hash"`
	Timestamp string         `json:"timestamp"`
	Author    string         `json:"author"`
	Tick      int            `json:"tick"`
	Analyzers map[string]any `json:"-"`
}

type MergedTimeSeries struct {
	Version       string             `json:"version"`
	TickSizeHours float64            `json:"tick_size_hours"`
	Analyzers     []string           `json:"analyzers"`
	Commits       []MergedCommitData `json:"commits"`
}

type Metric struct {
	Label string // Display label (e.g., "Total Functions").
	Value string // Pre-formatted value (e.g., "156").
}

type MetricComputer[M any] func(Report) (M, error)

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

type NDJSONLine struct {
	Hash      string `json:"hash"`
	Tick      int    `json:"tick"`
	AuthorID  int    `json:"author_id"`
	Timestamp string `json:"timestamp"`
	Analyzer  string `json:"analyzer"`
	Data      any    `json:"data"`
}

type NodeVisitor interface {
	OnEnter(n *node.Node, depth int)
	OnExit(n *node.Node, depth int)
}

type Parallelizable interface {
	// SequentialOnly returns true if this analyzer cannot be parallelized
	// (e.g. it tracks cumulative state across all commits).
	SequentialOnly() bool

	// CPUHeavy returns true if this analyzer's Consume() is CPU-intensive
	// (e.g. UAST processing) and benefits from W parallel workers.
	// Lightweight analyzers return false and run on the main goroutine
	// to avoid fork/merge overhead.
	CPUHeavy() bool

	// SnapshotPlumbing captures the current plumbing output state.
	// Called once per commit after core analyzers have run.
	// The returned value is opaque to the framework.
	SnapshotPlumbing() PlumbingSnapshot

	// ApplySnapshot restores plumbing state from a previously captured snapshot.
	// Called on forked copies before Consume().
	ApplySnapshot(snapshot PlumbingSnapshot)

	// ReleaseSnapshot releases any resources owned by the snapshot
	// (e.g. UAST trees). Called once per snapshot after all leaves
	// in the worker have consumed it.
	ReleaseSnapshot(snapshot PlumbingSnapshot)
}

type PlotRenderer func(model UnifiedModel, writer io.Writer) error

type PlumbingSnapshot any

type PreparationConfig struct {
	// Tick0 is the time of the first commit (for tick calculation).
	Tick0 time.Time
	// TickSize is the duration of one tick.
	TickSize time.Duration
	// PeopleDict maps author keys to author IDs.
	PeopleDict map[string]int
}

type PreparedCommit struct {
	Ctx       *Context
	Changes   []*gitlib.Change
	Cache     map[gitlib.Hash]*gitlib.CachedBlob
	FileDiffs map[string]pkgplumbing.FileDiffData
	Index     int
	Err       error
	// AuthorID is the resolved author identifier.
	AuthorID int
	// Tick is the time tick for this commit.
	Tick int
}

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

type Report = map[string]any

type ReportMeta struct {
	AnalyzerID string `json:"analyzer_id"`
	Version    string `json:"version"`
	SchemaHash string `json:"schema_hash"`
}

type ReportReader interface {
	// Meta returns the metadata for this analyzer's report.
	Meta() ReportMeta

	// Kinds returns the list of record kinds stored for this analyzer.
	Kinds() []string

	// Iter calls fn for each raw record of the given kind.
	// Iteration stops early if fn returns a non-nil error.
	Iter(kind string, fn func(raw []byte) error) error

	// Close releases resources. Idempotent.
	Close() error
}

type ReportSection interface {
	// SectionTitle returns the display title (e.g., "COMPLEXITY").
	SectionTitle() string

	// Score returns a 0-1 score, or ScoreInfoOnly for info-only sections.
	Score() float64

	// ScoreLabel returns formatted score (e.g., "8/10" or "Info").
	ScoreLabel() string

	// StatusMessage returns a summary message (e.g., "Good - reasonable complexity").
	StatusMessage() string

	// KeyMetrics returns ordered key metrics for display.
	KeyMetrics() []Metric

	// Distribution returns distribution data for bar charts.
	Distribution() []DistributionItem

	// TopIssues returns the top N issues/items to highlight.
	TopIssues(n int) []Issue

	// AllIssues returns all issues for verbose mode.
	AllIssues() []Issue
}

type ReportSectionProvider interface {
	CreateReportSection(report Report) ReportSection
}

type ReportStore interface {
	// Begin starts writing records for the given analyzer.
	Begin(analyzerID string, meta ReportMeta) (ReportWriter, error)

	// Open opens a reader for the given analyzer's stored records.
	Open(analyzerID string) (ReportReader, error)

	// AnalyzerIDs returns the ordered list of analyzer IDs in the store.
	AnalyzerIDs() []string

	// Close releases store-level resources. Idempotent.
	Close() error
}

type ReportWriter interface {
	// Write appends one typed record under the given kind.
	Write(kind string, record any) error

	// Close finalizes the write. After Close, the data is durable.
	// Idempotent: second call is a no-op.
	Close() error
}

type ResultAggregator interface {
	Aggregate(results map[string]Report)
	GetResult() Report
}

type SectionRendererFunc func(report Report) ([]plotpage.Section, error)

type SpillThresholdSetter interface {
	SetSpillThreshold(threshold int)
}

type SpilledUASTRecord struct {
	ChangeIndex int
	Before      *node.Node
	After       *node.Node
}

type StateSizer interface {
	EstimatedStateSize() int64
}

type StaticAnalyzer interface {
	Analyzer

	Analyze(root *node.Node) (Report, error)
	Thresholds() Thresholds

	// Aggregation methods.
	CreateAggregator() ResultAggregator

	// Formatting methods.
	FormatReport(report Report, writer io.Writer) error
	FormatReportJSON(report Report, writer io.Writer) error
	FormatReportYAML(report Report, writer io.Writer) error
	FormatReportPlot(report Report, writer io.Writer) error
	FormatReportBinary(report Report, writer io.Writer) error
}

type StaticProgressEvent struct {
	FilesProcessed int64
	RSSBytes       int64
	AggregatorSize int64
	Phase          string
}

type StaticProgressFunc func(event StaticProgressEvent)

type StaticRenderer interface {
	// SectionsToJSON converts report sections to a JSON-serializable value.
	SectionsToJSON(sections []ReportSection) any

	// RenderText writes human-readable text output for the given sections.
	RenderText(sections []ReportSection, verbose, noColor bool, writer io.Writer) error

	// RenderCompact writes single-line-per-section compact output.
	RenderCompact(sections []ReportSection, noColor bool, writer io.Writer) error
}

type StaticService struct {
	Analyzers []StaticAnalyzer

	// MaxWorkers limits the number of concurrent file analysis goroutines.
	// Zero means use min(runtime.NumCPU(), DefaultStaticMaxWorkers).
	MaxWorkers int

	// MallocTrimInterval is the number of files between native memory trim calls.
	// Zero means use DefaultMallocTrimInterval. Negative disables trimming.
	MallocTrimInterval int

	// NativeMemoryReleaseFn is called periodically to release native memory.
	// Defaults to gitlib.ReleaseNativeMemory when nil.
	NativeMemoryReleaseFn func()

	// AggregationMode controls whether per-item data is collected during aggregation.
	// Full (default) collects all data. SummaryOnly skips per-item collection.
	AggregationMode AggregationMode

	// SpillThreshold overrides the default spill-to-disk threshold on aggregators.
	// Zero means use the aggregator default. Derived from --memory-budget.
	SpillThreshold int

	// ProgressFunc is called at pipeline milestones when non-nil.
	// Called every ProgressInterval files during processing, and once after completion.
	ProgressFunc StaticProgressFunc

	// ProgressInterval is the number of files between progress callbacks.
	// Zero means use DefaultProgressInterval.
	ProgressInterval int

	// Renderer provides section-based output rendering.
	// Must be set before calling FormatJSON, FormatText, FormatCompact, or RunAndFormat.
	Renderer StaticRenderer
}

type StoreSectionRendererFunc func(reader ReportReader) ([]plotpage.Section, error)

type StoreWriter interface {
	WriteToStore(ctx context.Context, ticks []TICK, w ReportWriter) error
}

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

type TC struct {
	// CommitHash identifies the analyzed commit.
	CommitHash gitlib.Hash

	// Tick is the time-bucket index this commit belongs to.
	Tick int

	// AuthorID is the numeric identity of the commit author.
	AuthorID int

	// Timestamp is the commit's author time.
	Timestamp time.Time

	// Data carries the analyzer-specific per-commit payload.
	// The concrete type is defined by each analyzer.
	Data any
}

type TCSink func(tc TC, analyzerFlag string) error

type TICK struct {
	// Tick is the time-bucket index.
	Tick int

	// StartTime is the earliest commit timestamp in this tick.
	StartTime time.Time

	// EndTime is the latest commit timestamp in this tick.
	EndTime time.Time

	// Data carries the analyzer-specific aggregated payload.
	// The concrete type is defined by each aggregator.
	Data any
}

type Thresholds = map[string]map[string]any

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

type TypedCollection struct {
	Items      any           // concrete typed slice (e.g., []FunctionMetrics).
	SourceFile string        // stamped by StampSourceFile.
	ToMaps     ItemConverter // deferred converter.
}

type UnifiedModel struct {
	Version   string           `json:"version"   yaml:"version"`
	Analyzers []AnalyzerResult `json:"analyzers" yaml:"analyzers"`
}

type VisitorProvider interface {
	CreateVisitor() AnalysisVisitor
}