validate

type BuildDeps struct {
	// ExecCommand builds a command whose output this package CAPTURES, in the
	// shape the rest of the repository already uses for an exec seam. It
	// defaults to the package-level execCommand of archive.go.
	ExecCommand func(ctx context.Context, name string, arg ...string) *exec.Cmd

	// RunAttached executes a command and returns its combined output. It is the
	// seam the compile gate needs rather than this one: a long build is streamed
	// and the caller keeps the transcript, which is a different relationship with
	// the child process than "collect stdout and parse it".
	RunAttached func(cmd *exec.Cmd) ([]byte, error)

	// LookPath answers "is this tool installed at all". It is separate from
	// ExecCommand so the absent-binary branch stays reachable in a test on a host
	// that does have Portage — which is every host this is developed on. It
	// defaults to the package-level lookPath of pkgcheck.go.
	LookPath func(name string) (string, error)

	// IsolationProbe measures whether this process can create a network
	// namespace, returning the answer and, when it is no, the reason. It defaults
	// to ProbeIsolation and is consumed by the compile gate.
	IsolationProbe func() (bool, string)
}

type BuildRequest struct {
	// StagedRoot is the staged repository Stage produced — the repo root, the
	// directory holding profiles/ and the candidate's category directory. It is
	// NOT checked for existence here; see RunBuildGates.
	StagedRoot string

	// Key is the registry key as the operator asked about the package:
	// category/package, possibly carrying ":slot" or "@label".
	Key string

	// Version is the candidate version being validated.
	Version string

	// Depth is how far up the ladder to run. It decides the single phase the one
	// invocation runs, and therefore which gates can be derived at all.
	Depth Depth

	// RequireIsolation refuses to run a build this host cannot isolate. It is
	// consumed by the isolation policy rather than by the phase derivation.
	RequireIsolation bool

	// LogDir is where a FAILED run's log is retained. An empty
	// LogDir retains nothing and says so in the gate's reason, because a log
	// nobody was told about is a log nobody will read.
	LogDir string

	// Distdir is the directory this run resolved for the build's archives. It is
	// SET on the child as DISTDIR when it is non-empty.
	//
	// It is a COMPUTED input — resolved BY this run, from --distdir or from the
	// private directory an apply's own manifest step filled — so it is assigned
	// explicitly rather than admitted through allowedBuildEnv, which filters the
	// PARENT's environment. When DISTDIR sat on that allow-list the gate ran
	// against whatever distdir the operator's shell named, and --distdir never
	// reached the fetch. The allow-list keeps meaning one thing: NOTHING crosses
	// in from outside.
	//
	// EMPTY RESOLVES TO NOTHING. No DISTDIR is set and none is invented, so
	// Portage answers from its own configuration — the honest answer for a run
	// that resolved no directory of its own.
	Distdir string
}

type Class int

type Declared struct {
	Root       []Option
	Subproject map[string][]Option
	Sources    []string
}

type DeclineCause string

type Depth int

type DepthDecision struct {
	// Depth is how far this bump is validated.
	Depth Depth
	// Reason names the input that decided and, where one exists, quotes the
	// stated justification. It is never empty.
	Reason string
	// SkippedByPolicy reports that this bump received LESS validation than
	// policy chose for its class, and therefore must be counted as skipped
	// rather than validated. An explicit operator flag never sets it:
	// that is the operator's own instruction, not a package opting out.
	SkippedByPolicy bool
}

type DepthOverride struct {
	// Depth is the depth to use in place of the class default.
	Depth Depth
	// Reason is why this package is not validated the way its class says. It
	// travels into the decision verbatim so the report quotes the operator
	// rather than paraphrasing them.
	Reason string
}

type DepthPolicy struct {
	// ByClass is the depth each bump class earns. A class missing from
	// the map does not mean "no validation": see classDepth.
	ByClass map[Class]Depth
	// Overrides is keyed by the full package atom ("category/package"), the
	// same spelling the registry uses.
	Overrides map[string]DepthOverride
}

