cargo_docs_md/

linker.rs

//! Cross-reference linking for markdown documentation.
//!
//! This module provides the `LinkRegistry` which maps rustdoc item IDs to their
//! corresponding markdown file paths. This enables creating clickable links
//! between items in the generated documentation.
//!
//! # How It Works
//!
//! 1. During initialization, `LinkRegistry::build()` traverses the entire crate
//!    and records where each item's documentation will be written.
//!
//! 2. During markdown generation, `create_link()` is called to generate
//!    relative links from one file to another.
//!
//! # Path Formats
//!
//! The registry supports two output formats:
//!
//! - **Flat**: `module.md`, `parent__child.md` (double-underscore separators)
//! - **Nested**: `module/index.md`, `parent/child/index.md` (directory structure)
//!
//! # Example
//!
//! ```ignore
//! let registry = LinkRegistry::build(&krate, true); // flat format
//! let link = registry.create_link(&some_id, "index.md");
//! // Returns: Some("[`ItemName`](module.md)")
//! ```

use std::collections::HashMap;
use std::path::Path;

use rustdoc_types::{Crate, Id, ItemEnum, ItemKind, Visibility};
use unicode_normalization::UnicodeNormalization;

/// Kind of associated item for anchor generation.
///
/// Used to disambiguate anchors when multiple items share the same name
/// (e.g., `type Init` and `fn init` in the same impl block).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AssocItemKind {
    /// A method or function (`fn`)
    Method,

    /// An associated constant (`const`)
    Const,

    /// An associated type (`type`)
    Type,
}

/// Context for generating impl item anchors, distinguishing inherent vs trait impls.
///
/// For trait impls, we need to include the trait name in the anchor to avoid
/// duplicate anchors when multiple traits define the same associated type/const.
/// For example, both `impl Add for Foo` and `impl Sub for Foo` might have
/// `type Output`, which would create duplicate anchors without the trait name.
#[derive(Debug, Clone, Copy)]
pub enum ImplContext<'a> {
    /// Inherent impl (no trait) - anchors use format `typename-itemname`
    Inherent,

    /// Trait impl - anchors include trait name: `typename-traitname-itemname`
    Trait(&'a str),
}

/// Utilify functions to handle anchors
pub struct AnchorUtils;

impl AnchorUtils {
    /// Generate a compound anchor for an associated item on a type.
    ///
    /// This creates a unique anchor that combines the type name, item kind, and item name,
    /// enabling deep linking to specific items. The format is `typename-itemname` for methods
    /// (backward compatible), and `typename-kind-itemname` for constants and types to avoid
    /// collisions.
    ///
    /// # Arguments
    ///
    /// * `type_name` - The name of the type (struct, enum, trait, etc.)
    /// * `item_name` - The name of the method or associated item
    /// * `kind` - The kind of associated item (method, const, or type)
    ///
    /// # Examples
    ///
    /// ```ignore
    /// assert_eq!(assoc_item_anchor("Parser", "parse", AssocItemKind::Method), "parser-parse");
    /// assert_eq!(assoc_item_anchor("HashMap", "new", AssocItemKind::Method), "hashmap-new");
    /// assert_eq!(assoc_item_anchor("Vec", "Item", AssocItemKind::Type), "vec-type-item");
    /// assert_eq!(assoc_item_anchor("Vec", "ALIGN", AssocItemKind::Const), "vec-const-align");
    /// ```
    #[must_use]
    pub fn assoc_item_anchor(type_name: &str, item_name: &str, kind: AssocItemKind) -> String {
        let type_slug = Self::slugify_anchor(type_name);
        let item_slug = Self::slugify_anchor(item_name);

        match kind {
            // Methods use the simple format for backward compatibility
            AssocItemKind::Method => format!("{type_slug}-{item_slug}"),

            // Constants and types include the kind to disambiguate from methods
            AssocItemKind::Const => format!("{type_slug}-const-{item_slug}"),

            AssocItemKind::Type => format!("{type_slug}-type-{item_slug}"),
        }
    }

