agpm_cli/resolver/

types.rs

//! Core types and utilities for dependency resolution.
//!
//! This module provides shared types, context structures, and helper functions
//! used throughout the resolver. It consolidates:
//! - Resolution context and core shared state
//! - Context structures for different resolution phases
//! - Pure helper functions for dependency manipulation

use std::collections::HashMap;
use std::sync::Arc;

use dashmap::DashMap;

use crate::cache::Cache;
use crate::core::ResourceType;
use crate::core::operation_context::OperationContext;
use crate::lockfile::lockfile_dependency_ref::LockfileDependencyRef;
use crate::manifest::{Manifest, ResourceDependency};
use crate::source::SourceManager;
use crate::version::conflict::ConflictDetector;

// ============================================================================
// Resolution Mode Types
// ============================================================================

/// Determines which resolution strategy to use for a dependency
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ResolutionMode {
    /// Semantic versioning with constraints and tags
    Version,
    /// Direct git reference (branch or rev)
    GitRef,
}

impl ResolutionMode {
    /// Determine resolution mode from a dependency specification
    pub fn from_dependency(dep: &crate::manifest::ResourceDependency) -> Self {
        use crate::manifest::ResourceDependency;

        match dep {
            ResourceDependency::Simple(_) => Self::Version, // Default to version
            ResourceDependency::Detailed(d) => {
                if d.branch.is_some() || d.rev.is_some() {
                    Self::GitRef
                } else {
                    Self::Version
                }
            }
        }
    }
}

// ============================================================================
// Core Resolution Context
// ============================================================================

/// Core shared context for dependency resolution.
///
/// This struct holds immutable state that is shared across all
/// resolution services. It does not change during resolution.
pub struct ResolutionCore {
    /// The project manifest with dependencies and configuration
    pub manifest: Manifest,

    /// The cache for worktrees and Git operations
    pub cache: Cache,

    /// The source manager for resolving source URLs
    pub source_manager: SourceManager,

    /// Optional operation context for warnings and progress tracking
    pub operation_context: Option<Arc<OperationContext>>,
}

impl ResolutionCore {
    /// Create a new resolution core.
    pub fn new(
        manifest: Manifest,
        cache: Cache,
        source_manager: SourceManager,
        operation_context: Option<Arc<OperationContext>>,
    ) -> Self {
        Self {
            manifest,
            cache,
            source_manager,
            operation_context,
        }
    }

    /// Get a reference to the manifest.
    pub fn manifest(&self) -> &Manifest {
        &self.manifest
    }

    /// Get a reference to the cache.
    pub fn cache(&self) -> &Cache {
        &self.cache
    }

    /// Get a reference to the source manager.
    pub fn source_manager(&self) -> &SourceManager {
        &self.source_manager
    }

    /// Get a reference to the operation context if present.
    pub fn operation_context(&self) -> Option<&Arc<OperationContext>> {
        self.operation_context.as_ref()
    }
}

// ============================================================================
// Resolution Context Types
// ============================================================================

/// Type alias for dependency keys used in resolution maps.
///
/// Format: (ResourceType, dependency_name, source, tool, variant_inputs_hash)
///
/// The variant_inputs_hash ensures that dependencies with different template variables
/// are treated as distinct entries, preventing incorrect deduplication when multiple
/// parent resources need the same dependency with different variant inputs.
pub type DependencyKey = (ResourceType, String, Option<String>, Option<String>, String);

/// Base resolution context with immutable shared state.
///
/// This context is passed to most resolution operations and provides access
/// to the manifest, cache, source manager, and operation context.
///
/// Implements `Copy` because all fields are references (`&'a T`), making
/// it cheap to pass by value and enabling ergonomic usage in closures
/// and parallel processing contexts.
#[derive(Copy, Clone)]
pub struct ResolutionContext<'a> {
    /// The project manifest with dependencies and configuration
    pub manifest: &'a Manifest,

    /// The cache for worktrees and Git operations
    pub cache: &'a Cache,

    /// The source manager for resolving source URLs
    pub source_manager: &'a SourceManager,

    /// Optional operation context for warnings and progress tracking
    pub operation_context: Option<&'a Arc<OperationContext>>,
}

