manifestanalyzer

type Acceptance struct {
	// Accepted is true only when no blocking refusal was found.
	Accepted bool
	// Issues names every refusal, each carrying the offending file and document so a
	// human (and GitTarget status) can resolve it. Empty when Accepted.
	Issues []AcceptanceIssue
	// Retained lists the allowlisted documents kept outside the managed model. It is
	// informational: retention never blocks acceptance on its own (only a managed
	// file that shares bytes with one does, via IssueMixedFile).
	Retained []RetainedDocument
}

type AcceptanceIssue struct {
	Kind          IssueKind `json:"kind"`
	Path          string    `json:"path"`
	DocumentIndex int       `json:"documentIndex"`
	Message       string    `json:"message"`
	// Solvable says whether anyone can make this folder acceptable with the current
	// release, and Actor names who. Both are decided by the check that RAISED the issue,
	// because only that check knows: several kinds answer differently depending on which
	// branch emitted them. Actor is empty unless Solvable.
	Solvable bool  `json:"solvable"`
	Actor    Actor `json:"actor,omitempty"`
	// Field and Token add structured diagnostics for a render-fidelity refusal. They are empty
	// for structural acceptance issues, which predate the render-vs-live gate.
	Field string `json:"field,omitempty"`
	Token string `json:"token,omitempty"`
}

type AcceptancePolicy struct {
	// Allowlist names the non-API KRM kinds retained outside the managed model. It
	// is applied at store-build time (buildStoreFS), so allowlisted documents never
	// enter FilesByPath; the gate only refuses a managed file that illegally shares
	// bytes with one.
	Allowlist Allowlist
	// InScope reports whether a resolved resource belongs to this GitTarget's scope.
	// A nil predicate means "no scope restriction": every resolved resource is in
	// scope. The controller injects a namespace-aware predicate (M7); the CLI passes
	// nil.
	InScope func(types.ResourceIdentifier) bool
}

type AcceptanceRefusedError struct {
	Issues []AcceptanceIssue
}

type Actor string

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

type CauseKind string

type Class string

type Classification struct {
	Solvable bool
	Actor    Actor
}

type DesiredResource struct {
	Resource types.ResourceIdentifier
	Object   *unstructured.Unstructured
}

type DocumentCause struct {
	Kind   CauseKind `json:"kind,omitempty"`
	Detail string    `json:"detail,omitempty"`
}

type DocumentModel struct {
	// ManifestIdentity is the EFFECTIVE content identity (apiVersion + kind +
	// namespace + name). For a namespace-less namespaced resource it may carry a
	// namespace inherited from a kustomization.yaml that references the document
	// through its resources graph; NamespaceSource records that provenance.
	ManifestIdentity manifestedit.Identity

	// NamespaceSource records where ManifestIdentity.Namespace came from: the file
	// itself, a kustomization context, or nowhere (absent and unsupplied/ambiguous).
	// See NamespaceSourceKind.
	NamespaceSource NamespaceSource

	// Overrides is the unambiguous kustomize images/replicas override chain
	// governing this document's file, in build order — nil when no supported
	// render root supplies one, or when distinct roots disagree (the
	// ambiguous-kustomize-overrides diagnostic). The writer routes a live change
	// produced by one of these entries back to the entry instead of writing it
	// through into the source document. See
	// docs/design/support-boundary/finished/images-and-replicas-edit-through.md.
	Overrides *KustomizeOverrides

	// Rendered is what kustomize ACTUALLY renders this document to, plus which override
	// entry supplied each override-produced value — the values read off the real render, the
	// suppliers read off a dyed counterfactual one. It is what the write-side projection
	// inverts against, and it replaced ~400 lines that re-implemented kustomize's
	// transformers in order to guess the same thing.
	//
	// Nil when no render root supplies a chain, when distinct roots disagree, or when the
	// dyed build could not be trusted (see attributeRoot). Nil means NO ATTRIBUTION: the
	// writer routes nothing to an entry, and the verification re-render adjudicates whatever
	// the source document alone can carry. See
	// docs/design/support-boundary/render-attribution.md.
	Rendered *RenderedOverrides

	// ResourceIdentity is the API-side identity (GVR + namespace + name). It is set
	// only when the injected GVK->GVR mapper resolves the document's GVK to a single
	// served, allowed resource; structure-only analysis (and any unresolved lookup)
	// leaves it nil.
	ResourceIdentity *types.ResourceIdentifier

	// Mapping records why ResourceIdentity is or is not set, derived from the
	// followability registry. Structure-only analysis is always MappingNoSource
	// because no API source is wired in.
	Mapping MappingOutcome

	// MappingRefusal carries the solvability of a MappingNotFollowable outcome, decided
	// where the registry answer is still in hand. A GVK the registry has never heard of
	// is a CRD the platform operator can install; a GVK it knows but will not follow —
	// ambiguous, unserved, missing a verb — is not something either side can solve. The
	// acceptance gate sees only the outcome, so the split has to be recorded here.
	MappingRefusal Classification

	// Editable is false for SOPS-encrypted or otherwise non-patchable documents;
	// Cause carries the structured reason.
	Editable bool

	// Cause is the structured reason behind Editable — never free-text
	// classification. CauseNone for a cleanly editable document.
	Cause DocumentCause

	// Snapshot is the lazy body handle. It is unbuilt (zero) until a plan action
	// touches the document; identity indexing needs only a cheap header parse.
	Snapshot manifestedit.SnapshotRef
}