    /// Generate a compound anchor for a method on a type.
    ///
    /// This creates a unique anchor that combines the type name and method name,
    /// enabling deep linking to specific methods. The format is `typename-methodname`,
    /// where both parts are slugified.
    ///
    /// # Arguments
    ///
    /// * `type_name` - The name of the type (struct, enum, trait, etc.)
    /// * `method_name` - The name of the method or associated item
    ///
    /// # Examples
    ///
    /// ```ignore
    /// assert_eq!(method_anchor("Parser", "parse"), "parser-parse");
    /// assert_eq!(method_anchor("HashMap", "new"), "hashmap-new");
    /// assert_eq!(method_anchor("Vec<T>", "push"), "vec-push");
    /// ```
    #[must_use]
    pub fn method_anchor(type_name: &str, method_name: &str) -> String {
        Self::assoc_item_anchor(type_name, method_name, AssocItemKind::Method)
    }

    /// Generate an anchor for an associated item in an impl block, with trait disambiguation.
    ///
    /// This extends `assoc_item_anchor` to handle trait impls, where multiple traits
    /// may define the same associated type (e.g., `Output` in both `Add` and `Sub`).
    ///
    /// # Disambiguation Strategy
    ///
    /// - **Associated types/consts**: Always include trait name (high collision risk)
    /// - **Methods**: Only include trait name when it differs from the method name
    ///   - Avoids redundant `Clone::clone` → `type-clone-clone`
    ///   - Keeps `Debug::fmt` → `type-debug-fmt` for disambiguation from `Display::fmt`
    ///
    /// # Arguments
    ///
    /// * `type_name` - The name of the implementing type
    /// * `item_name` - The name of the associated item
    /// * `kind` - The kind of associated item
    /// * `impl_ctx` - Whether this is an inherent or trait impl
    ///
    /// # Anchor Formats
    ///
    /// | Context | Kind | Format | Example |
    /// |---------|------|--------|---------|
    /// | Inherent | Method | `type-method` | `vec-push` |
    /// | Inherent | Type | `type-type-item` | `vec-type-item` |
    /// | Inherent | Const | `type-const-item` | `vec-const-align` |
    /// | Trait(Clone) | Method | `type-method` | `vec-clone` (trait=method) |
    /// | Trait(Debug) | Method | `type-trait-method` | `vec-debug-fmt` (trait≠method) |
    /// | Trait(Add) | Type | `type-trait-type-item` | `vec-add-type-output` |
    /// | Trait(Add) | Const | `type-trait-const-item` | `vec-add-const-max` |
    #[must_use]
    pub fn impl_item_anchor(
        type_name: &str,
        item_name: &str,
        kind: AssocItemKind,
        impl_ctx: ImplContext<'_>,
    ) -> String {
        let type_slug = Self::slugify_anchor(type_name);
        let item_slug = Self::slugify_anchor(item_name);

        match impl_ctx {
            // Inherent impls: use the existing format
            ImplContext::Inherent => match kind {
                AssocItemKind::Method => format!("{type_slug}-{item_slug}"),
                AssocItemKind::Const => format!("{type_slug}-const-{item_slug}"),
                AssocItemKind::Type => format!("{type_slug}-type-{item_slug}"),
            },

            // Trait impls: include trait name to avoid collisions
            // For associated types/consts, always include trait name (high collision risk:
            // e.g., Add::Output vs Sub::Output on same type)
            // For methods, only include trait name when it differs from method name
            // (avoids redundant Clone::clone -> "type-clone-clone", but keeps
            // Debug::fmt -> "type-debug-fmt" for disambiguation from Display::fmt)
            ImplContext::Trait(trait_name) => {
                let trait_slug = Self::slugify_anchor(trait_name);
                match kind {
                    AssocItemKind::Method => {
                        if trait_slug == item_slug {
                            // Skip redundant trait prefix (e.g., Clone::clone, Default::default)
                            format!("{type_slug}-{item_slug}")
                        } else {
                            // Keep trait prefix for disambiguation (e.g., Debug::fmt vs Display::fmt)
                            format!("{type_slug}-{trait_slug}-{item_slug}")
                        }
                    },
                    AssocItemKind::Const => {
                        format!("{type_slug}-{trait_slug}-const-{item_slug}")
                    },
                    AssocItemKind::Type => format!("{type_slug}-{trait_slug}-type-{item_slug}"),
                }
            },
        }
    }