/// Context for transitive dependency resolution.
///
/// Extends the base resolution context with concurrent state needed for
/// parallel transitive dependency traversal and conflict detection.
pub struct TransitiveContext<'a> {
    /// Base immutable context
    pub base: ResolutionContext<'a>,

    /// Map tracking which dependencies are required by which resources (concurrent)
    pub dependency_map: &'a Arc<DashMap<DependencyKey, Vec<String>>>,

    /// Map tracking custom names for transitive dependencies (concurrent, for template variables)
    pub transitive_custom_names: &'a Arc<DashMap<DependencyKey, String>>,

    /// Conflict detector for version resolution
    pub conflict_detector: &'a mut ConflictDetector,

    /// Index of manifest overrides for deduplication with transitive deps
    pub manifest_overrides: &'a ManifestOverrideIndex,
}

/// Context for pattern expansion operations.
///
/// Extends the base resolution context with pattern alias tracking.
pub struct PatternContext<'a> {
    /// Base immutable context
    pub base: ResolutionContext<'a>,

    /// Map tracking pattern alias relationships (concrete_name -> pattern_name) (concurrent)
    pub pattern_alias_map: &'a Arc<DashMap<(ResourceType, String), String>>,
}

// ============================================================================
// Manifest Override Types
// ============================================================================

/// Stores override information from manifest dependencies.
///
/// When a resource appears both as a direct dependency in the manifest and as
/// a transitive dependency of another resource, this structure stores the
/// customizations from the manifest version to ensure they take precedence.
#[derive(Debug, Clone)]
pub struct ManifestOverride {
    /// Custom filename specified in manifest
    pub filename: Option<String>,

    /// Custom target path specified in manifest
    pub target: Option<String>,

    /// Install flag override
    pub install: Option<bool>,

    /// Manifest alias (for reference)
    pub manifest_alias: Option<String>,

    /// Original template variables from manifest
    pub template_vars: Option<serde_json::Value>,
}

/// Key for override index lookup.
///
/// This key uniquely identifies a resource variant for the purpose of
/// detecting when a transitive dependency should be overridden by a
/// direct manifest dependency.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct OverrideKey {
    /// The type of resource (Agent, Snippet, etc.)
    pub resource_type: ResourceType,

    /// Normalized path (without leading ./ and without extension)
    pub normalized_path: String,

    /// Source repository name (None for local dependencies)
    pub source: Option<String>,

    /// Target tool name
    pub tool: String,

    /// Variant inputs hash (computed from template_vars)
    pub variant_hash: String,
}

/// Override index mapping resource identities to their manifest customizations.
///
/// This index is built once during resolution from the manifest dependencies
/// and used to apply overrides to transitive dependencies that match.
pub type ManifestOverrideIndex = HashMap<OverrideKey, ManifestOverride>;

// ============================================================================
// Conflict Detection Types
// ============================================================================

/// Value type for resolved dependencies tracked for conflict detection.
///
/// Contains the resolution metadata needed to detect and resolve version conflicts
/// between different dependencies that resolve to the same resource.
#[derive(Debug, Clone)]
pub struct ResolvedDependencyInfo {
    /// The version constraint that was specified (e.g., "^1.0.0", "main", "abc123")
    pub version_constraint: String,

    /// The resolved commit SHA for this dependency
    pub resolved_sha: String,

    /// The version constraint of the parent dependency (if any)
    pub parent_version: Option<String>,

    /// The resolved SHA of the parent dependency (if any)
    pub parent_sha: Option<String>,

    /// The resolution mode used (Version or GitRef)
    pub resolution_mode: ResolutionMode,
}

/// Key type for resolved dependencies tracked for conflict detection.
///
/// Uniquely identifies a resolved dependency instance for conflict tracking.
pub type ConflictDetectionKey = (crate::lockfile::ResourceId, String, String);

/// Concurrent map type for tracking resolved dependencies during conflict detection.
///
/// This type is used throughout the resolver to track dependency resolution
/// metadata for detecting version conflicts between different dependency requirements.
pub type ResolvedDependenciesMap = Arc<DashMap<ConflictDetectionKey, ResolvedDependencyInfo>>;

// ============================================================================
// Manifest Override Helper Functions