type DepthRequest struct {
	// Package is the full atom ("category/package"), used to find an override.
	Package string
	// Class is how far the bump moved, from Classify. Callers must pass the
	// class Classify returns even when it also returns an error — see
	// ClassifyForDepth.
	Class Class
	// ResolvedType is the checker's answer ("bin" or "source"), NOT the raw
	// PackageConfig.Type field. That field is empty for most records and the
	// type is auto-detected from the ebuild (RESTRICT=bindist, a -bin suffix, a
	// binary SRC_URI); a resolver reading the raw field would see "" for almost
	// every binary package in the registry and schedule a compile for a
	// prebuilt blob. It arrives as a plain string because the resolved type
	// lives on autoupdate.CheckResult, and this package cannot import
	// autoupdate without an import cycle.
	//
	// Empty means nobody resolved it. That is NOT the same as "source": an
	// unresolved record keeps every gate its class earns, because losing gates
	// must never be something that happens by omission.
	ResolvedType string
	// Policy is the configured depth table and its per-package exceptions.
	Policy DepthPolicy
	// FlagDepth is `--depth`, nil when the operator did not give it. It is a
	// pointer because DepthNone is a meaningful value an operator may ask for,
	// and the zero value would otherwise be indistinguishable from "unset" —
	// the one confusion that switches validation off in silence.
	FlagDepth *Depth
	// Compile is `--compile`, which is exactly `--depth=compile`.
	Compile bool
}

type EbuildResult struct {
	Package        string       `json:"package"`
	Version        string       `json:"version"`
	Depth          string       `json:"depth"`
	DepthRequested string       `json:"depth_requested"`
	DepthReason    string       `json:"depth_reason,omitempty"`
	Gates          []GateResult `json:"gates"`
	Sources        []string     `json:"sources"`
	// Notes are facts about how the result was reached that no gate carries,
	// rendered under the ebuild's row.
	Notes []string `json:"notes,omitempty"`
}

type Finding struct {
	Gate     string   `json:"gate"`
	Severity Severity `json:"severity"`
	Detail   string   `json:"detail"`
}

type GateResult struct {
	Gate     string    `json:"gate"`
	Outcome  Outcome   `json:"outcome"`
	Reason   string    `json:"reason,omitempty"`
	Findings []Finding `json:"findings,omitempty"`

	// Declined is why a SKIPPED gate declined. It is meaningless on PASS and
	// FAILED, which measured something and therefore declined nothing.
	Declined DeclineCause `json:"-"`
}

type Option struct {
	Name       string // "aalib"
	Subproject string // "" for the root project
	Source     string // archive member or ebuild line it was read from
}