    /// Convert a name to a GitHub-style markdown anchor slug.
    ///
    /// This normalizes item names to match the anchor IDs generated by markdown
    /// renderers (GitHub, mdBook, etc.) when they process headings.
    ///
    /// # Rules Applied
    ///
    /// 1. Apply Unicode NFC normalization (canonical composition)
    /// 2. Convert to lowercase (full Unicode, not just ASCII)
    /// 3. Remove backticks (markdown code formatting)
    /// 4. Remove generics (`<T>`, `<K, V>`) by stripping `<...>` content
    /// 5. Replace spaces and underscores with hyphens
    /// 6. Remove non-alphanumeric characters (except hyphens)
    /// 7. Collapse consecutive hyphens
    /// 8. Trim leading/trailing hyphens
    ///
    /// # Examples
    ///
    /// ```ignore
    /// assert_eq!(slugify_anchor("HashMap"), "hashmap");
    /// assert_eq!(slugify_anchor("HashMap<K, V>"), "hashmap");
    /// assert_eq!(slugify_anchor("my_function"), "my-function");
    /// assert_eq!(slugify_anchor("Into<T>"), "into");
    /// assert_eq!(slugify_anchor("Größe"), "größe");
    /// ```
    #[must_use]
    pub fn slugify_anchor(name: &str) -> String {
        // Fast path: pure ASCII strings (common for Rust identifiers)
        // Skip NFC normalization overhead when not needed
        if name.is_ascii() {
            return Self::slugify_anchor_ascii(name);
        }

        // Slow path: Apply NFC normalization for Unicode strings
        // Handles composed vs decomposed forms (e.g., "é" vs "e\u{0301}")
        let normalized: String = name.nfc().collect();
        Self::slugify_anchor_impl(&normalized)
    }

    /// Fast ASCII-only slugification (no allocation for normalization).
    fn slugify_anchor_ascii(name: &str) -> String {
        let mut result = String::with_capacity(name.len());
        let mut in_generics = 0;
        let mut last_was_hyphen = true;

        for ch in name.chars() {
            match ch {
                '`' => {},

                '<' => in_generics += 1,

                '>' => {
                    if in_generics > 0 {
                        in_generics -= 1;
                    }
                },

                _ if in_generics == 0 => {
                    if ch.is_alphanumeric() {
                        result.push(ch.to_ascii_lowercase());
                        last_was_hyphen = false;
                    } else if (ch == ' ' || ch == '_' || ch == '-') && !last_was_hyphen {
                        result.push('-');
                        last_was_hyphen = true;
                    }
                },

                _ => {},
            }
        }

        if result.ends_with('-') {
            result.pop();
        }

        result
    }

    /// Unicode-aware slugification with full lowercase support.
    fn slugify_anchor_impl(name: &str) -> String {
        let mut result = String::with_capacity(name.len());
        let mut in_generics = 0;
        let mut last_was_hyphen = true;

        for ch in name.chars() {
            match ch {
                '`' => {},

                '<' => in_generics += 1,

                '>' => {
                    if in_generics > 0 {
                        in_generics -= 1;
                    }
                },

                _ if in_generics == 0 => {
                    if ch.is_alphanumeric() {
                        for lower_ch in ch.to_lowercase() {
                            result.push(lower_ch);
                        }

                        last_was_hyphen = false;
                    } else if (ch == ' ' || ch == '_' || ch == '-') && !last_was_hyphen {
                        result.push('-');

                        last_was_hyphen = true;
                    }
                },

                _ => {},
            }
        }

        if result.ends_with('-') {
            result.pop();
        }

        result
    }

    /// Check if an item kind generates a heading anchor in markdown.
    ///
    /// Only certain item types get `### \`Name\` headings in the generated output.
    /// Other items (methods, fields, variants) are rendered as bullet points
    /// without heading anchors.
    ///
    /// # Items with anchors
    ///
    /// - Struct, Enum, Trait, Function, Constant, `TypeAlias`, Macro, Module
    ///
    /// # Items without anchors
    ///
    /// - Methods (in impl blocks)
    /// - Struct fields
    /// - Enum variants
    /// - Associated types/constants
    /// - Trait methods
    #[must_use]
    pub const fn item_has_anchor(kind: ItemKind) -> bool {
        matches!(
            kind,
            ItemKind::Struct
                | ItemKind::Enum
                | ItemKind::Trait
                | ItemKind::Function
                | ItemKind::Constant
                | ItemKind::TypeAlias
                | ItemKind::Macro
                | ItemKind::Module
        )
    }
}

