Struct VersionResolver 

pub struct VersionResolver { /* private fields */ }

Centralized version resolver for batch SHA resolution.

The VersionResolver manages the collection and resolution of all dependency versions in a single batch operation, enabling optimal Git repository access patterns and maximum worktree reuse.

Implementations

impl VersionResolver

pub fn new(cache: Cache) -> Self

Creates a new version resolver with the given cache and default concurrency

Uses the same default concurrency as installation: max(10, 2 × CPU cores)

pub fn with_concurrency(cache: Cache, max_concurrency: usize) -> Self

Creates a new version resolver with explicit concurrency limit

pub fn add_version( &self, source: &str, url: &str, version: Option<&str>, resolution_mode: ResolutionMode, )

Adds a version to be resolved

Multiple calls with the same (source, version) pair will be deduplicated.

Arguments

• source - Source name from manifest
• url - Git repository URL
• version - Version specification (tag, branch, commit, or None for HEAD)
• resolution_mode - The resolution mode to use for this entry

pub async fn resolve_all( &self, progress: Option<Arc<MultiPhaseProgress>>, ) -> Result<()>

Resolves all collected versions to their commit SHAs using cached repositories.

This is the second phase of AGPM’s two-phase resolution architecture. Call after pre_sync_sources(). See documentation for detailed resolution process and performance characteristics.

Prerequisites

CRITICAL: pre_sync_sources() must be called first to populate the cache.

Performance

Uses batch git rev-parse --stdin to resolve multiple refs in a single process, reducing process spawn overhead from O(n) to O(1) per source. This is especially impactful on Windows where process spawning is expensive.

Example

let cache = Cache::new()?;
let mut resolver = VersionResolver::new(cache);
resolver.add_version("source", "https://github.com/org/repo.git", Some("v1.2.3"), ResolutionMode::Version);

resolver.pre_sync_sources(None).await?;  // Pass None for no progress tracking
resolver.resolve_all(None).await?;  // Pass None for no progress tracking

Errors

Returns an error if:

• Repository not pre-synced (call pre_sync_sources() first)
• Version/tag/branch not found or constraint unsatisfied
• Git operations fail or repository inaccessible

pub async fn resolve_single( &self, source: &str, url: &str, version: Option<&str>, ) -> Result<String>

Resolves a single version to SHA without affecting the batch

This is useful for incremental resolution or testing.

pub fn get_resolved_sha(&self, source: &str, version: &str) -> Option<String>

Gets the resolved SHA for a given source and version

Returns None if the version hasn’t been resolved yet.

Arguments

• source - Source name
• version - Version specification (use “HEAD” for None)

pub fn get_all_resolved(&self) -> HashMap<(String, String), String>

Gets all resolved SHAs as a HashMap

Useful for bulk operations or debugging.

pub fn get_all_resolved_full( &self, ) -> HashMap<(String, String), ResolvedVersion>

Gets all resolved versions with both SHA and resolved reference

Returns a HashMap with (source, version) -> ResolvedVersion

pub fn is_resolved(&self, source: &str, version: &str) -> bool

Checks if a specific version has been resolved

pub async fn pre_sync_sources( &self, progress: Option<Arc<MultiPhaseProgress>>, ) -> Result<()>

Pre-syncs all unique sources to ensure repositories are cloned/fetched.

This is the first phase of AGPM’s two-phase resolution architecture. Performs all Git network operations upfront before resolve_all(). Automatically deduplicates by source URL for efficiency.

Prerequisites

Call this method after adding versions via add_version() calls.

Example

use agpm_cli::resolver::version_resolver::VersionResolver;
use agpm_cli::resolver::types::ResolutionMode;
use agpm_cli::cache::Cache;

let cache = Cache::new()?;
let mut resolver = VersionResolver::new(cache);
resolver.add_version("source", "https://github.com/org/repo.git", Some("v1.0.0"), ResolutionMode::Version);

// Phase 1: Sync repositories (parallel network operations with progress)
resolver.pre_sync_sources(None).await?;  // Pass None for no progress tracking

// Phase 2: Resolve versions to SHAs (local operations)
resolver.resolve_all(None).await?;  // Pass None for no progress tracking

Arguments

• progress - Optional progress tracker. Pass None to disable progress tracking. When provided, displays real-time sync status with windowed updates showing which sources are being synced. The progress tracker automatically calculates window size based on the number of concurrent operations.

Errors

Returns an error if:

• Repository cloning or fetching fails (network, auth, invalid URL)
• Authentication fails for private repositories
• Insufficient disk space or repository corruption

pub fn get_bare_repo_path(&self, source: &str) -> Option<PathBuf>

Gets the bare repository path for a source

Returns None if the source hasn’t been processed yet.

pub fn register_bare_repo(&self, source: String, repo_path: PathBuf)

Registers a bare repository path for a source

This is used when manually ensuring a repository exists without clearing all state.

pub fn clear(&self)

Clears all resolved versions and cached data

Useful for testing or when starting a fresh resolution.

pub fn pending_count(&self) -> usize

Returns the number of unique versions to resolve

pub fn has_entries(&self) -> bool

Checks if the resolver has any entries to resolve.

This is a convenience method to determine if the resolver has been populated with version entries via add_version() calls. It’s useful for conditional logic to avoid unnecessary operations when no versions need resolution.

Returns

Returns true if there are entries that need resolution, false if the resolver is empty.

Example

let mut resolver = VersionResolver::new(cache);
assert!(!resolver.has_entries()); // Initially empty

resolver.add_version("source", "https://github.com/org/repo.git", Some("v1.0.0"), ResolutionMode::Version);
assert!(resolver.has_entries()); // Now has entries

pub fn resolved_count(&self) -> usize

Returns the number of successfully resolved versions