type Options struct {
	// Overlay is the tree to validate.
	Overlay string
	// Distdir names the directory to read archives from. Empty falls through to
	// the host's own `portageq distdir` — see distfiles.Locate, which never
	// creates the directory and never proves it writable.
	//
	// There is no configured rung between the two, because no configuration key
	// exists for it; the command passes --distdir here or nothing.
	Distdir string
	// Selector is "", "<category>" or "<category>/<package>". Empty validates
	// every ebuild in the overlay.
	Selector string
	// Depth is how far up the ladder this run goes, spelled the way `--depth`
	// and the config key spell it: none, options, patches, configure, compile
	// or install, each including every rung before it.
	//
	// EMPTY MEANS "options", AND THAT IS THE WHOLE COMPATIBILITY PROMISE.
	// Every caller written before the ladder existed leaves this field
	// zero, and each of them asked for exactly the static option gate. ParseDepth
	// refuses "" rather than answering DepthNone, precisely so a mistyped key
	// cannot switch validation off in silence — so the empty-to-options mapping
	// is made HERE, once, instead of being left to each caller to remember.
	//
	// It is a string and not a Depth so the word the operator typed survives into
	// the run and can be quoted back at them when it does not parse.
	Depth string
	// StagingRoot is the directory a run above DepthOptions prepares its staged
	// trees under, <StagingRoot>/<category>/<package>/<version>.
	//
	// It is unused at or below DepthOptions, which is why a --depth-less run
	// leaves it empty: the static gate reads files that are already on disk and
	// writes nothing, and a scratch directory nothing uses is a directory that
	// should not be created.
	//
	// IT MAY NOT RESOLVE INSIDE THE OVERLAY, and Stage refuses one that does
	// rather than trusting its callers: ScanOverlay walks the overlay
	// category/package deep and Reconcile turns every ebuild no registry pin
	// claims into a deletion candidate, so a staged tree parked under the overlay
	// root would be reported as a defect by this very command and deleted by
	// `overlay autoupdate --clean`.
	StagingRoot string

	// RequireIsolation refuses to run a build this host cannot isolate, exactly
	// as BuildRequest.RequireIsolation does for the applier — it IS that field,
	// carried to the one caller that had no way to set it.
	//
	// IT EXISTS BECAUSE ITS ABSENCE WAS A POLICY BYPASS, not a missing feature.
	// `autoupdate.validate.require_isolation` is honoured by the identical gates
	// under `overlay autoupdate`, and those gates were once unreachable from
	// `overlay validate`: every one of them SKIPPED, so nothing
	// this command did could be unisolated. Wiring the seams made them run, and
	// a build path that ignores the setting is not a command missing an option —
	// it is the operator's decision that builds must be isolated, silently not
	// applying to one of the two commands that build.
	//
	// The zero value is false, which is the shipped behaviour of both commands
	// when the key is unset: an unisolated build still runs and its pass
	// is labelled "unverified isolation" rather than refused, because creating
	// the namespace needs privilege an ordinary user does not have.
	RequireIsolation bool

	// DistNames answers, for ONE package directory, which upstream archives the
	// option gate may look for. It is the seam for a directory that cannot name
	// them itself — a staged tree has no Manifest until a manifest step runs, so
	// without it the gate would read nothing and report SKIPPED.
	//
	// NIL IS NOT AN EMPTY SLICE. Nil means nobody supplied anything: the gate
	// parses pkgDir/Manifest and the report is byte-identical to the one before
	// this field existed. A non-nil function returning no names is an ANSWER —
	// the caller looked and there is nothing to read — and is never quietly
	// replaced by a Manifest the caller has already spoken for.
	//
	// It is a func of pkgDir, never a bare []string, because one Run walks MANY
	// packages: a flat list would answer each ebuild with whichever name matched,
	// a confident verdict about the wrong tarball. It is per-CALL, never a field
	// on an applier, because a seam stored once would hand package A's names to
	// package B — a race under concurrent applies, wrong later under sequential
	// ones.
	DistNames func(pkgDir string) ([]string, error)

	// Logger receives the run's diagnostics. Nil discards them.
	Logger *slog.Logger

	// StagedManifest answers, for ONE package directory, the Manifest content
	// that package's STAGED tree must carry before a build gate can run in it.
	//
	// The caller owns it because this package cannot: Portage refuses an ebuild
	// whose Manifest does not describe its archive, Stage deliberately does not
	// copy the published Manifest (it describes the published versions), and
	// the step that GENERATES one, `pkgdev manifest`, lives in package
	// autoupdate, which imports this one — importing back would be a cycle.
	//
	// NIL MEANS NOTHING TRAVELS: nothing staged, nothing written, every build
	// gate SKIPPED naming what stopped it. A non-nil function's bytes are written
	// verbatim, because Portage VERIFIES their digests.
	//
	// A same-version caller (`overlay validate --depth`) feeds the PUBLISHED
	// Manifest, which describes the archive on disk; a bump caller feeds the
	// GENERATED one, since the published digests belong to the release being
	// replaced. It is a per-CALL func of pkgDir for the reasons DistNames gives.
	StagedManifest func(pkgDir string) ([]byte, error)

	// LogDir is where a FAILED build gate's whole transcript is retained.
	//
	// The gate's findings quote only a SUMMARY; the transcript holds everything
	// the phase printed — the compiler invocation, preceding warnings, the exact
	// line of a generated file — and is often what turns "configure failed" into
	// a diagnosis. It does NOT decide whether the findings name the cause: that
	// is failureExcerpt's selection, over the in-memory transcript, so a gate
	// names a removed upstream option with or without a LogDir.
	//
	// Empty retains nothing and the gate's reason says so, so the operator is
	// told the log was not kept rather than left to wonder. It is a plain
	// directory, not a func of pkgDir: one place for the whole run, and
	// RunBuildGates already names each log after its atom and version.
	LogDir string
}