type DocumentReport struct {
	Index    int                   `json:"index"`
	Class    Class                 `json:"class"`
	GVK      GVK                   `json:"gvk"`
	Identity manifestedit.Identity `json:"identity"`
	Editable bool                  `json:"editable"`
	// Cause is the structured reason a KRM document is not cleanly editable
	// (encrypted, non-editable construct). It is nil for an editable document and
	// for non-KRM/empty/invalid rows. Duplicate identity is no longer a per-document
	// attribute — it surfaces as an acceptance issue and a diagnostic instead.
	Cause *DocumentCause `json:"cause,omitempty"`
}

type EntryRole int

type FileModel struct {
	// Path is the file location relative to the scanned root.
	Path string

	// Documents are every managed document in the file, in document order.
	Documents []*DocumentModel

	// Original and Current are hydrated lazily at the commit boundary, and only for
	// the files a batch touches — they are nil for every untouched file, so the
	// resident store is byte-free. Structure-only analysis never hydrates, so both
	// stay nil.
	Original []byte // worktree bytes once hydrated; nil for a new or unhydrated file
	Current  []byte // bytes after applying plan actions; nil means "delete this file"
}

type FileReport struct {
	Path      string           `json:"path"`
	IsYAML    bool             `json:"isYaml"`
	Documents []DocumentReport `json:"documents,omitempty"`
}

type FolderScan struct {
	YAMLFiles    []manifestedit.FileContent
	NonYAML      []string
	Foreign      []ForeignEntry
	Ignore       *IgnoreMatcher
	IgnoreIssues []AcceptanceIssue
	Diagnostics  []manifestedit.Diagnostic
}

type ForeignEntry struct {
	Path string      `json:"path"`
	Kind ForeignKind `json:"kind"`
}

type ForeignKind string

type GVK struct {
	Group   string `json:"group"`
	Version string `json:"version"`
	Kind    string `json:"kind"`
}

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

type ImageOverride struct {
	// Source is the kustomization file path (slash) that declares the entry.
	Source string
	// Index is the entry's position within its file's images: sequence, so the
	// writer can pin the exact entry even when two entries share a name.
	Index int
	// Name matches an image whose name equals it at that point in the build chain.
	Name string
	// NewName / NewTag / Digest replace the matched image's components; each is
	// meaningful only when its Has* flag is set.
	NewName string
	NewTag  string
	Digest  string
	// HasNewName / HasNewTag / HasDigest record which keys the entry declares.
	HasNewName bool
	HasNewTag  bool
	HasDigest  bool
}