/// Registry mapping item IDs to their documentation file paths.
///
/// This is the central data structure for cross-reference resolution.
/// It's built once during generation and queried whenever we need to
/// create links between items.
#[derive(Debug, Default)]
pub struct LinkRegistry {
    /// Maps each item's ID to the markdown file path where it's documented.
    ///
    /// Paths are relative to the output directory root.
    /// Examples: `"index.md"`, `"span.md"`, `"span/index.md"`
    item_paths: HashMap<Id, String>,

    /// Maps each item's ID to its display name.
    ///
    /// Used to generate the link text (e.g., `[`name`](path)`).
    /// This is typically the item's identifier without the full path.
    item_names: HashMap<Id, String>,
}

impl LinkRegistry {
    /// Build a link registry by traversing all items in the crate.
    ///
    /// This function walks the module tree starting from the root and records
    /// the file path where each item will be documented. The paths depend on
    /// the output format (flat vs nested).
    ///
    /// # Arguments
    ///
    /// * `krate` - The parsed rustdoc crate containing all items
    /// * `flat_format` - If true, use flat paths (`mod.md`); if false, use nested (`mod/index.md`)
    /// * `include_private` - If true, include non-public items; if false, only public items
    ///
    /// # Returns
    ///
    /// A populated `LinkRegistry` ready for link creation.
    ///
    /// # Algorithm
    ///
    /// 1. Start at the crate root module
    /// 2. For each top-level module: register it and recursively process children
    /// 3. For structs/enums/traits at root level: register them to `index.md`
    /// 4. Other items (functions, constants) are registered within their module's file
    /// 5. Items are filtered by visibility unless `include_private` is true
    #[must_use]
    pub fn build(krate: &Crate, flat_format: bool, include_private: bool) -> Self {
        let mut registry = Self::default();

        // Get root module - if missing, return empty registry
        let Some(root) = krate.index.get(&krate.root) else {
            return registry;
        };

        // Process all items in the root module
        if let ItemEnum::Module(module) = &root.inner {
            for item_id in &module.items {
                if let Some(item) = krate.index.get(item_id) {
                    // Skip non-public items unless include_private is set
                    if !include_private && !matches!(item.visibility, Visibility::Public) {
                        continue;
                    }

                    match &item.inner {
                        // Modules get their own files and are processed recursively
                        ItemEnum::Module(_) => {
                            let module_name = item.name.as_deref().unwrap_or("unnamed");

                            // Determine the file path based on output format
                            let path = if flat_format {
                                format!("{module_name}.md")
                            } else {
                                format!("{module_name}/index.md")
                            };

                            // Recursively register this module and all its contents
                            registry.register_module_items(
                                krate,
                                *item_id,
                                item,
                                &path,
                                module_name,
                                flat_format,
                                include_private,
                            );
                        },

                        // Top-level items are in the root index.md
                        ItemEnum::Struct(_)
                        | ItemEnum::Enum(_)
                        | ItemEnum::Trait(_)
                        | ItemEnum::Function(_)
                        | ItemEnum::Constant { .. }
                        | ItemEnum::TypeAlias(_)
                        | ItemEnum::Macro(_) => {
                            let name = item.name.as_deref().unwrap_or("unnamed");
                            registry.item_paths.insert(*item_id, "index.md".to_string());
                            registry.item_names.insert(*item_id, name.to_string());
                        },

                        // Re-exports (pub use) are registered with their alias name
                        ItemEnum::Use(use_item) => {
                            if use_item.is_glob {
                                // Register items from glob re-export target
                                if let Some(target_id) = &use_item.id
                                    && let Some(target_module) = krate.index.get(target_id)
                                    && let ItemEnum::Module(module) = &target_module.inner
                                {
                                    for child_id in &module.items {
                                        if registry.item_paths.contains_key(child_id) {
                                            continue; // Already registered
                                        }

                                        if let Some(child) = krate.index.get(child_id) {
                                            if !include_private
                                                && !matches!(child.visibility, Visibility::Public)
                                            {
                                                continue;
                                            }

                                            let name = child.name.as_deref().unwrap_or("unnamed");
                                            registry
                                                .item_paths
                                                .insert(*child_id, "index.md".to_string());
                                            registry.item_names.insert(*child_id, name.to_string());
                                        }
                                    }
                                }
                            } else {
                                // Specific re-export - register both Use item AND target item
                                let name = &use_item.name;
                                registry.item_paths.insert(*item_id, "index.md".to_string());
                                registry.item_names.insert(*item_id, name.clone());

                                // Also register the target item's ID to this path
                                // This ensures links to the target resolve to the re-export location
                                if let Some(target_id) = &use_item.id
                                    && !registry.item_paths.contains_key(target_id)
                                {
                                    registry
                                        .item_paths
                                        .insert(*target_id, "index.md".to_string());
                                    registry.item_names.insert(*target_id, name.clone());
                                }
                            }
                        },

                        // Other items (primitives, etc.) don't need registration
                        _ => {},
                    }
                }
            }
        }

        registry
    }

