Documentation
¶
Overview ¶
Package federate provides multi-repo fan-out for go-code: resolve a repo pattern to a list of repos, then run per-repo primitives and correlate in Go. The go-code AGE graph is per-repo, so cross-repo signals are computed by fan-out + merge, never by a merged graph.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsRepoWarm ¶
IsRepoWarm reports whether repo root has a live (non-expired) touches entry.
Types ¶
type CrossPair ¶
type CrossPair struct {
RepoA string `json:"repoA"`
FileA string `json:"fileA"`
RepoB string `json:"repoB"`
FileB string `json:"fileB"`
CoChanges int `json:"coChanges"`
Score float64 `json:"score"`
G2 float64 `json:"g2"`
Significance string `json:"significance"`
Confidence float64 `json:"confidence"`
ConfidenceLevel string `json:"confidenceLevel"`
}
CrossPair is two files in DIFFERENT repos that change together within a window.
func CrossRepoCoChange ¶
func CrossRepoCoChange(ctx context.Context, repos []RepoRef, asOf time.Time, windowHours, minPairs int, minLift float64) []CrossPair
CrossRepoCoChange finds file-pairs spanning DIFFERENT repos that change within windowHours of each other, at least minPairs times, with raw lift optionally floored at minLift.
Per repo it runs one `git log --name-only --pretty=format:%x00%ct`, parses (timestamp, files), and buckets each (repo, file) touch into a window of windowHours. Two touches from different repos in the same bucket form a cross-repo co-occurrence. Pairs are counted at bucket level (a window where both appear counts as +1 regardless of how many touches each file has in that window), which is what the G² statistic assumes.
Ranking is by Wilson lower bound on directional confidence (support-aware, continuous, never saturates):
score = wilsonLowerBound(co, min(winA,winB), z)
wilsonLowerBound(pos, n, z) continuously penalizes thin support: a perfect rare coincidence (co=2, winA=winB=2, score≈0.34) ranks well below a well-supported loose coupling (co=8, winA=winB=10, score≈0.49). The score grows monotonically with more evidence and is never distorted by file rarity.
Ubiquitous files (touched in >85% of windows — CHANGELOGs, lockfiles, generated files) are dropped as stop-words by a binary pre-filter before scoring. The 85% threshold is intentionally high: genuine couplings often involve active files (touched in 60-70% of windows), so a lower threshold would wrongly suppress real signal.
G²/significance are informational (un-capped): the Dunning log-likelihood and its chi-square label are available for diagnostic use but do not drive ranking. Confidence = co / min(winA, winB); confidenceLevel is derived from the Wilson score via score.ConfidenceFromScore.
minLift is an optional raw-effect-size pre-filter (co·N / (winA·winB)); default 0 = no filter. Raw lift is NOT emitted in the result (it is an internal filter only) because it is an uninformative foot-gun for consumers: low-support pairs can have arbitrarily high lift.
Returns nil when fewer than 2 repos, a non-positive window, or no touches (best-effort, like CollectCoupling — a repo whose git log fails is skipped).
The fixed ts/windowSec bucketing is a coarse approximation: two commits a second apart but across a bucket boundary are missed. Accepted for "roughly coordinated changes"; a sliding window would be heavier (YAGNI here).
func CrossRepoCoChangeFromTouches ¶
func CrossRepoCoChangeFromTouches(ctx context.Context, touches []touch, windowHours, minPairs int, minLift float64) []CrossPair
CrossRepoCoChangeFromTouches computes cross-repo pairs from a pre-collected slice of touches. Separated from CrossRepoCoChange so the resilience layer can feed pre-warmed touches without re-running git log. Exported for use by the deadline-race partial-result path in the tool handler.
type RepoRef ¶
type RepoRef struct {
Slug string // basename of the repo dir (e.g. "acme-web"); not unique across a result set if the same basename exists under two localDirs
Root string // absolute local path
}
RepoRef identifies one repo in a federated set.
func ResolveRepos ¶
ResolveRepos expands a pattern into a list of RepoRef.
- "all" → every git repo directly under localDirs
- "<glob>" → repos whose basename matches the glob (filepath.Match)
- "<abs path>" → that single repo (must be a git repo)
A pattern that is an absolute path to an existing git repo is treated as a single explicit repo. localDirs are the parent directories holding checkouts (deps.LocalRepoDirs, e.g. /host/src).
type RepoTouch ¶
type RepoTouch struct {
// contains filtered or unexported fields
}
RepoTouch is one (repo, file) change at a committer timestamp. Exported so the resilience layer in the tool handler can pass pre-warmed touches to CrossRepoCoChangeFromTouches without re-running git log.
func WarmTouches ¶
WarmTouches returns the cached touches for root, or nil when the cache is cold. Returns a copy; callers may append to the result safely.
Source Files