type IssueKind string

type KustomizationInfo struct {
	// Path is the kustomization.yaml's own file path (slash), relative to the
	// scanned root.
	Path string

	// Resources holds the resources + bases entries exactly as written (local file
	// names, child-directory bases, or remote URLs), in file order. It is the raw
	// text, not resolved paths — cleanJoin resolves an entry against Path's directory.
	Resources []string

	// Unsupported is true when the kustomization uses a feature outside the
	// supported subset (hasUnsupportedKustomizeFeature) or a remote base, or is
	// unparseable. The writer must never edit an unsupported kustomization.
	Unsupported bool

	// Namespace is the kustomization's namespace: transformer value, empty when
	// it sets none. A new document placed directly in this kustomization's
	// directory (resolveKustomizeRoot) omits metadata.namespace when this is
	// set, exactly as an existing document in this context already does.
	Namespace string
}

type KustomizeOverrides struct {
	Images   []ImageOverride
	Replicas []ReplicaOverride
}

type Layout string

type ManifestStore struct {
	// Root is the scanned root, mirroring Report.Root. It is informational and
	// empty for an in-memory fs.FS.
	Root string

	// FilesByPath holds only managed files — those with at least one tracked KRM
	// document. A FileModel therefore always has at least one document until its
	// last is dropped, at which point Current goes nil and Deleted() fires.
	FilesByPath map[string]*FileModel

	// Indexes hold pointers into FilesByPath, not (path, index) pairs, so a
	// document delete that shifts a file's slice never invalidates them.
	//
	// ByManifestIdentity is single-valued: it is collected first-occurrence-wins
	// over the documents that CLAIM their identity (the collapse), so a later
	// document that duplicates an earlier identity is not the winner and is
	// detectable as such. Claiming mirrors manifestedit's duplicate rule exactly —
	// cleanly-editable and encrypted documents claim, documents with disallowed
	// constructs do not — so the collapse and manifestedit's duplicate diagnostic
	// agree. The diagnostic is emitted by the manifestedit index pass that feeds the
	// collapse.
	ByManifestIdentity map[manifestedit.Identity]*DocumentModel
	// ByResourceIdentity is populated once the GVK->GVR mapper resolves resource
	// identities (Track B / B3). It is empty under structure-only analysis.
	ByResourceIdentity map[types.ResourceIdentifier]*DocumentModel
	// ByGVK groups every managed document by its derived GroupVersionKind. It is
	// multi-valued: many resources of one kind are normal.
	ByGVK map[schema.GroupVersionKind][]*DocumentModel

	// Diagnostics are the scan- and index-level diagnostics gathered while building
	// the store, in scan order (scan diagnostics first, then per-document index
	// diagnostics).
	Diagnostics []manifestedit.Diagnostic

	// Retained holds the allowlisted non-API KRM documents (build directives such as
	// kustomization.yaml) recognised during the scan but deliberately kept OUT of
	// FilesByPath and the indexes — exactly like non-YAML auxiliary files. They have
	// no document set to empty, so they can never be swept, edited, or planned. They
	// are recorded only so the acceptance gate can name them and refuse a managed
	// file that illegally shares its bytes with one (a mixed file). It is empty
	// unless the store was built with a non-empty allowlist.
	Retained []RetainedDocument

	// Kustomizations indexes every kustomization.yaml found under the scanned root by
	// its directory (slash, relative to the root; "." for the root itself). New-file
	// placement consults it to decide whether a candidate directory is
	// kustomize-governed and, if so, which file's resources: list a new sibling must
	// be added to. Populated independent of the allowlist — build-directive discovery
	// does not depend on which files the writer materialises.
	Kustomizations map[string]*KustomizationInfo

	// Foreign lists the filesystem entries under spec.path that matched no recognized role
	// (non-YAML files, symlinks, submodules) and survived the .gittargetignore filter. The
	// acceptance gate refuses each one (foreignContentRefusals); the path is an
	// operator-exclusive subtree. See docs/spec/gitpath-foreign-content-stringency.md.
	Foreign []ForeignEntry

	// Ignore is the active root .gittargetignore matcher (nil when the path carries none).
	// It is consulted by the writer's write-plan precondition (§4.3) to assert that no path
	// the operator writes is shadowed by an ignore pattern — the one unrecoverable case.
	Ignore *IgnoreMatcher

	// IgnoreIssues carries parse-time .gittargetignore refusals (the catastrophic-pattern
	// denylist). The acceptance gate appends them so a footgun fails the GitTarget at the
	// same surface as any other refusal.
	IgnoreIssues []AcceptanceIssue

	// ValueFileRefs is the set of scanned non-KRM files (slash paths) a release document — an Argo
	// CD Application's helm.valueFiles or a Flux HelmRelease's spec.chart.spec.valuesFiles — names
	// by a path that matches locally: NAMED read-only context, not junk, and not proof the deployer
	// consumes this file. The acceptance gate consults it so a values file the repository points at
	// no longer refuses its folder as non-krm-yaml, and the discovery scan does not count it as
	// noise. It is never materialised, so the operator retains the file yet never writes it. See
	// docs/design/support-boundary/values-file-projection.md §2 (Move 1) and
	// values-content-architecture.md.
	ValueFileRefs map[string]struct{}

	// RenderedInventory records what each render root RENDERS TO, keyed by the root's
	// directory: which type lands in which namespace, from the objects kustomize actually
	// produced. It is what a tool must settle before it provisions from a folder, and it is
	// read off a real build, so a `namespace:` transformer or a base outside the subtree is
	// already accounted for. Empty for a root that failed to build, and absent for a
	// directory that is not a render root.
	RenderedInventory map[string]RenderedTypes
	// contains filtered or unexported fields
}

