agpm-cli 0.4.4

//! Check for available updates to installed dependencies.
//!
//! The `outdated` command analyzes the current project's lockfile against available
//! versions in Git repositories to identify dependencies that have newer versions
//! available. It provides both compatible updates (within version constraints) and
//! major updates (beyond current constraints).
//!
//! # Overview
//!
//! This module implements AGPM's update checking functionality, which:
//! - Compares installed versions against repository tags
//! - Respects semantic version constraints from the manifest
//! - Distinguishes between compatible and major updates
//! - Supports both table and JSON output formats
//! - Provides exit codes for CI/CD integration
//! - Handles Git repository caching and fetching
//!
//! # Command Usage
//!
//! ## Basic Usage
//!
//! ```bash
//! # Check all dependencies for updates
//! agpm outdated
//!
//! # Check specific dependencies
//! agpm outdated my-agent other-agent
//!
//! # Use cached data without fetching
//! agpm outdated --no-fetch
//!
//! # Exit with error code if updates available
//! agpm outdated --check
//!
//! # JSON output for scripting
//! agpm outdated --format json
//!
//! # Control parallelism
//! agpm outdated --max-parallel 5
//! ```
//!
//! ## Output Formats
//!
//! ### Table Format (Default)
//!
//! ```text
//! Package                        Current      Latest       Available    Tool
//! ─────────────────────────────────────────────────────────────────────────────
//! my-agent                       v1.0.0       v1.2.0       v2.0.0       claude-code
//! helper-agent                   v2.1.0       v2.1.0       v3.0.0       claude-code
//!
//! Summary:
//!   Total dependencies: 5
//!   2 dependencies have compatible updates
//!   2 dependencies have major updates available
//!   3 dependencies are up to date
//! ```
//!
//! ### JSON Format
//!
//! ```json
//! {
//!   "outdated": [
//!     {
//!       "name": "my-agent",
//!       "type": "agent",
//!       "source": "official",
//!       "tool": "claude-code",
//!       "current": "v1.0.0",
//!       "latest": "v1.2.0",
//!       "latest_available": "v2.0.0",
//!       "constraint": "^1.0.0",
//!       "has_update": true,
//!       "has_major_update": true
//!     }
//!   ],
//!   "summary": {
//!     "total": 5,
//!     "outdated": 2,
//!     "with_updates": 2,
//!     "with_major_updates": 2,
//!     "up_to_date": 3
//!   }
//! }
//! ```
//!
//! # Version Comparison Logic
//!
//! The outdated command performs sophisticated version analysis:
//!
//! 1. **Current Version**: The version installed and locked in `agpm.lock`
//! 2. **Latest Compatible**: The newest version that satisfies the manifest's version constraint
//! 3. **Latest Available**: The absolute newest version in the repository
//!
//! ## Update Types
//!
//! - **Compatible Update**: A newer version that satisfies the current constraint
//!   - `^1.0.0` constraint with `v1.2.0` available
//!   - Indicated by `has_update: true`
//!
//! - **Major Update**: A newer version that requires constraint changes
//!   - `^1.0.0` constraint with `v2.0.0` available
//!   - Indicated by `has_major_update: true`
//!
//! # Requirements
//!
//! - Requires an existing `agpm.lock` file (run `agpm install` first)
//! - Accesses Git repositories to fetch latest version information
//! - Supports both local cache and remote fetching modes
//!
//! # Integration with Other Commands
//!
//! The outdated command complements other AGPM commands:
//!
//! - [`crate::cli::install`] - Creates the required lockfile
//! - [`crate::cli::update`] - Updates dependencies to newer versions
//! - [`crate::cli::validate`] - Validates manifest and lockfile consistency
//!
//! # Error Handling
//!
//! Common error scenarios and their handling:
//!
//! - **Missing lockfile**: Returns error suggesting `agpm install`
//! - **Repository not cached**: Skips dependency or fails if `--no-fetch` used
//! - **Invalid version constraints**: Reports parsing errors with context
//! - **Network issues**: Graceful degradation with appropriate error messages
//!
//! # Examples
//!
//! ```rust,ignore
//! use agpm_cli::cli::outdated::OutdatedCommand;
//! use std::path::PathBuf;
//!
//! # async fn example() -> anyhow::Result<()> {
//! // Check all dependencies with default settings
//! let cmd = OutdatedCommand {
//!     dependencies: vec![],
//!     format: "table".to_string(),
//!     check: false,
//!     no_fetch: false,
//!     max_parallel: None,
//!     no_progress: false,
//! };
//!
//! cmd.execute_with_manifest_path(None).await?;
//! # Ok(())
//! # }
//! ```

use anyhow::{Context, Result};
use clap::Args;
use colored::Colorize;
use serde::{Deserialize, Serialize};
use std::path::PathBuf;
use tracing::{debug, info};

