configkit/records.go

package configkit

// Layer identifies the precedence layer responsible for a configuration value.
type Layer string

const (
	LayerDefault    Layer = "default"
	LayerMain       Layer = "main"
	LayerUnderlay   Layer = "underlay"
	LayerOverlay    Layer = "overlay"
	LayerCLI        Layer = "cli"
	LayerResolution Layer = "resolution"
)

// SourceKind identifies how a configuration source was acquired, independent
// of its precedence layer.
type SourceKind string

const (
	SourceKindFile       SourceKind = "file"
	SourceKindFilesystem SourceKind = "filesystem"
	SourceKindBytes      SourceKind = "bytes"
	SourceKindReader     SourceKind = "reader"
	SourceKindMapping    SourceKind = "mapping"
	SourceKindCLI        SourceKind = "cli"
)

// ChangeKind identifies a recorded operation. The zero value is
// used for input and default origins.
type ChangeKind string

const (
	// ChangeDecoding records the built-in transition to canonical typed values.
	// It is inspection metadata, not a manual recording intent exposed by
	// Resolution.
	ChangeDecoding ChangeKind = "decoding"
	// ChangeInheritance records structural input expansion. It is inspection
	// metadata, not a manual recording intent exposed by Resolution.
	ChangeInheritance    ChangeKind = "inheritance"
	ChangeDerivedDefault ChangeKind = "derived_default"
	ChangeNormalization  ChangeKind = "normalization"
)

// Severity classifies a diagnostic.
type Severity string

const (
	SeverityError   Severity = "error"
	SeverityWarning Severity = "warning"
)

// Code is a stable, machine-readable diagnostic classification.
type Code string