type MappingOutcome int

type NamespaceSource struct {
	Kind NamespaceSourceKind
	Path string
}

type NamespaceSourceKind string

type OverlapConflict struct {
	Ancestor   string `json:"ancestor"`
	Descendant string `json:"descendant"`
}

type OverrideEdit struct {
	// KustomizationPath is the kustomization file (slash, relative to the
	// GitTarget subtree) that carries the entry.
	KustomizationPath string
	// Create AUTHORS a new entry (via AppendKustomizationOverride) rather than editing a
	// scalar on an existing one: an overlay overriding a value its base supplies, where no
	// entry exists yet. Edit.EntryName is the new entry's name: (the image name for an
	// images: entry, the resource name for a replicas: entry); Edit.EntryIndex is unused.
	// Every authored entry is put to the re-render oracle before it can commit, so a proposal
	// that over-reaches is refused there, not written.
	Create bool
	// Edit is the bounded scalar update the manifestedit editor applies.
	Edit manifestedit.KustomizationEdit
}

type PlacementPolicy struct {
	ByType  map[string]string
	Default string
}

type PlacementRefusalReason string

type PlacementRefusedError struct {
	Reason   PlacementRefusalReason
	Resource string
	Path     string
	// contains filtered or unexported fields
}

type PlacementRequest struct {
	Identifier types.ResourceIdentifier
	Kind       string
	Sensitive  bool
	// WriteScope is the write jail relative to the scanned (render) root, set only when
	// render-root scoping re-rooted the scan past spec.path into a base an overlay reads.
	// Placement is documented as relative to spec.path, so a resolved path that would land
	// outside the jail (a declared or canonical path resolved against the render anchor) is
	// rebased under WriteScope rather than escaping it. Empty for a self-contained subtree,
	// where the scan root IS spec.path and every resolved path is already in scope.
	WriteScope string
}