/// Apply manifest overrides to a resource dependency.
///
/// This helper function centralizes the logic for applying manifest customizations
/// to transitive dependencies, ensuring consistent behavior across the codebase.
///
/// # Arguments
///
/// * `dep` - The resource dependency to modify (will be updated in-place)
/// * `override_info` - The override information from the manifest
/// * `normalized_path` - The normalized path for logging
///
/// # Effects
///
/// Modifies the dependency in-place with the following overrides:
/// - `filename` - Custom filename
/// - `target` - Custom target path
/// - `install` - Install flag override
/// - `template_vars` - Template variables (replaces transitive version)
///
/// # Logging
///
/// Logs debug information about applied overrides and warnings for non-detailed dependencies.
pub fn apply_manifest_override(
    dep: &mut ResourceDependency,
    override_info: &ManifestOverride,
    normalized_path: &str,
) {
    tracing::debug!(
        "Applying manifest override to transitive dependency: {} (normalized: {})",
        dep.get_path(),
        normalized_path
    );

    // Apply overrides to make transitive dep match manifest version
    if let ResourceDependency::Detailed(detailed) = dep {
        // Get the path before we start modifying the dependency
        let path = detailed.path.clone();

        if let Some(filename) = &override_info.filename {
            detailed.filename = Some(filename.clone());
        }

        if let Some(target) = &override_info.target {
            detailed.target = Some(target.clone());
        }

        if let Some(install) = override_info.install {
            detailed.install = Some(install);
        }

        // Replace template vars with manifest version for consistent rendering
        if let Some(template_vars) = &override_info.template_vars {
            detailed.template_vars = Some(template_vars.clone());
        }

        tracing::debug!(
            "Applied manifest overrides to '{}': filename={:?}, target={:?}, install={:?}, template_vars={}",
            path,
            detailed.filename,
            detailed.target,
            detailed.install,
            detailed.template_vars.is_some()
        );
    } else {
        tracing::warn!(
            "Cannot apply manifest override to non-detailed dependency: {}",
            dep.get_path()
        );
    }
}

// ============================================================================
// Dependency Helper Functions
// ============================================================================

/// Builds a resource identifier in the format `source:path`.
///
/// Resource identifiers are used for conflict detection and version resolution
/// to uniquely identify resources across different sources.
///
/// # Arguments
///
/// * `dep` - The resource dependency specification
///
/// # Returns
///
/// A string in the format `"source:path"`, or `"unknown:path"` for dependencies
/// without a source (e.g., local dependencies).
pub fn build_resource_id(dep: &ResourceDependency) -> String {
    let source = dep.get_source().unwrap_or("unknown");
    let path = dep.get_path();
    format!("{source}:{path}")
}

/// Normalizes a path by stripping leading `./` prefix.
///
/// This is a simple normalization that makes paths consistent for comparison
/// and lookup operations.
///
/// # Arguments
///
/// * `path` - The path string to normalize
///
/// # Returns
///
/// A normalized path string without leading `./`
///
/// # Examples
///
/// ```
/// use agpm_cli::resolver::types::normalize_lookup_path;
///
/// assert_eq!(normalize_lookup_path("./agents/helper.md"), "agents/helper");
/// assert_eq!(normalize_lookup_path("agents/helper.md"), "agents/helper");
/// assert_eq!(normalize_lookup_path("./foo"), "foo");
/// ```
pub fn normalize_lookup_path(path: &str) -> String {
    use std::path::{Component, Path};

    let path_obj = Path::new(path);

    // Build normalized path by iterating through components
    let mut components = Vec::new();
    for component in path_obj.components() {
        match component {
            Component::CurDir => continue, // Skip "."
            Component::Normal(os_str) => {
                components.push(os_str.to_string_lossy().to_string());
            }
            _ => {}
        }
    }

    // If we have components, strip extension from last one
    if let Some(last) = components.last_mut() {
        // Strip .md extension if present
        if let Some(stem) = Path::new(last.as_str()).file_stem() {
            *last = stem.to_string_lossy().to_string();
        }
    }

    if components.is_empty() {
        path.to_string()
    } else {
        components.join("/")
    }
}

