overlay

type AddResult struct {
	Added  []string // Successfully added files
	Errors []error  // Errors encountered during add
}

type Authorship int

type AxisFinding struct {
	// Axis is the property that differs: inherit, options, iuse or deps.
	Axis string
	// Detail is what the difference IS, always stated in the same direction —
	// what we added on top of ::gentoo, and what ::gentoo has that we dropped.
	// A bare "the inherit lines differ" would not have told anyone which 85
	// options they had just taken over by hand.
	Detail string
}

type Baseline struct {
	// Repo names the repository the baseline was read from.
	Repo string
	// Version is the version that repository carries: OUR version when it
	// carries it, and the nearest one it does carry otherwise.
	Version string
	// Path is the ebuild the comparison will actually read, so that "which file
	// was this measured against" is answered by the report instead of being
	// re-derived by whoever reads it.
	Path string
	// Distance is how far Version is from ours, in release steps — see
	// versionDistance, which states the unit. It is 0 exactly when the baseline
	// IS our version.
	//
	// It is reported because it bounds how much the comparison is worth: a
	// baseline one patch release away and a baseline three series away are not
	// the same kind of evidence, and against the second one most of the
	// difference may be nothing but the version move between the two. The
	// report must not let them look alike — a difference measured against
	// a far baseline is a question, not a finding.
	Distance int
	// Found reports whether ::gentoo carries the package at all.
	Found bool
	// Unexamined is non-empty when a baseline could not be read, and says why.
	//
	// That is a per-package state and not a run failure, following
	// verifyAgainstLocalContent, which already reads an unreadable ebuild as
	// NotVerified and exits 0 on the principle that absence of evidence is not
	// evidence. Reported as nothing at all, such a package would be
	// indistinguishable from one that matches ::gentoo exactly.
	Unexamined string
}

type CategoryNotFoundError struct {
	Category string
}

type Change struct {
	Type       ChangeType
	Category   string
	Package    string
	Version    string
	OldVersion string // for up/down
}

type ChangeType string

type Classified struct {
	// VersionMove, Ours and Unclassified are the per-class counts. They always
	// sum to the number of hunks returned beside them.
	VersionMove, Ours, Unclassified int
	// Reduced reports that the classification is an attributed one rather than a
	// shrug: either a usable third point was accepted (one of the first two
	// preferences for choosing it), or the baseline is our own version and no version noise was
	// possible in the first place.
	Reduced bool
	// Span is the version distance the third point covers, in the release steps
	// versionDistance measures — the same unit as Baseline.Distance, because the
	// bound compares the two. It is 0 when no third point was offered, and it is
	// reported even when the third point was refused: the refusal is only legible
	// if the width that caused it is printed beside it.
	Span int
}

type Collision struct {
	Target  string        // Full path both sources would be renamed to
	Sources []RenameMatch // Every match mapping to Target, in match order
}

type CollisionError struct {
	Collisions []Collision
}

type CompareOptions struct {
	// OnlyOutdated filters results to only show outdated packages
	OnlyOutdated bool
	// IncludeSynced includes packages that have the same version (up-to-date)
	// When true, StatusUpToDate packages are included in results
	// This is independent of OnlyOutdated - both can be combined
	IncludeSynced bool
	// IncludeNotInRemote includes packages that don't exist in remote
	IncludeNotInRemote bool
	// ProgressCallback, when non-nil, is invoked once per package as that
	// package's comparison completes. done is the cumulative count of packages
	// finished so far and total is the number of packages in the batch.
	// Because CompareWithProvider runs packages concurrently, the callback may
	// fire from multiple goroutines and the per-invocation order is not
	// deterministic; done is sourced from an atomic counter, so the value
	// observed by any single invocation is monotone non-decreasing.
	ProgressCallback func(done, total uint64)
	// Concurrency bounds the number of packages CompareWithProvider processes
	// in parallel. A value <= 0 is treated as DefaultCompareConcurrency.
	Concurrency int
	// Divergence is what the caller knows about each package, keyed by the bare
	// "category/package" atom. The caller builds it once, before the comparison
	// starts, and the comparison only reads it — so it is shared across the
	// per-package goroutines without a lock.
	//
	// Absence from the map IS the unknown state: nothing is recorded about that
	// package, which is not the same as "recorded as not patched". A nil map
	// therefore says nothing is known about anything, which is exactly the
	// degraded mode when the registry cannot be read — and costs no special case.
	Divergence map[string]Divergence
	// OverlayPath is the root of the overlay the compared packages were scanned
	// from. PackageInfo carries only Category/Package/Versions/LatestVersion, so
	// a check that must open the local ebuild gets its overlay-side root here.
	OverlayPath string
	// Redact lists values removed from any recorded failure text with
	// secrets.Scrub, so a token echoed inside an error reaches no report. nil
	// redacts nothing; an empty entry is ignored.
	Redact []string
	// Logger receives the diagnostics of the passes that take these options —
	// the review, realignment and baseline annotations and the review cache
	// they open. nil discards them.
	Logger *slog.Logger
}

