crawk 0.7.0

//! Module for locating and resolving Rust module paths within a crate.
//!
//! This module provides the [`CrateInfo`] struct which wraps cargo metadata
//! and provides functionality to resolve module paths (like `analysis::collect`)
//! to their corresponding file paths on disk.

mod module_tree;

use std::cell::RefCell;
use std::collections::HashMap;
use std::fmt;
use std::path::{Path, PathBuf};

use crate::cache::ParseCache;
use tracing::info;

use cargo_metadata::{Metadata, MetadataCommand};
use thiserror::Error;

/// Visibility of a Rust module as declared in source code.
///
/// Mirrors the Rust visibility syntax: `pub`, `pub(crate)`, `pub(super)`,
/// `pub(in path)`, or no keyword (private to the declaring module).
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub enum ModuleVisibility {
    /// `pub` — visible to everyone.
    Public,
    /// `pub(crate)` — visible anywhere within the crate.
    Crate,
    /// `pub(super)` — visible to the parent module and its descendants.
    Super,
    /// `pub(in path)` — visible within the subtree rooted at `path`.
    InPath(String),
    /// No visibility modifier — private to the declaring module.
    ///
    /// Note: `pub(self)` is semantically equivalent to no modifier and is also
    /// represented as this variant.
    Inherited,
}

impl fmt::Display for ModuleVisibility {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Public => f.write_str("pub"),
            Self::Crate => f.write_str("pub(crate)"),
            Self::Super => f.write_str("pub(super)"),
            Self::InPath(path) => write!(f, "pub(in {path})"),
            Self::Inherited => Ok(()),
        }
    }
}

/// The kind of compilation target a module belongs to.
#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub enum TargetKind {
    /// Library target (`lib.rs`).
    Lib,
    /// Binary target (`main.rs` or other `[[bin]]` targets).
    Bin,
    /// Integration test target (`tests/*.rs`).
    Test,
}

impl fmt::Display for TargetKind {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Lib => f.write_str("lib"),
            Self::Bin => f.write_str("bin"),
            Self::Test => f.write_str("test"),
        }
    }
}

/// Metadata identifying which compilation target a module belongs to.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct TargetInfo {
    /// The kind of target (lib, bin, test).
    kind: TargetKind,
    /// The target name from `Cargo.toml` (e.g., `"crawk"`, `"integration"`).
    name: String,
}

impl TargetInfo {
    /// Creates a new `TargetInfo`.
    #[must_use]
    pub fn new(kind: TargetKind, name: impl Into<String>) -> Self {
        Self {
            kind,
            name: name.into(),
        }
    }

    /// Returns the target kind.
    #[must_use]
    pub const fn kind(&self) -> &TargetKind {
        &self.kind
    }

    /// Returns the target name.
    #[must_use]
    pub fn name(&self) -> &str {
        &self.name
    }
}

impl fmt::Display for TargetInfo {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self.kind {
            TargetKind::Lib => fmt::Display::fmt(&self.kind, f),
            TargetKind::Bin | TargetKind::Test => write!(f, "{}:{}", self.kind, self.name),
        }
    }
}