type PlacementResult struct {
	// Path is the resolved file path (slash-separated), relative to the scanned
	// root (the GitTarget's spec.path).
	Path string
	// Append is true when Path already exists as a managed file the new document
	// should be appended to as an additional document; false for a brand-new file.
	Append bool
	// Source names which mechanism produced Path.
	Source PlacementSource
	// Kustomization is set when Path's directory carries a supported
	// kustomization.yaml whose resources: list does not already name Path — the
	// writer must add it as part of the same commit so kustomize picks the file
	// up ("add to the right kustomize file").
	Kustomization *KustomizationInfo
	// NamespaceInherited is true when Path's destination infers its namespace
	// from build context (a kustomization.yaml's namespace: transformer set to this
	// resource's own namespace) rather than from metadata.namespace in the file —
	// mirroring DocumentModel.NamespaceInheritedFromContext for a document that does
	// not exist yet. The writer must keep metadata.namespace out of the written
	// bytes, exactly as it already does for an in-place edit of an existing
	// document in the same context.
	NamespaceInherited bool
}

type PlacementSource string

type Plan struct {
	// Actions are the decided changes, in a deterministic order (by file path, then
	// document index, then identity), so output is stable regardless of map
	// iteration order. A resource already in sync produces NO action — the plan
	// lists only what would change.
	Actions []PlanAction
	// Diagnostics are planning-level problems (e.g. a touched file whose bytes were
	// not provided for hydration). Store-level diagnostics stay on the ManifestStore.
	Diagnostics []manifestedit.Diagnostic
	// RetainedOrphans counts the managed drops the sweep policy SUPPRESSED: documents
	// that would have been PlanDropOrphan under SweepDropOrphans and produced no action
	// at all under SweepRetainOrphans. It exists because a suppressed drop leaves no other
	// trace — the whole point is that it is absent from Actions, so nothing downstream
	// could otherwise tell "the mirror is converged" from "the mirror has stale documents
	// the policy is deliberately keeping". Purely informational: it is a count, not an
	// action, and it never reaches the commit path.
	RetainedOrphans int
}

type PlanAction struct {
	// Kind is what the action does.
	Kind PlanActionKind
	// Ref is the Git document the action concerns. It is the zero value for
	// PlanCreate, which has no existing location.
	Ref RecordRef
	// Identity is the manifest identity (apiVersion + kind + namespace + name)
	// involved, always set.
	Identity manifestedit.Identity
	// Resource is the resolved API-side identity (GVR + namespace + name). For a
	// desired-side action (create / patch / replace / skip) it is the cluster-truth
	// identity carried on the DesiredResource, so a create carries everything
	// ResourceIdentifier.ToGitPath needs to place a new file at apply time (M7)
	// without re-resolving the mapping. For a Git-only managed drop it is the
	// store-resolved identity. It is the zero value only when neither is known (a
	// skip over a document a structure-only store never resolved).
	Resource types.ResourceIdentifier
	// Desired is the clean object Git should contain, set for create/patch/replace
	// and nil for removals and skips.
	Desired *unstructured.Unstructured
	// Reason is a human-readable explanation, carried so renderers and status need
	// no recomputation.
	Reason string
}

type PlanActionKind string

type Policy struct {
	// Project maps a live API object to the clean desired state Git should contain.
	// A nil Project is treated as an identity passthrough (the object compared as-is).
	Project func(*unstructured.Unstructured) *unstructured.Unstructured
	// EditOptions are the manifestedit options (canonical renderer, list-match) used
	// when Decide must compare and choose patch vs. whole-replace.
	EditOptions manifestedit.EditOptions
	// Sweep decides whether the Git-only mark-and-sweep may emit managed drops. Its zero
	// value retains, so every caller that wants convergence must say so — see SweepMode.
	Sweep SweepMode
}

type ReadEdge struct {
	From string `json:"from"`
	To   string `json:"to"`
}

type RecordRef struct {
	FilePath      string
	DocumentIndex int
}

type RefusalReason struct {
	Code   string `json:"code"`
	Detail string `json:"detail"`
	// Solvable and Actor carry the refusal's own answer to "can this be solved, and by
	// whom" — projected verbatim from the acceptance issue that raised it, or decided by
	// the raise site for the reasons that are not issue kinds. Empty means unclassified; say
	// nothing about whether it can be solved.
	Solvable bool  `json:"solvable"`
	Actor    Actor `json:"actor,omitempty"`
}

type RenderDivergence struct {
	Field string
	Token string
}

type RenderRefusedError struct {
	// Reasons are the individual findings, sorted, so the message is stable across runs.
	Reasons []string
}

type RenderedImage struct {
	// Rendered is the image kustomize produces for this slot.
	Rendered string
	// Name, Tag and Digest are the entries supplying each component, or nil when the
	// source document does. They are the dye's answer, and the reason renderImage is gone.
	Name, Tag, Digest *ImageOverride
}

type RenderedOverrides struct {
	// Object is the whole object kustomize renders this document to. It is what the live
	// object is compared against, and it is the reason the writer can tell a value the BUILD
	// supplied from a value the USER set without modelling a single transformer: where the
	// live object and the render agree, the source keeps its bytes (see sourceForm).
	//
	// It is JSON-normalised, because a rendered object is not valid unstructured: kustomize
	// hands numbers back as Go `int`, which makes DeepCopyJSON panic outright.
	Object map[string]interface{}
	// Images is keyed by image slot (the container list path plus the container name), so
	// the live object, the Git document and the render all address the same field.
	Images map[string]RenderedImage
	// Replicas is set only when the document actually renders a spec.replicas — which is
	// kustomize's decision, not ours.
	Replicas *RenderedReplicas
}

type RenderedReplicas struct {
	Rendered int64
	Entry    *ReplicaOverride
}

type RenderedTypes struct {
	// ByNamespace lists the types that land in each namespace, sorted, keyed by namespace.
	ByNamespace map[string][]string `json:"byNamespace,omitempty"`

	// NamespaceUndeclared lists the types that render WITHOUT a namespace, sorted.
	//
	// It is NOT a list of cluster-scoped types. It holds two facts this scan cannot tell
	// apart: a genuinely cluster-scoped type, and a namespaced type relying on whatever
	// namespace the applier defaults to. Separating them needs API discovery, which a
	// structure-only scan does not have.
	//
	// A type can appear here AND under ByNamespace. Two ConfigMaps, one carrying a
	// namespace and one not, is an ordinary folder, not a contradiction.
	NamespaceUndeclared []string `json:"namespaceUndeclared,omitempty"`
}

type ReplicaOverride struct {
	// Source is the kustomization file path (slash) that declares the entry.
	Source string
	// Index is the entry's position within its file's replicas: sequence.
	Index int
	// Name matches the target document's metadata.name.
	Name string
	// Count is the replica count the entry pins.
	Count int64
}

type RepoCandidate struct {
	// Path is the candidate directory, slash-separated and relative to the repo root.
	Path string `json:"path"`
	// Layout is the candidate's structural shape.
	Layout Layout `json:"layout"`
	// AcceptedByOperator reports whether the operator would adopt this subtree today.
	AcceptedByOperator bool `json:"acceptedByOperator"`
	// RefusalReasons explains a non-acceptance; empty when accepted.
	RefusalReasons []RefusalReason `json:"refusalReasons,omitempty"`
	// RenderRoot reports whether the candidate is a kustomize render root (versus a
	// plain KRM folder).
	RenderRoot bool `json:"renderRoot"`
	// ReadScope lists the directories outside this candidate's own subtree whose content
	// its build renders: base kustomization directories its resources graph reaches, and
	// the directories holding individual resource files it renders from elsewhere. Empty
	// for plain and self-contained candidates.
	ReadScope []string `json:"readScope,omitempty"`
	// ReadBy is the reverse edge: the candidates whose build reads THIS directory. It is
	// usually empty, and structurally so — a directory another kustomization references is
	// never a render root, hence never a candidate — but not always: a plain folder holding
	// one file some distant kustomization lists in resources: is a candidate that another
	// folder depends on, and adopting it is the disruptive case a consumer must be able to
	// see. The rest of these edges end at directories no candidate list mentions; see
	// [RepoSummary.ReadEdges].
	ReadBy []string `json:"readBy,omitempty"`
	// InferredNamespace is the namespace the candidate resolves to: the kustomization's
	// namespace transformer for a render root, or the single explicit metadata.namespace
	// for a plain folder. Empty when none is set or the folder is ambiguous.
	InferredNamespace string `json:"inferredNamespace,omitempty"`
	// Resources counts the KRM this candidate covers (rendered vs editable) plus non-KRM.
	Resources ResourceCounts `json:"resources"`
	// RenderedTypes says which type lands in which namespace when this candidate renders.
	// It is what a tool must know before it provisions from the folder: the schemas that
	// have to be served where this is applied, and the exact (type, namespace) pairs a
	// watch rule can be written for. Empty for a render root kustomize could not build.
	RenderedTypes RenderedTypes `json:"renderedTypes"`
	// OverlapsWith lists other candidate paths this one nests with. Two overlapping
	// candidates can never both be proposed (one-owner-per-folder); the conflict is
	// reported, not resolved, in this cut.
	OverlapsWith []string `json:"overlapsWith,omitempty"`
}