type CompareReport struct {
	TotalPackages    int
	ComparedPackages int
	OutdatedCount    int
	NewerCount       int
	UpToDateCount    int
	NotInRemoteCount int
	ErrorCount       int
	Results          []CompareResult

	// Findings is everything the run established for the operator, as VALUES
	// rather than composed, coloured lines. One entry per compared package says
	// how its two versions relate; a package that also carries a divergence, a
	// stale declaration or a registry declaration carries a second entry.
	//
	// It is a MATERIALISED VIEW of Results: compareFindings is a pure function of
	// them, refreshed by CompareWithProvider once sorted and by EstablishFindings
	// after the annotation passes have run — a list built earlier would report a
	// divergence as unproved after the content had proved it ours.
	//
	// The ORDER is Results' (category/package), so no renderer invents its own.
	// Narrowing Results for display (--only-redundant, --only-patched) narrows the
	// TABLE and nothing this field says, as it narrows none of the counts above.
	Findings []Finding

	// Per-Verdict counts sit ALONGSIDE the per-Status counts above and never
	// replace or restate them: the two answer different questions ("how do the
	// versions relate?" vs "what should be done about it?"), so every compared
	// package is counted exactly once on each axis. Deriving either from the
	// other would silently change what the existing summary lines mean.
	VerdictKeepCount        int
	VerdictRedundantCount   int
	VerdictNeedsRebaseCount int
	VerdictUnknownCount     int

	// BaselineSkipped is non-empty when the review could not run at all: no
	// ::gentoo tree could be located, so NOTHING was examined. The text names
	// what was looked for, and MarkBaselineSkipped is what writes it.
	//
	// It is the report's only RUN-level state, and it is deliberately not the
	// per-package one. A baseline that exists but will not read is
	// Baseline.Unexamined on that package alone and never reaches here:
	// collapsing the two would have one unreadable ebuild declare that a run
	// which examined 320 packages examined none.
	//
	// Its ZERO VALUE renders nothing (formatBaselineSkipped), which is what keeps
	// a run that requested no review printing exactly what it printed before.
	// Without it the same run prints "All packages are up-to-date!" over
	// a comparison that never happened.
	BaselineSkipped string

	// NoBaselineCount is how many results ::gentoo carries no version of at all
	// — 84 of 321 packages on the measured overlay. It is written by
	// AnnotateBaseline and is, by construction, the number of Results whose
	// Baseline.Found is false: any second definition would be a second answer to
	// one question.
	//
	// It is a RUN-level count because the per-package fact cannot be printed. A
	// package ::gentoo does not carry has the ZERO Baseline, which is also what
	// a package no review examined has, so a per-package line would say "no
	// baseline" over every row of a plain `overlay compare`. Counted here it is
	// reported once, with its denominator, and renders nothing at 0.
	NoBaselineCount int

	// RealignAsked and RealignNoVerdict are the realignment review's own
	// arithmetic: how many divergences were put to the model, and how many of
	// those came back with no verdict. Both are written by
	// AnnotateRealignVerdicts and by nothing else.
	//
	// The second exists because an unreachable model is EXIT 0 and leaves an
	// EMPTY RealignVerdict on every package it could not judge — which renders as
	// silence, and silence reads as "every divergence was judged and none
	// objected". This is the number that says otherwise, and the first is the
	// denominator without which it cannot be read: 12 unjudged out of 12 and 12
	// out of 237 are different reports.
	//
	// They are RUN-level for the reason NoBaselineCount is: the per-package fact
	// is an absent field, indistinguishable from the same absent field on every
	// row of a plain `overlay compare`. Counted here they are stated once and
	// render nothing at 0.
	RealignAsked     int
	RealignNoVerdict int
	// RealignNoVerdictBy splits RealignNoVerdict by why each divergence came
	// back with no verdict, in the divergence review's words (ReviewFailure).
	// Its values sum to RealignNoVerdict. It is nil when nothing went
	// unanswered, and like the two counts above it is written only by
	// AnnotateRealignVerdicts.
	RealignNoVerdictBy map[ReviewFailure]int

	// Interrupted reports that the run stopped dispatching before it reached the
	// end of the package list it was handed: the context fired mid-scan, so some
	// packages were never compared at all.
	//
	// It is the one RUN-level fact CompareWithProvider writes itself: only the
	// dispatch loop sees the difference between "the list ended" and "we
	// stopped".
	//
	// Complete is !Interrupted, NEVER NotEvaluated == 0: a run cut short just
	// after its LAST package lost nothing, yet was still cut short, and the
	// operator who pressed ctrl+c must not read that it ended normally.
	//
	// The unreached gap is exactly TotalPackages - ComparedPackages, because
	// ComparedPackages++ runs for every result reaching the collector — every
	// status, filtered or not — so only a worker that never ran is missing.
	//
	// The field is not named Complete so that false, the zero value of a
	// hand-built report, means "not interrupted" rather than "cut short".
	Interrupted bool
}

