Module constraints 

Version constraint parsing, sets, and resolution system.

The constraints module contains the core constraint management system for AGPM, including constraint parsing, conflict detection, and multi-dependency resolution. See the module documentation for comprehensive examples. Version constraint parsing and resolution for AGPM dependencies.

This module provides comprehensive version constraint handling for AGPM dependencies, supporting semantic versioning, Git references, and various constraint types. It enables dependency resolution with conflict detection and version matching.

Version Constraint Types

AGPM supports several types of version constraints:

• Exact versions: "1.0.0" - Matches exactly the specified version
• Semantic version ranges: "^1.0.0", "~1.2.0", ">=1.0.0" - Uses semver ranges
• Git references: "main", "feature/branch", "abc123", "latest" - Git branches, tags, or commits

Constraint Resolution

The constraint system provides:

• Conflict detection: Prevents incompatible constraints for the same dependency
• Version resolution: Finds best matching versions from available options
• Prerelease handling: Manages alpha, beta, RC versions appropriately
• Precedence rules: Resolves multiple constraints consistently

Examples

Basic Constraint Parsing

use agpm_cli::version::constraints::VersionConstraint;

// Parse different constraint types
let exact = VersionConstraint::parse("1.0.0")?;
let caret = VersionConstraint::parse("^1.0.0")?;
let latest = VersionConstraint::parse("latest")?;
let branch = VersionConstraint::parse("main")?;

Constraint Set Management

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 versions = vec![
    Version::parse("0.9.0")?,
    Version::parse("1.5.0")?,
    Version::parse("2.0.0")?,
];

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

Dependency Resolution

use agpm_cli::version::constraints::ConstraintResolver;
use semver::Version;
use std::collections::HashMap;

let mut resolver = ConstraintResolver::new();
resolver.add_constraint("dep1", "^1.0.0")?;
resolver.add_constraint("dep2", "~2.1.0")?;

let mut available = HashMap::new();
available.insert("dep1".to_string(), vec![Version::parse("1.5.0")?]);
available.insert("dep2".to_string(), vec![Version::parse("2.1.3")?]);

let resolved = resolver.resolve(&available)?;

Constraint Syntax Reference

Syntax	Description	Example
1.0.0	Exact version	"1.0.0"
^1.0.0	Compatible within major version	"^1.0.0" matches 1.x.x
~1.2.0	Compatible within minor version	"~1.2.0" matches 1.2.x
>=1.0.0	Greater than or equal	">=1.0.0"
<2.0.0	Less than	"<2.0.0"
>=1.0.0, <2.0.0	Range constraint	Multiple constraints
main	Git branch reference	Branch name
latest	Git tag or branch name	Just a regular ref
v1.0.0	Git tag reference	Tag name
abc123	Git commit reference	Commit hash (full or abbreviated)

Version Resolution Precedence

When resolving versions, AGPM follows this precedence:

1. Exact matches take highest priority
2. Semantic version requirements are resolved to highest compatible version
3. Stable versions are preferred over prereleases (unless explicitly allowed)
4. Newer versions are preferred when multiple versions satisfy constraints
5. Git references bypass semantic versioning and use exact ref matching

Prerelease Version Handling

• Default behavior: Prereleases (alpha, beta, RC) are excluded from resolution
• Explicit inclusion: Use Git references to include prereleases
• Version ranges: Prereleases only match if explicitly specified in range
• Constraint sets: If any constraint allows prereleases, the entire set does

Error Conditions

The constraint system handles these error conditions:

• Conflicting constraints: Same dependency with incompatible requirements
• Invalid version strings: Malformed semantic version specifications
• Resolution failures: No available version satisfies all constraints
• Missing dependencies: Required dependency not found in available versions

Structs

ConstraintResolver

Manages version constraints for multiple dependencies and resolves them simultaneously.

ConstraintSet

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

Enums

VersionConstraint

A version constraint that defines acceptable versions for a dependency.