condition

package
v1.226.0-rc.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 11, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// PredicateCI matches when Atmos is running in a detected CI environment.
	PredicateCI = "ci"
	// PredicateLocal matches when Atmos is not running in a detected CI environment.
	PredicateLocal = "local"
	// PredicateAlways always matches.
	PredicateAlways = "always"
	// PredicateNever never matches.
	PredicateNever = "never"
	// PredicateSuccess matches a successful lifecycle status.
	PredicateSuccess = "success"
	// PredicateFailure matches a failed lifecycle status.
	PredicateFailure = "failure"

	CELTag = "!cel"
)

Variables

View Source 
var ErrInvalidWhenCondition = errors.New("invalid when condition")

ErrInvalidWhenCondition is returned when a `when` value cannot be normalized or evaluated.

Functions

func DecodeHook 

func DecodeHook() mapstructure.DecodeHookFunc

DecodeHook lets Viper/mapstructure decode string/list/map values into Condition fields.

func RegisterPredicate 

func RegisterPredicate(name string, fn PredicateFunc)

RegisterPredicate adds or replaces a named condition predicate.

func ValidateStep 

func ValidateStep(condition Condition) error

ValidateStep validates predicates used by workflow and custom command steps. Step runners evaluate lifecycle predicates against the current run status so cleanup steps can use `failure` and `always`.

Types

type Condition 

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

Condition is the normalized representation of a step/hook `when` value.

func Must 

func Must(value any) Condition

Must is a test/helper convenience for constructing conditions.

func New 

func New(value any) (Condition, error)

New normalizes a decoded YAML/mapstructure value.

func (Condition) Evaluate 

func (c Condition) Evaluate(ctx Context) bool

Evaluate returns whether the condition matches the supplied context. Empty conditions match by default. Evaluation errors return false; callers that need diagnostics should use EvaluateE.

func (Condition) EvaluateContinueE 

func (c Condition) EvaluateContinueE(ctx Context) (bool, error)

EvaluateContinueE evaluates a `continue:` condition against a step's own just-finished outcome (ctx.Status, expected to be PredicateSuccess or PredicateFailure). Unlike EvaluateWithImplicitSuccessE (used for `when:`, which defaults an unset condition to true only on success), an unset `continue:` always returns false — no forgiveness, preserving today's fail-stop behavior when `continue:` isn't set.

func (Condition) EvaluateE 

func (c Condition) EvaluateE(ctx Context) (bool, error)

EvaluateE returns whether the condition matches the supplied context and reports CEL runtime errors.

func (Condition) EvaluateWithImplicitSuccess 

func (c Condition) EvaluateWithImplicitSuccess(ctx Context) bool

EvaluateWithImplicitSuccess applies the hook-specific default: a condition that does not mention lifecycle status also requires success.

func (Condition) EvaluateWithImplicitSuccessE 

func (c Condition) EvaluateWithImplicitSuccessE(ctx Context) (bool, error)

EvaluateWithImplicitSuccessE is EvaluateWithImplicitSuccess with error reporting.

func (Condition) IsZero 

func (c Condition) IsZero() bool

IsZero reports whether no condition was configured.

func (Condition) MarshalJSON 

func (c Condition) MarshalJSON() ([]byte, error)

MarshalJSON preserves conditions when command configs are cloned through JSON.

func (Condition) MentionsAny 

func (c Condition) MentionsAny(names ...string) bool

MentionsAny reports whether any predicate with one of the supplied names is present in the condition tree.

func (Condition) MentionsCELIdentifier 

func (c Condition) MentionsCELIdentifier(name string) bool

MentionsCELIdentifier reports whether the condition's CEL expression(s) reference the named identifier (e.g. "checksum", "timestamp"). Used by pkg/runner/freshness to lazily compute expensive freshness facts only when a step's `when:` expression actually asks for them -- computing both checksum (hashes file content) and timestamp (stats mtimes) unconditionally would defeat the point of timestamp being the cheap option.

func (Condition) MentionsLifecycleStatus 

func (c Condition) MentionsLifecycleStatus() bool

MentionsLifecycleStatus reports whether the condition explicitly reasons about lifecycle status, either through a status predicate or a CEL `status` reference.

func (*Condition) UnmarshalJSON 

func (c *Condition) UnmarshalJSON(data []byte) error

UnmarshalJSON supports JSON config files and internal command cloning.

func (*Condition) UnmarshalYAML 

func (c *Condition) UnmarshalYAML(unmarshal func(any) error) error

UnmarshalYAML supports scalar, list, and object forms for `when`.

type Context 

type Context struct {
	CI        bool
	Status    string
	Stack     string
	Component string
	Workflow  string
	Step      string
	Hook      string
	Event     string
	Env       map[string]string
	// Answers carries caller-supplied structured facts (e.g. scaffold prompt
	// answers) available to CEL expressions as the `answers` map. Unlike Env,
	// values may be any type (string, bool, list, ...), not just strings.
	Answers map[string]any
	// OS is runtime.GOOS (e.g. "darwin", "linux", "windows"), letting `when:` replace a
	// dedicated `platforms:` field, e.g. `when: "os == 'darwin'"`.
	OS string
	// Arch is runtime.GOARCH (e.g. "amd64", "arm64").
	Arch string
	// Platform is OS+"/"+Arch (e.g. "linux/amd64"), for a single combined comparison.
	Platform string

	// ChecksumChanged/TimestampChanged/PreconditionsSuccess/Sources/Artifacts carry the
	// pkg/runner/freshness-computed facts for a step's `inputs:`/`artifacts:`/`preconditions:`,
	// exposed to `when:` as checksum.changed / timestamp.changed / preconditions.success /
	// sources / artifacts. Computed lazily -- callers should only populate the fact(s) a step's
	// `when:` actually mentions (see MentionsCELIdentifier), leaving the rest at their zero value.
	ChecksumChanged      bool
	TimestampChanged     bool
	PreconditionsSuccess bool
	// Sources/Artifacts are structured per-file records (not bare paths) so `when:` can compare
	// them directly, e.g. `sources.exists(s, artifacts.all(a, s.mtime > a.mtime))`, in addition
	// to the simpler checksum.changed/timestamp.changed convenience facts computed from the same
	// underlying data.
	Sources   []FileFact
	Artifacts []FileFact
}

Context carries runtime facts used to evaluate a declarative `when`.

type FileFact 

type FileFact struct {
	Path     string
	Mtime    int64
	Checksum string
}

FileFact is a resolved file's identity exposed to `when:` as one entry of the `sources`/ `artifacts` CEL lists. Mtime is a Unix timestamp (seconds) -- deliberately modification time, not ctime/atime/birthtime: mtime is the only one of the four that's both the correct staleness signal (content changes update it; permission/rename-only changes on ctime would cause false rebuilds) and portable via Go's stdlib (os.FileInfo.ModTime()) across every OS Atmos supports.

type Node 

type Node struct {
	Kind     string `json:"kind,omitempty"`
	Name     string `json:"name,omitempty"`
	Expr     string `json:"expr,omitempty"`
	Children []Node `json:"children,omitempty"`
	// contains filtered or unexported fields
}

Node is a small AST for declarative conditions.

func (Node) Evaluate 

func (n Node) Evaluate(ctx Context) bool

func (Node) EvaluateE 

func (n Node) EvaluateE(ctx Context) (bool, error)

type PredicateFunc 

type PredicateFunc func(Context) bool

PredicateFunc evaluates a named condition predicate against runtime facts.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.