kinetic_doc_types/

lib.rs

//! Shared metadata types for Kinetic's documentation generation pipeline.
//!
//! These types are referenced by:
//! - The `kinetic-doc-derive` proc-macro (generated code uses these types)
//! - The `doc-gen` tool (reads/writes `ComponentMetadata` as JSON)
//! - Any crate that derives `ComponentDoc`

use serde::{Deserialize, Serialize};

/// Metadata for a single component (source, transform, or sink).
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct ComponentMetadata {
    pub component_type: String,
    pub name: String,
    pub status: String,
    pub description: String,
    pub fields: Vec<FieldMetadata>,
    /// Component-specific metrics (beyond standard component metrics).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub metrics: Vec<MetricMetadata>,
    /// Output schema fields (for sources).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub outputs: Vec<OutputFieldMetadata>,
    /// Environment variables this component reads.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub env_vars: Vec<EnvVarMetadata>,
    /// Required IAM permissions (for AWS/cloud components).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub permissions: Vec<PermissionMetadata>,
}

/// Metadata for a single configuration field.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct FieldMetadata {
    pub name: String,
    pub rust_type: String,
    pub user_type: String,
    pub required: bool,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub default: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub example: Option<String>,
    pub secret: bool,
    pub description: String,
    /// Nested children for flattened structs or enum variants.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub children: Vec<FieldMetadata>,
    /// Category/group for sub-section rendering.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub category: Option<String>,
    /// Enum values if this field is an enum type.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub enum_values: Vec<EnumValueMetadata>,
    /// For polymorphic enum fields (like SamplingMode), the variant schemas.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub variants: Vec<VariantMetadata>,
    /// Cross-reference link to another component's documentation.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub reference: Option<String>,
    /// Type of reference for categorization (e.g., "codec", "component", "transform").
    #[serde(skip_serializing_if = "Option::is_none")]
    pub reference_type: Option<String>,
}

/// Metadata for an enum variant.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct EnumValueMetadata {
    /// The variant name (snake_case for serde).
    pub name: String,
    pub description: String,
}

/// Metadata for a polymorphic enum variant (e.g., Random, Systematic in SamplingMode).
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct VariantMetadata {
    /// Variant name (snake_case).
    pub name: String,
    pub description: String,
    /// Fields specific to this variant.
    pub fields: Vec<FieldMetadata>,
    /// Example YAML snippet for this variant.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub example: Option<String>,
}

/// Metadata for a component-specific metric.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct MetricMetadata {
    pub name: String,
    pub metric_type: String, // "counter", "histogram", "gauge"
    pub description: String,
    /// Dimension/tag names for this metric.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub tags: Vec<String>,
}

/// Metadata for an output field (sources only).
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct OutputFieldMetadata {
    pub name: String,
    pub field_type: String,
    pub description: String,
}

/// Metadata for an environment variable.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct EnvVarMetadata {
    pub name: String,
    pub description: String,
}

/// Metadata for a required IAM permission.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct PermissionMetadata {
    pub action: String,
    pub service: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub notes: Option<String>,
}

/// Trait for types that can provide metadata about their fields.
pub trait HasFieldsMetadata {
    /// Returns a list of metadata for all fields in the struct.
    fn fields_metadata() -> Vec<FieldMetadata>;
}

/// Implement `HasFieldsMetadata` for `Option<T>` to support flattening optional structs.
impl<T: HasFieldsMetadata> HasFieldsMetadata for Option<T> {
    fn fields_metadata() -> Vec<FieldMetadata> {
        T::fields_metadata()
    }
}

/// Implement `HasFieldsMetadata` for `Box<T>` to support flattening boxed structs.
impl<T: HasFieldsMetadata> HasFieldsMetadata for Box<T> {
    fn fields_metadata() -> Vec<FieldMetadata> {
        T::fields_metadata()
    }
}

/// Marker trait for enums to provide metadata about their variants.
pub trait HasEnumMetadata {
    /// Returns a list of metadata for all variants in the enum.
    fn enum_metadata() -> Vec<String>;
}

/// Trait for polymorphic enums to provide variant schema metadata.
pub trait HasVariantMetadata {
    /// Returns a list of variant metadata including field schemas.
    fn variant_metadata() -> Vec<VariantMetadata>;
}

/// Collection of all component metadata for the intermediate representation.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct ComponentRegistry {
    pub components: Vec<ComponentMetadata>,
}

impl ComponentRegistry {
    /// Sorts components by type then name for deterministic output.
    pub fn sort(&mut self) {
        self.components
            .sort_by(|a, b| (&a.component_type, &a.name).cmp(&(&b.component_type, &b.name)));
    }

    /// Serializes the registry to pretty-printed JSON.
    ///
    /// # Errors
    ///
    /// Returns an error if serialization fails.
    pub fn to_json(&self) -> serde_json::Result<String> {
        serde_json::to_string_pretty(self)
    }

    /// Deserializes a registry from JSON.
    ///
    /// # Errors
    ///
    /// Returns an error if deserialization fails.
    pub fn from_json(json: &str) -> serde_json::Result<Self> {
        serde_json::from_str(json)
    }
}

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

    #[test]
    fn test_roundtrip_json() {
        let registry = ComponentRegistry {
            components: vec![ComponentMetadata {
                component_type: "sink".to_string(),
                name: "kafka".to_string(),
                status: "stable".to_string(),
                description: "Produces events to Kafka.".to_string(),
                fields: vec![FieldMetadata {
                    name: "topic".to_string(),
                    rust_type: "String".to_string(),
                    user_type: "string".to_string(),
                    required: true,
                    default: None,
                    example: Some("events".to_string()),
                    secret: false,
                    description: "The Kafka topic.".to_string(),
                    children: vec![],
                    category: None,
                    enum_values: vec![],
                    variants: vec![],
                    reference: None,
                    reference_type: None,
                }],
                metrics: vec![],
                outputs: vec![],
                env_vars: vec![],
                permissions: vec![],
            }],
        };
        let json = registry.to_json().unwrap();
        let roundtripped = ComponentRegistry::from_json(&json).unwrap();
        assert_eq!(registry.components, roundtripped.components);
    }

    #[test]
    fn test_sort_deterministic() {
        let mut registry = ComponentRegistry {
            components: vec![
                ComponentMetadata {
                    component_type: "transform".to_string(),
                    name: "filter".to_string(),
                    status: "stable".to_string(),
                    description: String::new(),
                    fields: vec![],
                    metrics: vec![],
                    outputs: vec![],
                    env_vars: vec![],
                    permissions: vec![],
                },
                ComponentMetadata {
                    component_type: "source".to_string(),
                    name: "kafka".to_string(),
                    status: "stable".to_string(),
                    description: String::new(),
                    fields: vec![],
                    metrics: vec![],
                    outputs: vec![],
                    env_vars: vec![],
                    permissions: vec![],
                },
                ComponentMetadata {
                    component_type: "sink".to_string(),
                    name: "s3".to_string(),
                    status: "stable".to_string(),
                    description: String::new(),
                    fields: vec![],
                    metrics: vec![],
                    outputs: vec![],
                    env_vars: vec![],
                    permissions: vec![],
                },
            ],
        };
        registry.sort();
        let types: Vec<&str> = registry
            .components
            .iter()
            .map(|c| c.component_type.as_str())
            .collect();
        assert_eq!(types, vec!["sink", "source", "transform"]);
    }
}