    /// Recursively register all items within a module.
    ///
    /// This is called for each module in the crate to populate the registry
    /// with all items that can be linked to.
    ///
    /// # Arguments
    ///
    /// * `krate` - The full crate for looking up item details
    /// * `module_id` - ID of the module being registered
    /// * `module_item` - The module's Item data
    /// * `path` - File path where this module's docs will be written
    /// * `module_prefix` - Prefix for building child paths (e.g., "parent" or "`parent__child`")
    /// * `flat_format` - Whether to use flat naming convention
    /// * `include_private` - Whether to include non-public items
    #[expect(clippy::too_many_arguments, reason = "Complex method")]
    fn register_module_items(
        &mut self,
        krate: &Crate,
        module_id: Id,
        module_item: &rustdoc_types::Item,
        path: &str,
        module_prefix: &str,
        flat_format: bool,
        include_private: bool,
    ) {
        // First, register the module itself
        let module_name = module_item.name.as_deref().unwrap_or("unnamed");
        self.item_paths.insert(module_id, path.to_string());
        self.item_names.insert(module_id, module_name.to_string());

        // Then register all items within this module
        if let ItemEnum::Module(module) = &module_item.inner {
            for item_id in &module.items {
                if let Some(item) = krate.index.get(item_id) {
                    // Skip non-public items unless include_private is set
                    if !include_private && !matches!(item.visibility, Visibility::Public) {
                        continue;
                    }

                    let name = item.name.as_deref().unwrap_or("unnamed");

                    match &item.inner {
                        // Types and functions within this module are documented in its file
                        // They'll be linked with anchors (e.g., module.md#structname)
                        ItemEnum::Struct(_)
                        | ItemEnum::Enum(_)
                        | ItemEnum::Trait(_)
                        | ItemEnum::Function(_)
                        | ItemEnum::Constant { .. }
                        | ItemEnum::TypeAlias(_)
                        | ItemEnum::Macro(_) => {
                            self.item_paths.insert(*item_id, path.to_string());
                            self.item_names.insert(*item_id, name.to_string());
                        },

                        // Re-exports (pub use) are registered with their alias name
                        ItemEnum::Use(use_item) => {
                            if use_item.is_glob {
                                // Register items from glob re-export target
                                self.register_glob_items(krate, use_item, path, include_private);
                            } else {
                                // Specific re-export - register both Use item AND target item
                                self.item_paths.insert(*item_id, path.to_string());
                                self.item_names.insert(*item_id, use_item.name.clone());

                                // Also register the target item's ID to this path
                                // This ensures links to the target resolve to the re-export location
                                if let Some(target_id) = &use_item.id
                                    && !self.item_paths.contains_key(target_id)
                                {
                                    self.item_paths.insert(*target_id, path.to_string());
                                    self.item_names.insert(*target_id, use_item.name.clone());
                                }
                            }
                        },

                        // Nested modules get their own files - recurse into them
                        ItemEnum::Module(_) => {
                            // Build the file path for this submodule
                            let sub_path = if flat_format {
                                // Flat: parent__child__grandchild.md
                                format!("{module_prefix}__{name}.md")
                            } else {
                                // Nested: parent/child/grandchild/index.md
                                format!("{module_prefix}/{name}/index.md")
                            };

                            // Build the prefix for any further nesting
                            let sub_prefix = if flat_format {
                                format!("{module_prefix}__{name}")
                            } else {
                                format!("{module_prefix}/{name}")
                            };

                            // Recurse into the submodule
                            self.register_module_items(
                                krate,
                                *item_id,
                                item,
                                &sub_path,
                                &sub_prefix,
                                flat_format,
                                include_private,
                            );
                        },

                        // Other item types (impl blocks, etc.) don't need registration
                        _ => {},
                    }
                }
            }
        }
    }

