ci

type BlockPathRule ¶ added in v1.3.0

type BlockPathRule struct {
	ID       string
	Patterns []string
}

BlockPathRule fails for any path written by any layer that matches one of Patterns. Whiteout markers (`.wh.<name>` per-file tombstones and `.wh..wh..opq` opaque-directory markers) are skipped — they represent deletion events, not writes; the actual blob is in whichever earlier layer added the file, which this rule will surface there.

Whiteout detection is name-based, not DiffType-based, because per-layer trees (`Layer.Tree`) come straight from `image.ParseLayerTar` which leaves every node at the default `DiffType=Unchanged`. Removed status is only assigned downstream in stack.go / compare.go, against stacked or comparison trees this rule does not consume. The DiffType==Removed skip remains as defensive symmetry for callers that hand-construct trees with explicit deletion markers.

func (r BlockPathRule) Evaluate(ctx EvalContext) []RuleResult

func (r BlockPathRule) Name() string

type DenyWastePathRule ¶ added in v1.3.0

type DenyWastePathRule struct {
	ID       string
	Patterns []string
}

DenyWastePathRule fails for any wasted file (LayerCount >= 2) whose path matches one of Patterns. Reads ctx.Efficiency.WastedFiles directly.

func (r DenyWastePathRule) Evaluate(ctx EvalContext) []RuleResult

func (r DenyWastePathRule) Name() string

type EvalContext ¶ added in v1.3.0

type EvalContext struct {
	Efficiency   *image.EfficiencyResult
	TotalSize    int64
	Layers       []image.Layer
	StackedTrees []*image.FileTree
}

EvalContext bundles everything a rule might need to evaluate. Carrying Layers and StackedTrees on the context (rather than threading them through every rule's signature) keeps the existing efficiency-only rules simple while letting path-aware rules walk per-layer trees.

Layers and StackedTrees may be nil — efficiency-only tests don't need them, and rules MUST nil-check before iterating.

type HighestUserWastedPercent ¶

type HighestUserWastedPercent struct {
	Threshold float64
}

HighestUserWastedPercent fails if wasted bytes as a fraction of total size exceed the threshold. A threshold of 0 disables this rule (always passes).

func (r HighestUserWastedPercent) Evaluate(ctx EvalContext) []RuleResult

func (r HighestUserWastedPercent) Name() string

type HighestWastedBytes ¶

type HighestWastedBytes struct {
	Threshold int64
}

HighestWastedBytes fails if wasted bytes exceed the threshold. A threshold of 0 disables this rule (always passes).

func (r HighestWastedBytes) Evaluate(ctx EvalContext) []RuleResult

func (r HighestWastedBytes) Name() string

type LowestEfficiency ¶

type LowestEfficiency struct {
	Threshold float64
}

LowestEfficiency fails if the efficiency score is below the threshold. A threshold of 0 (or any non-positive value) disables this rule. A NaN score (e.g. an empty image with zero total bytes) is treated as a pass — the rule cannot meaningfully evaluate a non-finite score.

func (r LowestEfficiency) Evaluate(ctx EvalContext) []RuleResult

func (r LowestEfficiency) Name() string

type MaxLayerCountRule ¶ added in v1.3.0

type MaxLayerCountRule struct {
	ID       string
	MaxCount int
}

MaxLayerCountRule fails for any wasted file appearing in more than MaxCount layers. MaxCount of 0 disables the rule (always passes) — the config layer prevents 0 in practice, but a defensive guard avoids divide-by-nothing surprises if a caller constructs a zero-value rule.

func (r MaxLayerCountRule) Evaluate(ctx EvalContext) []RuleResult

func (r MaxLayerCountRule) Name() string

type Report ¶

type Report struct {
	Passed   bool
	Results  []RuleResult
	TopWaste []image.WastedFile
	Score    float64
}

Report holds the results of all rule evaluations.

func Evaluate(ctx EvalContext, rules []Rule) *Report

func (r *Report) ExitCode() int

func (r *Report) Print(w io.Writer)

PASS: Image efficiency check passed (score: 95%)

FAIL: Image efficiency check failed

Global Rules:
  efficiency:    85.0% (threshold: 90.0%)  FAIL
  wasted bytes:  12 MB (threshold: 50 MB)  PASS

Path Rules:
  block:         /var/lib/apt/lists/x  layer 3 (abc123)  (threshold: /var/lib/apt/lists/**)  FAIL
  deny-waste:    /usr/lib/python/foo.pyc (2 layers, 100 B)  (threshold: **/*.pyc)  FAIL

Top wasted files: …

Exit code: 1

type Rule ¶

type Rule interface {
	Name() string
	Evaluate(ctx EvalContext) []RuleResult
}

Rule evaluates one aspect of image efficiency. A rule may produce multiple RuleResults (e.g. one per matched path for BlockPathRule); efficiency rules always return exactly one.

When invoked through the package-level Evaluate(ctx, rules) function, ctx.Efficiency is guaranteed non-nil — the evaluator nil-guards before running rules so each rule body can dereference ctx.Efficiency directly. Tests calling rule.Evaluate(EvalContext{}) directly must populate ctx.Efficiency themselves; rules nil-check ctx.Layers and ctx.StackedTrees because those are optional even in production.

type RuleKind ¶ added in v1.3.0

type RuleKind int

RuleKind classifies a rule's reporting bucket. Report.Print uses Kind to route results into the "Global Rules:" / "Path Rules:" output sections — each rule stamps Kind onto every RuleResult it emits, so the printer never needs to consult an allowlist or the Rule that produced the result.

const (
	// RuleKindGlobal — rules that evaluate one image-wide property
	// (efficiency score, total wasted bytes). Always emit a single
	// RuleResult; render under the "Global Rules:" section.
	RuleKindGlobal RuleKind = iota

	// RuleKindPath — rules that match against per-layer trees or wasted
	// files. Emit one RuleResult per finding (or one PASS result if no
	// findings); render under the "Path Rules:" section.
	RuleKindPath
)

type RuleResult ¶

type RuleResult struct {
	RuleID    string
	Name      string
	Kind      RuleKind
	Passed    bool
	Actual    string
	Threshold string
	Detail    string
}

RuleResult holds the outcome of evaluating a single rule.

• RuleID identifies the specific finding for log-grep / future --rule-id filtering. For globals, RuleID equals Name. For path rules, RuleID typically encodes the location of the finding (e.g. "block:/root/.cache@layer-3" or "deny-pyc:/usr/lib/foo.pyc").
• Name is the human-readable rule kind shown in the report column ("efficiency", "block", "deny-waste"). Multiple findings from the same rule share the same Name.
• Kind controls which output section (Global vs Path Rules) the printer routes the result into.
• Actual / Threshold render in the standard "X (threshold: Y)" format. For path rules, Actual is the bare path; the layer index, count, and byte size live in Detail.
• Detail is optional context shown between Actual and the threshold parens for path rules — file path qualifier, layer location, etc. Globals leave Detail empty; the printer skips it for global results.