cue

Documentation

Overview

Package cue handles CUE configuration loading and validation.

Index

• Constants
• Variables
• func ErrorSummary(err error) string
• func FormatError(err error) error
• func FormatErrors(err error) []error
• func HasCUEFiles(dir string) (bool, error)
• func IdentifyBrokenFiles(paths []string) string
• type LoadResult
• type Loader
  • func NewLoader() *Loader
  • func (l *Loader) Context() *cue.Context
  • func (l *Loader) Load(dirs []string) (LoadResult, error)
  • func (l *Loader) LoadSingle(dir string) (cue.Value, error)
• type ValidationError
  • func FormatErrorWithContext(err error) *ValidationError
  • func (e *ValidationError) DetailedError() string
  • func (e *ValidationError) Error() string
• type ValidationOption
  • func Concrete(v bool) ValidationOption
• type Validator
  • func NewValidator() *Validator
  • func (v *Validator) Exists(value cue.Value, path string) bool
  • func (v *Validator) Validate(value cue.Value, opts ...ValidationOption) error
  • func (v *Validator) ValidatePath(value cue.Value, path string, opts ...ValidationOption) error

Constants

const (
	KeyAgents   = "agents"
	KeyRoles    = "roles"
	KeyContexts = "contexts"
	KeyTasks    = "tasks"
	KeySettings = "settings"
)

CUE configuration keys used throughout the codebase. Centralised here to prevent typos and ease refactoring.

Variables

var ConfigFiles = map[string]string{
	KeyAgents:   "agents.cue",
	KeyRoles:    "roles.cue",
	KeyContexts: "contexts.cue",
	KeyTasks:    "tasks.cue",
	KeySettings: "settings.cue",
}

ConfigFiles maps each category key to its CUE config filename.

var ErrNoCUEFiles = errors.New("no CUE files found")

ErrNoCUEFiles is returned when no CUE files are found in the provided directories.

Functions

func ErrorSummary

func ErrorSummary(err error) string

ErrorSummary returns a short summary of CUE errors.

func FormatError

func FormatError(err error) error

FormatError converts a CUE error into a user-friendly error. It extracts position information and formats messages for clarity.

func FormatErrors

func FormatErrors(err error) []error

FormatErrors formats multiple CUE errors into a single error message.

func HasCUEFiles

func HasCUEFiles(dir string) (bool, error)

HasCUEFiles checks if a directory contains any .cue files.

func IdentifyBrokenFiles

func IdentifyBrokenFiles(paths []string) string

IdentifyBrokenFiles compiles each CUE file individually and returns a summary of which files have errors. This is used to provide actionable diagnostics when a directory fails to load.

Types

type LoadResult

type LoadResult struct {
	// Value is the merged CUE value.
	Value cue.Value
	// GlobalLoaded indicates whether global config was loaded.
	GlobalLoaded bool
	// LocalLoaded indicates whether local config was loaded.
	LocalLoaded bool
}

LoadResult contains the result of loading CUE configuration.

type Loader

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

Loader loads and merges CUE configurations from directories.

func NewLoader

func NewLoader() *Loader

NewLoader creates a new CUE loader.

func (*Loader) Context

func (l *Loader) Context() *cue.Context

Context returns the underlying CUE context.

func (*Loader) Load

func (l *Loader) Load(dirs []string) (LoadResult, error)

Load loads CUE configuration from the specified directories. Directories are loaded in order, with later directories taking precedence via CUE unification (later values override earlier for matching keys). Empty or non-existent directories are skipped.

The caller convention is: dirs[0] = global config, dirs[1] = local config. GlobalLoaded/LocalLoaded indicate which of these were successfully loaded.

func (*Loader) LoadSingle

func (l *Loader) LoadSingle(dir string) (cue.Value, error)

LoadSingle loads CUE configuration from a single directory.

type ValidationError

type ValidationError struct {
	Path     string
	Message  string
	Line     int
	Column   int
	Filename string
	Context  string // Source context snippet around the error
}

ValidationError represents a validation error with context.

func FormatErrorWithContext

func FormatErrorWithContext(err error) *ValidationError

FormatErrorWithContext converts a CUE error into a ValidationError with source context. It reads the source file to provide a snippet around the error location.

func (*ValidationError) DetailedError

func (e *ValidationError) DetailedError() string

DetailedError returns a formatted error with source context. This is intended for display to users when they need to fix config errors.

func (*ValidationError) Error

func (e *ValidationError) Error() string

Error returns a concise error string with file:line:message format.

type ValidationOption

type ValidationOption func(*validationConfig)

ValidationOption configures validation behaviour.

func Concrete

func Concrete(v bool) ValidationOption

Concrete requires all values to be concrete (no definitions or constraints).

type Validator

type Validator struct{}

Validator validates CUE values.

func NewValidator

func NewValidator() *Validator

NewValidator creates a new CUE validator.

func (*Validator) Exists

func (v *Validator) Exists(value cue.Value, path string) bool

Exists checks if a path exists in the CUE value.

func (*Validator) Validate

func (v *Validator) Validate(value cue.Value, opts ...ValidationOption) error

Validate checks a CUE value for errors. By default, it only checks for structural errors. Use Concrete(true) to require all values to be concrete.

func (*Validator) ValidatePath

func (v *Validator) ValidatePath(value cue.Value, path string, opts ...ValidationOption) error

ValidatePath validates a specific path within a CUE value.