    /// Register items from a glob re-export target module.
    fn register_glob_items(
        &mut self,
        krate: &Crate,
        use_item: &rustdoc_types::Use,
        path: &str,
        include_private: bool,
    ) {
        let Some(target_id) = &use_item.id else {
            return;
        };
        let Some(target_module) = krate.index.get(target_id) else {
            return;
        };
        let ItemEnum::Module(module) = &target_module.inner else {
            return;
        };

        for child_id in &module.items {
            // Skip if already registered
            if self.item_paths.contains_key(child_id) {
                continue;
            }

            let Some(child) = krate.index.get(child_id) else {
                continue;
            };

            // Visibility filter
            if !include_private && !matches!(child.visibility, Visibility::Public) {
                continue;
            }

            let name = child.name.as_deref().unwrap_or("unnamed");
            self.item_paths.insert(*child_id, path.to_string());
            self.item_names.insert(*child_id, name.to_string());
        }
    }

    /// Get the file path where an item is documented.
    ///
    /// # Arguments
    ///
    /// * `id` - The item's unique ID from rustdoc JSON
    ///
    /// # Returns
    ///
    /// The relative file path (e.g., `"span.md"` or `"span/index.md"`),
    /// or `None` if the item isn't registered.
    #[must_use]
    pub fn get_path(&self, id: Id) -> Option<&String> {
        self.item_paths.get(&id)
    }

    /// Get the display name for an item.
    ///
    /// # Arguments
    ///
    /// * `id` - The item's unique ID from rustdoc JSON
    ///
    /// # Returns
    ///
    /// The item's name for display in links (e.g., `"Span"`),
    /// or `None` if the item isn't registered.
    #[must_use]
    pub fn get_name(&self, id: Id) -> Option<&String> {
        self.item_names.get(&id)
    }

    /// Create a markdown link to an item from a given source file.
    ///
    /// This is the main method used during markdown generation to create
    /// clickable links between documented items.
    ///
    /// # Arguments
    ///
    /// * `id` - The target item's ID
    /// * `from_path` - The source file creating the link (e.g., `"index.md"`)
    ///
    /// # Returns
    ///
    /// A formatted markdown link like `[``ItemName``](path/to/file.md)`,
    /// or `None` if the target item isn't registered.
    ///
    /// # Link Types
    ///
    /// - **Same file**: Returns an anchor link (`#itemname`)
    /// - **Different file**: Returns a relative path (`../other/file.md`)
    ///
    /// # Example
    ///
    /// ```ignore
    /// // From index.md linking to span.md
    /// registry.create_link(&span_id, "index.md")
    /// // Returns: Some("[`Span`](span.md)")
    ///
    /// // From span/index.md linking to index.md
    /// registry.create_link(&root_id, "span/index.md")
    /// // Returns: Some("[`crate`](../index.md)")
    /// ```
    #[must_use]
    pub fn create_link(&self, id: Id, from_path: &str) -> Option<String> {
        let target_path = self.item_paths.get(&id)?;
        let name = self.item_names.get(&id)?;

        // Calculate relative path from source to target file
        let relative_path = Self::compute_relative_path(from_path, target_path);

        // Determine the link destination:
        // - Same file: use an anchor (#name)
        // - Different file: use the relative path with anchor
        let link = if target_path == from_path {
            // Same file: use anchor only
            format!("#{}", AnchorUtils::slugify_anchor(name))
        } else {
            // Different file: append anchor to path
            format!("{}#{}", relative_path, AnchorUtils::slugify_anchor(name))
        };

        // Format as markdown link with backticks around the name
        Some(format!("[`{name}`]({link})"))
    }

