cloacina-macros 0.4.0

/*
 *  Copyright 2025-2026 Colliery Software
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */

//! Compile-time task registry for dependency management and validation.
//!
//! This module provides a registry system that tracks tasks and their dependencies
//! during compilation. It ensures that:
//! - Task IDs are unique (except in test environments)
//! - All dependencies exist
//! - No circular dependencies exist
//! - Provides helpful error messages with suggestions for typos
//!
//! The registry is implemented as a global singleton using `once_cell` and `Mutex`
//! for thread-safe access during compilation.

use once_cell::sync::Lazy;
use proc_macro2::TokenStream;
use quote::quote;
use std::collections::HashMap;
use std::sync::Mutex;

/// Global compile-time registry instance for task tracking
static COMPILE_TIME_TASK_REGISTRY: Lazy<Mutex<CompileTimeTaskRegistry>> =
    Lazy::new(|| Mutex::new(CompileTimeTaskRegistry::new()));

/// Information about a registered task
#[derive(Debug, Clone)]
pub struct TaskInfo {
    /// Unique identifier for the task
    pub id: String,
    /// List of task IDs that this task depends on
    pub dependencies: Vec<String>,
    /// Source file path where the task is defined
    pub file_path: String,
}

/// Registry that maintains task information and dependency relationships
/// during compilation
#[derive(Debug)]
pub struct CompileTimeTaskRegistry {
    /// Map of task IDs to their information
    tasks: HashMap<String, TaskInfo>,
    /// Adjacency list representation of the dependency graph
    dependency_graph: HashMap<String, Vec<String>>,
}

#[allow(dead_code)]
impl CompileTimeTaskRegistry {
    /// Creates a new empty task registry
    pub fn new() -> Self {
        Self {
            tasks: HashMap::new(),
            dependency_graph: HashMap::new(),
        }
    }

    /// Register a task in the compile-time registry
    ///
    /// # Arguments
    /// * `task_info` - Information about the task to register
    ///
    /// # Returns
    /// * `Ok(())` if registration was successful
    /// * `Err(CompileTimeError::DuplicateTaskId)` if the task ID is already registered
    pub fn register_task(&mut self, task_info: TaskInfo) -> Result<(), CompileTimeError> {
        let task_id = &task_info.id;

        // Check for duplicate task IDs
        if let Some(existing) = self.tasks.get(task_id) {
            return Err(CompileTimeError::DuplicateTaskId {
                task_id: task_id.clone(),
                existing_location: existing.file_path.clone(),
                duplicate_location: task_info.file_path.clone(),
            });
        }

        // Add to dependency graph
        self.dependency_graph
            .insert(task_id.clone(), task_info.dependencies.clone());

        // Store task info
        self.tasks.insert(task_id.clone(), task_info);

        Ok(())
    }

    /// Validate that all dependencies for a task exist in the registry
    ///
    /// # Arguments
    /// * `task_id` - ID of the task to validate dependencies for
    ///
    /// # Returns
    /// * `Ok(())` if all dependencies exist
    /// * `Err(CompileTimeError::MissingDependency)` if any dependency is missing
    /// * `Err(CompileTimeError::TaskNotFound)` if the task itself is not found
    pub fn validate_dependencies(&self, task_id: &str) -> Result<(), CompileTimeError> {
        // In test mode, be more lenient about missing tasks (they might be in different modules)
        let is_test_env = std::env::var("CARGO_CRATE_NAME")
            .map(|name| name.contains("test") || name == "cloacina")
            .unwrap_or(false)
            || std::env::var("CARGO_PKG_NAME")
                .map(|name| name.contains("test") || name == "cloacina")
                .unwrap_or(false);

        if is_test_env && !self.tasks.contains_key(task_id) {
            // In test mode, if the task doesn't exist in registry, just return OK
            // This handles cases where tasks are defined in different test modules
            return Ok(());
        }

        let task = self
            .tasks
            .get(task_id)
            .ok_or_else(|| CompileTimeError::TaskNotFound(task_id.to_string()))?;

        for dependency in &task.dependencies {
            if !self.tasks.contains_key(dependency) {
                if is_test_env {
                    // In test mode, just warn but don't fail for missing dependencies
                    continue;
                }
                return Err(CompileTimeError::MissingDependency {
                    task_id: task_id.to_string(),
                    dependency: dependency.clone(),
                    task_location: task.file_path.clone(),
                });
            }
        }

        Ok(())
    }