/// Extracts the filename from a path.
///
/// Returns the last component of a slash-separated path.
///
/// # Arguments
///
/// * `path` - The path string (may contain forward slashes)
///
/// # Returns
///
/// The filename if the path contains at least one component, `None` otherwise.
///
/// # Examples
///
/// ```
/// use agpm_cli::resolver::types::extract_filename_from_path;
///
/// assert_eq!(extract_filename_from_path("agents/helper.md"), Some("helper.md".to_string()));
/// assert_eq!(extract_filename_from_path("foo/bar/baz.txt"), Some("baz.txt".to_string()));
/// assert_eq!(extract_filename_from_path("single.md"), Some("single.md".to_string()));
/// assert_eq!(extract_filename_from_path(""), None);
/// ```
pub fn extract_filename_from_path(path: &str) -> Option<String> {
    std::path::Path::new(path).file_name().and_then(|n| n.to_str()).map(String::from)
}

/// Strips resource type directory prefix from a path.
///
/// This mimics the logic in `generate_dependency_name` to allow dependency
/// lookups to work with dependency names from the dependency map.
///
/// For paths like `agents/helpers/foo.md`, this returns `helpers/foo.md`.
/// For paths without a recognized resource type directory, returns `None`.
///
/// # Arguments
///
/// * `path` - The path string with forward slashes
///
/// # Returns
///
/// The path with the resource type directory prefix stripped, or `None` if
/// no resource type directory is found.
///
/// # Recognized Resource Type Directories
///
/// - agents
/// - snippets
/// - commands
/// - scripts
/// - hooks
/// - mcp-servers
///
/// # Examples
///
/// ```
/// use agpm_cli::resolver::types::strip_resource_type_directory;
///
/// assert_eq!(
///     strip_resource_type_directory("agents/helpers/foo.md"),
///     Some("helpers/foo.md".to_string())
/// );
/// assert_eq!(
///     strip_resource_type_directory("snippets/rust/best-practices.md"),
///     Some("rust/best-practices.md".to_string())
/// );
/// assert_eq!(
///     strip_resource_type_directory("commands/deploy.md"),
///     Some("deploy.md".to_string())
/// );
/// assert_eq!(
///     strip_resource_type_directory("foo/bar.md"),
///     None
/// );
/// assert_eq!(
///     strip_resource_type_directory("agents"),
///     None  // No components after the resource type dir
/// );
/// ```
pub fn strip_resource_type_directory(path: &str) -> Option<String> {
    use std::path::{Component, Path};

    let resource_type_dirs = ["agents", "snippets", "commands", "scripts", "hooks", "mcp-servers"];

    // Use Path::components() to handle both forward and back slashes
    let components: Vec<_> = Path::new(path)
        .components()
        .filter_map(|c| match c {
            Component::Normal(s) => s.to_str(),
            _ => None,
        })
        .collect();

    if components.len() > 1 {
        // Find the index of the first resource type directory
        if let Some(idx) = components.iter().position(|c| resource_type_dirs.contains(c)) {
            // Skip everything up to and including the resource type directory
            if idx + 1 < components.len() {
                // Always return with forward slashes for storage format
                return Some(components[idx + 1..].join("/"));
            }
        }
    }
    None
}

/// Formats a dependency reference with version suffix.
///
/// Creates a string in the format `"resource_type/name@version"` for use in
/// lockfile dependency lists.
///
/// # Arguments
///
/// * `resource_type` - The type of resource (Agent, Snippet, etc.)
/// * `name` - The resource name
/// * `version` - The version string (can be a semver tag, commit SHA, or "HEAD")
///
/// # Returns
///
/// A formatted dependency string with version.
///
/// # Examples
///
/// ```
/// use agpm_cli::core::ResourceType;
/// use agpm_cli::resolver::types::format_dependency_with_version;
///
/// let formatted = format_dependency_with_version(
///     ResourceType::Agent,
///     "helper",
///     "v1.0.0"
/// );
/// assert_eq!(formatted, "agent:helper@v1.0.0");
///
/// let formatted = format_dependency_with_version(
///     ResourceType::Snippet,
///     "utils",
///     "abc123"
/// );
/// assert_eq!(formatted, "snippet:utils@abc123");
/// ```
pub fn format_dependency_with_version(
    resource_type: ResourceType,
    name: &str,
    version: &str,
) -> String {
    LockfileDependencyRef::local(resource_type, name.to_string(), Some(version.to_string()))
        .to_string()
}