/// Errors that can occur during crate info operations.
#[derive(Debug, Error)]
pub enum CrateInfoError {
    /// Failed to execute cargo metadata command.
    #[error("Failed to execute cargo metadata: {0}")]
    MetadataExecution(#[from] cargo_metadata::Error),

    /// Path points to a workspace root rather than a single crate.
    #[error("workspace support is not yet implemented")]
    WorkspaceRoot,

    /// Package not found in cargo metadata (internal inconsistency).
    #[error("root package not found in cargo metadata")]
    PackageNotFound,

    /// No crate root file (lib.rs or main.rs) found for the package.
    #[error("No crate root file found for package '{0}'")]
    NoCrateRoot(String),

    /// The module path is empty.
    #[error("Module path cannot be empty")]
    EmptyModulePath,

    /// Module not found at the expected path.
    #[error("Module '{module_path}' not found")]
    ModuleNotFound {
        /// The module path that was not found.
        module_path: String,
    },

    /// Failed to read source file.
    #[error("Failed to read file '{path}': {source}")]
    FileRead {
        /// The path of the file that could not be read.
        path: PathBuf,
        /// The underlying IO error.
        source: std::io::Error,
    },

    /// The source file exceeds the maximum allowed size and was not parsed.
    ///
    /// Mirrors the analyzer's own `FileTooLarge` so the discovery path enforces the
    /// same limit; guards against excessive memory use on unexpectedly large files.
    #[error("File too large '{path}': {size} bytes (limit {limit} bytes)")]
    FileTooLarge {
        /// Path to the oversized file.
        path: PathBuf,
        /// Actual file size in bytes.
        size: u64,
        /// Maximum allowed size in bytes.
        limit: u64,
    },

    /// Failed to parse source file.
    #[error("Failed to parse file '{path}': {message}")]
    ParseError {
        /// The path of the file that could not be parsed.
        path: PathBuf,
        /// The parse error message.
        message: String,
    },

    /// Module path segment is invalid (path traversal or illegal characters).
    #[error("Invalid module path segment '{segment}'")]
    InvalidModuleSegment {
        /// The offending segment.
        segment: String,
    },

    /// Resolved path escapes the crate root directory.
    #[error("Resolved path escapes crate root")]
    PathTraversal,
}

impl CrateInfoError {
    /// Returns `true` if this error is a `ModuleNotFound` variant.
    #[must_use]
    pub const fn is_module_not_found(&self) -> bool {
        matches!(self, Self::ModuleNotFound { .. })
    }
}

/// Result type alias for crate info operations.
pub(crate) type Result<T> = std::result::Result<T, CrateInfoError>;

/// A struct representing information about a Rust module, including its path and source file.
///
/// This struct holds metadata about a specific module within a crate, including
/// the module's fully qualified path and the file system path where it is defined.
/// Modules can be defined either as separate files or as inline modules within
/// another file.
#[derive(Debug, Clone)]
pub struct ModuleInfo {
    /// The full module path (e.g., "analysis::collect")
    module_path: String,

    /// The file path where this module is defined
    source_file: PathBuf,

    /// The visibility of this module as declared in its parent
    visibility: ModuleVisibility,

    /// The compilation target this module belongs to
    target: TargetInfo,
}

impl ModuleInfo {
    /// Creates a new `ModuleInfo` instance.
    ///
    /// # Arguments
    ///
    /// * `module_path` - The fully qualified module path (e.g., "analysis::collect")
    /// * `source_file` - The file system path where this module is defined
    /// * `visibility` - The declared visibility of the module
    /// * `target` - The compilation target this module belongs to
    #[must_use]
    pub fn new(
        module_path: impl Into<String>,
        source_file: PathBuf,
        visibility: ModuleVisibility,
        target: TargetInfo,
    ) -> Self {
        Self {
            module_path: module_path.into(),
            source_file,
            visibility,
            target,
        }
    }

    /// Returns the fully qualified module path.
    #[must_use]
    pub fn path(&self) -> &str {
        &self.module_path
    }

    /// Returns the source file path for this module.
    ///
    /// For inline modules (such as test modules defined with `#[cfg(test)]`),
    /// this returns the path of the file containing the inline module definition.
    #[must_use]
    pub fn source(&self) -> &Path {
        &self.source_file
    }

    /// Returns the declared visibility of this module.
    #[must_use]
    pub const fn visibility(&self) -> &ModuleVisibility {
        &self.visibility
    }

    /// Returns the compilation target this module belongs to.
    #[must_use]
    pub const fn target(&self) -> &TargetInfo {
        &self.target
    }