    /// Validate that a single dependency exists in the registry
    ///
    /// # Arguments
    /// * `dependency` - ID of the dependency to validate
    ///
    /// # Returns
    /// * `Ok(())` if the dependency exists
    /// * `Err(CompileTimeError::MissingDependency)` if the dependency is not found
    #[allow(dead_code)]
    pub fn validate_single_dependency(&self, dependency: &str) -> Result<(), CompileTimeError> {
        if !self.tasks.contains_key(dependency) {
            return Err(CompileTimeError::MissingDependency {
                task_id: "unknown".to_string(),
                dependency: dependency.to_string(),
                task_location: "unknown".to_string(),
            });
        }
        Ok(())
    }

    /// Detect circular dependencies in the task graph using Tarjan's algorithm
    ///
    /// # Returns
    /// * `Ok(())` if no cycles are found
    /// * `Err(CompileTimeError::CircularDependency)` if a cycle is detected
    pub fn detect_cycles(&self) -> Result<(), CompileTimeError> {
        // In test mode, be more lenient about cycle detection
        let is_test_env = std::env::var("CARGO_CRATE_NAME")
            .map(|name| name.contains("test") || name == "cloacina")
            .unwrap_or(false)
            || std::env::var("CARGO_PKG_NAME")
                .map(|name| name.contains("test") || name == "cloacina")
                .unwrap_or(false);

        if is_test_env {
            // In test mode, skip cycle detection as tasks may be spread across modules
            return Ok(());
        }

        let mut visited = HashMap::new();
        let mut rec_stack = HashMap::new();

        for task_id in self.tasks.keys() {
            if !visited.get(task_id).unwrap_or(&false) {
                self.dfs_cycle_detection(task_id, &mut visited, &mut rec_stack, &mut Vec::new())?;
            }
        }

        Ok(())
    }

    /// Depth-first search implementation for cycle detection
    ///
    /// # Arguments
    /// * `task_id` - Current task being visited
    /// * `visited` - Map tracking visited tasks
    /// * `rec_stack` - Map tracking tasks in current recursion stack
    /// * `path` - Current path being explored
    ///
    /// # Returns
    /// * `Ok(())` if no cycle is found
    /// * `Err(CompileTimeError::CircularDependency)` if a cycle is detected
    fn dfs_cycle_detection(
        &self,
        task_id: &str,
        visited: &mut HashMap<String, bool>,
        rec_stack: &mut HashMap<String, bool>,
        path: &mut Vec<String>,
    ) -> Result<(), CompileTimeError> {
        visited.insert(task_id.to_string(), true);
        rec_stack.insert(task_id.to_string(), true);
        path.push(task_id.to_string());

        if let Some(dependencies) = self.dependency_graph.get(task_id) {
            for dependency in dependencies {
                if !visited.get(dependency).unwrap_or(&false) {
                    self.dfs_cycle_detection(dependency, visited, rec_stack, path)?;
                } else if *rec_stack.get(dependency).unwrap_or(&false) {
                    // Found cycle
                    let cycle_start = path.iter().position(|x| x == dependency).unwrap_or(0);
                    let cycle: Vec<String> = path[cycle_start..].to_vec();

                    return Err(CompileTimeError::CircularDependency {
                        cycle: cycle.clone(),
                        task_locations: cycle
                            .iter()
                            .filter_map(|id| self.tasks.get(id))
                            .map(|task| task.file_path.clone())
                            .collect(),
                    });
                }
            }
        }

        rec_stack.insert(task_id.to_string(), false);
        path.pop();
        Ok(())
    }

    /// Get all registered task IDs
    ///
    /// This is primarily used for IDE integration and error message suggestions
    ///
    /// # Returns
    /// A vector of all task IDs currently registered
    pub fn get_all_task_ids(&self) -> Vec<String> {
        self.tasks.keys().cloned().collect()
    }

    /// Clear the registry
    ///
    /// This is primarily used for testing to avoid state leakage between tests
    #[allow(dead_code)]
    pub fn clear(&mut self) {
        self.tasks.clear();
        self.dependency_graph.clear();
    }

    /// Get the current number of registered tasks
    #[allow(dead_code)]
    pub fn size(&self) -> usize {
        self.tasks.len()
    }
}

/// Errors that can occur during compile-time task validation
#[derive(Debug)]
#[allow(dead_code)]
pub enum CompileTimeError {
    /// A task ID was defined multiple times
    DuplicateTaskId {
        /// The duplicate task ID
        task_id: String,
        /// Location of the first definition
        existing_location: String,
        /// Location of the duplicate definition
        duplicate_location: String,
    },
    /// A task depends on a non-existent task
    MissingDependency {
        /// ID of the task with the missing dependency
        task_id: String,
        /// The missing dependency ID
        dependency: String,
        /// Location of the task definition
        task_location: String,
    },
    /// A circular dependency was detected between tasks
    CircularDependency {
        /// List of task IDs forming the cycle
        cycle: Vec<String>,
        /// File locations of the tasks in the cycle
        task_locations: Vec<String>,
    },
    /// A task ID was not found in the registry
    TaskNotFound(String),
}

