fraiseql_cli/schema/

merger.rs

//! Schema merger - combines language-generated types.json with TOML configuration
//!
//! This module merges:
//! - types.json: Generated by language implementations (Python, Go, etc.)
//! - fraiseql.toml: Configuration (security, federation, observers, caching, etc.)
//!
//! Result: Complete IntermediateSchema ready for compilation

use std::fs;

use anyhow::{Context, Result};
use fraiseql_core::schema::CrudNamingConfig;
use serde_json::{Value, json};

use crate::{
    config::TomlSchema,
    schema::{IntermediateSchema, intermediate::IntermediateQueryDefaults},
};

/// Convert a PascalCase GraphQL type name to a `snake_case` entity name.
///
/// Used to derive the entity segment for CRUD naming templates:
/// `"UserProfile"` → `"user_profile"`, `"User"` → `"user"`.
pub(crate) fn pascal_to_snake(type_name: &str) -> String {
    let mut out = String::with_capacity(type_name.len() + 4);
    for (i, ch) in type_name.chars().enumerate() {
        if ch.is_uppercase() && i > 0 {
            out.push('_');
        }
        out.push(ch.to_ascii_lowercase());
    }
    out
}

/// Resolve the `sql_source` for a TOML-defined mutation.
///
/// Precedence (highest first):
/// 1. Explicit `sql_source` on the mutation.
/// 2. `[crud]` naming config resolved from `operation` + entity derived from `return_type`.
///
/// Returns an error when neither is available, naming the offending mutation.
fn resolve_mutation_sql_source(
    mutation_name: &str,
    sql_source: Option<&str>,
    operation: &str,
    return_type: &str,
    crud: Option<&CrudNamingConfig>,
) -> Result<String> {
    if let Some(src) = sql_source {
        return Ok(src.to_string());
    }
    if let Some(cfg) = crud {
        let entity = pascal_to_snake(return_type);
        if let Some(resolved) = cfg.resolve(operation, &entity) {
            return Ok(resolved);
        }
    }
    anyhow::bail!(
        "Mutation '{mutation_name}' has no `sql_source` and no `[crud]` naming config \
         could resolve it (operation = {operation:?}, return_type = {return_type:?}). \
         Either add `sql_source` to the mutation or configure `[crud]` in fraiseql.toml."
    )
}

/// Schema merger combining language types and TOML config
pub struct SchemaMerger;

impl SchemaMerger {
    /// Merge types.json file with TOML configuration
    ///
    /// # Arguments
    /// * `types_path` - Path to types.json (from language implementation)
    /// * `toml_path` - Path to fraiseql.toml (configuration)
    ///
    /// # Returns
    /// Combined `IntermediateSchema`.
    ///
    /// # Errors
    ///
    /// Returns an error if either file cannot be read or parsed, or if the
    /// merged result cannot be deserialized into an `IntermediateSchema`.
    pub fn merge_files(types_path: &str, toml_path: &str) -> Result<IntermediateSchema> {
        // Load types.json
        let types_json = fs::read_to_string(types_path)
            .context(format!("Failed to read types.json from {types_path}"))?;
        let types_value: Value =
            serde_json::from_str(&types_json).context("Failed to parse types.json")?;

        // Load TOML
        let toml_schema = TomlSchema::from_file(toml_path)
            .context(format!("Failed to load TOML from {toml_path}"))?;

        // Note: TOML validation is skipped here because queries may reference types
        // from types.json (not yet loaded). Validation happens in the compiler after merge.

        // Merge
        Self::merge_values(&types_value, &toml_schema)
    }

    /// Merge TOML-only (no types.json)
    ///
    /// # Arguments
    /// * `toml_path` - Path to fraiseql.toml with inline type definitions
    ///
    /// # Returns
    /// `IntermediateSchema` from TOML definitions.
    ///
    /// # Errors
    ///
    /// Returns an error if the TOML file cannot be loaded, if validation fails,
    /// or if the merged result cannot be deserialized into an `IntermediateSchema`.
    pub fn merge_toml_only(toml_path: &str) -> Result<IntermediateSchema> {
        let toml_schema = TomlSchema::from_file(toml_path)
            .context(format!("Failed to load TOML from {toml_path}"))?;

        toml_schema.validate()?;

        // Convert TOML to intermediate schema
        let types_value = toml_schema.to_intermediate_schema();
        Self::merge_values(&types_value, &toml_schema)
    }