type CompareResult struct {
	Category      string
	Package       string
	LocalVersion  string // Version in Bentoo overlay
	RemoteVersion string // Version in Gentoo repository
	Status        CompareStatus

	// Verdict is the recommendation for this package.
	Verdict Verdict
	// Patched reports that a registry entry declares a divergence worth keeping.
	Patched bool
	// PatchedBy names the registry key that declared it, so a package with
	// several entries says which one is speaking.
	PatchedBy string
	// PatchedReason is the declared text. It is rendered on the declaration line
	// beneath the section (formatVerificationFindings' third case), capped at
	// patchedReasonCap — unlike PatchedBy, which is printed whole.
	PatchedReason string
	// Verified is the outcome of comparing the two ebuilds' bytes. It stays
	// NotVerified unless a content check ran.
	Verified Verification
	// DiffAdded and DiffRemoved are the line counts of that difference, ours
	// against upstream's: added is what our ebuild has and ::gentoo's does not.
	// They are meaningful ONLY when Verified == VerifiedDiffers and are zero
	// otherwise — a check that did not run has no magnitude to report, and a
	// byte-identical pair has none to find.
	//
	// They exist because the bare fact "differs" cannot be acted on. A one-line
	// difference is almost always ::gentoo revising an ebuild in place, without a
	// revbump, after we copied it; a four-hundred-line one is work of our own. The
	// report cannot tell those two apart — see formatVerificationFindings — but
	// the operator can, at a glance, once the size is on the line.
	DiffAdded   int
	DiffRemoved int

	// Authorship is what the overlay's own CONTENT proves about where the
	// difference came from. The two ebuilds' bytes cannot say it — they are
	// symmetric — but the files/ tree beside them can, so this is filled by
	// AnnotateAuthorship (authorship.go) after the comparison, never by it.
	//
	// AuthorshipUnproved, the zero value, means THE REPORT CANNOT TELL. It is
	// never a finding of "the change is upstream's": ::gentoo revises ebuilds in
	// place without a revbump, so a difference nothing here proves may still be
	// entirely ours and merely unprovable from the files. Reading unproved as
	// "not ours" would authorise exactly the removal this check exists to stop.
	Authorship Authorship
	// ProvedBy names the file that proves it, relative to the package directory
	// ("files/<name>"), so the operator can confirm the claim by looking instead
	// of re-deriving the path from what ${FILESDIR} expands to. It is
	// empty whenever Authorship is unproved: there is then no file to name.
	ProvedBy string
	// Review is a MODEL's reading of an undeclared divergence: printed beside the
	// finding and never an input to anything this report decides. It sits
	// on the result for the reason Authorship does — the pass that fills it
	// (AnnotateReviews, review.go) runs after the comparison and writes back onto
	// the report the caller is holding — and it is deliberately a THIRD field
	// beside Authorship rather than a widening of it: Authorship is what the
	// overlay's content PROVES, this is what a model SAYS, and a type that could
	// hold either would let one be read as the other.
	//
	// The zero ReviewNote means NOTHING WAS SAID, exactly as AuthorshipUnproved
	// does: every result no review reached — every `--no-review` run, every run
	// with no `claude` on PATH, every package whose reviewer errored, and every
	// finding that is not an undeclared divergence — carries it, and the renderer
	// prints nothing for it.
	Review ReviewNote
	// Reading is WHETHER ANYBODY READ this result, and when nobody did, why
	// not. It is a FOURTH field rather than something derived from the three
	// above for the reason the doc on Review just gave: the zero ReviewNote
	// covers four unrelated causes at once, so "is Review empty?" answers "no
	// review reached this" and cannot answer "did anybody read this?" — a
	// package nobody asked about and a package whose reviewer was killed both
	// carry the zero note, and only this field tells them apart.
	//
	// It is filled by AnnotateReviews (review.go), the same pass that fills
	// Review. Its zero value, ReadingNotRequested, is what every
	// result that pass never reached already carries, so a run with no review
	// is correct without anything being set.
	Reading Reading

	// LookupCause is why the upstream lookup failed. It is meaningful only when
	// Status == StatusError and is LookupCauseNone otherwise: a lookup that
	// succeeded has no cause to report.
	LookupCause LookupCause
	// ReviewFailure is why the review of this result did not come back. It is
	// meaningful only when Reading == ReadingFailed and is ReviewFailureNone
	// otherwise; Reading keeps its four values. Filled by AnnotateReviews.
	ReviewFailure ReviewFailure
	// FailureText is the full Error() text of whatever failed on this row —
	// the upstream lookup when Status == StatusError, the review when Reading
	// == ReadingFailed — after every CompareOptions.Redact value has been
	// scrubbed from it. It is empty on a row with no failure. It is kept whole
	// here; only a renderer's table cell may cut it.
	FailureText string

	// Baseline is the ::gentoo ebuild this package was measured against.
	// Its zero value is "no review ran, or ::gentoo does not carry this
	// package"; the run-level NoBaselineCount below is what turns the second of
	// those into a number, because the two are indistinguishable per package by
	// construction.
	Baseline Baseline
	// Axes are the structural differences between our ebuild and that baseline
	// — inherit, options, IUSE, dependencies. A nil slice means nothing
	// was compared or nothing differs, which is the same thing to a report that
	// prints only what it found.
	Axes []AxisFinding
	// Classified is what the three-way reduction concluded about the
	// differences: how many fell into each class and how much evidence it had.
	Classified Classified
	// Declarations are the `# BENTOO-DIVERGENCE:` tags our ebuild carries, with
	// Expired decided against the ::gentoo tree. They are the
	// EBUILD axis and never CompareOptions.Divergence, which is the registry
	// one.
	Declarations []DeclaredDivergence
	// RealignVerdict is a MODEL's opinion on whether an undeclared divergence is
	// still justified, and why. It is written by the realignment reviewer and
	// never by AnnotateBaseline: a verdict nobody produced is
	// worse than none, so an unreachable model leaves it empty.
	//
	// It is COMMENTARY. Nothing that decides a Verdict or an exit code may read
	// it, on the same fence DiffAdded/DiffRemoved already sit behind.
	RealignVerdict string
	// Others are the repositories other than ::gentoo that carry this package,
	// for the 84 of 321 packages ::gentoo does not. They are INFORMATIVE
	// ONLY and no realignment is ever proposed from one: a repository
	// outside ::gentoo has not been through the same review.
	//
	// They are filled by OtherRepositories, which needs the list of
	// locally available repositories — something AnnotateBaseline is not given
	// and deliberately does not go looking for.
	Others []OtherRepo
}

