ci

package
v0.4.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 3, 2026 License: GPL-3.0 Imports: 4 Imported by: 0

Documentation

Overview

Package ci computes provider-agnostic fan-out plans for CI systems from a magus workspace. CI system wrappers translate the output into their own matrix/pipeline format.

Index

Constants

This section is empty.

Variables

View Source
var ErrInvalidMaxShards = errors.New("ci: max shards must be -1 (unlimited) or a positive integer")

ErrInvalidMaxShards is returned when WithMaxShards receives a value of 0 or any negative integer other than -1 (the sentinel for "unlimited").

Functions

This section is empty.

Types

type DedupEntry

type DedupEntry struct {
	Project     string
	Target      string
	Hash        string
	ExtraBuilds int
	ExtraMs     int64
}

DedupEntry is one (project, target, hash) that was built redundantly across shards, with how many extra builds it caused and the wasted time.

type DedupResult

type DedupResult struct {
	TotalMisses     int
	UniqueKeys      int
	RedundantBuilds int
	RedundantMs     int64
	// Approx is set when some events lack a Hash (older reports), so grouping is
	// by (project, target) only and the count is an approximation.
	Approx bool
	// Top lists redundant keys sorted by wasted time descending.
	Top []DedupEntry
}

DedupResult is the cross-shard redundant-build analysis.

func Dedup

func Dedup(misses []MissBuild) DedupResult

Dedup measures cross-shard redundant builds: when the same (project, target, hash) is a cache miss on more than one shard, those extra builds are waste a shared remote cache would eliminate. Within a single shard's File a key counts once; the longest of the duplicated builds is treated as the necessary one, so the wasted time is total minus max.

type Forecaster

type Forecaster interface {
	Plan(projects []*types.Project, maxShards int) [][]*types.Project
}

Forecaster is the optional adaptive partitioner that replaces ceil-division when supplied to Build. Defined by interface to avoid an import cycle with magus/ci/forecast.

type MissBuild

type MissBuild struct {
	Project    string
	Target     string
	Hash       string
	DurationMs int64
	File       string
}

MissBuild is one cache-miss event, tagged with the shard report File it came from so the same key seen on two shards counts as two builds (and the same key twice within one shard counts once).

type Option

type Option func(*config)

Option mutates the Build configuration.

func WithForecaster

func WithForecaster(f Forecaster) Option

WithForecaster enables adaptive sharding; nil clears it (falls back to ceil-division).

func WithMaxShards

func WithMaxShards(n int) Option

WithMaxShards sets the shard limit; -1 = unlimited (capped at 256); 0 or other negatives return ErrInvalidMaxShards.

type Plan

type Plan struct {
	Shards      []Shard
	Source      string
	MaxParallel int // 0 = no cap (renderers emit max-parallel = len(Shards))
}

Plan is the output of Build: shards for a CI matrix plus source label and concurrency cap.

func Build

func Build(projects []*types.Project, source string, opts ...Option) (Plan, error)

Build partitions projects into at most maxShards shards via ceil-division (or a forecaster).

type Shard

type Shard struct {
	ID       string
	Projects []*types.Project
}

Shard is one runner's worth of work; ID is zero-padded so log entries sort correctly.

Directories

Path Synopsis
Package annotate emits CI job-log structure: the fold markers and the warning/error notices a CI provider recognizes.
Package annotate emits CI job-log structure: the fold markers and the warning/error notices a CI provider recognizes.
Package forecast picks an adaptive CI shard count using a USL model (N* = sqrt(W/α)) and packs projects via LPT bin-packing.
Package forecast picks an adaptive CI shard count using a USL model (N* = sqrt(W/α)) and packs projects via LPT bin-packing.
Package volatility provides Wilson-score volatility prediction and auto-retry for magus test runs.
Package volatility provides Wilson-score volatility prediction and auto-retry for magus test runs.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL