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"`
}

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 Allowlist struct {
	// contains filtered or unexported fields
}

type CauseKind string

type Class string

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

	// 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
}

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) declaring the entry.
	KustomizationPath string
	// Edit is the bounded scalar update the manifestedit editor applies.
	Edit manifestedit.KustomizationEdit
}

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

type PlacementRequest struct {
	Identifier types.ResourceIdentifier
	Kind       string
	Sensitive  bool
}

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
	// Cohort describes the sibling cohort and ladder step that produced Path;
	// empty unless Source is PlacementSourceInferred.
	Cohort string
	// 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) 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 (see design doc: "the new file inherits its
	// sibling's NamespaceSource").
	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
}

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
}

type RecordRef struct {
	FilePath      string
	DocumentIndex int
}

type RefusalReason struct {
	Code   string `json:"code"`
	Detail string `json:"detail"`
}

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 {
	// 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 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 base directories outside this candidate's own subtree that its
	// kustomization reads. Empty for plain and self-contained candidates.
	ReadScope []string `json:"readScope,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"`
	// 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"`
	// FleetRoot is true when the repo root is a cluster/fleet root (top-level clusters/ +
	// apps/ + infra/): a GitTarget points at an app subtree, never such a root. The root
	// is never itself a candidate; leaf folders still surface normally.
	FleetRoot bool `json:"fleetRoot,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) 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
}

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).
	Plan Policy
}

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

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 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
}