type CompareStatus int

type Conflict struct {
	Match    RenameMatch
	Existing string // Path to existing file
}

type ConflictError struct {
	Conflicts []Conflict
}

type Content struct {
	// Result is the finding. Only ContentIdentical may authorise a removal.
	Result ContentResult
	// Reason says why the result is ContentUnverifiable, or what differs when it
	// is ContentDiffers. It is empty when the two copies are identical, since
	// there is nothing to explain. When it names a difference it names the
	// VERSION or the PATH, never just the package: "zed differs" sends the
	// operator to diff a directory, "1.0 differs" sends them to a file.
	Reason string
	// Checked lists the versions actually compared byte for byte, for the plan to
	// print. On a difference the list stops at the version that differed, because
	// the comparison stops there too and claiming to have examined the rest would
	// be a false report.
	Checked []string
}

type ContentResult int

type DeclaredDivergence struct {
	// Axis is the property the divergence is about, AS THE MAINTAINER WROTE IT.
	// The tag's documentation spells it upper-case (`INHERIT:`) and the axis
	// names are lower-case (`inherit`); neither side is authoritative, so nothing is
	// normalised here and every consumer compares it with strings.EqualFold.
	// Rewriting the word would also cost the report the maintainer's own
	// spelling for the sake of a comparison that is one call away.
	Axis string
	// Reason is the maintainer's words, verbatim and uncapped. A declaration
	// without one is what declarations exist to abolish, so an empty Reason never
	// reaches this field: the tag is reported as malformed instead.
	Reason string
	// DropWhen is the condition from the `drop-when:` continuation line, empty
	// when the declaration states none. Empty is the ordinary case — most
	// divergences have no end in sight — and it is NOT an error: inventing a
	// condition would retire a divergence nobody retired.
	DropWhen string
	// Expired reports that DropWhen has been checked against the ::gentoo tree
	// and is met. It is written by EvaluateDeclarations, never by the parser:
	// expiry is a question about the tree, and reading it off the ebuild's own
	// text would answer it from the wrong source.
	Expired bool
}

type Divergence struct {
	// Patched reports that at least one registry entry for this atom declares
	// a divergence that must survive a bump.
	Patched bool
	// Reason is the declared text. It reaches the report through
	// CompareResult.PatchedReason and is capped there, not here: this type
	// carries what the registry said, and the width of a terminal is not its
	// concern.
	Reason string
	// Entry names the registry key that declared it, so a package with several
	// entries says which one is speaking.
	Entry string
}

type DivergenceReviewer interface {
	ReviewDivergence(ctx context.Context, req ReviewRequest) (ReviewNote, error)
}

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

type Effect struct {
	// Text is the sentence, at full length and with its internal whitespace
	// collapsed to single spaces.
	//
	// The collapse is SANITISATION, not layout. Some of this text is a language
	// model's, and the report's structure is its lines — "⚠ " opens a finding
	// this tool stands behind — so a newline inside a summary would forge a
	// second finding line about a package that need not exist. That is true of
	// every line-oriented consumer, including one reading the JSON export, so it
	// is done once here rather than hoped for at each renderer. What is NOT done
	// here is capping: a width is a terminal's business and the export has none.
	Text string
	// Source is where the sentence came from, and so how far it may be trusted.
	Source EffectSource
}

type EffectSource int

type FileChange struct {
	Type   FileType // ebuild, manifest, metadata, files, other
	Name   string   // filename
	Status string   // Added, Modified, Deleted, Renamed, Untracked
}

type FileKind string

type FileType string

