gen-bsky 0.1.21

#[cfg_attr(doc, aquamarine::aquamarine)]
/// # Taxonomies Module Documentation
///
/// ## Overview
///
/// The `Taxonomies` struct is responsible for representing taxonomical metadata
/// from blog post front matter, particularly the "tags" field. It deserializes
/// TOML front matter data from Markdown files and provides access to both raw
/// tags and formatted hashtags suitable for social media platforms.
///
/// ## Struct Purpose
///
/// `Taxonomies` serves as part of the front matter deserialization pipeline,
/// where it:
/// - Extracts tagged content from TOML metadata in blog posts
/// - Provides access to raw tag strings via the `tags()` method
/// - Converts raw tags into properly formatted hashtags via the `hashtags()`
///   method
///
/// ## Module Architecture
///
/// ```mermaid
/// graph TD
///     A["Markdown File"] --> B["TOML Front Matter"]
///     B --> C["FrontMatter Struct"]
///     C --> D["Taxonomies Struct"]
///     D --> E["Raw Tags"]
///     D --> F["Formatted Hashtags"]
///     F --> G["Social Media Posts"]
/// ```
///
/// ## Integration With Other Modules
///
/// The `Taxonomies` struct integrates with:
///
/// - **front_matter.rs**: Container module that includes taxonomies as an
///   optional field
/// - **tags.rs**: Provides hashtag formatting functionality used by the
///   `hashtags()` method
/// - **serde**: Used for TOML deserialization via derive macros
///
/// ## Example TOML Front Matter
///
/// ```toml
/// +++
/// title = "My Blog Post"
/// description = "A detailed description"
///
/// [taxonomies]
/// tags = ["rust", "programming", "web development"]
/// +++
/// ```
///
/// ## Typical Use Cases
///
/// - Extracting taxonomical metadata from blog posts
/// - Generating hashtags for social media posts from blog tags
/// - Supporting categorization and filtering of blog content
///
/// ## Type Hierarchy
///
/// ```text
/// FrontMatter
///  └── taxonomies: Option<Taxonomies>
///       └── tags: Vec<String>
/// ```
use serde::{Deserialize, Serialize};

use crate::draft::blog_post::front_matter::tags;

/// # Taxonomies Structure
///
/// A structure representing taxonomical metadata for blog posts, particularly
/// tags.
///
/// ## Fields
///
/// - `tags`: A vector of strings representing tag values from the front matter
///
/// ## Derivations
///
/// - `Default`: Creates an empty Taxonomies struct with no tags
/// - `Debug`: Enables debug formatting
/// - `Clone`: Allows the struct to be cloned
/// - `Serialize`/`Deserialize`: Enables TOML serialization/deserialization via
///   serde
///
/// ## Memory Characteristics
///
/// - Memory usage scales linearly with the number and size of tags
/// - No heap memory is used when tags vector is empty
/// - The size of a `Taxonomies` instance with an empty tags vector is minimal
///   (typically just the size of a Vec pointer, length, and capacity)
///
/// ## Visibility
///
/// The struct is marked `pub(crate)` which means it's visible within the crate
/// but not exposed as part of the public API.
#[derive(Default, Debug, Clone, Serialize, Deserialize)]
pub(crate) struct Taxonomies {
    /// The vector of tag strings extracted from front matter
    ///
    /// This field stores the raw tag values as they appear in the TOML front
    /// matter. Tags are typically short strings that categorize the content
    /// of the blog post.
    #[allow(dead_code)]
    tags: Vec<String>,
}

/// ## Test-only Constructor Method
///
/// This implementation is only available in test contexts and provides
/// a convenience constructor for creating `Taxonomies` instances directly.
#[cfg(test)]
impl Taxonomies {
    /// Creates a new Taxonomies instance with the specified tags.
    ///
    /// This constructor is only available in test contexts and simplifies
    /// the creation of test instances without having to deserialize from TOML.
    ///
    /// ## Parameters
    ///
    /// - `tags`: A vector of strings to use as tags
    ///
    /// ## Returns
    ///
    /// A new `Taxonomies` instance containing the provided tags
    ///
    /// ## Examples
    ///
    /// ```rust,ignore
    /// let tags = vec!["rust".to_string(), "programming".to_string()];
    /// let taxonomies = Taxonomies::new(tags);
    /// assert_eq!(taxonomies.tags(), vec!["rust", "programming"]);
    /// ```
    pub(crate) fn new(tags: Vec<String>) -> Self {
        Taxonomies { tags }
    }
}