type RepoReport struct {
	// Root is the scanned repository root as passed to ScanRepo. It is informational.
	Root string `json:"root,omitempty"`
	// Candidates are the enumerated subtrees, sorted by path.
	Candidates []RepoCandidate `json:"candidates"`
	// Summary is the repo-level roll-up.
	Summary RepoSummary `json:"summary"`
}

type RepoSummary struct {
	// CandidatesByLayout counts candidates per layout class.
	CandidatesByLayout map[Layout]int `json:"candidatesByLayout"`
	// Accepted and Refused count candidates by current operator acceptance.
	Accepted int `json:"accepted"`
	Refused  int `json:"refused"`
	// OverlapConflicts lists every nesting conflict between candidates.
	OverlapConflicts []OverlapConflict `json:"overlapConflicts,omitempty"`
	// ReadEdges is the repo's folder dependency graph: one edge per (candidate, directory
	// it renders from outside its own subtree), sorted. It is the same relation each
	// candidate's readScope/readBy report, collected in one place so a consumer can draw
	// the graph without walking the candidates.
	//
	// Most edges end at a directory that is NOT a candidate — a folder a kustomization
	// references is never a render root, so it is offered to nobody. Those nodes are the
	// edge targets absent from Candidates, and nothing else identifies them: they are not
	// all kustomize bases, since a referenced resource file or an out-of-subtree patch
	// makes its folder one too.
	ReadEdges []ReadEdge `json:"readEdges,omitempty"`
	// UnsupportedConstructs is the sorted, de-duplicated set of unsupported kustomize
	// features seen across refused-structural candidates, so a product can say "this repo
	// uses Helm inflation, which we don't manage".
	UnsupportedConstructs []string `json:"unsupportedConstructs,omitempty"`
}

type Report struct {
	Root        string                    `json:"root"`
	Files       []FileReport              `json:"files"`
	Summary     Summary                   `json:"summary"`
	Issues      []AcceptanceIssue         `json:"issues"`
	Diagnostics []manifestedit.Diagnostic `json:"diagnostics"`
}

type ResourceCounts struct {
	// Rendered is the number of managed KRM documents the candidate renders: its own
	// subtree plus every base it reads (readScope).
	Rendered int `json:"rendered"`
	// Editable is the number of managed KRM documents physically in the candidate's own
	// subtree — the source the operator would own and write in place.
	Editable int `json:"editable"`
	// NonKRM is the number of non-KRM YAML documents and foreign (non-YAML/symlink)
	// entries in the candidate's own subtree. Retained build directives (kustomization
	// files), operator artifacts (README.md), and accepted benign passengers (a license,
	// docs, .gitignore) are neither KRM nor NonKRM and are not counted.
	NonKRM int `json:"nonKrm"`
}