type Finding struct {
	// Kind names WHICH finding this is, so a renderer can group, count or
	// suppress a class of them without pattern-matching the prose. It is the
	// one field every producer sets.
	Kind FindingKind

	// Atom is what the finding is about: "<category>/<package>", exactly as an
	// operator types it.
	//
	// It is a FIELD and never a fragment of Detail: an identifier formatted into
	// a sentence cannot be counted, filtered on, used as a lookup key or
	// re-emitted as a JSON field — it can only be printed.
	//
	// It is empty on a RUN-scoped finding, and nowhere else. Exactly one kind is
	// about the run: FindingBaselineSkipped, which says no ::gentoo tree was
	// reached. Naming a package would assert something the run never established
	// about it, and repeating the sentence on all 321 packages would bury the
	// per-package findings. That is NOT a licence for a blank atom elsewhere:
	// renderCompareFindings' section caveat is not a Finding for the same reason
	// (it is about a subset the CALLER chose), and a package-scoped finding with
	// no atom is a bug the tests assert as one.
	Atom string

	// Detail is what was found, in one sentence the producer wrote and NOBODY
	// decorated: no colour, no escape sequence, no leading glyph, no padding, no
	// trailing newline. The "⚠ " that opens a warning today is the renderer's,
	// and so is the atom in front of the colon.
	//
	// It overlaps the fields below on purpose, as report.ManifestTarget.Error
	// does beside its Package: the fields are the FACTS, and this is the
	// producer's own sentence over them, kept verbatim so today's rendered line
	// survives unchanged and a later rewrite has a before to diff against.
	//
	// A divergence's EFFECT and its provenance are NOT flattened in here; they
	// are Effect below. "ours: files/nodejs-26.7.0-gcc17.patch" tells an operator
	// deciding whether to keep or delete a copy nothing; what must be headlined
	// is what the divergence DOES and who says so, and composed into this string
	// it could never be re-headlined.
	Detail string

	// Version is the overlay's version the finding was established at, and
	// Upstream is ::gentoo's, both empty when the finding is not about a version
	// pair.
	//
	// Two fields rather than one joined string because they are compared, not
	// concatenated: a consumer asking "did the two sides agree?" would otherwise
	// have to split a sentence apart to find out.
	Version  string
	Upstream string

	// Entry is the registry key that declared the divergence — the identifier an
	// operator greps packages.toml for — and empty when nothing declared one.
	//
	// It is printed VERBATIM wherever it is printed: a shortened key looks usable
	// and is not, which is worse than printing none. See patchedReasonCap, which
	// makes the opposite call about the reason for the opposite reason.
	Entry string

	// Added and Removed are the size of the difference between our ebuild and
	// ::gentoo's, ours against upstream's, and are zero on every finding that has
	// no difference to measure.
	//
	// They DESCRIBE and never decide: a large diff authorises nothing and
	// a small one forbids nothing. compare_diff_counts_fence_test.go holds that
	// mechanically over CompareResult's own DiffAdded/DiffRemoved, and these two
	// are named differently precisely so the fence keeps watching the source of
	// truth rather than a copy of it — a copy nobody may compute on either, but
	// one whose misuse the fence was never written to catch.
	Added, Removed int

	// Classified is how the three-way reduction divided ONE package's
	// differences — how many were attributed to the version move, how many to
	// us, how many to neither — together with how far the attribution reached.
	// Its zero value means NOTHING WAS CLASSIFIED, which is every package of
	// every run that asked for no baseline review, and is the same predicate
	// (`== (Classified{})`) that keeps those runs' rendering unchanged.
	//
	// It is the STRUCT and not a sentence, for the reason Atom is a field: "17
	// differences against the baseline, 4 of them attributed to nobody" cannot be
	// summed across a run, key a consumer's threshold, or reach a JSON export
	// without its digits being parsed back out. Detail is the sentence over it.
	//
	// It DESCRIBES and never decides, like Added and Removed: a large
	// unclassified count authorises no realignment and forbids none. Reduced and
	// Span are carried with the three counts because they are read TOGETHER — a
	// third point refused for being too wide and one never offered both
	// attribute nothing, and only the span tells them apart.
	Classified Classified

	// Authorship is what the overlay's own CONTENT proved about where a
	// difference came from. Its zero, AuthorshipUnproved, means THE REPORT CANNOT
	// TELL and is never "the change is upstream's" — which is exactly the
	// "nothing was established" zero every optional field here needs.
	Authorship Authorship

	// ProvedBy names the file that proves it, package-relative ("files/<name>"),
	// so the claim is confirmed with one `ls`. It is empty whenever Authorship is
	// unproved: there is then no file to name.
	//
	// It is SECONDARY EVIDENCE and not the headline. A filename proves authorship
	// and says nothing about what the divergence does, which is what an operator
	// deciding to keep or delete needs — see Effect.
	ProvedBy string

	// Effect is what the divergence DOES and whose sentence that is, held as two
	// values so a renderer can say which it is reading.
	//
	// This is the field the standing knowledge about `overlay compare` asks for
	// by name. Its zero — no text, EffectUnstated — is an honest "not known", and
	// a renderer meeting it says so rather than filling the silence.
	Effect Effect

	// Origin is which side a MODEL read the divergence as coming from. Its zero,
	// OriginUnknown, means nothing was said, which is every run no review
	// reached.
	//
	// It sits beside Effect rather than inside it because they are not the same
	// claim: Effect.Text is what the difference does, Origin is where it came
	// from, and a model can be useful about one while saying nothing about the
	// other. It is COMMENTARY in both cases — nothing that decides a verdict or
	// an exit code may read it.
	Origin ReviewOrigin

	// Proposal is the `patched` declaration a model offered for a divergence it
	// read as ours, empty otherwise.
	//
	// It is carried AT FULL LENGTH. The rendered line caps it at
	// patchedReasonCap so one model's essay cannot decide the width of the
	// report, and that cap is the RENDERER's: a value truncated on the way into
	// the report is truncated in the JSON export too, where there is no width to
	// respect and nothing to un-truncate it from.
	Proposal string
}

type FindingKind int

type Hunk struct {
	// Class is version-move, ours or unclassified, and is never empty on a hunk
	// this package returns: every difference lands in exactly one class, which
	// is what makes the three counts add up to the number of differences.
	Class string
	// Start and End are the half-open line range the hunk replaces in the
	// baseline, 1-based.
	Start, End int
	// Text is the hunk in both hands: every baseline line prefixed "-", then
	// every line of ours prefixed "+". It carries NO line numbers, and that is
	// what makes it comparable across two different diffs — a version move
	// shifts every line below it, so a hunk that matched by position would stop
	// matching as soon as anything above it changed size.
	Text string
}

type LocalRepo struct {
	// Name is the repository as the registry names it — "guru", not "::guru";
	// the report adds the "::" it prints.
	Name string
	// Path is the root of its tree, the directory <Path>/<category>/<package>
	// would be found under. It is read only when Available is true.
	Path string
	// Available reports that the repository's CONTENTS are on disk at Path.
	//
	// "Registered", "resolvable by name" and "configured with a URL" are none of
	// them available: nothing on this machine holds the tree, and the only true
	// answer the report can give about such a repository is that it was not
	// checked.
	Available bool
}