type Outcome string

type Passed struct {
	Project    []Option
	BuiltIn    []Option
	Unresolved []Unresolved
}

type PreparedBuild struct {
	// StagedRoot is the tree Stage produced, and it is empty only when no tree
	// was ever made. It travels even on the failing paths: the tree exists, and
	// it is where anyone diagnosing this looks first.
	StagedRoot string

	Gates  []GateResult
	Reason string

	// StageErr is non-nil when NO TREE WAS EVER PREPARED — the candidate's bytes
	// could not be read, or Stage refused. It wraps ErrStageUnpreparable on
	// Stage's own paths, which is why it is chained rather than restated: a
	// caller reacts to staging having failed without enumerating the ways it
	// can fail.
	StageErr error

	// GatesErr is non-nil when the gate ladder could not be started or was
	// interrupted. Neither is a verdict on the ebuild — the first is a caller's
	// bug about the REQUEST, the second is a build that ran and was killed — so
	// a caller that records either as "it does not build" is recording something
	// no gate said.
	GatesErr error
}

type PreparedBuildRequest struct {
	// Overlay is the published tree Stage copies the eclasses and profiles out
	// of; StagingRoot is where the single-package repository is built. Stage
	// refuses a staging root that resolves inside the overlay, which is what
	// keeps "never the overlay" a property of the code.
	Overlay     string
	StagingRoot string

	// Key is the registry key — category/package, possibly carrying ":slot" or
	// "@label" — and Version is the version being built. They name the candidate
	// to Portage; nothing here parses them back out of a filename.
	Key     string // registry key: category/package, possibly :slot or @label
	Version string

	// PackageDir is the PUBLISHED package directory the Manifest seam is asked
	// about — not the staged copy. The staged tree is the thing that LACKS a
	// Manifest, which is the whole reason the seam is being asked.
	PackageDir string

	// Ebuild is the candidate's bytes, written into the staged tree as they are.
	//
	// A caller that holds the bytes passes them; there is no path here for a
	// caller that holds only a file, because the one entry point that reads from
	// disk (buildDepthGates) reaches the core directly and keeps its read lazy.
	Ebuild []byte

	// Depth is how far up the ladder to go, passed through unchanged.
	Depth Depth

	// StagedManifest answers, for PackageDir, the Manifest content the staged
	// tree must carry before a build gate can run in it. Nil means NOTHING
	// TRAVELS — nothing is staged and nothing is built — which is exactly the
	// rule Options.StagedManifest states, read from the one helper both go
	// through rather than restated here.
	StagedManifest func(pkgDir string) ([]byte, error)

	// RequireIsolation is carried, not defaulted. The refusal inside
	// RunBuildGates fires only when the request carries it, and a policy that
	// applies to one of the two commands that build is not a policy.
	RequireIsolation bool

	// LogDir is where the whole transcript is kept for whoever has to go past
	// the summary — the run that needs one is exactly the run that FAILED.
	// Empty is still accepted and the gate's reason still says so.
	LogDir string

	// Distdir is the directory the build reads its archives from, set on the
	// child as DISTDIR. It is the caller's answer and never one
	// derived here — see BuildRequest.Distdir for why it travels as a field
	// instead of through the environment.
	//
	// Empty sets nothing and invents nothing, which is the same
	// answer a caller that never knew about this field gets.
	Distdir string

	// Deps is the command seam RunBuildGates and the host probe run through. Its
	// zero value means the real commands, which is what every production caller
	// passes.
	Deps BuildDeps
}

type Report struct {
	Overlay           string         `json:"overlay"`
	Results           []EbuildResult `json:"results"`
	UnmatchedSelector string         `json:"unmatched_selector,omitempty"`
}

type Severity string