const (
	CodeSourceInvalid       Code = "source.invalid"
	CodeSourceMissing       Code = "source.missing"
	CodeSourcePermission    Code = "source.permission"
	CodeSourceRead          Code = "source.read"
	CodeSourceNotRegular    Code = "source.not_regular"
	CodeSourceLimitExceeded Code = "source.limit_exceeded"
	CodeSourceReaderUsed    Code = "source.reader_used"

	CodeYAMLInvalid           Code = "yaml.invalid"
	CodeYAMLEmpty             Code = "yaml.empty"
	CodeYAMLMultipleDocuments Code = "yaml.multiple_documents"
	CodeYAMLRootType          Code = "yaml.root_type"
	CodeYAMLDuplicateKey      Code = "yaml.duplicate_key"
	CodeYAMLTag               Code = "yaml.tag"
	CodeYAMLAnchor            Code = "yaml.anchor"
	CodeYAMLAlias             Code = "yaml.alias"
	CodeYAMLMergeKey          Code = "yaml.merge_key"
	CodeYAMLScalar            Code = "yaml.scalar"
	CodeYAMLDepthLimit        Code = "yaml.depth_limit"
	CodeYAMLNodeLimit         Code = "yaml.node_limit"

	CodeSchemaRoot            Code = "schema.root"
	CodeSchemaUnsupportedType Code = "schema.unsupported_type"
	CodeSchemaAmbiguousField  Code = "schema.ambiguous_field"
	CodeSchemaTag             Code = "schema.tag"
	CodeSchemaTextCodec       Code = "schema.text_codec"
	CodeSchemaInline          Code = "schema.inline"
	CodeSchemaCycle           Code = "schema.cycle"
	CodeSchemaProjectionLimit Code = "schema.projection_limit"
	CodeSchemaCodec           Code = "schema.codec"
	CodeSchemaNonFinite       Code = "schema.non_finite"
	CodeSchemaDynamicType     Code = "schema.dynamic_type"

	CodeDecodeType         Code = "decode.type"
	CodeDecodeNull         Code = "decode.null"
	CodeDecodeRange        Code = "decode.range"
	CodeDecodeDuration     Code = "decode.duration"
	CodeDecodeText         Code = "decode.text"
	CodeDecodeUnknownField Code = "decode.unknown_field"
	CodeDecodeArrayLength  Code = "decode.array_length"

	CodeOptionsInvalid Code = "options.invalid"

	CodeImportDisabled      Code = "import.disabled"
	CodeImportInvalid       Code = "import.invalid"
	CodeImportMissing       Code = "import.missing"
	CodeImportPermission    Code = "import.permission"
	CodeImportRead          Code = "import.read"
	CodeImportOutsideRoot   Code = "import.outside_root"
	CodeImportCycle         Code = "import.cycle"
	CodeImportRepeated      Code = "import.repeated"
	CodeImportLimitExceeded Code = "import.limit_exceeded"
	CodeImportVersion       Code = "import.version"
	CodeSequenceInvalid     Code = "sequence.invalid"
	CodeSequenceConflict    Code = "sequence.conflict"
	CodeUnderlayVersion     Code = "underlay.version"

	CodeOverlayInvalid       Code = "overlay.invalid"
	CodeOverlayMissing       Code = "overlay.missing"
	CodeOverlayOutsideRoot   Code = "overlay.outside_root"
	CodeOverlayRepeated      Code = "overlay.repeated"
	CodeOverlayDirective     Code = "overlay.directive"
	CodeOverlayVersion       Code = "overlay.version"
	CodeOverlayLimitExceeded Code = "overlay.limit_exceeded"

	CodeComposeInvalid  Code = "compose.invalid"
	CodeComposeConflict Code = "compose.conflict"

	CodeVersionType       Code = "version.type"
	CodeVersionError      Code = "version.error"
	CodeVersionWarning    Code = "version.warning"
	CodeVersionHookFailed Code = "version.hook_failed"

	CodeResolveError            Code = "resolve.error"
	CodeResolveWarning          Code = "resolve.warning"
	CodeResolveHookFailed       Code = "resolve.hook_failed"
	CodeResolveInvalidPath      Code = "resolve.invalid_path"
	CodeResolveInvalidRecord    Code = "resolve.invalid_record"
	CodeResolveInvalidTarget    Code = "resolve.invalid_target"
	CodeResolveInvalidValue     Code = "resolve.invalid_value"
	CodeResolveUnrecordedChange Code = "resolve.unrecorded_change"

	CodeValidateError       Code = "validate.error"
	CodeValidateWarning     Code = "validate.warning"
	CodeValidateInvalidPath Code = "validate.invalid_path"
	CodeValidateMutation    Code = "validate.mutation"

	CodeSecretsInvalidPath   Code = "secrets.invalid_path"
	CodeSecretsMissing       Code = "secrets.missing"
	CodeSecretsPermission    Code = "secrets.permission"
	CodeSecretsRead          Code = "secrets.read"
	CodeSecretsNotRegular    Code = "secrets.not_regular"
	CodeSecretsInvalidName   Code = "secrets.invalid_name"
	CodeSecretsLimitExceeded Code = "secrets.limit_exceeded"
	CodeSecretsInvalidValue  Code = "secrets.invalid_value"
	CodeSecretsApplyFailed   Code = "secrets.apply_failed"

	CodeSecretRequired    Code = "secret.required"
	CodeSecretInvalidName Code = "secret.invalid_name"
	CodeSecretUnset       Code = "secret.unset"
	CodeSecretEmpty       Code = "secret.empty"

	CodeOverrideInvalidPath   Code = "override.invalid_path"
	CodeOverrideInvalidLabel  Code = "override.invalid_label"
	CodeOverrideInvalidValue  Code = "override.invalid_value"
	CodeOverrideDuplicate     Code = "override.duplicate"
	CodeOverrideOverlap       Code = "override.overlap"
	CodeOverrideDirective     Code = "override.directive"
	CodeOverrideVersion       Code = "override.version"
	CodeOverrideLimitExceeded Code = "override.limit_exceeded"

	CodeHistoryLimitExceeded Code = "history.limit_exceeded"

	CodeInheritanceInvalid Code = "inheritance.invalid"
	CodeInheritanceMissing Code = "inheritance.missing"
	CodeInheritanceCycle   Code = "inheritance.cycle"
	CodeInheritanceVersion Code = "inheritance.version"
)

// Location identifies a position in a configuration source. Zero line and column
// values mean that coordinates are unavailable or synthetic.
type Location struct {
	SourceID string
	Line     int
	Column   int
}