use crate::cache::Cache;
use crate::git::parse_git_url;
use crate::lockfile::{LockFile, LockedResource};
use crate::manifest::{Manifest, find_manifest_with_optional};
use crate::resolver::DependencyResolver;
use crate::utils::progress::{InstallationPhase, MultiPhaseProgress};
use crate::version::constraints::VersionConstraint;

/// Command to check for available updates to installed dependencies.
///
/// The `OutdatedCommand` analyzes the current project's lockfile against available
/// versions in Git repositories to identify dependencies that have newer versions.
/// It distinguishes between compatible updates (within version constraints) and
/// major updates (beyond current constraints).
///
/// # Fields
///
/// * `dependencies` - Specific dependencies to check. If empty, checks all dependencies
/// * `format` - Output format: "table" for human-readable or "json" for machine parsing
/// * `check` - Exit with code 1 if any updates are available (useful for CI/CD)
/// * `no_fetch` - Use cached repository data without fetching latest from remote
/// * `max_parallel` - Limit concurrent Git operations (default: 2 × CPU cores)
/// * `no_progress` - Disable progress indicators (set automatically by global flag)
///
/// # Examples
///
/// ## Check All Dependencies
///
/// ```rust,ignore
/// use agpm_cli::cli::outdated::OutdatedCommand;
///
/// # async fn example() -> anyhow::Result<()> {
/// let cmd = OutdatedCommand {
///     dependencies: vec![], // Check all
///     format: "table".to_string(),
///     check: false,
///     no_fetch: false,
///     max_parallel: None,
///     no_progress: false,
/// };
///
/// cmd.execute_with_manifest_path(None).await?;
/// # Ok(())
/// # }
/// ```
///
/// ## Check Specific Dependencies with JSON Output
///
/// ```rust,ignore
/// use agpm_cli::cli::outdated::OutdatedCommand;
///
/// # async fn example() -> anyhow::Result<()> {
/// let cmd = OutdatedCommand {
///     dependencies: vec!["my-agent".to_string(), "helper".to_string()],
///     format: "json".to_string(),
///     check: true, // Exit with error if updates found
///     no_fetch: false,
///     max_parallel: Some(5),
///     no_progress: true,
/// };
///
/// cmd.execute_with_manifest_path(None).await?;
/// # Ok(())
/// # }
/// ```
///
/// ## CI/CD Integration Example
///
/// ```rust,ignore
/// use agpm_cli::cli::outdated::OutdatedCommand;
///
/// # async fn ci_check() -> anyhow::Result<()> {
/// // This will exit with code 1 if any updates are available
/// let cmd = OutdatedCommand {
///     dependencies: vec![],
///     format: "json".to_string(), // Machine-readable output
///     check: true, // Fail build if updates exist
///     no_fetch: false, // Always check latest
///     max_parallel: Some(10), // Parallel for speed
///     no_progress: true, // No TTY in CI
/// };
///
/// cmd.execute_with_manifest_path(None).await?;
/// # Ok(())
/// # }
/// ```
#[derive(Debug, Args)]
#[command(about = "Check for available updates to installed dependencies", author, version)]
pub struct OutdatedCommand {
    /// Specific dependencies to check (checks all if omitted)
    #[arg(value_name = "DEPENDENCY")]
    pub dependencies: Vec<String>,

    /// Output format (table or json)
    #[arg(long, default_value = "table", value_parser = ["table", "json"])]
    pub format: String,

    /// Exit with non-zero code if updates are available
    #[arg(long)]
    pub check: bool,

    /// Skip fetching latest from remote (use cached data)
    #[arg(long)]
    pub no_fetch: bool,

    /// Maximum parallel operations
    #[arg(long, value_name = "NUMBER")]
    pub max_parallel: Option<usize>,

    /// Don't show progress bars (automatically set by global option)
    #[arg(skip)]
    pub no_progress: bool,
}

