@typokit/plugin-axum 0.2.1

package/src/rust_codegen/structs.rs

@@ -0,0 +1,1363 @@
+use std::collections::{HashMap, BTreeMap};
+use typokit_transform_native::type_extractor::{TypeMetadata, PropertyMetadata};
+use super::GeneratedOutput;
+
+/// Generate Rust struct files from a SchemaTypeMap.
+///
+/// Produces one `.typokit/models/{entity}.rs` per type, a
+/// `.typokit/models/common.rs` with shared framework types, and a
+/// `.typokit/models/mod.rs` that re-exports all entity modules.
+pub fn generate_structs(type_map: &HashMap<String, TypeMetadata>) -> Vec<GeneratedOutput> {
+    let mut outputs = Vec::new();
+    let mut module_names: Vec<String> = Vec::new();
+
+    // Collect utility types discovered during struct generation
+    let mut resolved_utility_types: BTreeMap<String, TypeMetadata> = BTreeMap::new();
+
+    // Sort by name for deterministic output
+    let mut sorted_types: Vec<(&String, &TypeMetadata)> = type_map.iter().collect();
+    sorted_types.sort_by_key(|(name, _)| name.to_string());
+
+    for (_name, metadata) in &sorted_types {
+        let module_name = to_snake_case(&metadata.name);
+        module_names.push(module_name.clone());
+
+        // Collect utility types referenced by properties
+        collect_utility_type_refs(metadata, type_map, &mut resolved_utility_types);
+
+        let content = generate_struct_file(metadata, type_map);
+        outputs.push(GeneratedOutput {
+            path: format!(".typokit/models/{}.rs", module_name),
+            content,
+            overwrite: true,
+        });
+    }
+
+    // Generate structs for resolved utility types
+    for (name, resolved_meta) in &resolved_utility_types {
+        let module_name = to_snake_case(name);
+        if !module_names.contains(&module_name) {
+            module_names.push(module_name.clone());
+            let content = generate_struct_file(resolved_meta, type_map);
+            outputs.push(GeneratedOutput {
+                path: format!(".typokit/models/{}.rs", module_name),
+                content,
+                overwrite: true,
+            });
+        }
+    }
+
+    // Generate common types (PaginatedResponse<T>, ErrorResponse)
+    module_names.push("common".to_string());
+    outputs.push(generate_common_types());
+
+    // Sort module_names for deterministic mod.rs output
+    module_names.sort();
+
+    // Collect all exported type names
+    let mut type_exports: Vec<(String, String)> = Vec::new();
+    for (_, metadata) in &sorted_types {
+        let module_name = to_snake_case(&metadata.name);
+        type_exports.push((module_name, metadata.name.clone()));
+    }
+    for (name, _) in &resolved_utility_types {
+        let module_name = to_snake_case(name);
+        type_exports.push((module_name, name.clone()));
+    }
+    type_exports.sort();
+
+    let mod_content = generate_models_mod(&module_names, &type_exports);
+    outputs.push(GeneratedOutput {
+        path: ".typokit/models/mod.rs".to_string(),
+        content: mod_content,
+        overwrite: true,
+    });
+
+    outputs
+}
+
+/// Generate a single struct file for an entity, with validation annotations
+/// and enum types for union literals.
+fn generate_struct_file(metadata: &TypeMetadata, type_map: &HashMap<String, TypeMetadata>) -> String {
+    let mut output = String::new();
+
+    output.push_str("// AUTO-GENERATED by @typokit/transform-native — DO NOT EDIT\n");
+
+    // Analyze what imports are needed
+    let has_chrono = metadata.properties.values().any(|p| is_date_type(&p.type_str));
+    let has_validation = metadata.properties.values().any(|p| has_any_validation(p));
+    let has_regex = metadata.properties.values().any(|p| has_pattern_annotation(p));
+
+    // Collect enums for union literal fields
+    let mut enums: Vec<(String, Vec<String>)> = Vec::new();
+    let mut sorted_props: Vec<(&String, &PropertyMetadata)> =
+        metadata.properties.iter().collect();
+    sorted_props.sort_by_key(|(name, _)| name.to_string());
+
+    for (prop_name, prop) in &sorted_props {
+        if is_union_literal(&prop.type_str) {
+            let variants = parse_union_literals(&prop.type_str);
+            let enum_name = format!("{}{}", metadata.name, to_pascal_case(&to_snake_case(prop_name)));
+            enums.push((enum_name, variants));
+        }
+    }
+
+    // Imports
+    output.push_str("use serde::{Deserialize, Serialize};\n");
+    if has_validation {
+        output.push_str("use validator::Validate;\n");
+    }
+    if has_chrono {
+        output.push_str("use chrono::{DateTime, Utc};\n");
+    }
+    if has_regex {
+        output.push_str("use once_cell::sync::Lazy;\n");
+        output.push_str("use regex::Regex;\n");
+    }
+
+    output.push('\n');
+
+    // Generate regex statics for @pattern fields
+    for (prop_name, prop) in &sorted_props {
+        if let Some(pattern) = get_pattern_annotation(prop) {
+            let static_name = regex_static_name(&metadata.name, prop_name);
+            output.push_str(&format!(
+                "static {}: Lazy<Regex> = Lazy::new(|| Regex::new(r\"{}\").unwrap());\n",
+                static_name, pattern
+            ));
+        }
+    }
+    if has_regex {
+        output.push('\n');
+    }
+
+    // Generate enum types for union literal fields
+    for (enum_name, variants) in &enums {
+        output.push_str(&generate_enum(enum_name, variants));
+        output.push('\n');
+    }
+
+    // Determine derives
+    let has_table = metadata
+        .jsdoc
+        .as_ref()
+        .map(|j| j.contains_key("table"))
+        .unwrap_or(false);
+
+    let mut derives = vec!["Debug", "Clone", "Serialize", "Deserialize"];
+    if has_table {
+        derives.push("sqlx::FromRow");
+    }
+    if has_validation {
+        derives.push("Validate");
+    }
+    output.push_str(&format!("#[derive({})]\n", derives.join(", ")));
+
+    output.push_str(&format!("pub struct {} {{\n", metadata.name));
+
+    // Generate fields
+    let mut enum_idx = 0;
+    for (prop_name, prop) in &sorted_props {
+        let field_name = to_snake_case(prop_name);
+        let is_union = is_union_literal(&prop.type_str);
+
+        let rust_type = if is_union {
+            let (ref enum_name, _) = enums[enum_idx];
+            enum_idx += 1;
+            enum_name.clone()
+        } else {
+            resolve_rust_type(&prop.type_str, prop_name, &prop.jsdoc, type_map)
+        };
+
+        // Serde rename if field name differs from original
+        if field_name != **prop_name {
+            output.push_str(&format!("    #[serde(rename = \"{}\")]\n", prop_name));
+        }
+
+        // Validation attributes
+        let validation_attrs = generate_validation_attrs(prop, &metadata.name, prop_name);
+        for attr in &validation_attrs {
+            output.push_str(&format!("    {}\n", attr));
+        }
+
+        if prop.optional {
+            output.push_str(&format!("    pub {}: Option<{}>,\n", field_name, rust_type));
+        } else {
+            output.push_str(&format!("    pub {}: {},\n", field_name, rust_type));
+        }
+    }
+
+    output.push_str("}\n");
+
+    output
+}
+
+/// Generate the models/mod.rs file that re-exports all entity modules
+fn generate_models_mod(module_names: &[String], type_exports: &[(String, String)]) -> String {
+    let mut output = String::new();
+    output.push_str("// AUTO-GENERATED by @typokit/transform-native — DO NOT EDIT\n");
+
+    for name in module_names {
+        output.push_str(&format!("pub mod {};\n", name));
+    }
+
+    if !type_exports.is_empty() || module_names.contains(&"common".to_string()) {
+        output.push('\n');
+        for (module_name, struct_name) in type_exports {
+            output.push_str(&format!("pub use {}::{};\n", module_name, struct_name));
+        }
+        if module_names.contains(&"common".to_string()) {
+            output.push_str("pub use common::{PaginatedResponse, ErrorResponse};\n");
+        }
+    }
+
+    output
+}
+
+/// Generate shared framework types: PaginatedResponse<T> and ErrorResponse.
+fn generate_common_types() -> GeneratedOutput {
+    let content = r#"// AUTO-GENERATED by @typokit/transform-native — DO NOT EDIT
+use serde::{Deserialize, Serialize};
+
+/// Paginated response wrapper for list endpoints
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PaginatedResponse<T> {
+    pub data: Vec<T>,
+    pub total: u32,
+    pub page: u32,
+    #[serde(rename = "pageSize")]
+    pub page_size: u32,
+    #[serde(rename = "totalPages")]
+    pub total_pages: u32,
+}
+
+/// Standard error response
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ErrorResponse {
+    pub error: String,
+    pub message: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub details: Option<serde_json::Value>,
+    #[serde(rename = "traceId")]
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub trace_id: Option<String>,
+}
+"#;
+
+    GeneratedOutput {
+        path: ".typokit/models/common.rs".to_string(),
+        content: content.to_string(),
+        overwrite: true,
+    }
+}
+
+// ─────────────────────────── Validation Annotations ───────────────────────────
+
+/// Check if a property has any validation annotations in its JSDoc
+fn has_any_validation(prop: &PropertyMetadata) -> bool {
+    prop.jsdoc.as_ref().map_or(false, |j| {
+        j.contains_key("minLength")
+            || j.contains_key("maxLength")
+            || j.contains_key("format")
+            || j.contains_key("pattern")
+            || j.contains_key("minimum")
+            || j.contains_key("maximum")
+    })
+}
+
+/// Check if a property has a @pattern annotation
+fn has_pattern_annotation(prop: &PropertyMetadata) -> bool {
+    prop.jsdoc
+        .as_ref()
+        .map_or(false, |j| j.contains_key("pattern"))
+}
+
+/// Get the @pattern annotation value
+fn get_pattern_annotation(prop: &PropertyMetadata) -> Option<String> {
+    prop.jsdoc
+        .as_ref()
+        .and_then(|j| j.get("pattern").cloned())
+}
+
+/// Generate the name for a regex static variable
+fn regex_static_name(struct_name: &str, field_name: &str) -> String {
+    format!(
+        "RE_{}_{}",
+        to_screaming_snake_case(struct_name),
+        to_screaming_snake_case(field_name)
+    )
+}
+
+/// Generate `#[validate(...)]` attributes for a property based on JSDoc tags
+fn generate_validation_attrs(
+    prop: &PropertyMetadata,
+    struct_name: &str,
+    prop_name: &str,
+) -> Vec<String> {
+    let mut attrs = Vec::new();
+    let jsdoc = match &prop.jsdoc {
+        Some(j) => j,
+        None => return attrs,
+    };
+
+    // Length validators — combine min/max into a single length() attribute
+    let min_len = jsdoc.get("minLength");
+    let max_len = jsdoc.get("maxLength");
+    if min_len.is_some() || max_len.is_some() {
+        let mut parts = Vec::new();
+        if let Some(min) = min_len {
+            parts.push(format!("min = {}", min));
+        }
+        if let Some(max) = max_len {
+            parts.push(format!("max = {}", max));
+        }
+        attrs.push(format!("#[validate(length({}))]", parts.join(", ")));
+    }
+
+    // Email format
+    if jsdoc.get("format").map(|v| v.as_str()) == Some("email") {
+        attrs.push("#[validate(email)]".to_string());
+    }
+
+    // Regex pattern
+    if jsdoc.contains_key("pattern") {
+        let static_name = regex_static_name(struct_name, prop_name);
+        attrs.push(format!("#[validate(regex(path = \"*{}\"))]", static_name));
+    }
+
+    // Range validators — combine min/max into a single range() attribute
+    let minimum = jsdoc.get("minimum");
+    let maximum = jsdoc.get("maximum");
+    if minimum.is_some() || maximum.is_some() {
+        let mut parts = Vec::new();
+        if let Some(min) = minimum {
+            parts.push(format!("min = {}", min));
+        }
+        if let Some(max) = maximum {
+            parts.push(format!("max = {}", max));
+        }
+        attrs.push(format!("#[validate(range({}))]", parts.join(", ")));
+    }
+
+    attrs
+}
+
+// ─────────────────────────── Union Literal Enums ──────────────────────────────
+
+/// Check if a type string is a union of string literals
+fn is_union_literal(ts_type: &str) -> bool {
+    if !ts_type.contains(" | ") {
+        return false;
+    }
+    ts_type
+        .split(" | ")
+        .all(|part| {
+            let trimmed = part.trim();
+            trimmed.starts_with('"') && trimmed.ends_with('"')
+        })
+}
+
+/// Parse variant names from a union literal type string
+fn parse_union_literals(ts_type: &str) -> Vec<String> {
+    ts_type
+        .split(" | ")
+        .map(|part| {
+            let trimmed = part.trim();
+            if trimmed.starts_with('"') && trimmed.ends_with('"') {
+                trimmed[1..trimmed.len() - 1].to_string()
+            } else {
+                trimmed.to_string()
+            }
+        })
+        .collect()
+}
+
+/// Generate a Rust enum for a union literal type
+fn generate_enum(name: &str, variants: &[String]) -> String {
+    let mut output = String::new();
+    output.push_str("#[derive(Debug, Clone, Serialize, Deserialize)]\n");
+    output.push_str(&format!("pub enum {} {{\n", name));
+    for variant in variants {
+        let pascal = variant_to_pascal(variant);
+        if pascal != *variant {
+            output.push_str(&format!("    #[serde(rename = \"{}\")]\n", variant));
+        }
+        output.push_str(&format!("    {},\n", pascal));
+    }
+    output.push_str("}\n");
+    output
+}
+
+/// Convert a union variant string to a PascalCase enum variant name
+fn variant_to_pascal(s: &str) -> String {
+    s.split(|c: char| c == '_' || c == '-' || c == ' ')
+        .filter(|part| !part.is_empty())
+        .map(|part| {
+            let mut chars = part.chars();
+            match chars.next() {
+                None => String::new(),
+                Some(c) => c.to_uppercase().collect::<String>() + chars.as_str(),
+            }
+        })
+        .collect()
+}
+
+// ─────────────────────────── Utility Type Resolution ──────────────────────────
+
+/// Collect utility type references from property type_str values.
+///
+/// Scans all properties in a type and resolves any Omit<T, K>, Partial<T>,
+/// or Pick<T, K> references against the type_map.
+fn collect_utility_type_refs(
+    metadata: &TypeMetadata,
+    type_map: &HashMap<String, TypeMetadata>,
+    resolved: &mut BTreeMap<String, TypeMetadata>,
+) {
+    for (_prop_name, prop) in &metadata.properties {
+        // Strip array wrappers to check inner type
+        let inner_type = strip_array_wrapper(&prop.type_str);
+        if let Some((utility, base_name, args)) = parse_utility_type(inner_type) {
+            if let Some(base) = type_map.get(&base_name) {
+                let resolved_name = utility_type_name(&utility, &base_name, &args);
+                if !resolved.contains_key(&resolved_name) {
+                    let resolved_meta = match utility.as_str() {
+                        "Omit" => resolve_omit(base, &args, &resolved_name),
+                        "Partial" => resolve_partial(base, &resolved_name),
+                        "Pick" => resolve_pick(base, &args, &resolved_name),
+                        _ => continue,
+                    };
+                    resolved.insert(resolved_name, resolved_meta);
+                }
+            }
+        }
+    }
+}
+
+/// Parse a utility type reference from a type string.
+/// Returns (utility, base_type_name, field_args).
+fn parse_utility_type(ts_type: &str) -> Option<(String, String, Vec<String>)> {
+    for prefix in &["Omit<", "Partial<", "Pick<"] {
+        if ts_type.starts_with(prefix) && ts_type.ends_with('>') {
+            let utility = prefix[..prefix.len() - 1].to_string();
+            let inner = &ts_type[prefix.len()..ts_type.len() - 1];
+
+            if utility == "Partial" {
+                return Some((utility, inner.trim().to_string(), vec![]));
+            }
+
+            if let Some((base, args_str)) = split_generic_args(inner) {
+                let base = base.trim().to_string();
+                let args: Vec<String> = args_str
+                    .split(" | ")
+                    .map(|s| s.trim().trim_matches('"').to_string())
+                    .collect();
+                return Some((utility, base, args));
+            }
+        }
+    }
+    None
+}
+
+/// Strip array wrappers ([] or Array<>) from a type string
+fn strip_array_wrapper(ts_type: &str) -> &str {
+    if ts_type.ends_with("[]") {
+        &ts_type[..ts_type.len() - 2]
+    } else if ts_type.starts_with("Array<") && ts_type.ends_with('>') {
+        &ts_type[6..ts_type.len() - 1]
+    } else {
+        ts_type
+    }
+}
+
+/// Generate a name for a resolved utility type
+fn utility_type_name(utility: &str, base_name: &str, args: &[String]) -> String {
+    match utility {
+        "Omit" => {
+            let fields: Vec<String> = args.iter().map(|a| to_pascal_case(&to_snake_case(a))).collect();
+            format!("{}Without{}", base_name, fields.join(""))
+        }
+        "Partial" => format!("Partial{}", base_name),
+        "Pick" => {
+            let fields: Vec<String> = args.iter().map(|a| to_pascal_case(&to_snake_case(a))).collect();
+            format!("{}Pick{}", base_name, fields.join(""))
+        }
+        _ => format!("{}{}", utility, base_name),
+    }
+}
+
+/// Resolve Omit<T, K> — copy base type but remove specified fields
+pub fn resolve_omit(base: &TypeMetadata, omit_fields: &[String], new_name: &str) -> TypeMetadata {
+    let mut properties = HashMap::new();
+    for (name, prop) in &base.properties {
+        if !omit_fields.contains(name) {
+            properties.insert(name.clone(), prop.clone());
+        }
+    }
+    TypeMetadata {
+        name: new_name.to_string(),
+        properties,
+        jsdoc: None,
+    }
+}
+
+/// Resolve Partial<T> — copy base type but wrap all fields in Option
+pub fn resolve_partial(base: &TypeMetadata, new_name: &str) -> TypeMetadata {
+    let mut properties = HashMap::new();
+    for (name, prop) in &base.properties {
+        let mut new_prop = prop.clone();
+        new_prop.optional = true;
+        properties.insert(name.clone(), new_prop);
+    }
+    TypeMetadata {
+        name: new_name.to_string(),
+        properties,
+        jsdoc: None,
+    }
+}
+
+/// Resolve Pick<T, K> — copy base type keeping only specified fields
+pub fn resolve_pick(base: &TypeMetadata, pick_fields: &[String], new_name: &str) -> TypeMetadata {
+    let mut properties = HashMap::new();
+    for (name, prop) in &base.properties {
+        if pick_fields.contains(name) {
+            properties.insert(name.clone(), prop.clone());
+        }
+    }
+    TypeMetadata {
+        name: new_name.to_string(),
+        properties,
+        jsdoc: None,
+    }
+}
+
+// ─────────────────────────── Type Mapping ─────────────────────────────────────
+
+/// Resolve a TypeScript type string to a Rust type, accounting for context
+/// (JSDoc annotations, property name heuristics, utility type references).
+fn resolve_rust_type(
+    ts_type: &str,
+    prop_name: &str,
+    jsdoc: &Option<HashMap<String, String>>,
+    type_map: &HashMap<String, TypeMetadata>,
+) -> String {
+    // Check for utility type reference (e.g., Omit<User, "id">)
+    if let Some((utility, base_name, args)) = parse_utility_type(ts_type) {
+        return utility_type_name(&utility, &base_name, &args);
+    }
+
+    // Array of utility type (e.g., Pick<User, "name">[]  )
+    if ts_type.ends_with("[]") {
+        let inner = &ts_type[..ts_type.len() - 2];
+        if parse_utility_type(inner).is_some() {
+            let inner_type = resolve_rust_type(inner, prop_name, jsdoc, type_map);
+            return format!("Vec<{}>", inner_type);
+        }
+    }
+
+    ts_type_to_rust_with_context(ts_type, prop_name, jsdoc)
+}
+
+/// Map a TypeScript type to a Rust type with context-aware integer inference.
+///
+/// Context rules for number types:
+/// - `@id` fields → `String` (UUID)
+/// - `@integer` override → `i64`
+/// - pagination params (page, pageSize, limit, offset, etc.) → `u32`
+/// - general numbers → `f64`
+fn ts_type_to_rust_with_context(
+    ts_type: &str,
+    prop_name: &str,
+    jsdoc: &Option<HashMap<String, String>>,
+) -> String {
+    if ts_type == "number" {
+        return number_type_from_context(prop_name, jsdoc);
+    }
+    ts_type_to_rust(ts_type)
+}
+
+/// Determine Rust numeric type from property context
+fn number_type_from_context(prop_name: &str, jsdoc: &Option<HashMap<String, String>>) -> String {
+    if let Some(j) = jsdoc {
+        if j.contains_key("id") {
+            return "String".to_string();
+        }
+        if j.contains_key("integer") {
+            return "i64".to_string();
+        }
+    }
+    // Pagination heuristic based on field name
+    match prop_name {
+        "page" | "pageSize" | "page_size" | "limit" | "offset" | "perPage" | "per_page"
+        | "total" | "totalPages" | "total_pages" | "count" | "size" => "u32".to_string(),
+        _ => "f64".to_string(),
+    }
+}
+
+/// Map a TypeScript type string to a Rust type string
+fn ts_type_to_rust(ts_type: &str) -> String {
+    match ts_type {
+        "string" => "String".to_string(),
+        "number" => "f64".to_string(),
+        "boolean" => "bool".to_string(),
+        t if is_date_type(t) => "DateTime<Utc>".to_string(),
+        "any" | "unknown" => "serde_json::Value".to_string(),
+        "null" | "void" | "undefined" => "()".to_string(),
+
+        // Array types: string[] → Vec<String>
+        t if t.ends_with("[]") => {
+            let inner = &t[..t.len() - 2];
+            format!("Vec<{}>", ts_type_to_rust(inner))
+        }
+        // Array<T> → Vec<T>
+        t if t.starts_with("Array<") && t.ends_with('>') => {
+            let inner = &t[6..t.len() - 1];
+            format!("Vec<{}>", ts_type_to_rust(inner))
+        }
+        // Record<K, V> → HashMap<K, V>
+        t if t.starts_with("Record<") && t.ends_with('>') => {
+            let inner = &t[7..t.len() - 1];
+            if let Some((key, value)) = split_generic_args(inner) {
+                format!(
+                    "std::collections::HashMap<{}, {}>",
+                    ts_type_to_rust(key.trim()),
+                    ts_type_to_rust(value.trim())
+                )
+            } else {
+                "std::collections::HashMap<String, serde_json::Value>".to_string()
+            }
+        }
+
+        // Union literal types (e.g. "active" | "inactive") → String
+        t if t.contains(" | ") => "String".to_string(),
+
+        // Named type reference (e.g. other struct) — keep as-is
+        t => t.to_string(),
+    }
+}
+
+/// Check if a type string represents a Date type
+fn is_date_type(ts_type: &str) -> bool {
+    ts_type == "Date" || ts_type == "DateTime"
+}
+
+/// Split two generic type arguments separated by a comma at the top level
+fn split_generic_args(s: &str) -> Option<(&str, &str)> {
+    let mut depth = 0;
+    for (i, c) in s.char_indices() {
+        match c {
+            '<' => depth += 1,
+            '>' => depth -= 1,
+            ',' if depth == 0 => {
+                return Some((&s[..i], &s[i + 1..]));
+            }
+            _ => {}
+        }
+    }
+    None
+}
+
+/// Convert a camelCase or PascalCase string to snake_case
+fn to_snake_case(s: &str) -> String {
+    let mut result = String::new();
+    for (i, c) in s.chars().enumerate() {
+        if c.is_uppercase() {
+            if i > 0 {
+                result.push('_');
+            }
+            result.push(c.to_lowercase().next().unwrap());
+        } else {
+            result.push(c);
+        }
+    }
+    result
+}
+
+/// Convert a snake_case string to PascalCase
+fn to_pascal_case(s: &str) -> String {
+    s.split('_')
+        .map(|part| {
+            let mut chars = part.chars();
+            match chars.next() {
+                None => String::new(),
+                Some(c) => c.to_uppercase().collect::<String>() + chars.as_str(),
+            }
+        })
+        .collect()
+}
+
+/// Convert a camelCase or PascalCase string to SCREAMING_SNAKE_CASE
+fn to_screaming_snake_case(s: &str) -> String {
+    to_snake_case(s).to_uppercase()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use typokit_transform_native::type_extractor::{PropertyMetadata, TypeMetadata};
+
+    fn make_type(name: &str, props: Vec<(&str, &str, bool)>) -> TypeMetadata {
+        let mut properties = HashMap::new();
+        for (pname, ptype, optional) in props {
+            properties.insert(
+                pname.to_string(),
+                PropertyMetadata {
+                    type_str: ptype.to_string(),
+                    optional,
+                    jsdoc: None,
+                },
+            );
+        }
+        TypeMetadata {
+            name: name.to_string(),
+            properties,
+            jsdoc: None,
+        }
+    }
+
+    fn make_table_type(name: &str, table_name: &str, props: Vec<(&str, &str, bool)>) -> TypeMetadata {
+        let mut metadata = make_type(name, props);
+        let mut jsdoc = HashMap::new();
+        jsdoc.insert("table".to_string(), table_name.to_string());
+        metadata.jsdoc = Some(jsdoc);
+        metadata
+    }
+
+    fn make_prop(type_str: &str, optional: bool) -> PropertyMetadata {
+        PropertyMetadata {
+            type_str: type_str.to_string(),
+            optional,
+            jsdoc: None,
+        }
+    }
+
+    fn make_prop_with_jsdoc(
+        type_str: &str,
+        optional: bool,
+        jsdoc_tags: Vec<(&str, &str)>,
+    ) -> PropertyMetadata {
+        let mut jsdoc = HashMap::new();
+        for (key, value) in jsdoc_tags {
+            jsdoc.insert(key.to_string(), value.to_string());
+        }
+        PropertyMetadata {
+            type_str: type_str.to_string(),
+            optional,
+            jsdoc: Some(jsdoc),
+        }
+    }
+
+    // ─── Original tests preserved ────────────────────────────────────────────
+
+    #[test]
+    fn test_ts_type_to_rust_primitives() {
+        assert_eq!(ts_type_to_rust("string"), "String");
+        assert_eq!(ts_type_to_rust("number"), "f64");
+        assert_eq!(ts_type_to_rust("boolean"), "bool");
+        assert_eq!(ts_type_to_rust("Date"), "DateTime<Utc>");
+    }
+
+    #[test]
+    fn test_ts_type_to_rust_arrays() {
+        assert_eq!(ts_type_to_rust("string[]"), "Vec<String>");
+        assert_eq!(ts_type_to_rust("number[]"), "Vec<f64>");
+        assert_eq!(ts_type_to_rust("Array<string>"), "Vec<String>");
+    }
+
+    #[test]
+    fn test_ts_type_to_rust_record() {
+        assert_eq!(
+            ts_type_to_rust("Record<string, unknown>"),
+            "std::collections::HashMap<String, serde_json::Value>"
+        );
+    }
+
+    #[test]
+    fn test_ts_type_to_rust_optional_maps_to_option() {
+        assert_eq!(ts_type_to_rust("string"), "String");
+    }
+
+    #[test]
+    fn test_to_snake_case() {
+        assert_eq!(to_snake_case("createdAt"), "created_at");
+        assert_eq!(to_snake_case("userId"), "user_id");
+        assert_eq!(to_snake_case("User"), "user");
+        assert_eq!(to_snake_case("HTMLParser"), "h_t_m_l_parser");
+        assert_eq!(to_snake_case("id"), "id");
+    }
+
+    #[test]
+    fn test_to_pascal_case() {
+        assert_eq!(to_pascal_case("user"), "User");
+        assert_eq!(to_pascal_case("created_at"), "CreatedAt");
+        assert_eq!(to_pascal_case("user_profile"), "UserProfile");
+    }
+
+    #[test]
+    fn test_generate_simple_struct() {
+        let mut type_map = HashMap::new();
+        type_map.insert(
+            "User".to_string(),
+            make_type("User", vec![
+                ("id", "string", false),
+                ("name", "string", false),
+                ("age", "number", false),
+                ("active", "boolean", false),
+            ]),
+        );
+
+        let outputs = generate_structs(&type_map);
+
+        let user_file = outputs.iter().find(|o| o.path.contains("user.rs") && !o.path.contains("mod.rs")).unwrap();
+        assert!(user_file.content.contains("pub struct User"));
+        assert!(user_file.content.contains("pub id: String"));
+        assert!(user_file.content.contains("pub name: String"));
+        assert!(user_file.content.contains("pub active: bool"));
+        assert!(user_file.content.contains("#[derive(Debug, Clone, Serialize, Deserialize)]"));
+        assert!(!user_file.content.contains("sqlx::FromRow"));
+        assert!(user_file.overwrite);
+    }
+
+    #[test]
+    fn test_generate_table_struct_has_sqlx_derive() {
+        let mut type_map = HashMap::new();
+        type_map.insert(
+            "User".to_string(),
+            make_table_type("User", "users", vec![
+                ("id", "string", false),
+                ("name", "string", false),
+            ]),
+        );
+
+        let outputs = generate_structs(&type_map);
+        let user_file = outputs.iter().find(|o| o.path.contains("user.rs") && !o.path.contains("mod.rs")).unwrap();
+        assert!(user_file.content.contains("sqlx::FromRow"));
+    }
+
+    #[test]
+    fn test_generate_optional_fields() {
+        let mut type_map = HashMap::new();
+        type_map.insert(
+            "Profile".to_string(),
+            make_type("Profile", vec![
+                ("bio", "string", true),
+                ("age", "number", true),
+                ("name", "string", false),
+            ]),
+        );
+
+        let outputs = generate_structs(&type_map);
+        let profile_file = outputs.iter().find(|o| o.path.contains("profile.rs")).unwrap();
+        assert!(profile_file.content.contains("pub bio: Option<String>"));
+        assert!(profile_file.content.contains("pub age: Option<f64>"));
+        assert!(profile_file.content.contains("pub name: String"));
+    }
+
+    #[test]
+    fn test_generate_date_fields() {
+        let mut type_map = HashMap::new();
+        type_map.insert(
+            "Event".to_string(),
+            make_type("Event", vec![
+                ("id", "string", false),
+                ("createdAt", "Date", false),
+                ("updatedAt", "Date", true),
+            ]),
+        );
+
+        let outputs = generate_structs(&type_map);
+        let event_file = outputs.iter().find(|o| o.path.contains("event.rs")).unwrap();
+        assert!(event_file.content.contains("use chrono::{DateTime, Utc};"));
+        assert!(event_file.content.contains("pub created_at: DateTime<Utc>"));
+        assert!(event_file.content.contains("pub updated_at: Option<DateTime<Utc>>"));
+    }
+
+    #[test]
+    fn test_generate_camel_case_fields_get_serde_rename() {
+        let mut type_map = HashMap::new();
+        type_map.insert(
+            "User".to_string(),
+            make_type("User", vec![
+                ("id", "string", false),
+                ("createdAt", "Date", false),
+            ]),
+        );
+
+        let outputs = generate_structs(&type_map);
+        let user_file = outputs.iter().find(|o| o.path.contains("user.rs") && !o.path.contains("mod.rs")).unwrap();
+        assert!(!user_file.content.contains("#[serde(rename = \"id\")]"));
+        assert!(user_file.content.contains("#[serde(rename = \"createdAt\")]"));
+    }
+
+    #[test]
+    fn test_generate_mod_rs() {
+        let mut type_map = HashMap::new();
+        type_map.insert("User".to_string(), make_type("User", vec![("id", "string", false)]));
+        type_map.insert("Post".to_string(), make_type("Post", vec![("id", "string", false)]));
+
+        let outputs = generate_structs(&type_map);
+        let mod_file = outputs.iter().find(|o| o.path.ends_with("mod.rs")).unwrap();
+        assert!(mod_file.content.contains("pub mod common;"));
+        assert!(mod_file.content.contains("pub mod post;"));
+        assert!(mod_file.content.contains("pub mod user;"));
+        assert!(mod_file.content.contains("pub use post::Post;"));
+        assert!(mod_file.content.contains("pub use user::User;"));
+        assert!(mod_file.content.contains("pub use common::{PaginatedResponse, ErrorResponse};"));
+        assert!(mod_file.overwrite);
+    }
+
+    #[test]
+    fn test_generate_file_paths() {
+        let mut type_map = HashMap::new();
+        type_map.insert(
+            "UserProfile".to_string(),
+            make_type("UserProfile", vec![("id", "string", false)]),
+        );
+
+        let outputs = generate_structs(&type_map);
+        let struct_file = outputs
+            .iter()
+            .find(|o| !o.path.ends_with("mod.rs") && !o.path.contains("common"))
+            .unwrap();
+        assert_eq!(struct_file.path, ".typokit/models/user_profile.rs");
+    }
+
+    #[test]
+    fn test_all_model_outputs_have_overwrite_true() {
+        let mut type_map = HashMap::new();
+        type_map.insert("User".to_string(), make_type("User", vec![("id", "string", false)]));
+
+        let outputs = generate_structs(&type_map);
+        for output in &outputs {
+            assert!(output.overwrite, "All generated model files should have overwrite: true");
+        }
+    }
+
+    // ─── US-002: Validation annotation tests ─────────────────────────────────
+
+    #[test]
+    fn test_validation_min_max_length() {
+        let mut type_map = HashMap::new();
+        let mut properties = HashMap::new();
+        properties.insert(
+            "name".to_string(),
+            make_prop_with_jsdoc("string", false, vec![("minLength", "2"), ("maxLength", "100")]),
+        );
+        type_map.insert(
+            "User".to_string(),
+            TypeMetadata {
+                name: "User".to_string(),
+                properties,
+                jsdoc: None,
+            },
+        );
+
+        let outputs = generate_structs(&type_map);
+        let user_file = outputs.iter().find(|o| o.path.contains("user.rs") && !o.path.contains("mod.rs")).unwrap();
+        assert!(user_file.content.contains("#[validate(length(min = 2, max = 100))]"));
+        assert!(user_file.content.contains("Validate"));
+        assert!(user_file.content.contains("use validator::Validate;"));
+    }
+
+    #[test]
+    fn test_validation_email_format() {
+        let mut type_map = HashMap::new();
+        let mut properties = HashMap::new();
+        properties.insert(
+            "email".to_string(),
+            make_prop_with_jsdoc("string", false, vec![("format", "email")]),
+        );
+        type_map.insert(
+            "User".to_string(),
+            TypeMetadata {
+                name: "User".to_string(),
+                properties,
+                jsdoc: None,
+            },
+        );
+
+        let outputs = generate_structs(&type_map);
+        let user_file = outputs.iter().find(|o| o.path.contains("user.rs") && !o.path.contains("mod.rs")).unwrap();
+        assert!(user_file.content.contains("#[validate(email)]"));
+    }
+
+    #[test]
+    fn test_validation_regex_pattern() {
+        let mut type_map = HashMap::new();
+        let mut properties = HashMap::new();
+        properties.insert(
+            "phone".to_string(),
+            make_prop_with_jsdoc("string", false, vec![("pattern", r"^\+[0-9]{10,15}$")]),
+        );
+        type_map.insert(
+            "User".to_string(),
+            TypeMetadata {
+                name: "User".to_string(),
+                properties,
+                jsdoc: None,
+            },
+        );
+
+        let outputs = generate_structs(&type_map);
+        let user_file = outputs.iter().find(|o| o.path.contains("user.rs") && !o.path.contains("mod.rs")).unwrap();
+        assert!(user_file.content.contains("use once_cell::sync::Lazy;"));
+        assert!(user_file.content.contains("use regex::Regex;"));
+        assert!(user_file.content.contains("static RE_USER_PHONE: Lazy<Regex>"));
+        assert!(user_file.content.contains(r#"Regex::new(r"^\+[0-9]{10,15}$")"#));
+        assert!(user_file.content.contains("#[validate(regex(path = \"*RE_USER_PHONE\"))]"));
+    }
+
+    #[test]
+    fn test_validation_range_min_max() {
+        let mut type_map = HashMap::new();
+        let mut properties = HashMap::new();
+        properties.insert(
+            "score".to_string(),
+            make_prop_with_jsdoc("number", false, vec![("minimum", "0"), ("maximum", "100")]),
+        );
+        type_map.insert(
+            "Result".to_string(),
+            TypeMetadata {
+                name: "Result".to_string(),
+                properties,
+                jsdoc: None,
+            },
+        );
+
+        let outputs = generate_structs(&type_map);
+        let result_file = outputs.iter().find(|o| o.path.contains("result.rs")).unwrap();
+        assert!(result_file.content.contains("#[validate(range(min = 0, max = 100))]"));
+    }
+
+    #[test]
+    fn test_validation_derive_only_when_needed() {
+        let mut type_map = HashMap::new();
+        type_map.insert(
+            "Simple".to_string(),
+            make_type("Simple", vec![("id", "string", false)]),
+        );
+
+        let outputs = generate_structs(&type_map);
+        let file = outputs.iter().find(|o| o.path.contains("simple.rs")).unwrap();
+        assert!(!file.content.contains("Validate"));
+        assert!(!file.content.contains("use validator::Validate;"));
+    }
+
+    // ─── US-002: Union literal enum tests ────────────────────────────────────
+
+    #[test]
+    fn test_union_literal_detection() {
+        assert!(is_union_literal("\"active\" | \"inactive\""));
+        assert!(is_union_literal("\"active\" | \"archived\" | \"deleted\""));
+        assert!(!is_union_literal("string"));
+        assert!(!is_union_literal("string | number")); // not all string literals
+        assert!(!is_union_literal("\"active\""));       // single literal, no union
+    }
+
+    #[test]
+    fn test_parse_union_literals_extracts_variants() {
+        let variants = parse_union_literals("\"active\" | \"archived\" | \"deleted\"");
+        assert_eq!(variants, vec!["active", "archived", "deleted"]);
+    }
+
+    #[test]
+    fn test_generate_enum_for_union_field() {
+        let mut type_map = HashMap::new();
+        let mut properties = HashMap::new();
+        properties.insert("id".to_string(), make_prop("string", false));
+        properties.insert(
+            "status".to_string(),
+            make_prop("\"active\" | \"archived\"", false),
+        );
+        type_map.insert(
+            "Todo".to_string(),
+            TypeMetadata {
+                name: "Todo".to_string(),
+                properties,
+                jsdoc: None,
+            },
+        );
+
+        let outputs = generate_structs(&type_map);
+        let todo_file = outputs.iter().find(|o| o.path.contains("todo.rs")).unwrap();
+        assert!(todo_file.content.contains("pub enum TodoStatus"));
+        assert!(todo_file.content.contains("#[serde(rename = \"active\")]"));
+        assert!(todo_file.content.contains("Active,"));
+        assert!(todo_file.content.contains("#[serde(rename = \"archived\")]"));
+        assert!(todo_file.content.contains("Archived,"));
+        assert!(todo_file.content.contains("pub status: TodoStatus"));
+    }
+
+    // ─── US-002: Integer inference tests ─────────────────────────────────────
+
+    #[test]
+    fn test_integer_inference_pagination_params() {
+        let empty_jsdoc: Option<HashMap<String, String>> = None;
+        assert_eq!(
+            ts_type_to_rust_with_context("number", "page", &empty_jsdoc),
+            "u32"
+        );
+        assert_eq!(
+            ts_type_to_rust_with_context("number", "pageSize", &empty_jsdoc),
+            "u32"
+        );
+        assert_eq!(
+            ts_type_to_rust_with_context("number", "limit", &empty_jsdoc),
+            "u32"
+        );
+        assert_eq!(
+            ts_type_to_rust_with_context("number", "offset", &empty_jsdoc),
+            "u32"
+        );
+        assert_eq!(
+            ts_type_to_rust_with_context("number", "total", &empty_jsdoc),
+            "u32"
+        );
+    }
+
+    #[test]
+    fn test_integer_inference_general_number() {
+        let empty_jsdoc: Option<HashMap<String, String>> = None;
+        assert_eq!(
+            ts_type_to_rust_with_context("number", "price", &empty_jsdoc),
+            "f64"
+        );
+        assert_eq!(
+            ts_type_to_rust_with_context("number", "amount", &empty_jsdoc),
+            "f64"
+        );
+    }
+
+    #[test]
+    fn test_integer_inference_jsdoc_integer_override() {
+        let mut jsdoc = HashMap::new();
+        jsdoc.insert("integer".to_string(), "".to_string());
+        let jsdoc = Some(jsdoc);
+        assert_eq!(
+            ts_type_to_rust_with_context("number", "quantity", &jsdoc),
+            "i64"
+        );
+    }
+
+    #[test]
+    fn test_integer_inference_id_field_is_string() {
+        let mut jsdoc = HashMap::new();
+        jsdoc.insert("id".to_string(), "".to_string());
+        let jsdoc = Some(jsdoc);
+        assert_eq!(
+            ts_type_to_rust_with_context("number", "id", &jsdoc),
+            "String"
+        );
+    }
+
+    #[test]
+    fn test_integer_inference_in_struct() {
+        let mut type_map = HashMap::new();
+        let mut properties = HashMap::new();
+        properties.insert(
+            "page".to_string(),
+            make_prop("number", false),
+        );
+        properties.insert(
+            "pageSize".to_string(),
+            make_prop("number", false),
+        );
+        properties.insert(
+            "price".to_string(),
+            make_prop("number", false),
+        );
+        type_map.insert(
+            "Query".to_string(),
+            TypeMetadata {
+                name: "Query".to_string(),
+                properties,
+                jsdoc: None,
+            },
+        );
+
+        let outputs = generate_structs(&type_map);
+        let query_file = outputs.iter().find(|o| o.path.contains("query.rs")).unwrap();
+        assert!(query_file.content.contains("pub page: u32"));
+        assert!(query_file.content.contains("pub page_size: u32"));
+        assert!(query_file.content.contains("pub price: f64"));
+    }
+
+    // ─── US-002: Common types tests ──────────────────────────────────────────
+
+    #[test]
+    fn test_common_types_generated() {
+        let type_map = HashMap::new();
+        let outputs = generate_structs(&type_map);
+        let common_file = outputs.iter().find(|o| o.path.contains("common.rs")).unwrap();
+        assert!(common_file.content.contains("pub struct PaginatedResponse<T>"));
+        assert!(common_file.content.contains("pub data: Vec<T>"));
+        assert!(common_file.content.contains("pub total: u32"));
+        assert!(common_file.content.contains("pub struct ErrorResponse"));
+        assert!(common_file.content.contains("pub error: String"));
+        assert!(common_file.content.contains("pub message: String"));
+        assert!(common_file.overwrite);
+    }
+
+    // ─── US-002: Utility type resolution tests ───────────────────────────────
+
+    #[test]
+    fn test_resolve_omit() {
+        let base = make_type("User", vec![
+            ("id", "string", false),
+            ("name", "string", false),
+            ("email", "string", false),
+            ("createdAt", "Date", false),
+        ]);
+
+        let resolved = resolve_omit(
+            &base,
+            &["id".to_string(), "createdAt".to_string()],
+            "CreateUserInput",
+        );
+        assert_eq!(resolved.name, "CreateUserInput");
+        assert_eq!(resolved.properties.len(), 2);
+        assert!(resolved.properties.contains_key("name"));
+        assert!(resolved.properties.contains_key("email"));
+        assert!(!resolved.properties.contains_key("id"));
+        assert!(!resolved.properties.contains_key("createdAt"));
+    }
+
+    #[test]
+    fn test_resolve_partial() {
+        let base = make_type("User", vec![
+            ("id", "string", false),
+            ("name", "string", false),
+            ("email", "string", false),
+        ]);
+
+        let resolved = resolve_partial(&base, "PartialUser");
+        assert_eq!(resolved.name, "PartialUser");
+        assert_eq!(resolved.properties.len(), 3);
+        for (_name, prop) in &resolved.properties {
+            assert!(prop.optional, "All fields in Partial<T> should be optional");
+        }
+    }
+
+    #[test]
+    fn test_resolve_pick() {
+        let base = make_type("User", vec![
+            ("id", "string", false),
+            ("name", "string", false),
+            ("email", "string", false),
+            ("createdAt", "Date", false),
+        ]);
+
+        let resolved = resolve_pick(
+            &base,
+            &["name".to_string(), "email".to_string()],
+            "UserPickNameEmail",
+        );
+        assert_eq!(resolved.name, "UserPickNameEmail");
+        assert_eq!(resolved.properties.len(), 2);
+        assert!(resolved.properties.contains_key("name"));
+        assert!(resolved.properties.contains_key("email"));
+    }
+
+    #[test]
+    fn test_parse_utility_type_omit() {
+        let result = parse_utility_type("Omit<User, \"id\" | \"createdAt\">");
+        assert!(result.is_some());
+        let (utility, base, args) = result.unwrap();
+        assert_eq!(utility, "Omit");
+        assert_eq!(base, "User");
+        assert_eq!(args, vec!["id", "createdAt"]);
+    }
+
+    #[test]
+    fn test_parse_utility_type_partial() {
+        let result = parse_utility_type("Partial<User>");
+        assert!(result.is_some());
+        let (utility, base, args) = result.unwrap();
+        assert_eq!(utility, "Partial");
+        assert_eq!(base, "User");
+        assert!(args.is_empty());
+    }
+
+    #[test]
+    fn test_parse_utility_type_pick() {
+        let result = parse_utility_type("Pick<User, \"name\" | \"email\">");
+        assert!(result.is_some());
+        let (utility, base, args) = result.unwrap();
+        assert_eq!(utility, "Pick");
+        assert_eq!(base, "User");
+        assert_eq!(args, vec!["name", "email"]);
+    }
+
+    #[test]
+    fn test_parse_utility_type_returns_none_for_regular_types() {
+        assert!(parse_utility_type("string").is_none());
+        assert!(parse_utility_type("User").is_none());
+        assert!(parse_utility_type("Vec<String>").is_none());
+    }
+
+    #[test]
+    fn test_utility_type_name_generation() {
+        assert_eq!(
+            utility_type_name("Omit", "User", &["id".to_string(), "createdAt".to_string()]),
+            "UserWithoutIdCreatedAt"
+        );
+        assert_eq!(utility_type_name("Partial", "User", &[]), "PartialUser");
+        assert_eq!(
+            utility_type_name("Pick", "User", &["name".to_string(), "email".to_string()]),
+            "UserPickNameEmail"
+        );
+    }
+
+    #[test]
+    fn test_utility_type_in_property_generates_resolved_struct() {
+        let mut type_map = HashMap::new();
+        type_map.insert(
+            "User".to_string(),
+            make_type("User", vec![
+                ("id", "string", false),
+                ("name", "string", false),
+                ("email", "string", false),
+            ]),
+        );
+
+        let mut route_properties = HashMap::new();
+        route_properties.insert(
+            "body".to_string(),
+            make_prop("Omit<User, \"id\">", false),
+        );
+        type_map.insert(
+            "CreateRoute".to_string(),
+            TypeMetadata {
+                name: "CreateRoute".to_string(),
+                properties: route_properties,
+                jsdoc: None,
+            },
+        );
+
+        let outputs = generate_structs(&type_map);
+
+        // Should generate a UserWithoutId struct
+        let resolved_file = outputs
+            .iter()
+            .find(|o| o.path.contains("user_without_id.rs"));
+        assert!(resolved_file.is_some(), "Should generate resolved utility type struct");
+        let content = &resolved_file.unwrap().content;
+        assert!(content.contains("pub struct UserWithoutId"));
+        assert!(content.contains("pub name: String"));
+        assert!(content.contains("pub email: String"));
+        assert!(!content.contains("pub id:"));
+    }
+
+    #[test]
+    fn test_enum_variant_to_pascal() {
+        assert_eq!(variant_to_pascal("active"), "Active");
+        assert_eq!(variant_to_pascal("in_progress"), "InProgress");
+        assert_eq!(variant_to_pascal("not-started"), "NotStarted");
+    }
+
+    #[test]
+    fn test_to_screaming_snake_case() {
+        assert_eq!(to_screaming_snake_case("User"), "USER");
+        assert_eq!(to_screaming_snake_case("createdAt"), "CREATED_AT");
+        assert_eq!(to_screaming_snake_case("phone"), "PHONE");
+    }
+}