type LookupCause int

type ManifestOptions struct {
	// Keep, if true, leaves the existing Manifest in place and lets pkgdev
	// reconcile it. By default, the existing Manifest is moved to a backup
	// before regeneration and restored only on failure (clean regen).
	Keep bool
	// DryRun, if true, lists the packages that would be processed without
	// running pkgdev or touching files.
	DryRun bool
	// Distdir, when non-empty, is used as pkgdev's --distdir. The path is
	// expanded (~ and relative paths) and created if missing, and is
	// preserved across runs as a persistent download cache. When empty,
	// a temporary directory is created under os.TempDir() and removed
	// when the run completes.
	Distdir string
	// Jobs is the maximum number of pkgdev invocations to run in parallel.
	// Values <= 0 fall back to DefaultManifestJobs. Internally clamped to
	// the number of targets so we never spin idle workers.
	Jobs int
	// DistfilesCache, when non-empty, points to a read-only distfiles cache
	// (typically /var/cache/distfiles) that is consulted before each pkgdev
	// invocation. For every DIST entry listed in the package's existing
	// Manifest, if a file with the same name exists in this cache, a symlink
	// is created in the working distdir so pkgdev can reuse it instead of
	// downloading. Empty string disables the optimization entirely. The
	// cache is never written to.
	DistfilesCache string
	// Reporter receives lifecycle events as workers process targets.
	// Nil means silent (no progress output) — it is normalized to tui.Noop().
	// The CLI typically wires a live TUI or plain reporter here.
	Reporter tui.Reporter
	// Summary composes the sentence the run's batch closes on, from the result
	// the caller is about to receive. Nil closes the batch with no wording at
	// all, which is what `overlay autoupdate` already passes today.
	//
	// It is a function because the words are the CALLER's and the numbers are
	// the run's: nothing is known to summarize until the last worker has
	// finished, inside this package, so the run supplies the facts when it has
	// them and the caller supplies the wording it chose.
	//
	// The library still relays the call because BatchStart is emitted inside
	// the run: a batch opened here and closed by the caller would stay open on
	// every path a caller forgets, and the Reporter's consumers would need a
	// case for a run that never ends.
	//
	// The four paths that return before the worker loop — an empty selection, a
	// preview, and the two pre-flight refusals — open no batch, so they never
	// reach this at all; a --dry-run emits no lifecycle event of any kind.
	Summary func(ManifestResult) string
}

type ManifestResult struct {
	// Updates is one entry per target the run FINISHED EVALUATING, in the order
	// the targets were given.
	//
	// On a run that reached the end of its list that is every target it was
	// handed. On an interrupted one it is short, and the two fields below are
	// what account for the difference — see Interrupted for why the missing
	// targets are absent rather than present and marked.
	Updates []ManifestUpdate
	// NotEvaluated is how many of the targets the run was handed it never
	// established an outcome for: the ones it never started, and the ones whose
	// pkgdev was still running when the run was cancelled.
	//
	// It is a fact about the RUN, which is why it is a field beside Updates
	// rather than a method over it: nothing in the slice can say how long the
	// slice was supposed to be. Its zero value is the honest answer for every
	// run that finished, and for a ManifestResult a caller assembled by hand.
	//
	// The report envelope carries the same number under the same name
	// (report.Run.NotEvaluated) so the mapping is a copy rather than a
	// translation — one less place for the two to drift apart.
	NotEvaluated int
	// Interrupted reports that the run stopped before reaching the end of its
	// target list.
	//
	// # It is separate from NotEvaluated, and both are needed
	//
	// A run cancelled in the instant after its LAST target completed lost
	// nothing: NotEvaluated is zero and the run was still cut short. Deriving
	// "was it interrupted" from "is the gap zero" would report that run as a
	// complete one, and the operator who pressed ctrl+c would be told their run
	// finished normally.
	//
	// # False is the safe zero value, which is why the field is not named Complete
	//
	// A ManifestResult built by hand — in a test, or by a caller wrapping a
	// slice — gets false, and false here means "not interrupted". A Complete
	// bool would default to "this run was cut short" and quietly draw the
	// interrupted block over every such report.
	Interrupted bool
}

type ManifestScope struct {
	Category string
	Package  string
}

type ManifestUpdate struct {
	Category string
	Package  string
	Success  bool
	// Error is the failure as the SENTENCE the formatters print, and it
	// deliberately carries no atom: FormatManifestResult and FormatRenameResult
	// both write "<category>/<package>: " immediately before it, so a copy of
	// the atom in here would be printed twice on every failure line.
	Error string
	// Err is that same failure as a VALUE — the cause wrapped with %w and with
	// the category/package that produced it.
	//
	// It exists beside Error rather than replacing it because a string is a
	// dead end: it cannot be unwrapped, it cannot be matched with errors.Is,
	// and a caller that needs to know WHICH failure it holds is reduced to
	// searching text for a phrase. It carries the atom although Error does not,
	// because an error travels on its own — into a log line, into another wrap,
	// into a report row assembled long after the loop that produced it — and an
	// error that has left the row naming its package cannot be reproduced.
	//
	// Nil on success, and nil only on success: "did this target fail?" is
	// answered by Success and Err agreeing, never by whether a field happens to
	// have been populated.
	Err error
	// Output is what the failing command printed — pkgdev's own diagnostic,
	// verbatim, including the "[bentoo] reused N distfile(s)" line the run
	// injects into the same stream. It is the text the operator acts on, and by
	// the time a report is rendered the terminal that streamed it live is gone.
	//
	// It is populated ONLY on failure. The capture is a verbatim, unbounded copy
	// of every byte the child wrote — a package fetching a large distfile can
	// emit megabytes of progress output — and a whole-overlay run would hold one
	// per target for as long as the caller holds the slice. A successful
	// target's output has no reader to justify that: it was already streamed
	// through the Reporter while the target ran.
	Output string
	// Reused is the number of distfiles symlinked from the distfiles cache
	// (e.g. /var/cache/distfiles) into the working distdir, sparing pkgdev
	// from re-downloading them. Zero when no cache is configured or no
	// matching files were found.
	Reused int
}