/// Information about a dependency's update status.
///
/// This structure represents the complete update analysis for a single dependency,
/// comparing the currently installed version against available versions in the
/// Git repository while respecting semantic version constraints.
///
/// # Fields
///
/// * `name` - The dependency name as specified in the manifest
/// * `resource_type` - Type of resource: "agent", "snippet", "command", "script", "hook", or "mcp-server"
/// * `source` - Source repository name from the manifest's `[sources]` section
/// * `tool` - The target tool: "claude-code", "opencode", "agpm", or custom
/// * `current` - Currently installed version from the lockfile
/// * `latest` - Latest version that satisfies the manifest's version constraint
/// * `latest_available` - Absolute latest version available in the repository
/// * `constraint` - Version constraint from the manifest (e.g., "^1.0.0", "latest")
/// * `has_update` - True if a compatible update is available within the constraint
/// * `has_major_update` - True if a major update is available beyond the constraint
///
/// # JSON Schema
///
/// When serialized to JSON, the structure follows this schema:
///
/// ```json
/// {
///   "name": "string",
///   "type": "agent|snippet|command|script|hook|mcp-server",
///   "source": "string",
///   "tool": "claude-code|opencode|agpm|custom",
///   "current": "string (semver)",
///   "latest": "string (semver)",
///   "latest_available": "string (semver)",
///   "constraint": "string (version constraint)",
///   "has_update": "boolean",
///   "has_major_update": "boolean"
/// }
/// ```
///
/// # Examples
///
/// ## Compatible Update Available
///
/// ```json
/// {
///   "name": "code-reviewer",
///   "type": "agent",
///   "source": "official",
///   "tool": "claude-code",
///   "current": "v1.0.0",
///   "latest": "v1.2.0",
///   "latest_available": "v1.2.0",
///   "constraint": "^1.0.0",
///   "has_update": true,
///   "has_major_update": false
/// }
/// ```
///
/// ## Major Update Available
///
/// ```json
/// {
///   "name": "helper-agent",
///   "type": "agent",
///   "source": "community",
///   "tool": "claude-code",
///   "current": "v1.5.0",
///   "latest": "v1.5.0",
///   "latest_available": "v2.1.0",
///   "constraint": "^1.0.0",
///   "has_update": false,
///   "has_major_update": true
/// }
/// ```
///
/// ## Up to Date
///
/// ```json
/// {
///   "name": "build-script",
///   "type": "script",
///   "source": "tools",
///   "tool": "claude-code",
///   "current": "v2.1.0",
///   "latest": "v2.1.0",
///   "latest_available": "v2.1.0",
///   "constraint": "^2.0.0",
///   "has_update": false,
///   "has_major_update": false
/// }
/// ```
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct OutdatedInfo {
    pub name: String,
    #[serde(rename = "type")]
    pub resource_type: String,
    pub source: String,
    pub tool: String,
    pub current: String,
    pub latest: String,           // Latest within constraint
    pub latest_available: String, // Absolute latest
    pub constraint: String,
    pub has_update: bool,       // Has update within constraint
    pub has_major_update: bool, // Has update beyond constraint
}

/// Summary statistics for the outdated analysis.
///
/// Provides aggregate information about the update status across all
/// dependencies in the project, useful for understanding the overall
/// maintenance status and planning update strategies.
///
/// # Fields
///
/// * `total` - Total number of dependencies analyzed
/// * `outdated` - Number of dependencies that were included in the analysis
/// * `with_updates` - Number of dependencies with compatible updates available
/// * `with_major_updates` - Number of dependencies with major updates available
/// * `up_to_date` - Number of dependencies that are current (total - outdated)
///
/// # Calculations
///
/// - `up_to_date = total - outdated`
/// - A dependency can have both `has_update` and `has_major_update` true
/// - `outdated` only includes dependencies that were actually analyzed (excludes local deps)
///
/// # JSON Schema
///
/// ```json
/// {
///   "total": "number (integer)",
///   "outdated": "number (integer)",
///   "with_updates": "number (integer)",
///   "with_major_updates": "number (integer)",
///   "up_to_date": "number (integer)"
/// }
/// ```
///
/// # Example
///
/// ```json
/// {
///   "total": 10,
///   "outdated": 3,
///   "with_updates": 2,
///   "with_major_updates": 1,
///   "up_to_date": 7
/// }
/// ```
///
/// This example shows:
/// - 10 total dependencies in the lockfile
/// - 3 dependencies were analyzed for updates (7 were skipped, likely local)
/// - 2 dependencies have compatible updates within their constraints
/// - 1 dependency has a major update available beyond its constraint
/// - 7 dependencies are up to date or were skipped
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct OutdatedSummary {
    pub total: usize,
    pub outdated: usize,
    pub with_updates: usize,
    pub with_major_updates: usize,
    pub up_to_date: usize,
}

/// Complete result of the outdated analysis.
///
/// This is the top-level structure returned by the outdated command when
/// using JSON output format. It combines the detailed per-dependency
/// information with aggregate summary statistics.
///
/// # Fields
///
/// * `outdated` - Detailed information for each dependency analyzed
/// * `summary` - Aggregate statistics across all dependencies
///
/// # JSON Schema
///
/// ```json
/// {
///   "outdated": [
///     {
///       "name": "string",
///       "type": "string",
///       "source": "string",
///       "tool": "string",
///       "current": "string",
///       "latest": "string",
///       "latest_available": "string",
///       "constraint": "string",
///       "has_update": "boolean",
///       "has_major_update": "boolean"
///     }
///   ],
///   "summary": {
///     "total": "number",
///     "outdated": "number",
///     "with_updates": "number",
///     "with_major_updates": "number",
///     "up_to_date": "number"
///   }
/// }
/// ```
///
/// # Usage
///
/// This structure is primarily used for JSON serialization when the
/// `--format json` flag is specified. It allows external tools and
/// scripts to programmatically analyze dependency update status.
///
/// ```rust,ignore
/// use agpm_cli::cli::outdated::{OutdatedResult, OutdatedInfo, OutdatedSummary};
/// use serde_json;
///
/// # fn example() -> anyhow::Result<()> {
/// let result = OutdatedResult {
///     outdated: vec![
///         // ... OutdatedInfo instances
///     ],
///     summary: OutdatedSummary {
///         total: 5,
///         outdated: 2,
///         with_updates: 1,
///         with_major_updates: 1,
///         up_to_date: 3,
///     },
/// };
///
/// let json = serde_json::to_string_pretty(&result)?;
/// println!("{}", json);
/// # Ok(())
/// # }
/// ```
#[derive(Debug, Serialize, Deserialize)]
pub struct OutdatedResult {
    pub outdated: Vec<OutdatedInfo>,
    pub summary: OutdatedSummary,
}