/// Formats a dependency reference without version suffix.
///
/// Creates a string in the format `"resource_type/name"` for use in
/// dependency tracking before version resolution.
///
/// # Arguments
///
/// * `resource_type` - The type of resource (Agent, Snippet, etc.)
/// * `name` - The resource name
///
/// # Returns
///
/// A formatted dependency string without version.
///
/// # Examples
///
/// ```
/// use agpm_cli::core::ResourceType;
/// use agpm_cli::resolver::types::format_dependency_without_version;
///
/// let formatted = format_dependency_without_version(ResourceType::Agent, "helper");
/// assert_eq!(formatted, "agent:helper");
///
/// let formatted = format_dependency_without_version(ResourceType::Command, "deploy");
/// assert_eq!(formatted, "command:deploy");
/// ```
pub fn format_dependency_without_version(resource_type: ResourceType, name: &str) -> String {
    LockfileDependencyRef::local(resource_type, name.to_string(), None).to_string()
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::manifest::DetailedDependency;

    #[test]
    fn test_normalize_lookup_path() {
        // Extensions are stripped for consistent lookup
        assert_eq!(normalize_lookup_path("./agents/helper.md"), "agents/helper");
        assert_eq!(normalize_lookup_path("agents/helper.md"), "agents/helper");
        assert_eq!(normalize_lookup_path("snippets/helpers/foo.md"), "snippets/helpers/foo");
        assert_eq!(normalize_lookup_path("./foo.md"), "foo");
        assert_eq!(normalize_lookup_path("./foo"), "foo");
        assert_eq!(normalize_lookup_path("foo"), "foo");
    }

    #[test]
    fn test_extract_filename_from_path() {
        assert_eq!(extract_filename_from_path("agents/helper.md"), Some("helper.md".to_string()));
        assert_eq!(extract_filename_from_path("foo/bar/baz.txt"), Some("baz.txt".to_string()));
        assert_eq!(extract_filename_from_path("single.md"), Some("single.md".to_string()));
        assert_eq!(extract_filename_from_path(""), None);
        // Path::file_name() normalizes trailing slashes
        assert_eq!(extract_filename_from_path("trailing/"), Some("trailing".to_string()));
    }

    #[test]
    fn test_strip_resource_type_directory() {
        assert_eq!(
            strip_resource_type_directory("agents/helpers/foo.md"),
            Some("helpers/foo.md".to_string())
        );
        assert_eq!(
            strip_resource_type_directory("snippets/rust/best-practices.md"),
            Some("rust/best-practices.md".to_string())
        );
        assert_eq!(
            strip_resource_type_directory("commands/deploy.md"),
            Some("deploy.md".to_string())
        );
        assert_eq!(strip_resource_type_directory("foo/bar.md"), None);
        assert_eq!(strip_resource_type_directory("agents"), None);
        assert_eq!(
            strip_resource_type_directory("mcp-servers/filesystem.json"),
            Some("filesystem.json".to_string())
        );
    }

    #[test]
    fn test_format_dependency_with_version() {
        assert_eq!(
            format_dependency_with_version(ResourceType::Agent, "helper", "v1.0.0"),
            "agent:helper@v1.0.0"
        );
        assert_eq!(
            format_dependency_with_version(ResourceType::Snippet, "utils", "abc123"),
            "snippet:utils@abc123"
        );
    }

    #[test]
    fn test_format_dependency_without_version() {
        assert_eq!(
            format_dependency_without_version(ResourceType::Agent, "helper"),
            "agent:helper"
        );
        assert_eq!(
            format_dependency_without_version(ResourceType::Command, "deploy"),
            "command:deploy"
        );
    }

    #[test]
    fn test_build_resource_id() {
        let dep = ResourceDependency::Detailed(Box::new(DetailedDependency {
            source: Some("test-source".to_string()),
            path: "agents/helper.md".to_string(),
            version: Some("v1.0.0".to_string()),
            branch: None,
            rev: None,
            command: None,
            args: None,
            target: None,
            filename: None,
            dependencies: None,
            tool: None,
            flatten: None,
            install: None,
            template_vars: Some(serde_json::Value::Object(serde_json::Map::new())),
        }));
        let resource_id = build_resource_id(&dep);
        assert!(resource_id.contains("agents/helper.md"));
    }
}