    /// Merge from directory with auto-discovery
    ///
    /// # Arguments
    /// * `toml_path` - Path to fraiseql.toml (configuration)
    /// * `schema_dir` - Path to directory containing schema files
    ///
    /// # Returns
    /// `IntermediateSchema` from loaded files + TOML definitions.
    ///
    /// # Errors
    ///
    /// Returns an error if either file cannot be loaded or validated, if the
    /// directory cannot be read, or if the merged result cannot be deserialized.
    pub fn merge_from_directory(toml_path: &str, schema_dir: &str) -> Result<IntermediateSchema> {
        let toml_schema = TomlSchema::from_file(toml_path)
            .context(format!("Failed to load TOML from {toml_path}"))?;

        toml_schema.validate()?;

        // Load all files from directory
        let types_value = crate::schema::MultiFileLoader::load_from_directory(schema_dir)
            .context(format!("Failed to load schema from directory {schema_dir}"))?;

        // Merge with TOML definitions
        Self::merge_values(&types_value, &toml_schema)
    }

    /// Load a named section from a set of files, returning `None` when the list is empty.
    fn load_section(files: &[String], key: &str) -> Result<Option<serde_json::Value>> {
        if files.is_empty() {
            return Ok(None);
        }
        let paths: Vec<std::path::PathBuf> = files.iter().map(std::path::PathBuf::from).collect();
        let loaded = crate::schema::MultiFileLoader::load_from_paths(&paths)
            .with_context(|| format!("Failed to load {key} files"))?;
        Ok(loaded.get(key).cloned())
    }

    /// Parse a JSON file and extend the target vectors with its `types`, `queries`, and
    /// `mutations` arrays. Missing keys are silently skipped.
    fn extend_from_json_file(
        path: &std::path::Path,
        all_types: &mut Vec<Value>,
        all_queries: &mut Vec<Value>,
        all_mutations: &mut Vec<Value>,
    ) -> Result<()> {
        let content = fs::read_to_string(path)
            .with_context(|| format!("Failed to read {}", path.display()))?;
        let value: Value = serde_json::from_str(&content)
            .with_context(|| format!("Failed to parse {}", path.display()))?;
        for (vec, key) in [
            (all_types as &mut Vec<Value>, "types"),
            (all_queries, "queries"),
            (all_mutations, "mutations"),
        ] {
            if let Some(Value::Array(items)) = value.get(key) {
                vec.extend(items.iter().cloned());
            }
        }
        Ok(())
    }

    /// Apply TOML metadata (`sql_source`, `description`) to a type JSON object in place.
    fn enrich_type_from_toml(
        enriched_type: &mut Value,
        toml_type: &crate::config::toml_schema::TypeDefinition,
    ) {
        enriched_type["sql_source"] = json!(toml_type.sql_source);
        if let Some(desc) = &toml_type.description {
            enriched_type["description"] = json!(desc);
        }
    }

    /// Merge explicit file lists
    ///
    /// # Arguments
    /// * `toml_path` - Path to fraiseql.toml (configuration)
    /// * `type_files` - Vector of type file paths
    /// * `query_files` - Vector of query file paths
    /// * `mutation_files` - Vector of mutation file paths
    ///
    /// # Returns
    /// IntermediateSchema from loaded files + TOML definitions
    ///
    /// # Errors
    ///
    /// Returns an error if the TOML file cannot be loaded or validated, or if any
    /// of the type/query/mutation files fail to load or parse.
    pub fn merge_explicit_files(
        toml_path: &str,
        type_files: &[String],
        query_files: &[String],
        mutation_files: &[String],
    ) -> Result<IntermediateSchema> {
        let toml_schema = TomlSchema::from_file(toml_path)
            .context(format!("Failed to load TOML from {toml_path}"))?;

        toml_schema.validate()?;

        let mut types_value = serde_json::json!({
            "types": [],
            "queries": [],
            "mutations": []
        });

        if let Some(v) = Self::load_section(type_files, "types")? {
            types_value["types"] = v;
        }
        if let Some(v) = Self::load_section(query_files, "queries")? {
            types_value["queries"] = v;
        }
        if let Some(v) = Self::load_section(mutation_files, "mutations")? {
            types_value["mutations"] = v;
        }

        Self::merge_values(&types_value, &toml_schema)
    }