type MatchResult struct {
	Matches  []RenameMatch
	Warnings []string
}

type OtherRepo struct {
	// Name is the repository as the registry names it — "guru", not "::guru";
	// the report adds the "::" it prints.
	Name string
	// Version is the version that repository carries, empty when it carries
	// none. It is meaningless unless Checked is true.
	Version string
	// Checked reports that the repository's contents were actually read. False
	// means NOT CHECKED — the repository is registered but not available
	// locally — and never "it does not carry the package".
	Checked bool
}

type PackageStatus struct {
	Category string
	Package  string
	Changes  []FileChange
}

type PatternValidator struct{}

type PruneBatch struct {
	// Identical is the default batch — redundant by version, undeclared, and
	// byte-identical. Every plan in it is Eligible.
	Identical []PrunePlan
	// Diverging holds the packages that carry something of ours, declared or not.
	// They are planned and printed either way; they are Eligible only under
	// --include-patched.
	Diverging []PrunePlan
	// Refused holds everything no flag may act on, each with its reason.
	Refused []PrunePlan
}

type PruneClass int

type PruneOptions struct {
	// OverlayPath is the root of the overlay being pruned. Our side of every
	// comparison is OverlayPath/category/package.
	OverlayPath string
	// IncludePatched is the --include-patched flag: the operator saying out loud
	// that they accept discarding local work. It moves nothing between
	// classes — it only decides whether the diverging batch is Eligible.
	IncludePatched bool
	// RegistryKeys maps "category/package" to every registry key for that atom.
	// It is SUPPLIED by the caller and never looked up here, which is what keeps
	// this package free of an import edge to internal/autoupdate.
	//
	// Nothing is ever joined from one of these keys into a filesystem path.
	// SplitPackageKey now refuses a "." or ".." half, but the structure is what
	// keeps traversal absent here, not that check.
	RegistryKeys map[string][]string
}

type PrunePlan struct {
	// Category and Package come from the compare result, which comes from the
	// overlay scan. They are the only two names any path here is built from.
	Category string
	Package  string

	// Versions is every version in OUR directory — not the versions that were
	// compared. Removing the directory removes all of them, including the ones
	// ::gentoo never carried, and a plan listing only the compared ones would
	// understate the removal.
	Versions []string

	// Files is every file under the package directory, as a path RELATIVE to it:
	// the plan prints category/package as its heading, so repeating it on every
	// line is noise.
	//
	// Manifest and metadata.xml ARE listed even though the comparison ignores
	// them. They are not evidence about whether the copy is ours, but the
	// removal deletes them all the same, and a plan that hid them would understate
	// what it is about to do.
	//
	// Directories are not listed as entries of their own: the overlay is a git
	// tree, git cannot carry an empty directory, so every directory the removal
	// takes has at least one file listed under it.
	Files []string

	// RegistryKeys are the registry entries that would be deleted with the
	// package, exactly as the caller supplied them — every one of them, since 90
	// of 321 atoms carry more than one entry and leaving one behind orphans it.
	// This package never looks them up: internal/overlay does not know what TOML
	// is, which is the layering rule.
	RegistryKeys []string

	// Eligible is what THIS RUN may do about the package: true only when the
	// class, the flags and the evidence all allow a removal. A false Eligible on a
	// planned package is not an error — it is the plan saying "here it is, and
	// here is why I am leaving it alone".
	Eligible bool

	// Class is what the evidence says. See PruneClass.
	Class PruneClass

	// Reason says why the package was refused, or what diverges. It is empty only
	// for PruneIdentical, where there is nothing to explain; every Refused and
	// every Diverging plan carries one.
	Reason string
}

type PruneResult struct {
	// Plan is the plan this result is about, carried whole so the caller can name
	// the package, and reach its RegistryKeys, without keeping its own index into
	// the batch it handed over.
	Plan PrunePlan

	// Removed is true only when os.RemoveAll returned without error. It is the
	// caller's authority to delete the package's registry entries:
	// the entry goes only for a package whose directory actually went.
	Removed bool

	// Err is why the removal did not happen — a refusal by the guard, or what
	// os.RemoveAll returned.
	//
	// Err is non-nil EXACTLY when Removed is false. The two are one fact seen from
	// two sides, and a result where they disagree leaves the caller unable to say
	// whether the package is still on disk — while its next act is deleting that
	// package's registry entries. A "removed with an error" would orphan the
	// directory; a "not removed, no error" would orphan the entry.
	Err error
}

type PullMode int