impl Default for OutdatedCommand {
    fn default() -> Self {
        Self {
            dependencies: vec![],
            format: "table".to_string(),
            check: false,
            no_fetch: false,
            max_parallel: None,
            no_progress: false,
        }
    }
}

impl OutdatedCommand {
    /// Execute the outdated command with an optional manifest path.
    ///
    /// This is the main entry point for the outdated command. It locates the
    /// manifest file (either from the provided path or by searching the current
    /// directory hierarchy) and delegates to [`Self::execute_from_path`].
    ///
    /// # Arguments
    ///
    /// * `manifest_path` - Optional path to the `agpm.toml` file. If `None`,
    ///   searches the current directory and parent directories for the manifest.
    ///
    /// # Returns
    ///
    /// Returns `Ok(())` if the analysis completes successfully, or an error if:
    /// - The manifest file cannot be found or parsed
    /// - The lockfile is missing or invalid
    /// - Git repositories cannot be accessed
    /// - Version parsing fails
    ///
    /// # Exit Codes
    ///
    /// When `self.check` is true, the process will exit with code 1 if any
    /// updates are available (either compatible or major updates).
    ///
    /// # Examples
    ///
    /// ```rust,ignore
    /// use agpm_cli::cli::outdated::OutdatedCommand;
    /// use std::path::PathBuf;
    ///
    /// # async fn example() -> anyhow::Result<()> {
    /// // Use default manifest discovery
    /// let cmd = OutdatedCommand::default();
    /// cmd.execute_with_manifest_path(None).await?;
    ///
    /// // Use specific manifest path
    /// let manifest_path = Some(PathBuf::from("/path/to/agpm.toml"));
    /// cmd.execute_with_manifest_path(manifest_path).await?;
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`anyhow::Error`] for various failure conditions:
    /// - `"No manifest found"` - No `agpm.toml` in current or parent directories
    /// - `"Failed to load manifest"` - Manifest exists but has syntax errors
    /// - `"No lockfile found"` - Missing `agpm.lock` file (run `agpm install` first)
    pub async fn execute_with_manifest_path(self, manifest_path: Option<PathBuf>) -> Result<()> {
        let manifest_path = find_manifest_with_optional(manifest_path)?;
        self.execute_from_path(manifest_path).await
    }

    /// Execute the outdated command with a specific manifest path.
    ///
    /// Performs the complete outdated analysis workflow:
    /// 1. Loads the manifest and validates the lockfile exists
    /// 2. Initializes the cache and dependency resolver
    /// 3. Optionally syncs Git repositories to fetch latest versions
    /// 4. Analyzes each dependency for available updates
    /// 5. Generates summary statistics and displays results
    /// 6. Exits with appropriate code if `--check` is enabled
    ///
    /// # Arguments
    ///
    /// * `manifest_path` - Absolute path to the `agpm.toml` manifest file
    ///
    /// # Returns
    ///
    /// Returns `Ok(())` on successful completion. If `self.check` is true and
    /// updates are available, the process will exit with code 1 instead of
    /// returning normally.
    ///
    /// # Errors
    ///
    /// Returns errors for:
    /// - Invalid or missing manifest/lockfile
    /// - Cache initialization failures
    /// - Git repository access issues
    /// - Version parsing or constraint resolution errors
    ///
    /// # Progress Reporting
    ///
    /// Shows progress through multiple phases when `!self.no_progress`:
    /// 1. "Syncing sources" - Fetching latest repository data
    /// 2. "Checking versions" - Analyzing each dependency
    ///
    /// # Examples
    ///
    /// ```rust,ignore
    /// use agpm_cli::cli::outdated::OutdatedCommand;
    /// use std::path::PathBuf;
    ///
    /// # async fn example() -> anyhow::Result<()> {
    /// let cmd = OutdatedCommand {
    ///     dependencies: vec![],
    ///     format: "table".to_string(),
    ///     check: false,
    ///     no_fetch: false,
    ///     max_parallel: None,
    ///     no_progress: false,
    /// };
    ///
    /// let manifest_path = PathBuf::from("./agpm.toml");
    /// cmd.execute_from_path(manifest_path).await?;
    /// # Ok(())
    /// # }
    /// ```
    pub async fn execute_from_path(self, manifest_path: PathBuf) -> Result<()> {
        info!("Checking for outdated dependencies");

        // 1. Load manifest and lockfile
        let manifest = Manifest::load(&manifest_path)
            .with_context(|| format!("Failed to load manifest from {manifest_path:?}"))?;

        let lockfile_path = manifest_path.with_file_name("agpm.lock");

        // Check if lockfile exists first - the outdated command requires it
        if !lockfile_path.exists() {
            return Err(anyhow::anyhow!(
                "No lockfile found at {lockfile_path:?}. Run 'agpm install' first to create a lockfile."
            ));
        }

        let lockfile = LockFile::load(&lockfile_path)
            .with_context(|| format!("Failed to load lockfile from {lockfile_path:?}"))?;

        // 2. Initialize cache and resolver
        let cache = Cache::new().context("Failed to initialize cache")?;

        // 3. Create resolver for version resolution
        let mut resolver = DependencyResolver::new(manifest.clone(), cache.clone())
            .context("Failed to create dependency resolver")?;

        // 4. Pre-sync sources if not skipped
        let progress = if self.no_progress {
            None
        } else {
            Some(MultiPhaseProgress::new(!self.no_progress))
        };

        if !self.no_fetch {
            if let Some(ref progress) = progress {
                progress.start_phase(InstallationPhase::SyncingSources, Some("Syncing sources"));
            }

            // Convert dependencies to the format expected by pre_sync_sources
            let deps: Vec<(String, crate::manifest::ResourceDependency)> = manifest
                .all_dependencies()
                .into_iter()
                .map(|(name, dep)| (name.to_string(), dep.clone()))
                .collect();

            resolver.pre_sync_sources(&deps).await.context("Failed to sync sources")?;

            // Progress is automatically handled by MultiPhaseProgress
        }

        // 5. Check each dependency for updates
        if let Some(ref progress) = progress {
            progress
                .start_phase(InstallationPhase::ResolvingDependencies, Some("Checking versions"));
        }

        let mut outdated_deps = Vec::new();

        for locked in lockfile.all_resources() {
            let name = &locked.name;
            // Filter by specific dependencies if requested
            if !self.dependencies.is_empty() && !self.dependencies.contains(name) {
                continue;
            }

            debug!("Checking dependency: {}", name);

            if let Some(outdated_info) =
                self.check_dependency(name, locked, &manifest, &cache, &resolver).await?
            {
                outdated_deps.push(outdated_info);
            }
        }

        // Progress is automatically handled by MultiPhaseProgress

        // 6. Calculate summary
        let summary = self.calculate_summary(&outdated_deps, lockfile.all_resources().len());

        // 7. Display results
        self.display_results(&outdated_deps, &summary)?;

        // 8. Exit with appropriate code
        if self.check && outdated_deps.iter().any(|d| d.has_update || d.has_major_update) {
            std::process::exit(1);
        }

        Ok(())
    }

    /// Analyze a single dependency for available updates.
    ///
    /// Performs the core update analysis for one dependency by:
    /// 1. Finding the dependency specification in the manifest
    /// 2. Retrieving available versions from the Git repository
    /// 3. Filtering versions based on semantic version constraints
    /// 4. Comparing current, latest compatible, and latest available versions
    /// 5. Determining update availability within and beyond constraints
    ///
    /// # Arguments
    ///
    /// * `name` - The dependency name from the lockfile
    /// * `locked` - The locked resource information from `agpm.lock`
    /// * `manifest` - The project manifest containing dependency specifications
    /// * `cache` - Cache instance for accessing Git repositories
    /// * `resolver` - Dependency resolver for version operations
    ///
    /// # Returns
    ///
    /// Returns `Ok(Some(OutdatedInfo))` if the dependency was analyzed successfully,
    /// `Ok(None)` if the dependency should be skipped (local dependency, not found
    /// in manifest, or repository not cached), or an error if analysis fails.
    ///
    /// # Skipped Dependencies
    ///
    /// Dependencies are skipped when:
    /// - Not found in the manifest (orphaned lockfile entry)
    /// - Local path dependency (no version to check)
    /// - Repository not present in cache and `--no-fetch` is enabled
    ///
    /// # Version Analysis
    ///
    /// The method performs semantic version analysis:
    /// 1. Parses all repository tags as semantic versions
    /// 2. Filters versions that satisfy the manifest constraint
    /// 3. Identifies the latest compatible version within the constraint
    /// 4. Identifies the absolute latest version available
    /// 5. Compares against the currently installed version
    ///
    /// # Examples
    ///
    /// ```rust,ignore
    /// # use agpm_cli::cli::outdated::OutdatedCommand;
    /// # use agpm_cli::lockfile::LockedResource;
    /// # use agpm_cli::manifest::Manifest;
    /// # use agpm_cli::cache::Cache;
    /// # use agpm_cli::resolver::DependencyResolver;
    /// # async fn example(
    /// #     cmd: &OutdatedCommand,
    /// #     locked: &LockedResource,
    /// #     manifest: &Manifest,
    /// #     cache: &Cache,
    /// #     resolver: &DependencyResolver,
    /// # ) -> anyhow::Result<()> {
    /// if let Some(info) = cmd.check_dependency(
    ///     "my-agent",
    ///     locked,
    ///     manifest,
    ///     cache,
    ///     resolver,
    /// ).await? {
    ///     println!("Found update for {}: {} -> {}",
    ///         info.name, info.current, info.latest);
    /// }
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns errors for:
    /// - Invalid version constraint parsing
    /// - Git repository access failures
    /// - Version parsing errors
    /// - Missing source repository in manifest
    async fn check_dependency(
        &self,
        name: &str,
        locked: &LockedResource,
        manifest: &Manifest,
        cache: &Cache,
        resolver: &DependencyResolver,
    ) -> Result<Option<OutdatedInfo>> {
        // Find the dependency in the manifest
        let dep = manifest.find_dependency(name);
        if dep.is_none() {
            debug!("Dependency {} not found in manifest", name);
            return Ok(None);
        }
        let dep = dep.unwrap();

        // Skip local dependencies
        if dep.is_local() {
            debug!("Skipping local dependency: {}", name);
            return Ok(None);
        }

        // Get the source
        let source_name =
            dep.get_source().ok_or_else(|| anyhow::anyhow!("Dependency {name} has no source"))?;

        // Get the version constraint
        let constraint_str = dep
            .get_version()
            .map_or_else(|| "latest".to_string(), std::string::ToString::to_string);
        let constraint = VersionConstraint::parse(&constraint_str)?;

        // Get available versions from the repository
        // Construct the bare repo path based on source URL
        let source_url = manifest
            .sources
            .get(source_name)
            .ok_or_else(|| anyhow::anyhow!("Source {source_name} not found in manifest"))?;

        // Parse the Git URL to get owner and repo name
        let (owner, repo) = parse_git_url(source_url)
            .unwrap_or_else(|_| ("unknown".to_string(), source_name.to_string()));

        // Construct the bare repo path: cache_dir/sources/owner_repo.git
        // Bare repositories have .git suffix in the cache
        let bare_repo_path =
            cache.get_cache_location().join("sources").join(format!("{owner}_{repo}.git"));

        if !bare_repo_path.exists() {
            debug!("Repository not found in cache at {:?}, skipping", bare_repo_path);
            return Ok(None);
        }

        let available_versions = resolver.get_available_versions(&bare_repo_path).await?;

        // Filter to semantic versions
        let mut semver_versions: Vec<semver::Version> = available_versions
            .iter()
            .filter_map(|v| {
                // Try to parse as semver (with or without 'v' prefix)
                let version_str = v.trim_start_matches('v');
                semver::Version::parse(version_str).ok()
            })
            .collect();

        // Sort versions (latest first)
        semver_versions.sort_by(|a, b| b.cmp(a));

        if semver_versions.is_empty() {
            debug!("No semantic versions found for {}", name);
            return Ok(None);
        }

        // Get current version
        let version_str = locked
            .version
            .as_ref()
            .ok_or_else(|| anyhow::anyhow!("Dependency {name} has no version in lockfile"))?;
        let current_str = version_str.trim_start_matches('v');
        let current_version = semver::Version::parse(current_str)
            .with_context(|| format!("Failed to parse current version {version_str} for {name}"))?;

        // Find latest within constraint
        let latest_compatible = semver_versions
            .iter()
            .find(|v| constraint.matches(v))
            .cloned()
            .unwrap_or_else(|| current_version.clone());

        // Find absolute latest
        let latest_available = semver_versions[0].clone();

        // Determine if updates are available
        let has_update = latest_compatible > current_version;
        let has_major_update = latest_available > latest_compatible;

        // Format versions with 'v' prefix if original had it
        let format_version = |v: &semver::Version| {
            if locked.version.as_ref().is_some_and(|s| s.starts_with('v')) {
                format!("v{v}")
            } else {
                v.to_string()
            }
        };

        // Determine resource type from manifest
        let resource_type = if manifest.agents.contains_key(name) {
            "agent"
        } else if manifest.snippets.contains_key(name) {
            "snippet"
        } else if manifest.commands.contains_key(name) {
            "command"
        } else if manifest.scripts.contains_key(name) {
            "script"
        } else if manifest.hooks.contains_key(name) {
            "hook"
        } else if manifest.mcp_servers.contains_key(name) {
            "mcp-server"
        } else {
            "unknown"
        };

        Ok(Some(OutdatedInfo {
            name: name.to_string(),
            resource_type: resource_type.to_string(),
            source: source_name.to_string(),
            tool: locked.tool.clone(),
            current: locked.version.clone().unwrap_or_else(|| "unknown".to_string()),
            latest: format_version(&latest_compatible),
            latest_available: format_version(&latest_available),
            constraint: constraint_str,
            has_update,
            has_major_update,
        }))
    }

    /// Calculate aggregate summary statistics from outdated analysis results.
    ///
    /// Processes the list of analyzed dependencies to generate summary statistics
    /// about update availability across the entire project. This provides a
    /// high-level view of the project's maintenance status.
    ///
    /// # Arguments
    ///
    /// * `outdated` - List of dependencies that were analyzed for updates
    /// * `total` - Total number of dependencies in the lockfile
    ///
    /// # Returns
    ///
    /// Returns an [`OutdatedSummary`] containing:
    /// - Total dependencies in the lockfile
    /// - Number of dependencies analyzed (excluding local/skipped)
    /// - Number with compatible updates available
    /// - Number with major updates available
    /// - Number that are up to date
    ///
    /// # Calculation Logic
    ///
    /// - `outdated = outdated.len()` (dependencies that were analyzed)
    /// - `with_updates = count(has_update == true)`
    /// - `with_major_updates = count(has_major_update == true)`
    /// - `up_to_date = total - outdated` (includes skipped dependencies)
    ///
    /// Note that a dependency can have both `has_update` and `has_major_update`
    /// set to true when both compatible and major updates are available.
    ///
    /// # Examples
    ///
    /// ```rust,ignore
    /// # use agpm_cli::cli::outdated::{OutdatedCommand, OutdatedInfo};
    /// # fn example() {
    /// let cmd = OutdatedCommand::default();
    /// let outdated_deps = vec![
    ///     // Dependencies with various update statuses...
    /// ];
    ///
    /// let summary = cmd.calculate_summary(&outdated_deps, 10);
    /// println!("Total: {}, Outdated: {}, Updates: {}",
    ///     summary.total, summary.outdated, summary.with_updates);
    /// # }
    /// ```
    fn calculate_summary(&self, outdated: &[OutdatedInfo], total: usize) -> OutdatedSummary {
        let with_updates = outdated.iter().filter(|d| d.has_update).count();
        let with_major_updates = outdated.iter().filter(|d| d.has_major_update).count();
        let outdated_count = outdated.len();
        let up_to_date = total - outdated_count;

        OutdatedSummary {
            total,
            outdated: outdated_count,
            with_updates,
            with_major_updates,
            up_to_date,
        }
    }

    /// Display the outdated analysis results in the requested format.
    ///
    /// Routes the output to either table or JSON format based on the
    /// `self.format` setting. This is the final step in the outdated
    /// command workflow.
    ///
    /// # Arguments
    ///
    /// * `outdated` - List of dependencies with update information
    /// * `summary` - Aggregate statistics across all dependencies
    ///
    /// # Returns
    ///
    /// Returns `Ok(())` on successful output, or an error if JSON
    /// serialization fails.
    ///
    /// # Output Formats
    ///
    /// - `"table"` - Human-readable table with colored output
    /// - `"json"` - Machine-readable JSON for scripting
    ///
    /// # Examples
    ///
    /// ```rust,ignore
    /// # use agpm_cli::cli::outdated::{OutdatedCommand, OutdatedInfo, OutdatedSummary};
    /// # fn example() -> anyhow::Result<()> {
    /// let cmd = OutdatedCommand {
    ///     format: "json".to_string(),
    ///     // ... other fields
    ///     # dependencies: vec![],
    ///     # check: false,
    ///     # no_fetch: false,
    ///     # max_parallel: None,
    ///     # no_progress: false,
    /// };
    ///
    /// let outdated = vec![];
    /// let summary = OutdatedSummary {
    ///     total: 5,
    ///     outdated: 0,
    ///     with_updates: 0,
    ///     with_major_updates: 0,
    ///     up_to_date: 5,
    /// };
    ///
    /// cmd.display_results(&outdated, &summary)?;
    /// # Ok(())
    /// # }
    /// ```
    fn display_results(&self, outdated: &[OutdatedInfo], summary: &OutdatedSummary) -> Result<()> {
        match self.format.as_str() {
            "json" => self.display_json(outdated, summary),
            _ => self.display_table(outdated, summary),
        }
    }

    /// Display results in JSON format for machine consumption.
    ///
    /// Serializes the complete analysis results as pretty-printed JSON
    /// to stdout. This format is ideal for CI/CD pipelines, scripts,
    /// and other automated tooling that needs to process update information.
    ///
    /// # Arguments
    ///
    /// * `outdated` - List of dependencies with detailed update information
    /// * `summary` - Aggregate summary statistics
    ///
    /// # Returns
    ///
    /// Returns `Ok(())` on successful serialization and output, or an
    /// error if JSON serialization fails.
    ///
    /// # Output Format
    ///
    /// The JSON output follows the [`OutdatedResult`] schema with
    /// pretty-printing for readability:
    ///
    /// ```json
    /// {
    ///   "outdated": [
    ///     {
    ///       "name": "my-agent",
    ///       "type": "agent",
    ///       "source": "official",
    ///       "tool": "claude-code",
    ///       "current": "v1.0.0",
    ///       "latest": "v1.2.0",
    ///       "latest_available": "v2.0.0",
    ///       "constraint": "^1.0.0",
    ///       "has_update": true,
    ///       "has_major_update": true
    ///     }
    ///   ],
    ///   "summary": {
    ///     "total": 5,
    ///     "outdated": 1,
    ///     "with_updates": 1,
    ///     "with_major_updates": 1,
    ///     "up_to_date": 4
    ///   }
    /// }
    /// ```
    ///
    /// # Examples
    ///
    /// ```rust,ignore
    /// # use agpm_cli::cli::outdated::{OutdatedCommand, OutdatedInfo, OutdatedSummary};
    /// # fn example() -> anyhow::Result<()> {
    /// let cmd = OutdatedCommand::default();
    /// let outdated = vec![];
    /// let summary = OutdatedSummary {
    ///     total: 5,
    ///     outdated: 0,
    ///     with_updates: 0,
    ///     with_major_updates: 0,
    ///     up_to_date: 5,
    /// };
    ///
    /// cmd.display_json(&outdated, &summary)?;
    /// # Ok(())
    /// # }
    /// ```
    fn display_json(&self, outdated: &[OutdatedInfo], summary: &OutdatedSummary) -> Result<()> {
        let result = OutdatedResult {
            outdated: outdated.to_vec(),
            summary: summary.clone(),
        };

        println!("{}", serde_json::to_string_pretty(&result)?);
        Ok(())
    }

    /// Display results in human-readable table format.
    ///
    /// Renders the analysis results as a formatted table with colored output
    /// to highlight different types of updates. This format is optimized for
    /// human consumption and provides a quick visual overview of update status.
    ///
    /// # Arguments
    ///
    /// * `outdated` - List of dependencies that were analyzed for updates
    /// * `summary` - Aggregate statistics for the summary section
    ///
    /// # Returns
    ///
    /// Returns `Ok(())` on successful display.
    ///
    /// # Color Coding
    ///
    /// The table uses colors to indicate update status:
    /// - **Yellow** package names: Updates available
    /// - **Green** latest versions: Compatible updates within constraints
    /// - **Cyan** available versions: Major updates beyond constraints
    /// - **Normal** text: No updates or up-to-date
    ///
    /// # Output Format
    ///
    /// ## With Updates Available
    ///
    /// ```text
    /// Package                        Current      Latest       Available    Tool
    /// ─────────────────────────────────────────────────────────────────────────────
    /// my-agent                       v1.0.0       v1.2.0       v2.0.0       claude-code
    /// helper-script                  v2.1.0       v2.1.0       v3.0.0       claude-code
    ///
    /// Summary:
    ///   Total dependencies: 5
    ///   2 dependencies have compatible updates
    ///   2 dependencies have major updates available
    ///   3 dependencies are up to date
    /// ```
    ///
    /// ## All Up to Date
    ///
    /// ```text
    /// All dependencies are up to date!
    /// ```
    ///
    /// # Examples
    ///
    /// ```rust,ignore
    /// # use agpm_cli::cli::outdated::{OutdatedCommand, OutdatedInfo, OutdatedSummary};
    /// # fn example() -> anyhow::Result<()> {
    /// let cmd = OutdatedCommand::default();
    /// let outdated = vec![];
    /// let summary = OutdatedSummary {
    ///     total: 5,
    ///     outdated: 0,
    ///     with_updates: 0,
    ///     with_major_updates: 0,
    ///     up_to_date: 5,
    /// };
    ///
    /// cmd.display_table(&outdated, &summary)?;
    /// // Prints: "All dependencies are up to date!"
    /// # Ok(())
    /// # }
    /// ```
    fn display_table(&self, outdated: &[OutdatedInfo], summary: &OutdatedSummary) -> Result<()> {
        if outdated.is_empty() {
            println!("{}", "All dependencies are up to date!".green());
            return Ok(());
        }

        // Print header
        println!(
            "\n{:<30} {:<12} {:<12} {:<12} {:<15}",
            "Package".bold(),
            "Current".bold(),
            "Latest".bold(),
            "Available".bold(),
            "Tool".bold()
        );
        println!("{}", "─".repeat(85));

        // Print each dependency
        for dep in outdated {
            let name = if dep.has_update || dep.has_major_update {
                dep.name.yellow()
            } else {
                dep.name.normal()
            };

            let latest = if dep.has_update {
                dep.latest.green()
            } else {
                dep.latest.normal()
            };

            let available = if dep.has_major_update {
                dep.latest_available.cyan()
            } else {
                dep.latest_available.normal()
            };

            println!(
                "{:<30} {:<12} {:<12} {:<12} {:<15}",
                name,
                dep.current,
                latest,
                available,
                dep.tool.bright_black()
            );
        }

        // Print summary
        println!("\n{}", "Summary:".bold());
        println!("  Total dependencies: {}", summary.total);
        if summary.with_updates > 0 {
            println!(
                "  {} dependencies have compatible updates",
                summary.with_updates.to_string().green()
            );
        }
        if summary.with_major_updates > 0 {
            println!(
                "  {} dependencies have major updates available",
                summary.with_major_updates.to_string().cyan()
            );
        }
        println!("  {} dependencies are up to date", summary.up_to_date.to_string().green());

        Ok(())
    }
}