/// ## Main Implementation Block
///
/// Contains methods available in all contexts for accessing tag data
/// and converting to hashtags.
impl Taxonomies {
    /// Returns a clone of the tags vector.
    ///
    /// This method provides access to the raw tag data stored in the
    /// `Taxonomies` struct. Since it returns a clone, the caller gets
    /// ownership of the returned vector without affecting the original
    /// data.
    ///
    /// ## Returns
    ///
    /// A `Vec<String>` containing clones of all tags
    ///
    /// ## Performance
    ///
    /// - **Time Complexity**: O(n) where n is the number of tags
    /// - **Space Complexity**: O(n) for the cloned vector
    /// - Creates a new allocation for the returned vector
    /// - Each string in the vector is cloned, requiring additional allocations
    ///
    /// ## Examples
    ///
    /// ```rust,ignore
    /// let taxonomies = Taxonomies::new(vec!["rust".to_string(), "programming".to_string()]);
    /// let tags = taxonomies.tags();
    /// assert_eq!(tags, vec!["rust", "programming"]);
    /// ```
    ///
    /// ## Edge Cases
    ///
    /// - Returns an empty vector if no tags are present
    /// - No special handling for empty or invalid tags - returns them as-is
    pub(crate) fn tags(&self) -> Vec<String> {
        self.tags.clone()
    }