    /// Returns a new `ModuleInfo` with the given module path, preserving all other fields.
    #[must_use]
    pub fn with_path(self, new_path: impl Into<String>) -> Self {
        Self {
            module_path: new_path.into(),
            ..self
        }
    }
}

/// Memoized filesystem lookups, valid for the lifetime of one [`CrateInfo`].
///
/// Module resolution peels every path prefix of every module (see
/// [`split_inline_scope`](CrateInfo::split_inline_scope)), so the same prefixes
/// are resolved once per descendant without a memo, and every containment check
/// re-canonicalizes the same crate root directory.
#[derive(Debug, Clone, Default)]
struct ResolveCache {
    /// Module path → resolved source file. Successful resolutions only:
    /// `CrateInfoError` is not `Clone`, and replaying a generic error would
    /// lose the original diagnostic.
    modules: HashMap<String, PathBuf>,

    /// Directory → its canonicalized form.
    canonical_dirs: HashMap<PathBuf, PathBuf>,
}

/// A struct that wraps cargo metadata and provides module path resolution.
///
/// This struct holds the metadata for a Rust crate and provides methods to
/// resolve module paths (like `analysis::collect`) to their corresponding
/// file paths on disk.
#[derive(Debug, Clone)]
pub(crate) struct CrateInfo {
    /// The cargo metadata for the crate.
    metadata: Metadata,

    /// The name of the root package in the workspace.
    root_package_name: String,

    /// Index of the root package within `metadata.packages`, resolved once at
    /// construction. `metadata.packages` is never mutated after `new`, so this
    /// stays valid for the lifetime of the `CrateInfo`.
    root_package_index: usize,

    /// Memoized resolution results. Interior mutability keeps the resolution
    /// API on `&self`; crawk is single-threaded, so `RefCell` suffices.
    resolve_cache: RefCell<ResolveCache>,
}

impl CrateInfo {
    /// Creates a new `CrateInfo` instance from a crate path.
    ///
    /// # Arguments
    ///
    /// * `crate_path` - Path to the root directory of the crate (containing Cargo.toml)
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - The cargo metadata command fails to execute
    /// - No root package is found in the workspace
    pub(crate) fn new(crate_path: &Path) -> Result<Self> {
        let metadata = MetadataCommand::new().current_dir(crate_path).exec()?;

        let root_package_name = metadata
            .root_package()
            .ok_or(CrateInfoError::WorkspaceRoot)?
            .name
            .to_string();

        let root_package_index = metadata
            .packages
            .iter()
            .position(|p| p.name == root_package_name)
            .ok_or(CrateInfoError::WorkspaceRoot)?;

        Ok(Self {
            metadata,
            root_package_name,
            root_package_index,
            resolve_cache: RefCell::default(),
        })
    }

    /// Returns the memoized file for `module_path`, if it was resolved before.
    pub(super) fn cached_module(&self, module_path: &str) -> Option<PathBuf> {
        self.resolve_cache
            .borrow()
            .modules
            .get(module_path)
            .cloned()
    }

    /// Records a successful module resolution in the memo.
    pub(super) fn cache_module(&self, module_path: &str, resolved: &Path) {
        self.resolve_cache
            .borrow_mut()
            .modules
            .insert(module_path.to_owned(), resolved.to_path_buf());
    }

    /// Canonicalizes `dir`, reusing the result on later calls.
    ///
    /// Containment checks run once per resolved module and always against one
    /// of a handful of target root directories, so the canonical form is worth
    /// keeping instead of re-walking the directory's symlinks every time.
    ///
    /// # Errors
    ///
    /// Returns [`CrateInfoError::FileRead`] if canonicalization fails.
    pub(super) fn canonical_dir(&self, dir: &Path) -> Result<PathBuf> {
        if let Some(cached) = self.resolve_cache.borrow().canonical_dirs.get(dir) {
            return Ok(cached.clone());
        }

        let canonical = dir
            .canonicalize()
            .map_err(|source| CrateInfoError::FileRead {
                path: dir.to_path_buf(),
                source,
            })?;
        self.resolve_cache
            .borrow_mut()
            .canonical_dirs
            .insert(dir.to_path_buf(), canonical.clone());
        Ok(canonical)
    }

