Struct ConstraintSet 

pub struct ConstraintSet { /* private fields */ }

A collection of version constraints that must all be satisfied simultaneously.

ConstraintSet manages multiple VersionConstraints for a single dependency, ensuring that all constraints are compatible and can be resolved together. It provides conflict detection, version matching, and best-match selection.

Constraint Combination

When multiple constraints are added to a set, they create an intersection of requirements. For example:

• >=1.0.0 AND <2.0.0 = versions in range [1.0.0, 2.0.0)
• ^1.0.0 AND ~1.2.0 = versions compatible with both (e.g., 1.2.x)

Conflict Detection

The constraint set detects and prevents conflicting constraints:

• Multiple exact versions: 1.0.0 AND 2.0.0 (impossible to satisfy)
• Conflicting Git refs: main AND develop (can’t be both branches)

Resolution Strategy

When selecting from available versions, the set:

1. Filters versions that satisfy ALL constraints
2. Excludes prereleases unless explicitly allowed
3. Selects the highest remaining version

Examples

Basic Usage

use agpm_cli::version::constraints::{ConstraintSet, VersionConstraint};
use semver::Version;

let mut set = ConstraintSet::new();
set.add(VersionConstraint::parse(">=1.0.0")?)?;
set.add(VersionConstraint::parse("<2.0.0")?)?;

let version = Version::parse("1.5.0")?;
assert!(set.satisfies(&version));

let version = Version::parse("2.0.0")?;
assert!(!set.satisfies(&version)); // Outside range

Best Match Selection

use agpm_cli::version::constraints::{ConstraintSet, VersionConstraint};
use semver::Version;

let mut set = ConstraintSet::new();
set.add(VersionConstraint::parse("^1.0.0")?)?;

let versions = vec![
    Version::parse("0.9.0")?,  // Too old
    Version::parse("1.0.0")?,  // Matches
    Version::parse("1.5.0")?,  // Matches, higher
    Version::parse("2.0.0")?,  // Too new
];

let best = set.find_best_match(&versions).unwrap();
assert_eq!(best, &Version::parse("1.5.0")?); // Highest compatible

Conflict Detection

use agpm_cli::version::constraints::{ConstraintSet, VersionConstraint};
use semver::Version;

let mut set = ConstraintSet::new();
set.add(VersionConstraint::parse("1.0.0")?)?; // Exact version

// This will fail - can't have two different exact versions
let result = set.add(VersionConstraint::parse("2.0.0")?);
assert!(result.is_err());

Implementations

impl ConstraintSet

pub const fn new() -> Self

Creates a new empty constraint set

Returns

Returns a new ConstraintSet with no constraints

pub fn add(&mut self, constraint: VersionConstraint) -> Result<()>

Add a constraint to this set with conflict detection.

This method adds a new constraint to the set after checking for conflicts with existing constraints. If the new constraint would create an impossible situation (like requiring two different exact versions), an error is returned.

Arguments

• constraint - The VersionConstraint to add to this set

Returns

Returns Ok(()) if the constraint was added successfully, or Err if it conflicts with existing constraints.

Conflict Detection

Current conflict detection covers:

• Exact version conflicts: Different exact versions for the same dependency
• Git ref conflicts: Different Git references for the same dependency

Future versions may add more sophisticated conflict detection for semantic version ranges.

Examples

use agpm_cli::version::constraints::{ConstraintSet, VersionConstraint};

let mut set = ConstraintSet::new();

// These constraints are compatible
set.add(VersionConstraint::parse(">=1.0.0")?)?;
set.add(VersionConstraint::parse("<2.0.0")?)?;

// This would conflict with exact versions
set.add(VersionConstraint::parse("1.5.0")?)?;
let result = set.add(VersionConstraint::parse("1.6.0")?);
assert!(result.is_err()); // Conflict: can't be both 1.5.0 AND 1.6.0

pub fn satisfies(&self, version: &Version) -> bool

Check if a version satisfies all constraints in this set.

This method tests whether a given version passes all the constraints in this set. For a version to be acceptable, it must satisfy every single constraint - this represents a logical AND operation.

Arguments

• version - The semantic version to test against all constraints

Returns

Returns true if the version satisfies ALL constraints, false if it fails to satisfy any constraint.

