Module version

agpm_cli

Module version 

Source
Expand description

Version constraint parsing, comparison, and resolution for AGPM dependencies.

This module provides comprehensive version management for AGPM, handling semantic versioning, Git references, and dependency resolution. It supports multiple version specification formats and provides sophisticated constraint resolution with conflict detection and prerelease handling.

§Module Organization

  • constraints - Version constraint parsing, sets, and resolution
  • comparison - Version comparison utilities and analysis
  • Core types and functions for Git tag resolution

§Version Specifications

AGPM supports several version specification formats:

§Semantic Versions

  • Exact versions: "1.0.0" - Matches exactly the specified version
  • Caret ranges: "^1.0.0" - Compatible within major version (1.x.x)
  • Tilde ranges: "~1.2.0" - Compatible within minor version (1.2.x)
  • Comparison ranges: ">=1.0.0", "<2.0.0", ">=1.0.0, <2.0.0"

§Special Keywords

  • Wildcard: "*" - Matches any version

§Git References

  • Branches: "main", "develop", "feature/auth"
  • Tags: "v1.0.0", "release-2023-01"
  • Commits: "abc123..." (full or abbreviated SHA)

§Version Resolution Strategy

The version resolution system follows this process:

  1. Tag Discovery: Fetch all tags from the Git repository
  2. Semantic Parsing: Parse tags as semantic versions where possible
  3. Constraint Matching: Apply version constraints to find candidates
  4. Best Selection: Choose the highest compatible version
  5. Fallback Handling: Use branches or commits if no tags match

§Constraint Resolution Features

  • Multi-constraint support: Combine multiple constraints per dependency
  • Conflict detection: Prevent impossible constraint combinations
  • Prerelease handling: Sophisticated alpha/beta/RC version management
  • Cross-dependency resolution: Resolve entire dependency graphs

§Examples

§Basic Git Tag Resolution

use agpm_cli::version::{VersionResolver, VersionInfo};
use agpm_cli::git::GitRepo;
use std::path::PathBuf;

let repo = GitRepo::new(PathBuf::from("/path/to/repo"));
let resolver = VersionResolver::from_git_tags(&repo).await?;

// Resolve different constraint types
if let Ok(Some(version)) = resolver.resolve("^1.0.0") {
    println!("Resolved caret constraint to: {}", version.tag);
}

§Advanced Constraint Resolution

use agpm_cli::version::constraints::{ConstraintResolver, VersionConstraint};
use semver::Version;
use std::collections::HashMap;

let mut resolver = ConstraintResolver::new();

// Add constraints for multiple dependencies
resolver.add_constraint("web-framework", "^2.0.0")?;
resolver.add_constraint("database", "~1.5.0")?;
resolver.add_constraint("auth-lib", ">=3.0.0")?;

// Provide available versions
let mut available = HashMap::new();
available.insert("web-framework".to_string(), vec![Version::parse("2.1.0")?]);
available.insert("database".to_string(), vec![Version::parse("1.5.3")?]);
available.insert("auth-lib".to_string(), vec![Version::parse("3.2.0")?]);

// Resolve all dependencies simultaneously
let resolved = resolver.resolve(&available)?;
println!("Resolved {} dependencies", resolved.len());

§Version Comparison and Analysis

use agpm_cli::version::comparison::VersionComparator;

let available_versions = vec![
    "v1.0.0".to_string(),
    "v1.5.0".to_string(),
    "v2.0.0".to_string(),
];

// Check for newer versions
let has_updates = VersionComparator::has_newer_version("1.2.0", &available_versions)?;
println!("Updates available: {}", has_updates);

// Get all newer versions sorted by recency
let newer = VersionComparator::get_newer_versions("1.2.0", &available_versions)?;
for version in newer {
    println!("Newer version: {}", version);
}

// Find the latest version
if let Some(latest) = VersionComparator::get_latest(&available_versions)? {
    println!("Latest version: {}", latest);
}

§Prerelease Version Handling

AGPM provides sophisticated prerelease version management:

  • Default exclusion: Most constraints exclude prereleases for stability
  • Explicit inclusion: Use Git refs to include them
  • Constraint inheritance: If any constraint allows prereleases, all do
  • Version precedence: Stable versions are preferred when available

§Error Handling

The version system provides comprehensive error handling:

  • Invalid version strings: Malformed semantic versions are rejected
  • Conflicting constraints: Impossible combinations are detected early
  • Missing dependencies: Required dependencies without versions are flagged
  • Resolution failures: Unsatisfiable constraints are clearly reported

§Cross-References

Modules§

comparison
Version comparison utilities and analysis functions.
conflict
Version conflict detection and circular dependency detection.
constraints
Version constraint parsing, sets, and resolution system.

Structs§

VersionInfo
Version information extracted from a Git tag.
VersionResolver
Resolves semantic versions from Git repository tags.

Enums§

VersionConstraint
Represents different types of version constraints in AGPM.

Functions§

matches_requirement
Check if a version string satisfies a version requirement.
parse_version_constraint
Parse a version constraint string into a structured constraint type.
parse_version_req
Parse a version requirement string, normalizing ‘v’ prefixes.
split_prefix_and_version
Splits a version string into an optional prefix and the version/constraint part.