manifestanalyzer

type Actor string

type Candidate struct {
	// Path is slash-separated and relative to the repository root.
	Path   string `json:"path"`
	Layout Layout `json:"layout"`
	// AcceptedByOperator reports whether the operator would adopt this folder today.
	AcceptedByOperator bool            `json:"acceptedByOperator"`
	RefusalReasons     []RefusalReason `json:"refusalReasons,omitempty"`
	// RenderRoot reports whether the candidate is a kustomize render root.
	RenderRoot bool `json:"renderRoot"`
	// ReadScope lists the directories outside this candidate's 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.
	//
	// It is the field that explains the most confusing accept the scan produces: a folder
	// reported acceptedByOperator with resources.editable 0 is an overlay whose documents
	// live in a base it does not own. Read with [Candidate.ReadBy] and
	// [RepoSummary.ReadEdges], it is one direction of the repository's folder graph.
	ReadScope []string `json:"readScope,omitempty"`
	// ReadBy names the candidates whose build renders THIS directory's content — the edge
	// that decides whether adopting a folder is merely wrong or actively disruptive.
	//
	// It is usually empty, and structurally so: a directory another kustomization
	// references is never a render root, so it is never offered as a candidate at all, and
	// those edges end at a directory no candidate list mentions instead. The exception is a
	// plain folder holding a file some distant kustomization lists under resources: — a
	// candidate that another folder genuinely depends on.
	ReadBy []string `json:"readBy,omitempty"`
	// InferredNamespace is the namespace the candidate resolves to, when unambiguous.
	InferredNamespace string         `json:"inferredNamespace,omitempty"`
	Resources         ResourceCounts `json:"resources"`
	// RenderedTypes says which type this folder renders into which namespace. For a render
	// root it is read off a real kustomize build, so it covers what the folder pulls from a
	// base outside its own subtree and has the namespace transformer already applied; for a
	// plain folder the documents are the render.
	//
	// It answers the two questions that gate provisioning from a folder scan, and both gate
	// a step that is not cheap to undo. The schemas have to be served wherever this is
	// applied — a type the destination does not serve does not degrade, the apply fails
	// with "no matches for kind" and waits for the next resync. And naming a GitTarget's
	// allowed source namespaces, or one watch rule per (type, namespace), needs the exact
	// pairs: [Candidate.InferredNamespace] is one name, and a folder can render into
	// several.
	//
	// Everything is empty for a render root kustomize could not build. What it renders is
	// not knowable, and saying nothing is the honest answer.
	RenderedTypes RenderedTypes `json:"renderedTypes"`
	// OverlapsWith lists candidate paths this one nests with. Two overlapping candidates
	// can never both become GitTargets — a folder has exactly one owner.
	OverlapsWith []string `json:"overlapsWith,omitempty"`
}

type FolderReport struct {
	TypeMeta `json:",inline"`

	Spec   FolderReportSpec   `json:"spec"`
	Status FolderReportStatus `json:"status"`
}

type FolderReportSpec struct {
	// Root is the scanned folder as passed to ScanFolder. Empty for ScanFolderFS.
	Root string `json:"root,omitempty"`
	// Mode is always [ModeScanFolder].
	Mode string `json:"mode"`
}

type FolderReportStatus struct {
	// Generator names the build that produced this report. Never empty.
	Generator Generator `json:"generator"`
	// Accepted is the gate decision. When false, Issues says why.
	Accepted bool `json:"accepted"`
	// Issues is empty when Accepted, and never nil in the marshaled JSON.
	Issues []Issue `json:"issues"`
	// Retained lists the build directives read as context.
	Retained []RetainedDocument `json:"retained,omitempty"`
}

type Generator struct {
	// Name is the producing tool, e.g. "manifest-analyzer".
	Name string `json:"name"`
	// Version is the release, e.g. "v0.39.1", or "dev" for a build carrying no version.
	Version string `json:"version"`
}

type Identity struct {
	APIVersion string `json:"apiVersion"`
	Kind       string `json:"kind"`
	Namespace  string `json:"namespace"`
	Name       string `json:"name"`
}

type Issue struct {
	Kind IssueKind `json:"kind"`
	// Path is the offending file, slash-separated and relative to the scan root. Empty
	// when the issue is about the folder as a whole.
	Path string `json:"path"`
	// DocumentIndex is the zero-based index of the offending document within Path.
	DocumentIndex int `json:"documentIndex"`
	// Message is a human-readable explanation. It is not a stable string.
	Message string `json:"message"`
	// Solvable says whether anyone can make this folder acceptable with this release. It
	// is set by the check that raised the issue, because only that check knows: one code
	// answers differently depending on which branch emitted it, which is why this is a
	// field on the emitted value rather than a table beside the constants.
	//
	// It describes THIS RELEASE and promises nothing about the future, so read it on every
	// scan rather than caching a mapping from it.
	Solvable bool `json:"solvable"`
	// Actor names who can solve it. Empty unless Solvable — a code alone cannot tell "fix
	// your YAML" from "this folder cannot be adopted", and rendering an out-of-scope
	// refusal as "fix your repository" to someone who cannot is what this half prevents.
	Actor Actor `json:"actor,omitempty"`
}