type StageRecord struct {
	// Package and Version name the bump, for the human who opens the file. They
	// are deliberately NOT what identifies the record: the path does that,
	// so a tree moved into the wrong directory is already the wrong tree
	// whatever these two say.
	Package string `json:"package,omitempty"`
	Version string `json:"version,omitempty"`

	// ProducedBy names what wrote this record: ProducedByApplier or
	// ProducedByValidate. A record written by a read-only validation run is
	// evidence about a tree's outcome, NOT a licence to publish it.
	//
	// EMPTY MEANS ProducedByApplier, and the read path is where that is said —
	// see ReadStageRecord. Every record already on an operator's disk was
	// written before this field existed, and every one of them came from the
	// applier.
	ProducedBy string `json:"produced_by,omitempty"`

	// Depth is the depth this run SELECTED, which is the depth the gates below
	// were asked to cover — not the depth they reached. Reuse compares it
	// against the depth the promoting run selects, and the comparison is "not
	// below": a compile-deep proof answers a configure-deep question, a
	// options-deep proof does not.
	Depth Depth `json:"depth"`

	// Gates is one entry per gate the run reported, with its outcome and its
	// reason. A record with no gate in it proves nothing and is treated as no
	// record at all — "something was checked" is not a statement anybody can act
	// on.
	Gates []GateResult `json:"gates"`

	// EbuildDigest is the candidate's bytes AS THEY WERE STAGED — before the
	// build fixer edited them.
	//
	// The pre-fixer bytes are the ones that matter, and getting this wrong is
	// invisible: the build fixer edits the staged ebuild in place, so a digest
	// taken from the tree as it stands after a repair would never again match
	// what the next run computes from the overlay, and EVERY bump the fixer
	// touched would revalidate — which are exactly the slow ones, the ones that
	// needed a repair in the first place. The bump would still publish; it would
	// just quietly pay for a second build every time.
	EbuildDigest string `json:"ebuild_digest"`

	// ValidatedDigest is the candidate's bytes AS THE GATES READ THEM, fixer
	// and operator edits included, taken when the record is written for a run
	// whose gates passed. It is empty on any other run. EbuildDigest says which
	// bump the tree is about; this says which bytes were proved, so a staged
	// ebuild edited after its proof no longer matches and is validated again.
	ValidatedDigest string `json:"validated_digest,omitempty"`

	// SubstitutionDigest covers the per-package rewrites the applier applies to
	// the staged candidate after staging it (a tracked commit hash, an auxiliary
	// variable). It is empty when the bump declares none, which is the ordinary
	// case and the reason it is not folded into EbuildDigest: the two runs being
	// compared read the same source ebuild, so only these values can make their
	// candidates differ.
	SubstitutionDigest string `json:"substitution_digest,omitempty"`

	// DistfileDigest is the digest the published package Manifest records for
	// the package's distfiles. It is the one input that is not in the overlay's
	// text at all, and a tarball re-rolled upstream under the SAME name between
	// staging and promotion moves it — at which point every gate's answer was
	// about a source tree that is no longer the one being published.
	DistfileDigest string `json:"distfile_digest,omitempty"`

	// VendorUnpublished names the vendor tarball the proved run generated but did
	// not publish, empty when it generated none or published the one it did. The
	// tree's Manifest digests that tarball, so promoting the tree as it stands
	// would publish an ebuild whose vendor distfile nobody serves; reuse refuses
	// while it is set and the vendor step runs again. A record written before the
	// field existed reads as empty.
	VendorUnpublished string `json:"vendor_unpublished,omitempty"`
}

type StageRequest struct {
	Overlay, StagingRoot, Key, Version string
	EbuildBytes                        []byte
}

type StagedCandidate struct {
	Key     string // registry key: category/package, possibly :slot or @label
	Version string
}

type StagedSweepPlan struct {
	StagingRoot string
	Remove      []string     // trees this sweep would remove, sorted
	Kept        []SweptEntry // everything else, with the reason it stays, sorted
}

type SweepReport struct {
	Removed []string
	Kept    []SweptEntry
}

type SweepRequest struct {
	Overlay     string
	StagingRoot string
	InScope     []StagedCandidate
}

type SweptEntry struct {
	Path   string
	Reason string
}

type Unresolved struct {
	Text string // the text as written, e.g. `-D${plugin}=`
	Line int    // 1-based, so the operator can go straight to it
}