    /// Number of memoized module resolutions (test observability).
    #[cfg(test)]
    pub(super) fn cached_module_count(&self) -> usize {
        self.resolve_cache.borrow().modules.len()
    }

    /// Number of directories whose canonical form is memoized (test observability).
    #[cfg(test)]
    pub(super) fn canonical_dir_count(&self) -> usize {
        self.resolve_cache.borrow().canonical_dirs.len()
    }

    /// Returns the name of the root package.
    #[must_use]
    pub(crate) fn root_package_name(&self) -> &str {
        &self.root_package_name
    }

    /// Returns all compilation targets in the crate.
    ///
    /// Always includes library and binary targets. When `include_tests` is
    /// `true`, also includes integration test targets.
    pub(crate) fn all_targets(&self, include_tests: bool) -> Vec<(TargetInfo, PathBuf)> {
        let Some(package) = self.root_package() else {
            return vec![];
        };

        let mut result = Vec::new();
        for target in &package.targets {
            let src_path = target.src_path.as_std_path().to_path_buf();
            if target.is_lib() {
                result.push((
                    TargetInfo::new(TargetKind::Lib, target.name.as_str()),
                    src_path,
                ));
            } else if target.is_bin() {
                result.push((
                    TargetInfo::new(TargetKind::Bin, target.name.as_str()),
                    src_path,
                ));
            } else if include_tests && target.kind.contains(&cargo_metadata::TargetKind::Test) {
                result.push((
                    TargetInfo::new(TargetKind::Test, target.name.as_str()),
                    src_path,
                ));
            }
        }
        // Sort: Lib first, then Bin, then Test
        result.sort_by(|a, b| {
            a.0.kind()
                .cmp(b.0.kind())
                .then_with(|| a.0.name().cmp(b.0.name()))
        });
        result
    }

    /// Returns `true` if `file_path` is a compilation target's own entry-point
    /// source file (library root, binary root, or integration-test root), as
    /// reported by `cargo_metadata` — not inferred from a hardcoded filename.
    pub(crate) fn is_target_entry_point(&self, file_path: &Path) -> bool {
        self.root_package().is_some_and(|package| {
            package
                .targets
                .iter()
                .any(|target| target.src_path.as_std_path() == file_path)
        })
    }

    /// Returns the root package from cargo metadata.
    fn root_package(&self) -> Option<&cargo_metadata::Package> {
        self.metadata.packages.get(self.root_package_index)
    }

    /// Returns a list of the given module and all its submodules with their source files.
    ///
    /// This method parses the source files using the `syn` crate to extract
    /// module declarations. It can optionally include test modules (those with
    /// `#[cfg(test)]` attribute).
    ///
    /// # Arguments
    ///
    /// * `module_path` - A module path like `analysis::collect` or `mycrate::analysis`
    /// * `include_tests` - If `true`, includes modules marked with `#[cfg(test)]`
    /// * `recursive` - If `true`, recursively collects all submodules. If `false`, only the
    ///   current module and its direct submodules are returned (without traversing deeper).
    ///   When `include_tests` is `true` and `recursive` is `false`, only the test module
    ///   directly under the given module is included.
    ///
    /// # Returns
    ///
    /// Returns <code>Ok(Vec<[ModuleInfo]>)</code> containing information about each module and its source file.
    /// For inline modules (like `#[cfg(test)] mod tests`), the source file is the containing file.
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - The module path cannot be resolved
    /// - The source file cannot be read
    /// - The source file cannot be parsed
    pub(crate) fn get_module_tree(
        &self,
        module_path: &str,
        recursive: bool,
        include_tests: bool,
        target: &TargetInfo,
        cache: &mut ParseCache,
    ) -> Result<Vec<ModuleInfo>> {
        let file_path = self.resolve_module(module_path, cache)?;

        // Normalize the module path (remove crate name prefix if present)
        let normalized_path = self.normalize_module_path(module_path);
        info!(
            "Module tree: '{}' \u{2192} {}, recursive={recursive}",
            normalized_path,
            file_path.display()
        );

        // Determine if this is an inline module and compute inline scope
        let (_, inline_scope) = self.split_inline_scope(&normalized_path, &file_path, cache);

        let root_visibility =
            self.compute_root_visibility(&normalized_path, &file_path, &inline_scope, cache)?;

        if recursive {
            Self::collect_submodules_recursive(
                &file_path,
                &normalized_path,
                root_visibility,
                &inline_scope,
                include_tests,
                target,
                cache,
            )
        } else {
            Self::collect_submodules_shallow(
                &file_path,
                &normalized_path,
                root_visibility,
                &inline_scope,
                include_tests,
                target,
                cache,
            )
        }
    }