type PullResult struct {
	Success       bool     // True if the pull completed without conflicts
	UpToDate      bool     // True if the branch was already current with upstream
	CommitsPulled int      // Number of commits the upstream was ahead by
	Branch        string   // Branch that was pulled into
	Upstream      string   // Upstream ref the commits came from (e.g. "origin/master")
	Conflicts     []string // List of conflicting file paths
	Message       string   // Human-readable status message
}

type PushResult struct {
	UpToDate bool   // True if nothing was pushed (already up-to-date)
	Message  string // Status message from git
}

type Reading int

type RealignNote struct {
	// Justified is the model's answer: does the divergence still earn its place?
	//
	// It is a plain bool with no third state, and Why below is what keeps that
	// honest: a note with no reason says nothing at all (realignNoteSpeaks), so
	// "false" can never arrive by default and be read as a judgement.
	Justified bool `json:"justified"`
	// Why is the model's reason, in its own words. A verdict without one
	// is an instruction rather than an input — "not justified" with nothing
	// behind it cannot be checked, argued with, or acted on — so a note that
	// carries no Why is treated as no note.
	Why string `json:"why"`
	// BaselineText is the ::gentoo text that would replace the divergence when
	// the model judges it unjustified. It is a PROPOSAL printed on a
	// terminal: nothing here writes it into an ebuild, because the overlay
	// auto-commits and a write would be a publish.
	//
	// It is empty for a divergence the model considers justified — there is then
	// nothing to replace — and may also be empty on an unjustified one, which
	// the report says rather than hides.
	BaselineText string `json:"baseline_text"`
}

type RealignRequest struct {
	// Category, Package and Version identify the package for the reviewer's
	// prose. They are NOT part of the cache's index: the verdict is a reading of
	// the two files, and the same two files are the same question.
	Category, Package, Version string
	// Ours is our overlay ebuild at Version; Baseline is the ::gentoo ebuild it
	// was measured against. The ORDER is meaningful — the answer is about what
	// OURS carries on top of the baseline — so a request with the two swapped
	// would invert the judgement.
	Ours, Baseline []byte
}

type RealignReviewer interface {
	ReviewRealignment(ctx context.Context, req RealignRequest) (RealignNote, error)
}

type RenameError struct {
	Match   RenameMatch
	Message string
}

type RenameMatch struct {
	Category    string // e.g., "media-plugins"
	Package     string // e.g., "gst-plugins-base"
	OldFilename string // e.g., "gst-plugins-base-1.24.11-r1.ebuild"
	NewFilename string // e.g., "gst-plugins-base-1.26.10.ebuild"
	OldPath     string // Full path to old file
	NewPath     string // Full path to new file
	HasRevision bool   // True if old filename had -rN suffix
}

type RenameOptions struct {
	DryRun     bool // Simulate without executing
	SkipPrompt bool // Skip confirmation prompts
	NoManifest bool // Skip Manifest updates
	Force      bool // Proceed despite warnings
}

type RenameResult struct {
	Matches         []RenameMatch    // All found matches
	Renamed         []RenameMatch    // Successfully renamed
	Failed          []RenameError    // Failed operations
	VersionFiles    []VersionFile    // Version-specific files detected
	Conflicts       []Conflict       // Target files that already exist
	Collisions      []Collision      // Targets shared by two or more matches
	ManifestUpdates []ManifestUpdate // Manifest update results
	Warnings        []string         // Non-fatal scan warnings
}

type RenameSpec struct {
	Category       string // "*" for all categories, or specific category
	PackagePattern string // Glob pattern for package names
	OldVersion     string // Exact old version to match
	NewVersion     string // New version to rename to
}

type RepoFileChange struct {
	Type ChangeType // Add, Del, Mod
	Kind FileKind
	Path string // path relative to overlay root (e.g. "eclass/rpm.eclass")
	Name string // filename only (e.g. "rpm.eclass")
}

type ReviewFailure int

type ReviewNote struct {
	// Origin is where the divergence came from, as the model read it.
	Origin ReviewOrigin `json:"origin"`
	// Summary is one line saying what the divergence does.
	Summary string `json:"summary"`
	// Declaration is proposed `patched` text for the registry. It is
	// empty unless Origin is OriginOverlay: there is nothing of ours to declare
	// about a change that is not ours. It is a PROPOSAL — text on a terminal,
	// never a file.
	Declaration string `json:"declaration"`
}

type ReviewOrigin int

type ReviewRequest struct {
	// Category, Package and Version identify the package for the reviewer's
	// prose. They are NOT part of the cache's index: the classification is a
	// reading of the two files, keyed on their content alone.
	Category, Package, Version string
	// Ours and Theirs are the two ebuilds at Version — ours from the overlay,
	// theirs from ::gentoo — read through resolvePackagePaths, the one path
	// construction in this package. The ORDER is meaningful: Origin below names a
	// side, so a request with the two swapped would invert the answer.
	Ours, Theirs []byte
}

type ValidationError struct {
	Pattern string // The pattern that failed validation
	Reason  string // Human-readable explanation of why validation failed
}

type ValidationResult struct {
	Valid    bool     // True if overlay structure is valid
	Errors   []string // Critical issues that prevent operation
	Warnings []string // Non-critical issues
}

type Verdict int

type Verification int

type VersionFile struct {
	Category string
	Package  string
	Path     string
	Filename string
}

type VersionFilesBlockError struct {
	Files []VersionFile
}

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

type VersionMove struct{ From, To string }