type RetainedDocument struct {
	Location manifestedit.Location
	Identity manifestedit.Identity
	GVK      schema.GroupVersionKind
	// Unsupported is true for a whole-file kustomization retention that the operator
	// cannot map back to editable source documents, for either of two reasons:
	//
	//   - it uses a feature outside the supported contextual-namespace subset
	//     (generators / patches / components / helm / replacements / transformers /
	//     name(pre|suf)fix / remote bases), or declares malformed images/replicas; or
	//   - it is a render root KUSTOMIZE CANNOT BUILD (reasonRenderFailed). If the build
	//     fails, Flux cannot deploy the folder either, and we cannot know what it renders
	//     to — and a silent pass would be worse than useless, because a root that yields
	//     no chain also yields no ambiguity, which disarms the write-fan-in guard.
	//
	// The acceptance gate refuses either (IssueUnsupportedKustomize) rather than writing
	// into content it cannot safely manage. Only ever set on a whole-file retention.
	Unsupported bool
	// UnsupportedFeatures names the constructs that made this retention unsupported, as
	// the user wrote them ("configMapGenerator", "remote-base", "render-failed"). It
	// carries the parse-time answer to the refusal, which is what lets the acceptance
	// gate decide solvability per construct instead of per code — one code with two very
	// different answers is the whole reason the solvability field exists. Sorted; empty
	// when Unsupported is false.
	UnsupportedFeatures []string
}

type ScanPolicy struct {
	// Acceptance configures the adoption gate (allowlist + scope). Its allowlist also
	// drives store construction, so allowlisted documents are retained, not planned.
	Acceptance AcceptancePolicy
	// Plan configures the planner (projection + edit options). A dry-run has no GitTarget
	// and therefore no prune policy to read, so a caller that wants the folder's orphans
	// listed must set Plan.Sweep to SweepDropOrphans deliberately — see FolderScanPlanPolicy.
	Plan Policy
}

type ScanResult struct {
	Store      *ManifestStore
	Acceptance Acceptance
	Plan       Plan
}

type SourceFormRefusedError struct {
	// Field is the path of the list that could not be aligned, as a user would read it.
	Field string
}

type Summary struct {
	FilesTotal   int                                  `json:"filesTotal"`
	YAMLFiles    int                                  `json:"yamlFiles"`
	NonYAMLFiles int                                  `json:"nonYamlFiles"`
	Documents    int                                  `json:"documents"`
	Duplicates   int                                  `json:"duplicates"`
	Encrypted    int                                  `json:"encrypted"`
	ByClass      map[Class]int                        `json:"byClass"`
	ByGVK        map[string]int                       `json:"byGvk"`
	Diagnostics  map[manifestedit.DiagnosticLevel]int `json:"diagnostics"`
}

type SweepMode string

type WriteIntent struct {
	// SourcePath is the file holding the document, slash-relative to the scan root.
	SourcePath string
	// Kind and Name identify the document within that file.
	Kind, Name string
	// Desired is the live object the document must render to. It is the whole point of
	// the check, and it is nil only when Removed or Unchecked says there is nothing to
	// check against.
	Desired *unstructured.Unstructured
	// Removed marks a document the flush deletes: it must disappear from the render.
	Removed bool
	// Unchecked marks a write whose rendered form we cannot predict, so the object is
	// permitted to move without being compared. There are exactly two: a SENSITIVE
	// document (the file is SOPS-encrypted, so kustomize renders the ciphertext, which
	// no plaintext live object can equal), and a bounded FIELD PATCH (the event carries
	// a few assignments, never a whole object to compare against).
	//
	// Unchecked weakens the oracle for those documents, and it is stated rather than
	// hidden: we can still prove that such a write disturbs nothing ELSE, which is the
	// half that protects other people's environments.
	Unchecked bool
	// Governed marks a document whose write was routed through a kustomization override
	// chain. These are the writes the oracle exists for, so one that turns out not to be
	// rendered by any root at all is a contradiction, and refused rather than skipped.
	Governed bool
}