Examples

use agpm_cli::version::constraints::{ConstraintSet, VersionConstraint};
use semver::Version;

let mut set = ConstraintSet::new();
set.add(VersionConstraint::parse(">=1.0.0")?)?; // Must be at least 1.0.0
set.add(VersionConstraint::parse("<2.0.0")?)?;  // Must be less than 2.0.0
set.add(VersionConstraint::parse("^1.0.0")?)?;  // Must be compatible with 1.0.0

assert!(set.satisfies(&Version::parse("1.5.0")?)); // Satisfies all three
assert!(!set.satisfies(&Version::parse("0.9.0")?)); // Fails >=1.0.0
assert!(!set.satisfies(&Version::parse("2.0.0")?)); // Fails <2.0.0

Performance Note

This method short-circuits on the first constraint that fails, making it efficient even with many constraints.

pub fn find_best_match<'a>( &self, versions: &'a [Version], ) -> Option<&'a Version>

Find the best matching version from a list of available versions.

This method filters provided versions to find those that satisfy all constraints, then selects the “best” match according to AGPM’s resolution strategy. The selection prioritizes newer versions while respecting prerelease preferences.

Resolution Strategy

1. Filter candidates: Keep only versions that satisfy all constraints
2. Sort by version: Order candidates from highest to lowest version
3. Apply prerelease policy: Remove prereleases unless explicitly allowed
4. Select best: Return the highest remaining version

Arguments

• versions - Slice of available versions to choose from

Returns

Returns Some(&Version) with the best matching version, or None if no version satisfies all constraints.

Examples

use agpm_cli::version::constraints::{ConstraintSet, VersionConstraint};
use semver::Version;

let mut set = ConstraintSet::new();
set.add(VersionConstraint::parse("^1.0.0")?)?;

let versions = vec![
    Version::parse("0.9.0")?,    // Too old
    Version::parse("1.0.0")?,    // Compatible
    Version::parse("1.2.0")?,    // Compatible, newer
    Version::parse("1.5.0")?,    // Compatible, newest
    Version::parse("2.0.0")?,    // Too new
];

let best = set.find_best_match(&versions).unwrap();
assert_eq!(best, &Version::parse("1.5.0")?); // Highest compatible version

Prerelease Handling

use agpm_cli::version::constraints::{ConstraintSet, VersionConstraint};
use semver::Version;

let mut set = ConstraintSet::new();
set.add(VersionConstraint::parse("^1.0.0")?)?; // Doesn't allow prereleases

let versions = vec![
    Version::parse("1.0.0")?,
    Version::parse("1.1.0-alpha.1")?,  // Prerelease
    Version::parse("1.1.0")?,           // Stable
];

let best = set.find_best_match(&versions).unwrap();
assert_eq!(best, &Version::parse("1.1.0")?); // Stable version preferred

pub fn allows_prerelease(&self) -> bool

Check if any constraint in this set allows prerelease versions.

This method determines the prerelease policy for the entire constraint set. If ANY constraint in the set allows prereleases, the entire set is considered to allow prereleases. This ensures that explicit prerelease constraints (like latest-prerelease or Git refs) are respected.

Returns

Returns true if any constraint allows prereleases, false if all constraints exclude prereleases.

Examples

use agpm_cli::version::constraints::{ConstraintSet, VersionConstraint};

let mut stable_set = ConstraintSet::new();
stable_set.add(VersionConstraint::parse("^1.0.0")?)?;
stable_set.add(VersionConstraint::parse("~1.2.0")?)?;
assert!(!stable_set.allows_prerelease()); // All constraints exclude prereleases

let mut prerelease_set = ConstraintSet::new();
prerelease_set.add(VersionConstraint::parse("^1.0.0")?)?;
prerelease_set.add(VersionConstraint::parse("main")?)?; // Git ref allows prereleases
assert!(prerelease_set.allows_prerelease()); // One constraint allows prereleases

Impact on Resolution

This setting affects find_best_match behavior:

• If false: Prerelease versions are filtered out before selection
• If true: Prerelease versions are included in selection

Trait Implementations

impl Clone for ConstraintSet

fn clone(&self) -> ConstraintSet

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ConstraintSet

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ConstraintSet

fn default() -> Self

Returns the “default value” for a type.