type IssueKind string

type Layout string

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

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

type RefusalReason struct {
	// Code is an [IssueKind] value, or [ReasonRefusedStructural]. The type makes that
	// relationship compile-checked rather than merely stated: a candidate's refusal is
	// the acceptance gate's own issue, projected up.
	Code IssueKind `json:"code"`
	// Detail is human-readable and not a stable string.
	Detail string `json:"detail"`
	// Solvable says whether anyone can make this candidate acceptable with this release.
	// A report produced before this field shipped carries no `solvable` key at all; read
	// that as "nobody said", not as false.
	Solvable bool `json:"solvable"`
	// Actor names who can solve it. Empty unless Solvable.
	Actor Actor `json:"actor,omitempty"`
}

type RenderedTypes struct {
	// ByNamespace lists the types that land in each namespace, sorted, keyed by namespace.
	// These are the exact (type, namespace) pairs, and the only ones.
	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, and must not be read as one. 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, and a structure-only scan has none — so the honest reading is "we do not
	// know where these land". A scan that does have discovery can split them, in a field
	// added then rather than a name reserved now.
	//
	// A type can appear here AND under ByNamespace. Two ConfigMaps, one carrying a
	// namespace and one not, is an ordinary folder rather than a contradiction.
	NamespaceUndeclared []string `json:"namespaceUndeclared,omitempty"`
}

type RepoReport struct {
	TypeMeta `json:",inline"`

	Spec   RepoReportSpec   `json:"spec"`
	Status RepoReportStatus `json:"status"`
}

type RepoReportSpec struct {
	// Root is the scanned repository root as passed to ScanRepo.
	Root string `json:"root,omitempty"`
	// Mode is always [ModeScanRepo].
	Mode string `json:"mode"`
}

type RepoReportStatus struct {
	// Generator names the build that produced this report. Never empty.
	Generator  Generator   `json:"generator"`
	Candidates []Candidate `json:"candidates"`
	Summary    RepoSummary `json:"summary"`
}

type RepoSummary struct {
	CandidatesByLayout map[Layout]int    `json:"candidatesByLayout"`
	Accepted           int               `json:"accepted"`
	Refused            int               `json:"refused"`
	OverlapConflicts   []OverlapConflict `json:"overlapConflicts,omitempty"`
	// ReadEdges is the repository's folder dependency graph, sorted: one edge per
	// (candidate, directory it renders from outside its own subtree). It is the same
	// relation [Candidate.ReadScope] and [Candidate.ReadBy] report per folder, collected so
	// a consumer can draw the graph without walking the candidate list.
	//
	// Most edges end at a directory that is not a candidate: a folder some kustomization
	// references is never a render root, so it is offered to nobody, and a consumer that
	// draws only candidates draws no edges at all. Those nodes are exactly the edge targets
	// absent from [RepoReportStatus.Candidates] — the report does not also publish them as a
	// list, because a second copy of a set difference is a second thing to keep true.
	ReadEdges []ReadEdge `json:"readEdges,omitempty"`
	// UnsupportedConstructs is the sorted, de-duplicated set of unsupported kustomize
	// features seen across refused candidates, so a tool can say "this repository uses
	// Helm inflation, which the operator does not manage".
	UnsupportedConstructs []string `json:"unsupportedConstructs,omitempty"`
}

type ResourceCounts struct {
	Rendered int `json:"rendered"`
	Editable int `json:"editable"`
	NonKRM   int `json:"nonKrm"`
}

type RetainedDocument struct {
	Path          string `json:"path"`
	DocumentIndex int    `json:"documentIndex"`
	// Identity is set only when a named Kubernetes resource is hiding inside an
	// allowlisted build-directive file — the mixed-file case, which is refused. It is nil
	// for the ordinary whole-file retention of a kustomization.yaml, which names no
	// resource.
	Identity *Identity `json:"identity,omitempty"`
	// Unsupported reports that this retained file uses a construct the writer cannot map
	// back to editable source. It is the cause of an IssueUnsupportedKustomize.
	Unsupported bool `json:"unsupported,omitempty"`
}

type TypeMeta struct {
	APIVersion string `json:"apiVersion"`
	Kind       string `json:"kind"`
}