    /// Compute the relative path from one file to another.
    ///
    /// This function calculates the relative path needed to navigate from
    /// one markdown file to another within the generated documentation.
    /// Uses `pathdiff` for robust cross-platform path calculation.
    ///
    /// # Arguments
    ///
    /// * `from` - The source file path (e.g., `"span/index.md"`)
    /// * `to` - The target file path (e.g., `"field/index.md"`)
    ///
    /// # Returns
    ///
    /// A relative path string (e.g., `"../field/index.md"`)
    ///
    /// # Examples
    ///
    /// - Same directory: `"index.md"` → `"span.md"` = `"span.md"`
    /// - Into subdirectory: `"index.md"` → `"span/index.md"` = `"span/index.md"`
    /// - Up to parent: `"span/index.md"` → `"index.md"` = `"../index.md"`
    /// - Sibling directory: `"span/index.md"` → `"field/index.md"` = `"../field/index.md"`
    #[must_use]
    pub fn compute_relative_path(from: &str, to: &str) -> String {
        // Same file - no path needed
        if from == to {
            return String::new();
        }

        // Get the directory containing 'from' (not the file itself)
        let from_dir = Path::new(from).parent().unwrap_or_else(|| Path::new(""));

        // Use pathdiff for robust relative path calculation
        pathdiff::diff_paths(to, from_dir)
            .map_or_else(|| to.to_string(), |p| p.to_string_lossy().into_owned())
    }
}

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

    /// Test: Files in the same directory need no path prefix.
    #[test]
    fn test_relative_path_same_dir() {
        assert_eq!(
            LinkRegistry::compute_relative_path("index.md", "span.md"),
            "span.md"
        );
    }

    /// Test: Linking from root into a subdirectory.
    #[test]
    fn test_relative_path_child_dir() {
        assert_eq!(
            LinkRegistry::compute_relative_path("index.md", "span/index.md"),
            "span/index.md"
        );
    }

    /// Test: Linking from subdirectory back to root.
    #[test]
    fn test_relative_path_parent_dir() {
        assert_eq!(
            LinkRegistry::compute_relative_path("span/index.md", "index.md"),
            "../index.md"
        );
    }

    /// Test: Linking between sibling directories.
    #[test]
    fn test_relative_path_sibling_dir() {
        assert_eq!(
            LinkRegistry::compute_relative_path("span/index.md", "field/index.md"),
            "../field/index.md"
        );
    }

    /// Test: Simple lowercase conversion.
    #[test]
    fn test_slugify_simple() {
        assert_eq!(AnchorUtils::slugify_anchor("HashMap"), "hashmap");
        assert_eq!(AnchorUtils::slugify_anchor("Span"), "span");
    }

    /// Test: Generics are stripped.
    #[test]
    fn test_slugify_generics() {
        assert_eq!(AnchorUtils::slugify_anchor("HashMap<K, V>"), "hashmap");
        assert_eq!(AnchorUtils::slugify_anchor("Vec<T>"), "vec");
        assert_eq!(AnchorUtils::slugify_anchor("Into<T>"), "into");
        assert_eq!(AnchorUtils::slugify_anchor("Result<T, E>"), "result");
    }

    /// Test: Nested generics are handled.
    #[test]
    fn test_slugify_nested_generics() {
        assert_eq!(AnchorUtils::slugify_anchor("Option<Vec<T>>"), "option");
        assert_eq!(AnchorUtils::slugify_anchor("Box<dyn Fn()>"), "box");
    }

    /// Test: Underscores become hyphens.
    #[test]
    fn test_slugify_underscores() {
        assert_eq!(AnchorUtils::slugify_anchor("my_function"), "my-function");
        assert_eq!(
            AnchorUtils::slugify_anchor("some_long_name"),
            "some-long-name"
        );
    }

    /// Test: Spaces become hyphens.
    #[test]
    fn test_slugify_spaces() {
        assert_eq!(AnchorUtils::slugify_anchor("Some Name"), "some-name");
    }

    /// Test: Backticks are stripped.
    #[test]
    fn test_slugify_backticks() {
        assert_eq!(AnchorUtils::slugify_anchor("`HashMap`"), "hashmap");
        assert_eq!(AnchorUtils::slugify_anchor("`Vec<T>`"), "vec");
    }

    /// Test: Punctuation is stripped.
    #[test]
    fn test_slugify_punctuation() {
        assert_eq!(AnchorUtils::slugify_anchor("item!"), "item");
        assert_eq!(AnchorUtils::slugify_anchor("print!"), "print");
    }

    /// Test: Consecutive hyphens are collapsed.
    #[test]
    fn test_slugify_consecutive_hyphens() {
        assert_eq!(AnchorUtils::slugify_anchor("a__b"), "a-b");
        assert_eq!(AnchorUtils::slugify_anchor("a - b"), "a-b");
    }

    /// Test: Unicode characters are preserved and lowercased.
    #[test]
    fn test_slugify_unicode() {
        // German
        assert_eq!(AnchorUtils::slugify_anchor("Größe"), "größe");
        // French
        assert_eq!(AnchorUtils::slugify_anchor("café"), "café");
        // Mixed unicode with underscores
        assert_eq!(AnchorUtils::slugify_anchor("naïve_string"), "naïve-string");
    }

    /// Test: Unicode normalization (composed vs decomposed).
    #[test]
    fn test_slugify_unicode_normalization() {
        // "é" can be represented as:
        // - U+00E9 (LATIN SMALL LETTER E WITH ACUTE) - composed
        // - U+0065 U+0301 (e + COMBINING ACUTE ACCENT) - decomposed
        let composed = "caf\u{00E9}"; // café with composed é
        let decomposed = "cafe\u{0301}"; // café with decomposed é

        // Both should produce the same result after NFC normalization
        assert_eq!(
            AnchorUtils::slugify_anchor(composed),
            AnchorUtils::slugify_anchor(decomposed)
        );
        assert_eq!(AnchorUtils::slugify_anchor(composed), "café");
    }

    /// Test: Unicode uppercase conversion (beyond ASCII).
    #[test]
    fn test_slugify_unicode_uppercase() {
        // German sharp S: ẞ (U+1E9E) lowercases to ß (U+00DF)
        assert_eq!(AnchorUtils::slugify_anchor("GROẞE"), "große");

        // Greek
        assert_eq!(AnchorUtils::slugify_anchor("ΩMEGA"), "ωmega");
    }

    // =========================================================================
    // method_anchor tests
    // =========================================================================

    /// Test: Basic method anchor generation.
    #[test]
    fn test_method_anchor_basic() {
        assert_eq!(
            AnchorUtils::method_anchor("Parser", "parse"),
            "parser-parse"
        );
        assert_eq!(AnchorUtils::method_anchor("HashMap", "new"), "hashmap-new");
        assert_eq!(AnchorUtils::method_anchor("Vec", "push"), "vec-push");
    }

    /// Test: Method anchor with generics in type name.
    #[test]
    fn test_method_anchor_with_generics() {
        assert_eq!(AnchorUtils::method_anchor("Vec<T>", "push"), "vec-push");
        assert_eq!(
            AnchorUtils::method_anchor("HashMap<K, V>", "insert"),
            "hashmap-insert"
        );
        assert_eq!(
            AnchorUtils::method_anchor("Option<T>", "unwrap"),
            "option-unwrap"
        );
    }

    /// Test: Method anchor with underscores.
    #[test]
    fn test_method_anchor_underscores() {
        assert_eq!(
            AnchorUtils::method_anchor("MyType", "my_method"),
            "mytype-my-method"
        );
        assert_eq!(
            AnchorUtils::method_anchor("some_type", "do_thing"),
            "some-type-do-thing"
        );
    }

    /// Test: Method anchor preserves case normalization.
    #[test]
    fn test_method_anchor_case() {
        assert_eq!(
            AnchorUtils::method_anchor("MyStruct", "DoSomething"),
            "mystruct-dosomething"
        );
    }
}