Version Constraints

Version Constraints

Setup: See /installation for one-time SDK/CLI/MCP install.
Layers: SDK (Go) → CLI (shell) → MCP (AI tools) — pick your entry point.

When to Use

• You need to check if a version satisfies a constraint expression (e.g., ">=1.0.0,<2.0.0")
• You are resolving dependency version compatibility
• You need to filter versions by semver ranges (caret ^, tilde ~, wildcards x/*)
• You are working with constraint expressions that combine AND (comma) / OR (||) logic

Decision Tree

Need to check version against constraints?
├─ Single constraint (e.g., ">=1.0.0")?       → ParseConstraint() + Constraint.Match()
├─ AND logic (comma-separated, e.g., ">=1.0.0,<2.0.0")?
│                                              → ParseConstraintSet() / default CLI
├─ OR logic (||-separated, e.g., ">=1.0.0 || >=3.0.0")?
│                                              → ParseConstraintUnion() / --type union
├─ Quick one-liner (parse + match)?            → Version.Matches(expr)
├─ Version-centric check?                      → Version.Satisfies(constraint)
└─ Filter a collection by constraint?          → FilterByConstraint() / versions filter --constraint

Constraint Operators Reference

Combining: comma , = AND, double-pipe || = OR. Spaces around operators are NOT supported: use >=1.0.0 not >= 1.0.0.

Caret ^ semantics: ^1.2.3 = >=1.2.3,<2.0.0; ^0.2.3 = >=0.2.3,<0.3.0 (more restrictive for 0.x); ^0.0.3 = >=0.0.3,<0.0.4.

Tilde ~ semantics: ~1.2.3 = >=1.2.3,<1.3.0 (patch-level changes only).

Wildcard semantics: 1.x = 1.X = 1.* = >=1.0.0,<2.0.0; 1.2.x = >=1.2.0,<1.3.0.

Task Patterns

Check if a version satisfies a range constraint

Goal: Is "1.5.0" within ">=1.0.0,<2.0.0"?

SDK approach:

cs, _ := versions.ParseConstraintSet(">=1.0.0,<2.0.0")
v := versions.NewVersion("1.5.0")
ok := cs.Satisfies(v) // true

// Or the one-liner:
ok, _ := versions.NewVersion("1.5.0").Matches(">=1.0.0,<2.0.0")

CLI approach:

versions constraint ">=1.0.0,<2.0.0" 1.5.0        # AND logic (default)
versions satisfies 1.5.0 ">=1.0.0,<2.0.0"          # version-centric

MCP approach:

{"tool": "version_constraint_check", "arguments": {"expression": ">=1.0.0,<2.0.0", "version": "1.5.0"}}

Check if a version satisfies OR logic constraints

Goal: Is "3.5.0" within ">=1.0.0,<2.0.0 || >=3.0.0"?

SDK approach:

cu, _ := versions.ParseConstraintUnion(">=1.0.0,<2.0.0 || >=3.0.0")
ok := cu.Satisfies(versions.NewVersion("3.5.0"))  // true
ok = cu.Satisfies(versions.NewVersion("2.5.0"))   // false

CLI approach:

versions constraint ">=1.0.0 || >=3.0.0" 3.5.0 --type union    # match (3.5.0 >= 3.0.0)
versions constraint ">=1.0.0 || >=3.0.0" 2.5.0 --type union    # no match

MCP approach:

{"tool": "version_constraint_check", "arguments": {"expression": ">=1.0.0 || >=3.0.0", "version": "3.5.0", "type": "union"}}

Use caret constraint

Goal: Check if "1.9.9" is compatible with "^1.2.3" (matches >=1.2.3, <2.0.0).

SDK approach:

c, _ := versions.ParseConstraint("^1.2.3")
c.Match(versions.NewVersion("1.9.9"))  // true
c.Match(versions.NewVersion("2.0.0"))  // false

// Caret with 0.x is more restrictive:
c2, _ := versions.ParseConstraint("^0.2.3")  // >=0.2.3, <0.3.0

CLI approach:

versions constraint "^1.2.3" 1.9.9 --type single    # true
versions constraint "^1.2.3" 2.0.0 --type single    # false

MCP approach:

{"tool": "version_constraint_check", "arguments": {"expression": "^1.2.3", "version": "1.9.9", "type": "single"}}

Use tilde constraint

Goal: Check if "1.2.9" is within patch-level range "~1.2.3" (matches >=1.2.3, <1.3.0).

SDK approach:

c, _ := versions.ParseConstraint("~1.2.3")
c.Match(versions.NewVersion("1.2.9"))  // true
c.Match(versions.NewVersion("1.3.0"))  // false

CLI approach:

versions constraint "~1.2.3" 1.2.9 --type single    # true
versions constraint "~1.2.3" 1.3.0 --type single    # false

MCP approach:

{"tool": "version_constraint_check", "arguments": {"expression": "~1.2.3", "version": "1.2.9", "type": "single"}}

Filter a version list by constraint

Goal: From ["0.5.0", "1.0.0", "1.5.0", "2.0.0"], keep only versions matching ">=1.0.0,<2.0.0".

SDK approach:

cs, _ := versions.ParseConstraintSet(">=1.0.0,<2.0.0")
versionList := versions.NewVersions("0.5.0", "1.0.0", "1.5.0", "2.0.0")
filtered := versions.FilterByConstraintSet(versionList, cs)
// filtered = [1.0.0, 1.5.0]

CLI approach:

versions filter --constraint ">=1.0.0,<2.0.0" 0.5.0 1.0.0 1.5.0 2.0.0

MCP approach:

{"tool": "version_filter", "arguments": {"versions": ["0.5.0", "1.0.0", "1.5.0", "2.0.0"], "constraint": ">=1.0.0,<2.0.0"}}

API Reference

SDK — Parsing Functions

// Parse a single constraint expression (e.g. ">=1.0.0", "^1.2.3", "~1.2.3")
func ParseConstraint(expr string) (*Constraint, error)

// Parse comma-separated AND constraints (e.g. ">=1.0.0,<2.0.0")
func ParseConstraintSet(expr string) (*ConstraintSet, error)

// Parse ||-separated OR constraint sets (e.g. ">=1.0.0,<2.0.0 || >=3.0.0")
func ParseConstraintUnion(expr string) (*ConstraintUnion, error)

SDK — Matching Methods

// Single constraint matching
func (c *Constraint) Match(v *Version) bool
func (c *Constraint) String() string

// ConstraintSet (AND logic) — all must match
func (cs *ConstraintSet) Match(v *Version) bool
func (cs *ConstraintSet) Satisfies(v *Version) bool   // alias for Match
func (cs *ConstraintSet) Len() int
func (cs *ConstraintSet) String() string

// ConstraintUnion (OR logic) — any set must match
func (cu *ConstraintUnion) Match(v *Version) bool
func (cu *ConstraintUnion) Satisfies(v *Version) bool // alias for Match
func (cu *ConstraintUnion) String() string

// Version-centric convenience methods
func (v *Version) Satisfies(constraint *Constraint) bool
func (v *Version) Matches(expr string) (bool, error)  // parse + match one-liner

SDK — Filter Functions

func FilterByConstraint(versions []*Version, constraint *Constraint) []*Version
func FilterByConstraintSet(versions []*Version, cs *ConstraintSet) []*Version

CLI Commands

# Check constraint — single type
versions constraint "<expr>" <version> --type single

# Check constraint — ConstraintSet (AND logic, default)
versions constraint "<expr>" <version>

# Check constraint — ConstraintUnion (OR logic)
versions constraint "<expr>" <version> --type union

# Version-centric check (auto-detects type)
versions satisfies <version> "<constraint-expression>"

# Filter by constraint — single
versions filter --constraint "<expr>" --constraint-type single <versions...>

# Filter by constraint — set (default)
versions filter --constraint "<expr>" <versions...>

# Filter by constraint — union
versions filter --constraint "<expr>" --constraint-type union <versions...>

Examples:

versions constraint ">=1.0.0,<2.0.0" 1.5.0         # AND logic
versions constraint ">=1.0.0 || >=3.0.0" 3.5.0 --type union
versions satisfies 1.5.0 ">=1.0.0,<2.0.0"
versions filter --constraint ">=1.0.0,<2.0.0" 0.5.0 1.0.0 1.5.0 2.0.0

MCP Tools

Cross-References

• [[version-check]] — for simpler boolean type checks (IsStable, IsBeta, etc.)
• [[version-comparison]] — for direct pairwise version comparison
• [[version-range-query]] — for range queries on version collections
• [[version-parsing]] — for parsing version strings before constraint checking

Important Notes

• Caret ^ follows npm semver semantics: ^1.2.3 = >=1.2.3,<2.0.0, but ^0.2.3 = >=0.2.3,<0.3.0 (more restrictive for 0.x)
• Tilde ~ allows patch-level changes only: ~1.2.3 matches 1.2.x but NOT 1.3.0
• Wildcards x/X/* are equivalent: 1.x = 1.X = 1.*
• ConstraintSet (comma) = AND, ConstraintUnion (||) = OR
• Spaces around operators are NOT supported: use >=1.0.0 not >= 1.0.0
• ParseConstraintSet wraps errors with context (parse constraint "BAD": ...); ParseConstraintUnion does NOT
• CLI constraint type defaults to "set" (AND); use --type single for single constraint, --type union for OR logic