    /// Merge from domains (domain-based organization)
    ///
    /// # Arguments
    /// * `toml_path` - Path to fraiseql.toml with domain_discovery enabled
    ///
    /// # Returns
    /// `IntermediateSchema` from all domains (types.json, queries.json, mutations.json).
    ///
    /// # Errors
    ///
    /// Returns an error if the TOML cannot be loaded or validated, if domain
    /// discovery fails, if any domain file cannot be parsed, or if the merged
    /// result cannot be deserialized.
    pub fn merge_from_domains(toml_path: &str) -> Result<IntermediateSchema> {
        let toml_schema = TomlSchema::from_file(toml_path)
            .context(format!("Failed to load TOML from {toml_path}"))?;

        toml_schema.validate()?;

        // Resolve domains from configuration
        let domains = toml_schema
            .domain_discovery
            .resolve_domains()
            .context("Failed to discover domains")?;

        if domains.is_empty() {
            // No domains found, return empty schema merged with TOML definitions
            let empty_value = serde_json::json!({
                "types": [],
                "queries": [],
                "mutations": []
            });
            return Self::merge_values(&empty_value, &toml_schema);
        }

        let mut all_types = Vec::new();
        let mut all_queries = Vec::new();
        let mut all_mutations = Vec::new();

        for domain in domains {
            for filename in ["types.json", "queries.json", "mutations.json"] {
                let path = domain.path.join(filename);
                if path.exists() {
                    Self::extend_from_json_file(
                        &path,
                        &mut all_types,
                        &mut all_queries,
                        &mut all_mutations,
                    )?;
                }
            }
        }

        let types_value = serde_json::json!({
            "types": all_types,
            "queries": all_queries,
            "mutations": all_mutations,
        });

        // Merge with TOML definitions
        Self::merge_values(&types_value, &toml_schema)
    }

    /// Merge with TOML includes (glob patterns for schema files)
    ///
    /// # Arguments
    /// * `toml_path` - Path to fraiseql.toml with schema.includes section
    ///
    /// # Returns
    /// `IntermediateSchema` from loaded files + TOML definitions.
    ///
    /// # Errors
    ///
    /// Returns an error if the TOML cannot be loaded or validated, if any glob
    /// pattern is invalid, if a matched file cannot be parsed, or if the merged
    /// result cannot be deserialized.
    pub fn merge_with_includes(toml_path: &str) -> Result<IntermediateSchema> {
        let toml_schema = TomlSchema::from_file(toml_path)
            .context(format!("Failed to load TOML from {toml_path}"))?;

        toml_schema.validate()?;

        // If includes are specified, load and merge files
        let types_value = if toml_schema.includes.is_empty() {
            // No includes specified, use empty schema
            serde_json::json!({
                "types": [],
                "queries": [],
                "mutations": []
            })
        } else {
            let resolved = toml_schema
                .includes
                .resolve_globs()
                .context("Failed to resolve glob patterns in schema.includes")?;

            // Load all type files
            let type_files: Vec<std::path::PathBuf> = resolved.types;
            let mut merged_types = if type_files.is_empty() {
                serde_json::json!({
                    "types": [],
                    "queries": [],
                    "mutations": []
                })
            } else {
                crate::schema::MultiFileLoader::load_from_paths(&type_files)
                    .context("Failed to load type files")?
            };

            // Load and merge query files
            if !resolved.queries.is_empty() {
                let loaded = crate::schema::MultiFileLoader::load_from_paths(&resolved.queries)
                    .context("Failed to load query files")?;
                let new_items =
                    loaded.get("queries").and_then(Value::as_array).cloned().unwrap_or_default();
                if let Some(Value::Array(existing)) = merged_types.get_mut("queries") {
                    existing.extend(new_items);
                }
            }

            // Load and merge mutation files
            if !resolved.mutations.is_empty() {
                let loaded = crate::schema::MultiFileLoader::load_from_paths(&resolved.mutations)
                    .context("Failed to load mutation files")?;
                let new_items =
                    loaded.get("mutations").and_then(Value::as_array).cloned().unwrap_or_default();
                if let Some(Value::Array(existing)) = merged_types.get_mut("mutations") {
                    existing.extend(new_items);
                }
            }

            merged_types
        };

        // Merge with TOML definitions
        Self::merge_values(&types_value, &toml_schema)
    }