// SourceInfo describes one input acquired during loading. Kind says how it was
// read; Layer says its priority role. Path is canonical for a host file and
// namespace-relative for a filesystem file; synthetic sources have no Path.
// Destination says where the source contributes in the assembled configuration.
// UnderlayIndex is the one-based original underlay position, or zero for other
// sources. ImportedFrom identifies the declaration that included this source.
type SourceInfo struct {
	ID    string
	Label string
	Path  string
	// Destination is the effective mapping or sequence-container path. It is a
	// detached snapshot. A fallback container is marked by DestinationIsFallback.
	Destination Path
	// PlacementMode describes how this source was placed. Mapping is the zero
	// value; CLI and overlay sources report mapping placement unless item placement
	// was applied to that source.
	PlacementMode PlacementMode
	// DestinationIsFallback marks Destination as the nearest resolved enclosing
	// container when an enclosing item index is not yet assigned. It is false for
	// exact destinations, including an item source's own sequence container.
	DestinationIsFallback bool
	Layer                 Layer
	Kind                  SourceKind
	UnderlayIndex         int
	ImportedFrom          *Location
	// VersionEvidence is sanitized evidence for source-local declaration processing
	// in an enabled source-version load. It is nil when that processing did not
	// occur, including MainOnly mode and synthetic CLI sources. During callbacks
	// and failed loads, text is conservatively withheld; successful final source
	// records reflect completed sensitivity classification.
	VersionEvidence *SourceVersionEvidence
	// EmptyImportSelections records completed optional declarations that selected no
	// sources, in declaration order. Paths are local to this declaring source.
	// Each record identifies the declaration mapping and selector;
	// it does not list candidates or explain why a path was absent. Result, error,
	// and callback snapshots detach these records and their paths.
	EmptyImportSelections []EmptyImportSelection
}

// ImportSelector identifies the selector used by an import declaration.
type ImportSelector string

const (
	// ImportSelectorPath identifies a named-file selector.
	ImportSelectorPath ImportSelector = "path"
	// ImportSelectorDirectory identifies a literal directory search.
	ImportSelectorDirectory ImportSelector = "dir"
	// ImportSelectorGlob identifies a path-glob selector.
	ImportSelectorGlob ImportSelector = "glob"
)

// EmptyImportSelection records an optional import declaration that selected no
// sources. Path is local to the declaring source; Location identifies its
// declaration mapping and source ID.
type EmptyImportSelection struct {
	Path     Path
	Location Location
	Selector ImportSelector
}

// SourceVersionEvidence records an observed version declaration in one input
// document when source-version checks are enabled. A non-nil record with
// Version.Present false records absence; it does not mean a checker ran or
// accepted a value. Version.Text is empty when final sensitivity classification
// or conservative masking during callbacks or failed loads hides it.
// Version.Present and Version.Null retain their meaning.
// Source queries return copies you can change without changing stored evidence.
// See docs/config.md for disclosure
// and lifecycle details.
type SourceVersionEvidence struct {
	Path     Path
	Version  Version
	Location *Location
	Redacted bool
}

// Diagnostic is a safe structured problem report. Message and source labels must
// never contain configuration values or other secrets.
type Diagnostic struct {
	Code     Code
	Severity Severity
	Path     Path
	Message  string
	Primary  *Location
	Related  []Location
}

// InheritanceStep identifies values copied from From to To by inheritance.
// These are configuration paths. Reference names the controlling destination
// extends path; Locations identify that directive rather than the copied value.
type InheritanceStep struct {
	From      Path
	To        Path
	Reference Path
	Locations []Location
}

// Origin describes where a final value came from. Multiple locations identify
// contributors to a combined value. Resolution identifies an application operation
// instead of a file location. Inheritance describes the copying steps, while
// Layer and Locations still identify the value's sources.
type Origin struct {
	Layer       Layer
	Locations   []Location
	Operation   ChangeKind
	Inheritance []InheritanceStep
}

// FieldInfo describes a final configuration path: whether input supplied it,
// whether it is null, and where it came from.
type FieldInfo struct {
	Explicit bool
	Null     bool
	Origin   Origin
}

// Change describes a definition or application-resolution operation. Path can name
// an ancestor operation affecting the queried descendant. Historical values are
// intentionally not exposed by this record.
type Change struct {
	Path         Path
	Origin       Origin
	Previous     []Origin
	Reasons      []string
	Dependencies []Path
}