README
¶
semver CEL plugin
Exposes a semver object inside every CEL tenet so policies can
parse and compare Semantic Versioning 2.0.0
strings without resorting to regex tricks.
Implementation lives in this package; the plugin is registered as a
default in pkg/evaluator/cel/evaluator.go.
Methods
| Expression | Returns | Description |
|---|---|---|
semver.major("1.2.3") |
int |
The major component. |
semver.minor("1.2.3") |
int |
The minor component. |
semver.patch("1.2.3") |
int |
The patch component. |
semver.prerelease("1.2.3-alpha.1") |
string |
The pre-release label, or "" if none. |
semver.build("1.2.3+sha.abc") |
string |
The build metadata, or "" if none. |
semver.parse("1.2.3-alpha+sha") |
map |
All components plus original, as a map. |
semver.isValid("1.2.3") |
bool |
True if the argument parses as a semver. |
semver.isStable("1.2.3") |
bool |
True when major >= 1 and there is no pre-release tag. |
semver.compare(a, b) |
int |
-1 if a < b, 0 if equal, 1 if a > b. |
semver.isNewer(a, b) |
bool |
Shorthand for compare(a, b) > 0. |
semver.isOlder(a, b) |
bool |
Shorthand for compare(a, b) < 0. |
semver.equal(a, b) |
bool |
Shorthand for compare(a, b) == 0. |
semver.satisfies(v, constraint) |
bool |
Evaluates a Masterminds/semver constraint (^1.2.3, >=1.0.0 <2.0.0, ~1.2, …). |
Types
major, minor, and patch return int so callers can do
arithmetic directly. Wrap with CEL's string() constructor when a
string is needed:
string(semver.major(subject.name)) // -> "1"
Leading v
Version strings with a leading v (e.g. "v1.2.3") are accepted
and produce the same result as the un-prefixed form.
Validation
Unparseable inputs return a CEL evaluation error. When you need to
guard an expression, reach for semver.isValid first:
semver.isValid(subject.name) && semver.major(subject.name) >= 2
Recipes
Reject artefacts below a baseline:
semver.satisfies(predicate.data.version, ">=2.0.0 <3.0.0")
Block pre-release builds from promoting to production:
semver.isStable(predicate.data.version)
Only allow patch bumps compared to a pinned base:
semver.major(predicate.data.version) == semver.major(context.base) &&
semver.minor(predicate.data.version) == semver.minor(context.base) &&
!semver.isOlder(predicate.data.version, context.base)
Documentation
¶
Overview ¶
Package semver provides a CEL-runtime plugin that exposes a `semver` object with helpers for parsing and comparing Semantic Versioning 2.0.0 strings. See docs/03-ampel-policy-guide.md for the list of exposed methods and usage examples.
Index ¶
- Variables
- type Plugin
- type SemverTool
- func (st *SemverTool) CompileOptions() []cel.EnvOption
- func (*SemverTool) ConvertToNative(_ reflect.Type) (any, error)
- func (st *SemverTool) ConvertToType(typeVal ref.Type) ref.Val
- func (*SemverTool) Equal(_ ref.Val) ref.Val
- func (st *SemverTool) Functions() []cel.EnvOption
- func (*SemverTool) ProgramOptions() []cel.ProgramOption
- func (*SemverTool) Type() ref.Type
- func (st *SemverTool) Value() any
- type TypeAdapter
Constants ¶
This section is empty.
Variables ¶
var SemverType = cel.ObjectType("semver", traits.ReceiverType)
SemverType is the CEL object type registered for the `semver` global. Like the other plugin tools, it is an opaque handle the CEL compiler uses to dispatch method calls.
Functions ¶
This section is empty.
Types ¶
type Plugin ¶
type Plugin struct {
Tool *SemverTool
}
Plugin wires the semver tool into ampel's CEL evaluator.
func (*Plugin) Capabilities ¶
func (p *Plugin) Capabilities() []api.Capability
type SemverTool ¶
type SemverTool struct{}
SemverTool is the host object for the `semver.*` methods in CEL.
func (*SemverTool) CompileOptions ¶
func (st *SemverTool) CompileOptions() []cel.EnvOption
func (*SemverTool) ConvertToNative ¶
func (*SemverTool) ConvertToNative(_ reflect.Type) (any, error)
func (*SemverTool) ConvertToType ¶
func (st *SemverTool) ConvertToType(typeVal ref.Type) ref.Val
func (*SemverTool) Functions ¶
func (st *SemverTool) Functions() []cel.EnvOption
Functions registers the member overloads exposed on the semver object. Every accessor accepts a string and either returns a numeric/string component or a bool — the failure mode for an unparseable input is a CEL error that surfaces at evaluation time.
func (*SemverTool) ProgramOptions ¶
func (*SemverTool) ProgramOptions() []cel.ProgramOption
func (*SemverTool) Type ¶
func (*SemverTool) Type() ref.Type
func (*SemverTool) Value ¶
func (st *SemverTool) Value() any
type TypeAdapter ¶
type TypeAdapter struct{}
TypeAdapter registers SemverTool with CEL's runtime type system.
func (TypeAdapter) NativeToValue ¶
func (TypeAdapter) NativeToValue(value any) ref.Val
Source Files