    /// Merge JSON types with TOML schema
    #[allow(clippy::cognitive_complexity)] // Reason: deep merge of two schema formats with many field-level transformations
    fn merge_values(types_value: &Value, toml_schema: &TomlSchema) -> Result<IntermediateSchema> {
        // Typo guard: [queries.defaults] is a common mistake for [query_defaults].
        if toml_schema.queries.contains_key("defaults") {
            anyhow::bail!(
                "Found a query definition named 'defaults' under [queries.defaults]. \
                 Did you mean [query_defaults] to set global auto-param defaults?\n\
                 If you intended a query called 'defaults', rename it to avoid confusion."
            );
        }

        // Start with arrays for types, queries, mutations (not objects!)
        // This matches IntermediateSchema structure which uses Vec<T>
        let mut types_array: Vec<Value> = Vec::new();
        let mut queries_array: Vec<Value> = Vec::new();
        let mut mutations_array: Vec<Value> = Vec::new();

        // Process types from types.json (comes as array from language SDKs)
        if let Some(types_obj) = types_value.get("types") {
            match types_obj {
                // Handle array format (from language SDKs)
                Value::Array(types_list) => {
                    for type_item in types_list {
                        if let Some(type_name) = type_item.get("name").and_then(|v| v.as_str()) {
                            let mut enriched_type = type_item.clone();
                            if let Some(toml_type) = toml_schema.types.get(type_name) {
                                Self::enrich_type_from_toml(&mut enriched_type, toml_type);
                            }
                            types_array.push(enriched_type);
                        }
                    }
                },
                // Handle object format (from TOML-only, for backward compatibility)
                Value::Object(types_map) => {
                    for (type_name, type_value) in types_map {
                        let mut enriched_type = type_value.clone();
                        enriched_type["name"] = json!(type_name);

                        // Convert fields from object to array format if needed
                        if let Some(Value::Object(fields_map)) = enriched_type.get("fields") {
                            let fields_array: Vec<Value> = fields_map
                                .iter()
                                .map(|(field_name, field_value)| {
                                    let mut field = field_value.clone();
                                    field["name"] = json!(field_name);
                                    field
                                })
                                .collect();
                            enriched_type["fields"] = json!(fields_array);
                        }

                        if let Some(toml_type) = toml_schema.types.get(type_name) {
                            Self::enrich_type_from_toml(&mut enriched_type, toml_type);
                        }

                        types_array.push(enriched_type);
                    }
                },
                _ => {},
            }
        }

        // Add types from TOML that aren't already in types_array
        let existing_type_names: std::collections::HashSet<_> = types_array
            .iter()
            .filter_map(|t| t.get("name").and_then(|v| v.as_str()).map(str::to_string))
            .collect();

        for (type_name, toml_type) in &toml_schema.types {
            if !existing_type_names.contains(type_name) {
                types_array.push(json!({
                    "name": type_name,
                    "sql_source": toml_type.sql_source,
                    "description": toml_type.description,
                    "fields": toml_type.fields.iter().map(|(fname, fdef)| {
                        let mut field = json!({
                            "name": fname,
                            "type": fdef.field_type,
                            "nullable": fdef.nullable,
                            "description": fdef.description,
                        });
                        if let Some(ref h) = fdef.hierarchy {
                            field["hierarchy"] = json!(h);
                        }
                        field
                    }).collect::<Vec<_>>(),
                }));
            }
        }

        if let Some(Value::Array(queries_list)) = types_value.get("queries") {
            queries_array.clone_from(queries_list);
        }

        // Add queries from TOML
        for (query_name, toml_query) in &toml_schema.queries {
            queries_array.push(json!({
                "name": query_name,
                "return_type": toml_query.return_type,
                "returns_list": toml_query.return_array,
                "sql_source": toml_query.sql_source,
                "description": toml_query.description,
                "args": toml_query.args.iter().map(|arg| json!({
                    "name": arg.name,
                    "type": arg.arg_type,
                    "required": arg.required,
                    "default": arg.default,
                    "description": arg.description,
                })).collect::<Vec<_>>(),
            }));
        }

        if let Some(Value::Array(mutations_list)) = types_value.get("mutations") {
            mutations_array.clone_from(mutations_list);
        }

        // Add mutations from TOML
        for (mutation_name, toml_mutation) in &toml_schema.mutations {
            let sql_source = resolve_mutation_sql_source(
                mutation_name,
                toml_mutation.sql_source.as_deref(),
                &toml_mutation.operation,
                &toml_mutation.return_type,
                toml_schema.crud.as_ref(),
            )?;
            mutations_array.push(json!({
                "name": mutation_name,
                "return_type": toml_mutation.return_type,
                "sql_source": sql_source,
                "operation": toml_mutation.operation,
                "description": toml_mutation.description,
                "args": toml_mutation.args.iter().map(|arg| json!({
                    "name": arg.name,
                    "type": arg.arg_type,
                    "required": arg.required,
                    "default": arg.default,
                    "description": arg.description,
                })).collect::<Vec<_>>(),
            }));
        }

        // Build merged schema with arrays
        let mut merged = serde_json::json!({
            "version": "2.0.0",
            "types": types_array,
            "queries": queries_array,
            "mutations": mutations_array,
        });

        // Warn when PKCE is enabled without state encryption (insecure configuration).
        if let Some(pkce) = &toml_schema.security.pkce {
            if pkce.enabled {
                let enc_enabled =
                    toml_schema.security.state_encryption.as_ref().is_some_and(|e| e.enabled);
                if !enc_enabled {
                    tracing::warn!(
                        "pkce.enabled = true but state_encryption.enabled = false. \
                         PKCE state will be stored unencrypted. \
                         Set [security.state_encryption] enabled = true for production."
                    );
                }
            }
        }

        // Add security configuration if available in TOML
        merged["security"] = json!({
            "default_policy": toml_schema.security.default_policy,
            "rules": toml_schema.security.rules.iter().map(|r| json!({
                "name": r.name,
                "rule": r.rule,
                "description": r.description,
                "cacheable": r.cacheable,
                "cache_ttl_seconds": r.cache_ttl_seconds,
            })).collect::<Vec<_>>(),
            "policies": toml_schema.security.policies.iter().map(|p| json!({
                "name": p.name,
                "type": p.policy_type,
                "rule": p.rule,
                "roles": p.roles,
                "strategy": p.strategy,
                "attributes": p.attributes,
                "description": p.description,
                "cache_ttl_seconds": p.cache_ttl_seconds,
            })).collect::<Vec<_>>(),
            "field_auth": toml_schema.security.field_auth.iter().map(|fa| json!({
                "type_name": fa.type_name,
                "field_name": fa.field_name,
                "policy": fa.policy,
            })).collect::<Vec<_>>(),
            "enterprise": json!({
                "rate_limiting_enabled": toml_schema.security.enterprise.rate_limiting_enabled,
                "auth_endpoint_max_requests": toml_schema.security.enterprise.auth_endpoint_max_requests,
                "auth_endpoint_window_seconds": toml_schema.security.enterprise.auth_endpoint_window_seconds,
                "audit_logging_enabled": toml_schema.security.enterprise.audit_logging_enabled,
                "audit_log_backend": toml_schema.security.enterprise.audit_log_backend,
                "audit_retention_days": toml_schema.security.enterprise.audit_retention_days,
                "error_sanitization": toml_schema.security.enterprise.error_sanitization,
                "hide_implementation_details": toml_schema.security.enterprise.hide_implementation_details,
                "constant_time_comparison": toml_schema.security.enterprise.constant_time_comparison,
                "pkce_enabled": toml_schema.security.enterprise.pkce_enabled,
            }),
            "error_sanitization": toml_schema.security.error_sanitization,
            "rate_limiting": toml_schema.security.rate_limiting,
            "state_encryption": toml_schema.security.state_encryption,
            "pkce": toml_schema.security.pkce,
            "api_keys": toml_schema.security.api_keys,
            "token_revocation": toml_schema.security.token_revocation,
            "trusted_documents": toml_schema.security.trusted_documents,
        });

        // Embed observers configuration if enabled or if any backend URL is set
        if toml_schema.observers.enabled
            || toml_schema.observers.redis_url.is_some()
            || toml_schema.observers.nats_url.is_some()
        {
            if toml_schema.observers.backend == "nats" && toml_schema.observers.nats_url.is_none() {
                tracing::warn!(
                    "observers.backend is \"nats\" but observers.nats_url is not set; \
                     the runtime will require FRAISEQL_NATS_URL to be configured"
                );
            }
            merged["observers_config"] = json!({
                "enabled": toml_schema.observers.enabled,
                "backend": toml_schema.observers.backend,
                "redis_url": toml_schema.observers.redis_url,
                "nats_url": toml_schema.observers.nats_url,
                "handlers": toml_schema.observers.handlers.iter().map(|h| json!({
                    "name": h.name,
                    "event": h.event,
                    "action": h.action,
                    "webhook_url": h.webhook_url,
                    "retry_strategy": h.retry_strategy,
                    "max_retries": h.max_retries,
                    "description": h.description,
                })).collect::<Vec<_>>(),
            });
        }

        // Embed federation configuration if enabled
        if toml_schema.federation.enabled {
            merged["federation_config"] = serde_json::to_value(&toml_schema.federation)
                .context("Failed to serialize federation config")?;
        }

        // Embed subscriptions configuration (hooks, limits)
        let subs_json = serde_json::to_value(&toml_schema.subscriptions)
            .context("Failed to serialize subscriptions config")?;
        if subs_json != serde_json::json!({}) {
            merged["subscriptions_config"] = subs_json;
        }

        // Embed validation config (depth/complexity limits)
        let val_json = serde_json::to_value(&toml_schema.validation)
            .context("Failed to serialize validation config")?;
        if val_json != serde_json::json!({}) {
            merged["validation_config"] = val_json;
        }

        // Embed debug config when enabled
        if toml_schema.debug.enabled {
            let debug_json = serde_json::to_value(&toml_schema.debug)
                .context("Failed to serialize debug config")?;
            merged["debug_config"] = debug_json;
        }

        // Embed MCP config when enabled
        if toml_schema.mcp.enabled {
            merged["mcp_config"] =
                serde_json::to_value(&toml_schema.mcp).context("Failed to serialize MCP config")?;
        }

        // Embed REST config when enabled (with path validation)
        if toml_schema.rest.enabled {
            let path = &toml_schema.rest.path;
            if !path.starts_with('/') {
                anyhow::bail!("REST config: `path` must start with '/' (got {path:?})");
            }

            let rest_config: fraiseql_core::schema::RestConfig = toml_schema.rest.clone().into();

            merged["rest_config"] =
                serde_json::to_value(&rest_config).context("Failed to serialize REST config")?;
        }

        // Embed naming convention
        merged["naming_convention"] = serde_json::to_value(toml_schema.naming_convention)
            .context("Failed to serialize naming_convention")?;

        // Embed hierarchy definitions for ID-based ltree operators
        if let Some(ref hierarchies) = toml_schema.hierarchies {
            merged["hierarchies_config"] = serde_json::to_value(hierarchies)
                .context("Failed to serialize hierarchies config")?;
        }

        // Convert to IntermediateSchema
        let mut schema = serde_json::from_value::<IntermediateSchema>(merged)
            .context("Failed to convert merged schema to IntermediateSchema")?;

        // Inject TOML [query_defaults] into the schema so the converter can apply
        // them as project-wide fallbacks for list-query auto-params.
        schema.query_defaults = Some(IntermediateQueryDefaults {
            where_clause: toml_schema.query_defaults.where_clause,
            order_by:     toml_schema.query_defaults.order_by,
            limit:        toml_schema.query_defaults.limit,
            offset:       toml_schema.query_defaults.offset,
        });

        Ok(schema)
    }
}