    /// Converts tags to properly formatted hashtags.
    ///
    /// This method transforms the raw tags into social media-friendly hashtags
    /// by delegating to the `tags::hashtags` function. Each tag is processed
    /// to:
    /// 1. Remove any existing hashtag prefix
    /// 2. Capitalize each word
    /// 3. Remove spaces between words
    /// 4. Add a '#' prefix
    ///
    /// ## Returns
    ///
    /// A `Vec<String>` containing formatted hashtags
    ///
    /// ## Integration with tags module
    ///
    /// This method relies on the `tags::hashtags` function to handle the actual
    /// formatting logic. See the documentation for that function for details on
    /// hashtag formatting rules.
    ///
    /// ## Performance
    ///
    /// - **Time Complexity**: O(n × m) where:
    ///   - n = number of tags
    ///   - m = average tag length
    /// - **Space Complexity**: O(n × k) where k is the average formatted
    ///   hashtag length
    /// - Clones the entire tags vector before processing
    /// - Each hashtag requires a new String allocation
    ///
    /// ## Examples
    ///
    /// ```rust,ignore
    /// let taxonomies = Taxonomies::new(vec![
    ///     "rust".to_string(),
    ///     "web development".to_string()
    /// ]);
    /// let hashtags = taxonomies.hashtags();
    /// assert_eq!(hashtags, vec!["#Rust", "#WebDevelopment"]);
    /// ```
    ///
    /// ## Edge Cases
    ///
    /// - Returns an empty vector if no tags are present
    /// - Handles empty strings, whitespace-only strings, and strings with
    ///   existing hashtags
    /// - Unicode characters are properly maintained and capitalized
    /// - See `tags::hashtags` documentation for additional edge case handling
    pub(crate) fn hashtags(&self) -> Vec<String> {
        tags::hashtags(self.tags.clone())
    }
}

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

    /// Helper macro for testing hashtag conversions
    macro_rules! test_taxonomies_hashtags {
        ($test_name:ident, $input:expr, $expected:expr) => {
            #[test]
            fn $test_name() {
                let input: Vec<String> = $input.iter().map(|s| s.to_string()).collect();
                let taxonomies = Taxonomies::new(input);
                let result = taxonomies.hashtags();
                let expected: Vec<String> = $expected.iter().map(|s| s.to_string()).collect();
                assert_eq!(
                    result, expected,
                    "taxonomies.hashtags() with {:?} should return {:?}, got {:?}",
                    $input, expected, result
                );
            }
        };
    }

    /// Helper macro for testing tag access
    macro_rules! test_taxonomies_tags {
        ($test_name:ident, $input:expr) => {
            #[test]
            fn $test_name() {
                let input: Vec<String> = $input.iter().map(|s| s.to_string()).collect();
                let taxonomies = Taxonomies::new(input.clone());
                let result = taxonomies.tags();
                assert_eq!(
                    result, input,
                    "taxonomies.tags() should return the same tags that were input"
                );
            }
        };
    }

    // TOML deserialization tests
    #[test]
    fn test_deserialize_taxonomies_basic() {
        let toml_str = r#"tags = ["rust", "programming"]"#;
        let taxonomies: Taxonomies = toml::from_str(toml_str).unwrap();
        assert_eq!(taxonomies.tags, vec!["rust", "programming"]);
    }

    #[test]
    fn test_deserialize_taxonomies_empty() {
        let toml_str = r#"tags = []"#;
        let taxonomies: Taxonomies = toml::from_str(toml_str).unwrap();
        assert_eq!(taxonomies.tags, Vec::<String>::new());
    }

    #[test]
    fn test_deserialize_taxonomies_with_spaces() {
        let toml_str = r#"tags = ["rust lang", "web development"]"#;
        let taxonomies: Taxonomies = toml::from_str(toml_str).unwrap();
        assert_eq!(taxonomies.tags, vec!["rust lang", "web development"]);
    }

    #[test]
    fn test_deserialize_taxonomies_with_unicode() {
        let toml_str = r#"tags = ["café", "москва", "日本"]"#;
        let taxonomies: Taxonomies = toml::from_str(toml_str).unwrap();
        assert_eq!(taxonomies.tags, vec!["café", "москва", "日本"]);
    }

    #[test]
    fn test_deserialize_taxonomies_with_special_chars() {
        let toml_str = r#"tags = ["c++", "node.js", "design-patterns"]"#;
        let taxonomies: Taxonomies = toml::from_str(toml_str).unwrap();
        assert_eq!(taxonomies.tags, vec!["c++", "node.js", "design-patterns"]);
    }

    // Constructor tests
    #[test]
    fn test_new_constructor() {
        let tags = vec!["rust".to_string(), "programming".to_string()];
        let taxonomies = Taxonomies::new(tags.clone());
        assert_eq!(taxonomies.tags, tags);
    }

    #[test]
    fn test_default_constructor() {
        let taxonomies = Taxonomies::default();
        assert_eq!(taxonomies.tags, Vec::<String>::new());
    }

    // Tags method tests
    test_taxonomies_tags!(test_tags_basic, &["rust", "programming"]);

    #[test]
    fn test_tags_empty() {
        let taxonomies = Taxonomies::new(vec![]);
        let result = taxonomies.tags();
        assert_eq!(result, Vec::<String>::new());
    }

    test_taxonomies_tags!(test_tags_with_spaces, &["rust lang", "web development"]);
    test_taxonomies_tags!(test_tags_with_unicode, &["café", "москва", "日本"]);
    test_taxonomies_tags!(
        test_tags_with_special_chars,
        &["c++", "node.js", "design-patterns"]
    );

    // Hashtags method tests - basic functionality
    test_taxonomies_hashtags!(
        test_hashtags_basic,
        &["rust", "programming"],
        &["#Rust", "#Programming"]
    );

    #[test]
    fn test_hashtags_empty() {
        let taxonomies = Taxonomies::new(vec![]);
        let result = taxonomies.hashtags();
        assert_eq!(result, Vec::<String>::new());
    }

    test_taxonomies_hashtags!(
        test_hashtags_with_spaces,
        &["rust lang", "web development"],
        &["#RustLang", "#WebDevelopment"]
    );
    test_taxonomies_hashtags!(
        test_hashtags_unicode,
        &["café", "москва", "日本"],
        &["#Café", "#Москва", "#日本"]
    );
    test_taxonomies_hashtags!(
        test_hashtags_special_chars,
        &["c++", "node.js", "design-patterns"],
        &["#C++", "#Node.js", "#Design-patterns"]
    );

    // Hashtags method tests - edge cases
    test_taxonomies_hashtags!(
        test_hashtags_existing_hashtags,
        &["#rust", "#programming"],
        &["#Rust", "#Programming"]
    );
    test_taxonomies_hashtags!(
        test_hashtags_mixed,
        &["#rust", "programming", "web development"],
        &["#Rust", "#Programming", "#WebDevelopment"]
    );
    test_taxonomies_hashtags!(
        test_hashtags_whitespace,
        &["  rust  ", " programming "],
        &["#Rust", "#Programming"]
    );
    test_taxonomies_hashtags!(
        test_hashtags_empty_strings,
        &["", "rust", ""],
        &["#", "#Rust", "#"]
    );

    // Performance and memory tests
    #[test]
    fn test_large_tag_vector() {
        // Create a large vector of tags
        let tags: Vec<String> = (0..1000).map(|i| format!("tag{i}")).collect();
        let taxonomies = Taxonomies::new(tags);

        // Test tags() method with large vector
        let result_tags = taxonomies.tags();
        assert_eq!(result_tags.len(), 1000);
        assert_eq!(result_tags[0], "tag0");
        assert_eq!(result_tags[999], "tag999");

        // Test hashtags() method with large vector
        let result_hashtags = taxonomies.hashtags();
        assert_eq!(result_hashtags.len(), 1000);
        assert_eq!(result_hashtags[0], "#Tag0");
        assert_eq!(result_hashtags[999], "#Tag999");
    }

    #[test]
    fn test_repeated_tag_access() {
        let taxonomies = Taxonomies::new(vec!["rust".to_string(), "programming".to_string()]);

        // Multiple calls to tags() should yield identical results
        let tags1 = taxonomies.tags();
        let tags2 = taxonomies.tags();
        let tags3 = taxonomies.tags();

        assert_eq!(tags1, tags2);
        assert_eq!(tags2, tags3);
        assert_eq!(tags1, vec!["rust", "programming"]);

        // Multiple calls to hashtags() should yield identical results
        let hashtags1 = taxonomies.hashtags();
        let hashtags2 = taxonomies.hashtags();
        let hashtags3 = taxonomies.hashtags();

        assert_eq!(hashtags1, hashtags2);
        assert_eq!(hashtags2, hashtags3);
        assert_eq!(hashtags1, vec!["#Rust", "#Programming"]);
    }

    #[test]
    fn test_ownership_semantics() {
        let original_tags = vec!["rust".to_string(), "programming".to_string()];
        let taxonomies = Taxonomies::new(original_tags.clone());

        // Calling tags() should not change the original struct
        let returned_tags = taxonomies.tags();
        assert_eq!(returned_tags, original_tags);

        // Modifying the returned tags should not affect the original struct
        let mut modified_tags = taxonomies.tags();
        modified_tags.push("modified".to_string());
        assert_eq!(taxonomies.tags(), original_tags);
        assert_ne!(taxonomies.tags(), modified_tags);
    }

    // Integration with front_matter module
    #[test]
    fn test_front_matter_integration() {
        let toml_str = r#"
            title = "Test Post"
            description = "A test post"
            
            [taxonomies]
            tags = ["rust", "programming", "web development"]
        "#;

        // Use local struct to simulate FrontMatter without circular dependency
        #[derive(Deserialize)]
        struct TestFrontMatter {
            taxonomies: Option<Taxonomies>,
        }

        let front_matter: TestFrontMatter = toml::from_str(toml_str).unwrap();
        assert!(front_matter.taxonomies.is_some());

        let taxonomies = front_matter.taxonomies.unwrap();
        assert_eq!(
            taxonomies.tags(),
            vec!["rust", "programming", "web development"]
        );
        assert_eq!(
            taxonomies.hashtags(),
            vec!["#Rust", "#Programming", "#WebDevelopment"]
        );
    }

    // TOML serialization tests
    #[test]
    fn test_serialize_taxonomies() {
        let taxonomies = Taxonomies::new(vec!["rust".to_string(), "programming".to_string()]);
        let serialized = toml::to_string(&taxonomies).unwrap();
        assert_eq!(serialized, "tags = [\"rust\", \"programming\"]\n");
    }

    #[test]
    fn test_serialize_empty_taxonomies() {
        let taxonomies = Taxonomies::default();
        let serialized = toml::to_string(&taxonomies).unwrap();
        assert_eq!(serialized, "tags = []\n");
    }

    // Roundtrip serialization/deserialization
    #[test]
    fn test_taxonomies_roundtrip() {
        let original = Taxonomies::new(vec!["rust".to_string(), "programming".to_string()]);
        let serialized = toml::to_string(&original).unwrap();
        let deserialized: Taxonomies = toml::from_str(&serialized).unwrap();

        assert_eq!(original.tags(), deserialized.tags());
        assert_eq!(original.hashtags(), deserialized.hashtags());
    }
}