repolint

type CRDBinding struct {
	// GoFile is the path to the Go source file (relative to repo root)
	// containing GoStruct. The file is parsed standalone; cross-file
	// type references are not followed (drift checks should bind to
	// the leaf struct directly, not to a parent that embeds it).
	GoFile string
	// GoStruct is the unqualified struct type name to inspect.
	GoStruct string
	// CRDFile is the path to the YAML manifest containing the
	// CustomResourceDefinition (relative to repo root).
	CRDFile string
	// CRDPath is the sequence of map keys (and string-encoded array
	// indices) that walks from the YAML document root to the schema
	// object whose `properties:` map should mirror GoStruct's fields.
	CRDPath []string
	// IgnoreGoFields lists Go JSON tags that the CRD does not need
	// to declare (rare; e.g. computed-only fields the API server
	// would never accept). Empty in normal operation.
	IgnoreGoFields []string
	// IgnoreCRDProperties lists CRD property keys that the Go struct
	// does not need to declare (rare; e.g. metadata sentinels that
	// were intentionally added to the schema for kubectl tooling but
	// are not deserialized by the controller).
	IgnoreCRDProperties []string
}

type CRDDriftReport struct {
	// Binding records which check produced this report (so callers
	// can format messages tying the diff back to the file pair).
	Binding CRDBinding
	// GoMissingInCRD lists JSON tag names declared on GoStruct but
	// absent from the CRD's properties map. These are fields the
	// controller will write but kube-apiserver will silently drop.
	GoMissingInCRD []string
	// CRDMissingInGo lists property keys declared on the CRD but
	// absent from GoStruct. These are fields kube-apiserver will
	// accept but no Go reader unmarshals — usually a stale schema
	// from a renamed field.
	CRDMissingInGo []string
}

type CRDFetcher interface {
	GetCRD(ctx context.Context, name string) (*apiextv1.CustomResourceDefinition, error)
}

type ClusterDriftBinding struct {
	// CRDName is the metadata.name of the deployed CustomResourceDefinition
	// (e.g. "workspaces.llmsafespaces.dev").
	CRDName string
	// CRDFile is the path to the chart's CRD YAML, relative to repo root.
	CRDFile string
	// CRDPath walks from the document root to the schema node whose
	// `properties:` keys are compared. Same shape as CRDBinding.CRDPath.
	// Typically ["spec","versions","0","schema","openAPIV3Schema","properties","spec"].
	CRDPath []string
	// IgnoreClusterProperties lists keys present on the deployed CRD
	// but intentionally absent from the chart (rare; e.g. a field
	// deprecated server-side that callers no longer set).
	IgnoreClusterProperties []string
	// IgnoreChartProperties lists keys present in the chart but
	// intentionally not yet rolled out to the cluster (rare; only
	// useful during a multi-step migration where the chart leads).
	IgnoreChartProperties []string
}

type ClusterDriftReport struct {
	Binding ClusterDriftBinding
	// ChartMissingInCluster lists keys declared in the chart YAML but
	// absent from the deployed CRD. These are fields the binary will
	// try to write but the apiserver will silently drop. This is the
	// worklog 0465 incident symptom and the primary thing this check
	// is here to surface.
	ChartMissingInCluster []string
	// ClusterMissingInChart lists keys declared on the deployed CRD
	// but absent from the chart. Indicates a stale CRD on the cluster
	// from a previous chart version that has since been pruned.
	ClusterMissingInChart []string
}

type DriftConfig struct {
	// CanonicalDir is the source-of-truth directory.
	CanonicalDir string
	// MirrorDir is the secondary copy that must mirror CanonicalDir.
	MirrorDir string
	// Glob restricts the comparison to files matching this pattern
	// (filepath.Match syntax; relative to dir entries' base names).
	// Files not matching are ignored entirely — including READMEs and
	// other side files that are allowed to differ.
	Glob string
}

type DriftReport struct {
	// MissingInMirror are files present in CanonicalDir but absent
	// (or ignored by Glob) in MirrorDir.
	MissingInMirror []string
	// ExtraInMirror are files present in MirrorDir but absent in
	// CanonicalDir.
	ExtraInMirror []string
	// ContentDiffers lists files present in both but with different
	// SHA-256 content hashes.
	ContentDiffers []string
}

type Duplicate struct {
	Version int
	Files   []string
}

type MainlineCollision struct {
	Version     int
	LocalFiles  []string
	RemoteFiles []string
}

type MainlineReport struct {
	Collisions []MainlineCollision
	NextNumber int
}

type SentinelReport struct {
	// Sentinels lists the basenames of NNNN_ files found, sorted lexically.
	Sentinels []string
}

type SequenceConfig struct {
	// Dir is the directory to scan.
	Dir string
	// Pattern matches versioned filenames. Capture group 1 MUST be the
	// numeric version. If RequirePaired is true, capture group 3 MUST
	// be "up" or "down".
	Pattern *regexp.Regexp
	// RequirePaired, when true, asserts every (version, name) tuple
	// has both an up and a down file. Use false for single-file
	// schemes like worklogs.
	RequirePaired bool
	// GrandfatherBelow, when > 0, exempts existing collisions and
	// gaps at versions strictly less than this value from failing the
	// check. New entries at or above this threshold are still subject
	// to all rules. Use this when historical duplicates exist and
	// rewriting them is impractical (e.g. cross-references in 20+
	// files); the goal is to prevent NEW drift, not relitigate old.
	GrandfatherBelow int
	// AllowGaps, when true, treats sequence gaps as warnings rather
	// than failures. Duplicates and unpaired-files are still hard
	// failures. Use this for append-only artifacts (worklogs) where
	// gaps from concurrent merges + auto-renames are an expected
	// failure mode that the autofix bot cannot heal without breaking
	// MainlineCheck. Migrations should NEVER allow gaps — an
	// out-of-sequence migration breaks schema rebuild.
	AllowGaps bool
}

type SequenceReport struct {
	// MaxVersion is the highest version found. Zero if dir is empty.
	MaxVersion int
	// SeenVersions are all unique version numbers, sorted.
	SeenVersions []int
	// MissingVersions lists numbers in [1, MaxVersion] that no file
	// covers. (A run with MaxVersion=0 has no missing versions.)
	MissingVersions []int
	// Duplicates lists every version that has more than one
	// (name) entry. Note: a paired up+down counts as ONE entry.
	Duplicates []Duplicate
	// UnpairedFiles lists filenames that lack their matching up/down
	// counterpart (only populated when RequirePaired=true).
	UnpairedFiles []string
	// GapsAllowed mirrors SequenceConfig.AllowGaps. When true, OK()
	// ignores MissingVersions; callers can detect the warning state
	// via HasWarnings().
	GapsAllowed bool
}

type WorklogRename struct {
	From string // original filename (basename only)
	To   string // new filename (basename only)
}