evocoupling

type AdviseOptions struct {
	// MinCorrelation drops pairs below the threshold. Zero keeps every
	// pair the coupling analysis surfaced.
	MinCorrelation float64

	// IncludeLowSupport keeps pairs flagged LowSupport. Off by default:
	// young or sparse histories mark almost every pair low-support, and
	// advisories built on them are noise.
	IncludeLowSupport bool
}

type Advisory struct {
	Touched     string  `json:"touched"`
	Expected    string  `json:"expected"`
	Correlation float64 `json:"correlation"`
}

type AutoSigmaOptions struct {
	// TargetStddev is the desired correlation-estimator standard deviation.
	// Default 0.05 ("two decimal places of stability"). Drives required
	// ESS via required = 1 / TargetStddev². Smaller stddev → larger sigma.
	TargetStddev float64

	// CoveragePercentile selects which point on the ESS distribution
	// across the evaluation grid must meet required ESS. 50 = median
	// ("typical density"), 25 = stricter coverage ("honest in sparse
	// regions"). Range [1, 99]; default 50.
	CoveragePercentile float64

	// EvalPoints is the number of evaluation centerAt timestamps spread
	// uniformly across [WindowStart, WindowEnd]. Default 20; min 3 so the
	// percentile has at least a start/middle/end to interpolate.
	EvalPoints int

	// WindowStart and WindowEnd bound the analysis window. The binary
	// search picks σ in [1 minute, WindowEnd - WindowStart].
	WindowStart time.Time
	WindowEnd   time.Time
}

type AutoSigmaResult struct {
	Sigma             time.Duration
	RequiredESS       float64
	AchievedESSMedian float64
	AchievedESSP25    float64
	LowConfidence     bool
	Reason            string
	DensityCap        time.Duration
}

type CouplingPair struct {
	PackageA      string   `json:"package_a"`
	PackageB      string   `json:"package_b"`
	Correlation   float64  `json:"correlation"`
	PearsonBinned *float64 `json:"pearson_binned,omitempty"`
	NMI           *float64 `json:"nmi,omitempty"`
	Divergence    *float64 `json:"divergence,omitempty"`
	LowSupport    bool     `json:"low_support,omitempty"`
}

type KernelFunc func(delta, sigma time.Duration) float64

type Options struct {
	Sigma   time.Duration
	Kernel  KernelFunc
	MinCorr float64

	// MIEnabled toggles the binned mutual-information metrics. When false
	// (v1 default), Analyze emits only the existing Correlation column
	// and JSON output is byte-stable with pre-MI consumers.
	MIEnabled bool

	// MIMinSupport is the n_11 floor below which a pair is flagged
	// LowSupport. Zero is replaced with defaultMIMinSupport (3) so
	// `Options{MIEnabled: true}` is a sensible call.
	MIMinSupport int

	// WindowStart anchors the presence matrix; commits before it are
	// dropped from the MI computation. Zero value falls back to the
	// earliest commit time in the input — common-case ergonomics.
	WindowStart time.Time
}

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

type PresenceMatrix struct {
	// Bins lists bin start times in chronological order, length n_bins.
	Bins []time.Time
	// Packages lists package names in lexicographic order, length n_packages.
	Packages []string
	// Present is indexed [binIdx][pkgIdx]; true iff Packages[pkgIdx]
	// appeared in any commit during the bin [Bins[binIdx], Bins[binIdx]+binWidth).
	Present [][]bool
}

type TimedPackageSet struct {
	Time     time.Time
	Packages map[string]struct{}
}