impl CompileTimeError {
    /// Convert the error into a compile-time error token stream
    ///
    /// This generates detailed error messages with suggestions for typos
    /// and available tasks when dependencies are missing.
    pub fn to_compile_error(&self) -> TokenStream {
        match self {
            CompileTimeError::DuplicateTaskId {
                task_id,
                existing_location,
                duplicate_location,
            } => {
                let msg = format!(
                    "Duplicate task ID '{}'. Already defined at '{}', redefined at '{}'",
                    task_id, existing_location, duplicate_location
                );
                quote! { compile_error!(#msg); }
            }
            CompileTimeError::MissingDependency {
                task_id,
                dependency,
                task_location,
            } => {
                let registry = get_registry().lock().unwrap();
                let available_tasks = registry.get_all_task_ids();

                // Find similar task names for suggestions
                let suggestions = find_similar_task_names(dependency, &available_tasks);

                let mut msg = format!(
                    "Task '{}' depends on undefined task '{}'\n\n",
                    task_id, dependency
                );

                if !suggestions.is_empty() {
                    msg.push_str(&format!(
                        "Did you mean one of these?\n  {}\n\n",
                        suggestions.join("\n  ")
                    ));
                }

                msg.push_str(&format!(
                    "Available tasks: [{}]\n\n",
                    available_tasks.join(", ")
                ));

                if task_location != "unknown" {
                    msg.push_str(&format!("Task defined at: {}", task_location));
                }

                quote! { compile_error!(#msg); }
            }
            CompileTimeError::CircularDependency {
                cycle,
                task_locations,
            } => {
                let cycle_str = cycle.join(" -> ");
                let locations_str = task_locations.join(", ");
                let msg = format!(
                    "Circular dependency detected: {} (defined at: {})",
                    cycle_str, locations_str
                );
                quote! { compile_error!(#msg); }
            }
            CompileTimeError::TaskNotFound(task_id) => {
                let msg = format!("Task '{}' not found in registry", task_id);
                quote! { compile_error!(#msg); }
            }
        }
    }
}

/// Get the global compile-time registry instance
///
/// This provides thread-safe access to the registry during compilation
pub fn get_registry() -> &'static Lazy<Mutex<CompileTimeTaskRegistry>> {
    &COMPILE_TIME_TASK_REGISTRY
}

/// Find task names similar to the given name for typo suggestions
///
/// Uses Levenshtein distance to find similar task names
///
/// # Arguments
/// * `target` - The task name to find similar names for
/// * `available` - List of available task names
///
/// # Returns
/// Up to 3 task names that are similar to the target
fn find_similar_task_names(target: &str, available: &[String]) -> Vec<String> {
    available
        .iter()
        .filter_map(|name| {
            let distance = levenshtein_distance(target, name);
            if distance <= 2 && distance < target.len() / 2 {
                Some(name.clone())
            } else {
                None
            }
        })
        .take(3)
        .collect()
}

/// Calculate the Levenshtein distance between two strings
///
/// Used for finding similar task names when suggesting fixes for typos
///
/// # Arguments
/// * `a` - First string
/// * `b` - Second string
///
/// # Returns
/// The minimum number of single-character edits required to change one string into the other
#[allow(clippy::needless_range_loop)] // Classic algorithm - direct indexing is clearer than iterators
fn levenshtein_distance(a: &str, b: &str) -> usize {
    let a_len = a.len();
    let b_len = b.len();

    if a_len == 0 {
        return b_len;
    }
    if b_len == 0 {
        return a_len;
    }

    let mut matrix = vec![vec![0; b_len + 1]; a_len + 1];

    for (i, row) in matrix.iter_mut().enumerate().take(a_len + 1) {
        row[0] = i;
    }
    for j in 0..=b_len {
        matrix[0][j] = j;
    }

    for i in 1..=a_len {
        for j in 1..=b_len {
            let cost = if a.chars().nth(i - 1) == b.chars().nth(j - 1) {
                0
            } else {
                1
            };
            matrix[i][j] = std::cmp::min(
                std::cmp::min(matrix[i - 1][j] + 1, matrix[i][j - 1] + 1),
                matrix[i - 1][j - 1] + cost,
            );
        }
    }

    matrix[a_len][b_len]
}