    /// Public wrapper around [`resolve_module`](Self::resolve_module).
    ///
    /// Resolves a module path (e.g., `"foo::bar"`) to the corresponding source file.
    ///
    /// # Errors
    ///
    /// Returns an error if the module cannot be found or the crate root is invalid.
    pub(crate) fn resolve_module_path_to_file(
        &self,
        module_path: &str,
        cache: &mut ParseCache,
    ) -> Result<PathBuf> {
        self.resolve_module(module_path, cache)
    }

    /// Collects the module tree rooted at a source file, without module path resolution.
    ///
    /// Use this for targets (like integration tests) whose root file is not
    /// discoverable through the normal `resolve_module` mechanism.
    ///
    /// # Errors
    ///
    /// Returns an error if the source file cannot be read or parsed.
    pub(crate) fn get_module_tree_for_file(
        src_path: &Path,
        target: &TargetInfo,
        include_cfg_tests: bool,
        cache: &mut ParseCache,
    ) -> Result<Vec<ModuleInfo>> {
        Self::collect_submodules_recursive_crate_root(src_path, include_cfg_tests, target, cache)
    }

    /// Normalizes a module path by removing the crate name prefix if present.
    /// Also normalizes "lib" alias to the crate name.
    /// Also normalizes binary target file stems (e.g., "main" for main.rs).
    /// If the module path is just the crate name/lib/binary, returns empty string.
    fn normalize_module_path(&self, module_path: &str) -> String {
        let parts: Vec<&str> = module_path.split("::").collect();
        if parts.is_empty() {
            return module_path.to_owned();
        }

        let first_part = parts[0];

        // Check if first part is the crate name or "lib" alias
        if first_part == self.root_package_name() || first_part == "lib" {
            return if parts.len() == 1 {
                // Just the crate name/lib - return empty (analyzing crate root)
                String::new()
            } else {
                parts[1..].join("::")
            };
        }

        // Check if first part is a binary target file stem (e.g., "main", "app")
        if let Some(package) = self.root_package()
            && Self::find_binary_by_file_stem(package, first_part).is_some()
        {
            return if parts.len() == 1 {
                // Just the binary target name - return empty (analyzing binary root)
                String::new()
            } else {
                // Strip the binary target prefix
                parts[1..].join("::")
            };
        }

        module_path.to_owned()
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::path::Path;

    /// The cached index must select the real root package that
    /// `Metadata::root_package` identifies, not a namesake — a wrong or stale
    /// index would silently return a different package.
    #[test]
    fn root_package_uses_cached_index_pointing_at_the_root_package() {
        let info = CrateInfo::new(Path::new("fixtures/modules")).unwrap();
        let cached = info.root_package().expect("cached root package");
        let expected = info.metadata.root_package().expect("metadata root package");
        assert_eq!(cached.id, expected.id);
        assert_eq!(cached.name.to_string(), info.root_package_name());
    }
}