mockforge_openapi/

spec.rs

//! OpenAPI specification loading and parsing
//!
//! This module handles loading OpenAPI specifications from files,
//! parsing them, and providing basic operations on the specs.
//! It also supports Swagger 2.0 specifications by converting them
//! to OpenAPI 3.0 format automatically.

use crate::swagger_convert;
use mockforge_foundation::error::{Error, Result};
use openapiv3::{OpenAPI, ReferenceOr, Schema};
use std::collections::HashSet;
use std::path::Path;
use tokio::fs;
use tracing;

/// HTTP methods that make a `paths.<path>.<key>` entry an Operation Object.
const OPERATION_KEYS: [&str; 8] = [
    "get", "put", "post", "delete", "options", "head", "patch", "trace",
];

/// Insert an empty `responses` object into any operation that lacks one,
/// returning how many were repaired.
///
/// OpenAPI 3.x marks `responses` as REQUIRED on an Operation Object, and the
/// `openapiv3` crate enforces that, so a spec missing it fails to deserialize
/// with a bare `missing field \`responses\`` and no indication of WHERE. Specs
/// emitted by proxies and API-discovery tools routinely omit it: they observe
/// requests, so they know paths, methods and schemas, but have nothing to say
/// about responses.
///
/// Refusing those specs outright is the wrong trade for this codebase. Request
/// generation, load testing and conformance probing all derive from paths,
/// parameters and `requestBody`; none of them read `responses`. So a missing
/// `responses` costs nothing we actually use, while rejecting the document
/// costs the user their entire run.
///
/// Reported by Srikanth on #79: a proxy-generated spec where 63 of 70
/// operations had no `responses` failed to load at all.
///
/// The repair is deliberately narrow. It only fills in a field the spec says is
/// mandatory, never invents response *content*, and leaves every other
/// validation error to surface normally.
fn fill_missing_operation_responses(raw: &mut serde_json::Value) -> usize {
    let Some(paths) = raw.get_mut("paths").and_then(|p| p.as_object_mut()) else {
        return 0;
    };

    let mut repaired = 0;
    for (_path, item) in paths.iter_mut() {
        let Some(item) = item.as_object_mut() else {
            continue;
        };
        for method in OPERATION_KEYS {
            let Some(op) = item.get_mut(method).and_then(|o| o.as_object_mut()) else {
                continue;
            };
            if !op.contains_key("responses") {
                op.insert(
                    "responses".to_string(),
                    serde_json::Value::Object(serde_json::Map::new()),
                );
                repaired += 1;
            }
        }
    }
    repaired
}

/// JSON Schema primitive names that OAS 3.1 may put in a `type` array.
/// Anything else under a key named `type` is left alone (security schemes
/// use a string; vendor junk should not be rewritten).
const JSON_SCHEMA_TYPE_NAMES: &[&str] = &[
    "null", "boolean", "object", "array", "number", "string", "integer",
];

fn is_json_schema_type_name(name: &str) -> bool {
    JSON_SCHEMA_TYPE_NAMES.contains(&name)
}

/// Convert OAS 3.1 JSON Schema `type` arrays into OAS 3.0 `type` + `nullable`.
///
/// `openapiv3` deserializes schema `type` as a string. OAS 3.1 (JSON Schema
/// 2020-12) allows `type: ["string", "null"]`. LLM-generated specs do this
/// constantly. Serde then fails with `invalid type: sequence, expected a
/// string` and no JSON path, so a 1.8MB document is unusable.
///
/// Reported by Srikanth on #79 (i): `custom_limit_oas.json` (openapi 3.1.0)
/// had exactly two such arrays (`taxId`, `nickname`) and `mockforge bench`
/// died before extracting any of its 1750 operations.
///
/// The repair is narrow:
/// - only rewrite `type` when every array element is a JSON Schema type name
/// - `["string", "null"]` (either order) becomes `type: "string"` plus
///   `nullable: true`
/// - `["string"]` becomes `type: "string"`
/// - a union of two non-null primitives takes the first; `openapiv3` cannot
///   represent that union, and failing the whole spec is worse
/// - `required: ["a", "b"]` and other string arrays are not `type`, so they
///   are not touched
fn coerce_json_schema_type_arrays(raw: &mut serde_json::Value) -> usize {
    fn walk(value: &mut serde_json::Value) -> usize {
        let mut repaired = 0;
        match value {
            serde_json::Value::Object(map) => {
                repaired += coerce_type_array_in_object(map);
                for child in map.values_mut() {
                    repaired += walk(child);
                }
            }
            serde_json::Value::Array(items) => {
                for child in items {
                    repaired += walk(child);
                }
            }
            _ => {}
        }
        repaired
    }
    walk(raw)
}

fn coerce_type_array_in_object(map: &mut serde_json::Map<String, serde_json::Value>) -> usize {
    let Some(serde_json::Value::Array(items)) = map.get("type") else {
        return 0;
    };
    if items.is_empty() {
        return 0;
    }

    // Reject anything that is not a JSON Schema type-name array. A `required`
    // list lives under a different key; this guard is for a `type` that
    // happens to be an array of something else.
    let mut names = Vec::with_capacity(items.len());
    for item in items {
        let Some(name) = item.as_str() else {
            return 0;
        };
        if !is_json_schema_type_name(name) {
            return 0;
        }
        names.push(name.to_string());
    }

    let nullable = names.iter().any(|n| n == "null");
    let mut non_null = names.into_iter().filter(|n| n != "null");
    // `type: ["null"]` has no remaining primitive. `string` is the least-wrong
    // stand-in so the document still deserializes.
    let primary = non_null.next().unwrap_or_else(|| "string".to_string());

    map.insert("type".to_string(), serde_json::Value::String(primary));
    if nullable {
        // OAS 3.0 equivalent of including "null" in a 3.1 type union.
        map.insert("nullable".to_string(), serde_json::Value::Bool(true));
    }
    1
}

/// Apply [`fill_missing_operation_responses`] and
/// [`coerce_json_schema_type_arrays`], warning once per kind so a
/// non-conformant spec is visible rather than silently accepted.
fn repair_spec_for_parsing(raw: &mut serde_json::Value, source: &str) {
    let repaired = fill_missing_operation_responses(raw);
    if repaired > 0 {
        tracing::warn!(
            "{source}: {repaired} operation(s) had no `responses` field, which OpenAPI 3.x \
             requires. Treating them as having no declared responses so the spec can load. \
             Request generation does not use `responses`, but response-schema validation \
             will have nothing to check for these operations."
        );
    }

    let type_arrays = coerce_json_schema_type_arrays(raw);
    if type_arrays > 0 {
        tracing::warn!(
            "{source}: {type_arrays} schema `type` value(s) were OpenAPI 3.1 type arrays \
             (for example `[\"string\", \"null\"]`). Coerced them to OpenAPI 3.0 `type` + \
             `nullable` so the spec can load."
        );
    }
}

/// OpenAPI specification loader and parser
#[derive(Debug, Clone)]
pub struct OpenApiSpec {
    /// The parsed OpenAPI specification
    pub spec: OpenAPI,
    /// Path to the original spec file
    pub file_path: Option<String>,
    /// Raw OpenAPI document preserved as JSON for resolving unsupported constructs
    pub raw_document: Option<serde_json::Value>,
}

impl OpenApiSpec {
    /// Load OpenAPI spec from a file path
    ///
    /// Supports both OpenAPI 3.x and Swagger 2.0 specifications.
    /// Swagger 2.0 specs are automatically converted to OpenAPI 3.0 format.
    pub async fn from_file<P: AsRef<Path>>(path: P) -> Result<Self> {
        let path_ref = path.as_ref();
        let content = fs::read_to_string(path_ref)
            .await
            .map_err(|e| Error::io_with_context("reading OpenAPI spec file", e.to_string()))?;

        let raw_json = if path_ref.extension().and_then(|s| s.to_str()) == Some("yaml")
            || path_ref.extension().and_then(|s| s.to_str()) == Some("yml")
        {
            let yaml_value: serde_yaml::Value = serde_yaml::from_str(&content)
                .map_err(|e| Error::config(format!("Failed to parse YAML OpenAPI spec: {}", e)))?;
            serde_json::to_value(&yaml_value).map_err(|e| {
                Error::config(format!("Failed to convert YAML OpenAPI spec to JSON: {}", e))
            })?
        } else {
            serde_json::from_str(&content)
                .map_err(|e| Error::config(format!("Failed to parse JSON OpenAPI spec: {}", e)))?
        };

        // Check if this is a Swagger 2.0 spec and convert if necessary
        let (raw_document, spec) = if swagger_convert::is_swagger_2(&raw_json) {
            tracing::info!("Detected Swagger 2.0 specification, converting to OpenAPI 3.0");
            let converted =
                swagger_convert::convert_swagger_to_openapi3(&raw_json).map_err(|e| {
                    Error::config(format!("Failed to convert Swagger 2.0 to OpenAPI 3.0: {}", e))
                })?;
            let spec: OpenAPI = serde_json::from_value(converted.clone()).map_err(|e| {
                Error::config(format!("Failed to parse converted OpenAPI spec: {}", e))
            })?;
            (converted, spec)
        } else {
            let mut raw_json = raw_json;
            repair_spec_for_parsing(&mut raw_json, "OpenAPI spec");
            let spec: OpenAPI = serde_json::from_value(raw_json.clone()).map_err(|e| {
                // Enhanced error reporting for debugging missing field errors
                let error_str = format!("{}", e);
                let mut error_msg = format!("Failed to read OpenAPI spec: {}", e);

                // If it's a missing field error, add diagnostic information
                if error_str.contains("missing field") {
                    tracing::error!("OpenAPI deserialization error: {}", error_str);

                    // Add context about the spec structure
                    if let Some(info) = raw_json.get("info") {
                        if let Some(info_obj) = info.as_object() {
                            let has_desc = info_obj.contains_key("description");
                            error_msg
                                .push_str(&format!(" | Info.description present: {}", has_desc));
                        }
                    }
                    if let Some(servers) = raw_json.get("servers") {
                        if let Some(servers_arr) = servers.as_array() {
                            error_msg.push_str(&format!(" | Servers count: {}", servers_arr.len()));
                        }
                    }
                }

                Error::config(error_msg)
            })?;
            (raw_json, spec)
        };

        Ok(Self {
            spec,
            file_path: path_ref.to_str().map(|s| s.to_string()),
            raw_document: Some(raw_document),
        })
    }

    /// Load OpenAPI spec from string content
    ///
    /// Supports both OpenAPI 3.x and Swagger 2.0 specifications.
    /// Swagger 2.0 specs are automatically converted to OpenAPI 3.0 format.
    pub fn from_string(content: &str, format: Option<&str>) -> Result<Self> {
        let raw_json = if format == Some("yaml") || format == Some("yml") {
            let yaml_value: serde_yaml::Value = serde_yaml::from_str(content)
                .map_err(|e| Error::config(format!("Failed to parse YAML OpenAPI spec: {}", e)))?;
            serde_json::to_value(&yaml_value).map_err(|e| {
                Error::config(format!("Failed to convert YAML OpenAPI spec to JSON: {}", e))
            })?
        } else {
            serde_json::from_str(content)
                .map_err(|e| Error::config(format!("Failed to parse JSON OpenAPI spec: {}", e)))?
        };

        // Check if this is a Swagger 2.0 spec and convert if necessary
        let (raw_document, spec) = if swagger_convert::is_swagger_2(&raw_json) {
            let converted =
                swagger_convert::convert_swagger_to_openapi3(&raw_json).map_err(|e| {
                    Error::config(format!("Failed to convert Swagger 2.0 to OpenAPI 3.0: {}", e))
                })?;
            let spec: OpenAPI = serde_json::from_value(converted.clone()).map_err(|e| {
                Error::config(format!("Failed to parse converted OpenAPI spec: {}", e))
            })?;
            (converted, spec)
        } else {
            let mut raw_json = raw_json;
            repair_spec_for_parsing(&mut raw_json, "OpenAPI spec");
            let spec: OpenAPI = serde_json::from_value(raw_json.clone())
                .map_err(|e| Error::io_with_context("reading OpenAPI spec", e.to_string()))?;
            (raw_json, spec)
        };

        Ok(Self {
            spec,
            file_path: None,
            raw_document: Some(raw_document),
        })
    }

    /// Load OpenAPI spec from JSON value
    ///
    /// Supports both OpenAPI 3.x and Swagger 2.0 specifications.
    /// Swagger 2.0 specs are automatically converted to OpenAPI 3.0 format.
    pub fn from_json(json: serde_json::Value) -> Result<Self> {
        // Check if this is a Swagger 2.0 spec and convert if necessary
        let (raw_document, spec) = if swagger_convert::is_swagger_2(&json) {
            let converted = swagger_convert::convert_swagger_to_openapi3(&json).map_err(|e| {
                Error::config(format!("Failed to convert Swagger 2.0 to OpenAPI 3.0: {}", e))
            })?;
            let spec: OpenAPI = serde_json::from_value(converted.clone()).map_err(|e| {
                Error::config(format!("Failed to parse converted OpenAPI spec: {}", e))
            })?;
            (converted, spec)
        } else {
            let mut json = json;
            repair_spec_for_parsing(&mut json, "OpenAPI spec");
            let spec: OpenAPI = serde_json::from_value(json.clone())
                .map_err(|e| Error::config(format!("Failed to parse JSON OpenAPI spec: {}", e)))?;
            (json, spec)
        };

        Ok(Self {
            spec,
            file_path: None,
            raw_document: Some(raw_document),
        })
    }

    /// Validate the OpenAPI specification
    ///
    /// This method provides basic validation. For comprehensive validation
    /// with detailed error messages, use `spec_parser::OpenApiValidator::validate()`.
    pub fn validate(&self) -> Result<()> {
        // Basic validation - check that we have at least one path
        if self.spec.paths.paths.is_empty() {
            return Err(Error::validation("OpenAPI spec must contain at least one path"));
        }

        // Check that info section has required fields
        if self.spec.info.title.is_empty() {
            return Err(Error::validation("OpenAPI spec info must have a title"));
        }

        if self.spec.info.version.is_empty() {
            return Err(Error::validation("OpenAPI spec info must have a version"));
        }

        Ok(())
    }

    /// Enhanced validation with detailed error reporting
    pub fn validate_enhanced(&self) -> crate::spec_parser::ValidationResult {
        // Convert to JSON value for enhanced validator
        if let Some(raw) = &self.raw_document {
            let format = if raw.get("swagger").is_some() {
                crate::spec_parser::SpecFormat::OpenApi20
            } else if let Some(version) = raw.get("openapi").and_then(|v| v.as_str()) {
                if version.starts_with("3.1") {
                    crate::spec_parser::SpecFormat::OpenApi31
                } else {
                    crate::spec_parser::SpecFormat::OpenApi30
                }
            } else {
                // Default to 3.0 if we can't determine
                crate::spec_parser::SpecFormat::OpenApi30
            };
            crate::spec_parser::OpenApiValidator::validate(raw, format)
        } else {
            // Fallback to basic validation if no raw document
            crate::spec_parser::ValidationResult::failure(vec![
                crate::spec_parser::ValidationError::new(
                    "Cannot perform enhanced validation without raw document".to_string(),
                ),
            ])
        }
    }

    /// Get the OpenAPI version
    pub fn version(&self) -> &str {
        &self.spec.openapi
    }

    /// Get the API title
    pub fn title(&self) -> &str {
        &self.spec.info.title
    }

    /// Get the API description
    pub fn description(&self) -> Option<&str> {
        self.spec.info.description.as_deref()
    }

    /// Get the API version
    pub fn api_version(&self) -> &str {
        &self.spec.info.version
    }

    /// Get the server URLs
    pub fn servers(&self) -> &[openapiv3::Server] {
        &self.spec.servers
    }

    /// Get all paths defined in the spec
    pub fn paths(&self) -> &openapiv3::Paths {
        &self.spec.paths
    }

    /// Get all schemas defined in the spec
    pub fn schemas(&self) -> Option<&indexmap::IndexMap<String, ReferenceOr<Schema>>> {
        self.spec.components.as_ref().map(|c| &c.schemas)
    }

    /// Get all security schemes defined in the spec
    pub fn security_schemes(
        &self,
    ) -> Option<&indexmap::IndexMap<String, ReferenceOr<openapiv3::SecurityScheme>>> {
        self.spec.components.as_ref().map(|c| &c.security_schemes)
    }

    /// Get all operations for a given path
    pub fn operations_for_path(
        &self,
        path: &str,
    ) -> std::collections::HashMap<String, openapiv3::Operation> {
        let mut operations = std::collections::HashMap::new();

        if let Some(path_item_ref) = self.spec.paths.paths.get(path) {
            // Handle the ReferenceOr<PathItem> case
            if let Some(path_item) = path_item_ref.as_item() {
                // Round 40 (#888 / #79) — Srikanth's Google Apigee
                // spec puts the shared auth / format query
                // parameters at PATH level, not on each operation.
                // OpenAPI 3.0 §4.7.10.1: "Parameters that are
                // included in the Operation Object inherit the
                // parameters defined in the Path Item Object. If a
                // parameter is already defined at the Path Item, the
                // new definition will override it but can never
                // remove it." We materialise that inheritance HERE
                // (the lowest common point under both registry
                // builders), so a request that violates a path-level
                // `enum` or `type: boolean` reaches the validator's
                // parameter loop instead of silently passing. We
                // also resolve `$ref` parameters via
                // `components.parameters` so the validator's loop
                // (which skips `ReferenceOr::Reference` entries via
                // `as_item()`) actually sees them.
                let resolved_path_params: Vec<ReferenceOr<openapiv3::Parameter>> =
                    path_item.parameters.iter().map(|p| self.resolve_parameter_ref(p)).collect();
                let merge = |op: &openapiv3::Operation| -> openapiv3::Operation {
                    // Resolve op-level refs too — same as path-level.
                    let mut resolved_op = op.clone();
                    resolved_op.parameters =
                        op.parameters.iter().map(|p| self.resolve_parameter_ref(p)).collect();
                    merge_path_params_into_operation(&resolved_op, &resolved_path_params)
                };
                if let Some(op) = &path_item.get {
                    operations.insert("GET".to_string(), merge(op));
                }
                if let Some(op) = &path_item.post {
                    operations.insert("POST".to_string(), merge(op));
                }
                if let Some(op) = &path_item.put {
                    operations.insert("PUT".to_string(), merge(op));
                }
                if let Some(op) = &path_item.delete {
                    operations.insert("DELETE".to_string(), merge(op));
                }
                if let Some(op) = &path_item.patch {
                    operations.insert("PATCH".to_string(), merge(op));
                }
                if let Some(op) = &path_item.head {
                    operations.insert("HEAD".to_string(), merge(op));
                }
                if let Some(op) = &path_item.options {
                    operations.insert("OPTIONS".to_string(), merge(op));
                }
                if let Some(op) = &path_item.trace {
                    operations.insert("TRACE".to_string(), merge(op));
                }
            }
        }

        operations
    }

    /// Get all paths with their operations
    pub fn all_paths_and_operations(
        &self,
    ) -> std::collections::HashMap<String, std::collections::HashMap<String, openapiv3::Operation>>
    {
        self.spec
            .paths
            .paths
            .iter()
            .map(|(path, _)| (path.clone(), self.operations_for_path(path)))
            .collect()
    }

    /// Get a schema by reference (returns wrapped OpenApiSchema)
    pub fn get_schema(&self, reference: &str) -> Option<crate::schema::OpenApiSchema> {
        self.resolve_schema(reference).map(crate::schema::OpenApiSchema::new)
    }

    /// Resolve a schema reference to the raw Schema
    ///
    /// This resolves `$ref` references like `#/components/schemas/User` to the
    /// actual schema definition, handling nested references recursively.
    pub fn resolve_schema_ref(&self, reference: &str) -> Option<Schema> {
        self.resolve_schema(reference)
    }

    /// Round 40 (#888 / #79) — resolve a parameter `$ref` (typically
    /// `#/components/parameters/foo`) into the inline `Parameter`
    /// item it points at. Returns the input unchanged when the
    /// reference can't be resolved (e.g. external `$ref`) so the
    /// validator can fall back to its prior behaviour (skip via
    /// `as_item()`) instead of panicking. Used by
    /// `operations_for_path` to materialise refs at registry build
    /// time, since the validator's parameter loop skips
    /// `ReferenceOr::Reference` entries — which was why Srikanth's
    /// Google Apigee spec silently passed every path-level param
    /// violation: the path-level `parameters:` list is entirely
    /// `$ref:` to shared common params like `_.xgafv`,
    /// `prettyPrint`, etc.
    pub fn resolve_parameter_ref(
        &self,
        p_ref: &ReferenceOr<openapiv3::Parameter>,
    ) -> ReferenceOr<openapiv3::Parameter> {
        match p_ref {
            ReferenceOr::Item(_) => p_ref.clone(),
            ReferenceOr::Reference { reference } => {
                let Some(name) = reference.strip_prefix("#/components/parameters/") else {
                    return p_ref.clone();
                };
                let Some(components) = self.spec.components.as_ref() else {
                    return p_ref.clone();
                };
                match components.parameters.get(name) {
                    Some(ReferenceOr::Item(p)) => ReferenceOr::Item(p.clone()),
                    Some(ReferenceOr::Reference { reference: nested }) => {
                        // Tail-resolve a chained ref (rare in practice
                        // but allowed by the spec).
                        let Some(nested_name) = nested.strip_prefix("#/components/parameters/")
                        else {
                            return p_ref.clone();
                        };
                        match components.parameters.get(nested_name) {
                            Some(ReferenceOr::Item(p)) => ReferenceOr::Item(p.clone()),
                            _ => p_ref.clone(),
                        }
                    }
                    None => p_ref.clone(),
                }
            }
        }
    }

    /// Validate security requirements
    pub fn validate_security_requirements(
        &self,
        security_requirements: &[openapiv3::SecurityRequirement],
        auth_header: Option<&str>,
        api_key: Option<&str>,
    ) -> Result<()> {
        if security_requirements.is_empty() {
            return Ok(());
        }

        // Security requirements are OR'd - if any requirement is satisfied, pass
        for requirement in security_requirements {
            if self.is_security_requirement_satisfied(requirement, auth_header, api_key)? {
                return Ok(());
            }
        }

        Err(Error::validation(
            "Security validation failed: no valid authentication provided",
        ))
    }

    fn resolve_schema(&self, reference: &str) -> Option<Schema> {
        let mut visited = HashSet::new();
        self.resolve_schema_recursive(reference, &mut visited)
    }

    fn resolve_schema_recursive(
        &self,
        reference: &str,
        visited: &mut HashSet<String>,
    ) -> Option<Schema> {
        if !visited.insert(reference.to_string()) {
            tracing::warn!("Detected recursive schema reference: {}", reference);
            return None;
        }

        let schema_name = reference.strip_prefix("#/components/schemas/")?;
        let components = self.spec.components.as_ref()?;
        let schema_ref = components.schemas.get(schema_name)?;

        match schema_ref {
            ReferenceOr::Item(schema) => Some(schema.clone()),
            ReferenceOr::Reference { reference: nested } => {
                self.resolve_schema_recursive(nested, visited)
            }
        }
    }

    /// Check if a single security requirement is satisfied
    fn is_security_requirement_satisfied(
        &self,
        requirement: &openapiv3::SecurityRequirement,
        auth_header: Option<&str>,
        api_key: Option<&str>,
    ) -> Result<bool> {
        // All schemes in the requirement must be satisfied (AND)
        for (scheme_name, _scopes) in requirement {
            if !self.is_security_scheme_satisfied(scheme_name, auth_header, api_key)? {
                return Ok(false);
            }
        }
        Ok(true)
    }

    /// Check if a security scheme is satisfied
    fn is_security_scheme_satisfied(
        &self,
        scheme_name: &str,
        auth_header: Option<&str>,
        api_key: Option<&str>,
    ) -> Result<bool> {
        let security_schemes = match self.security_schemes() {
            Some(schemes) => schemes,
            None => return Ok(false),
        };

        let scheme = match security_schemes.get(scheme_name) {
            Some(scheme) => scheme,
            None => {
                return Err(Error::config(format!("Security scheme '{}' not found", scheme_name)))
            }
        };

        let scheme = match scheme {
            ReferenceOr::Item(s) => s,
            ReferenceOr::Reference { reference } => {
                // Resolve $ref like "#/components/securitySchemes/BearerAuth"
                let ref_name =
                    reference.strip_prefix("#/components/securitySchemes/").ok_or_else(|| {
                        Error::config(format!(
                            "Unsupported security scheme reference format: {}",
                            reference
                        ))
                    })?;
                match security_schemes.get(ref_name) {
                    Some(ReferenceOr::Item(resolved)) => resolved,
                    Some(ReferenceOr::Reference { .. }) => {
                        return Err(Error::config(format!(
                            "Nested security scheme reference not supported: {}",
                            ref_name
                        )))
                    }
                    None => {
                        return Err(Error::config(format!(
                            "Security scheme '{}' not found",
                            ref_name
                        )))
                    }
                }
            }
        };

        match scheme {
            openapiv3::SecurityScheme::HTTP { scheme, .. } => {
                match scheme.as_str() {
                    "bearer" => match auth_header {
                        Some(header) if header.starts_with("Bearer ") => Ok(true),
                        _ => Ok(false),
                    },
                    "basic" => match auth_header {
                        Some(header) if header.starts_with("Basic ") => Ok(true),
                        _ => Ok(false),
                    },
                    _ => Ok(false), // Unsupported scheme
                }
            }
            openapiv3::SecurityScheme::APIKey { location, .. } => match location {
                openapiv3::APIKeyLocation::Header => Ok(auth_header.is_some()),
                openapiv3::APIKeyLocation::Query => Ok(api_key.is_some()),
                openapiv3::APIKeyLocation::Cookie => Ok(api_key.is_some()),
            },
            openapiv3::SecurityScheme::OpenIDConnect { .. } => {
                // OpenID Connect uses Bearer tokens, same as OAuth2
                match auth_header {
                    Some(header) if header.starts_with("Bearer ") => Ok(true),
                    _ => Ok(false),
                }
            }
            openapiv3::SecurityScheme::OAuth2 { .. } => {
                // For OAuth2, check if Bearer token is provided
                match auth_header {
                    Some(header) if header.starts_with("Bearer ") => Ok(true),
                    _ => Ok(false),
                }
            }
        }
    }

    /// Get global security requirements
    pub fn get_global_security_requirements(&self) -> Vec<openapiv3::SecurityRequirement> {
        self.spec.security.clone().unwrap_or_default()
    }

    /// Resolve a request body reference
    pub fn get_request_body(&self, reference: &str) -> Option<&openapiv3::RequestBody> {
        if let Some(components) = &self.spec.components {
            if let Some(param_name) = reference.strip_prefix("#/components/requestBodies/") {
                if let Some(request_body_ref) = components.request_bodies.get(param_name) {
                    return request_body_ref.as_item();
                }
            }
        }
        None
    }

    /// Resolve a response reference
    pub fn get_response(&self, reference: &str) -> Option<&openapiv3::Response> {
        if let Some(components) = &self.spec.components {
            if let Some(response_name) = reference.strip_prefix("#/components/responses/") {
                if let Some(response_ref) = components.responses.get(response_name) {
                    return response_ref.as_item();
                }
            }
        }
        None
    }

    /// Resolve an example reference
    pub fn get_example(&self, reference: &str) -> Option<&openapiv3::Example> {
        if let Some(components) = &self.spec.components {
            if let Some(example_name) = reference.strip_prefix("#/components/examples/") {
                if let Some(example_ref) = components.examples.get(example_name) {
                    return example_ref.as_item();
                }
            }
        }
        None
    }
}

/// Round 40 (#888 / #79) — merge path-level parameters from a
/// `PathItem` into an `Operation`'s own parameters per OpenAPI 3.0
/// §4.7.10.1. Returns a cloned `Operation` whose `parameters` list
/// contains every path-level entry, followed by every operation-level
/// entry, with collisions on `(name, in)` resolved in favour of the
/// operation-level definition. The original `Operation` is not
/// mutated. Lives in `spec.rs` so every registry builder that calls
/// `operations_for_path` benefits from the merge automatically.
pub(crate) fn merge_path_params_into_operation(
    operation: &openapiv3::Operation,
    path_level_params: &[ReferenceOr<openapiv3::Parameter>],
) -> openapiv3::Operation {
    use std::collections::HashSet;
    if path_level_params.is_empty() {
        return operation.clone();
    }
    let mut op_keys: HashSet<(String, String)> = HashSet::new();
    for p_ref in &operation.parameters {
        if let Some(key) = parameter_key(p_ref) {
            op_keys.insert(key);
        }
    }
    let mut merged: Vec<ReferenceOr<openapiv3::Parameter>> =
        Vec::with_capacity(path_level_params.len() + operation.parameters.len());
    for p_ref in path_level_params {
        match parameter_key(p_ref) {
            Some(key) if op_keys.contains(&key) => {}
            _ => merged.push(p_ref.clone()),
        }
    }
    merged.extend(operation.parameters.iter().cloned());
    let mut cloned = operation.clone();
    cloned.parameters = merged;
    cloned
}

fn parameter_key(p_ref: &ReferenceOr<openapiv3::Parameter>) -> Option<(String, String)> {
    let p = p_ref.as_item()?;
    let (name, in_loc) = match p {
        openapiv3::Parameter::Path { parameter_data, .. } => (parameter_data.name.clone(), "path"),
        openapiv3::Parameter::Query { parameter_data, .. } => {
            (parameter_data.name.clone(), "query")
        }
        openapiv3::Parameter::Header { parameter_data, .. } => {
            (parameter_data.name.clone(), "header")
        }
        openapiv3::Parameter::Cookie { parameter_data, .. } => {
            (parameter_data.name.clone(), "cookie")
        }
    };
    Some((name, in_loc.to_string()))
}

#[cfg(test)]
mod tests {
    use super::*;
    use openapiv3::{SchemaKind, Type};

    #[test]
    fn resolves_security_scheme_ref() {
        let yaml = r#"
openapi: 3.0.3
info:
  title: Test API
  version: "1.0.0"
paths:
  /test:
    get:
      security:
        - BearerRef: []
      responses:
        '200':
          description: OK
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
    BearerRef:
      $ref: '#/components/securitySchemes/BearerAuth'
        "#;

        let spec = OpenApiSpec::from_string(yaml, Some("yaml")).expect("spec parses");

        // Bearer token should satisfy the referenced scheme
        let result = spec
            .is_security_scheme_satisfied("BearerRef", Some("Bearer token123"), None)
            .expect("should resolve ref");
        assert!(result);

        // Missing token should fail
        let result = spec
            .is_security_scheme_satisfied("BearerRef", None, None)
            .expect("should resolve ref");
        assert!(!result);
    }

    #[test]
    fn resolves_nested_schema_references() {
        let yaml = r#"
openapi: 3.0.3
info:
  title: Test API
  version: "1.0.0"
paths: {}
components:
  schemas:
    Apiary:
      type: object
      properties:
        id:
          type: string
        hive:
          $ref: '#/components/schemas/Hive'
    Hive:
      type: object
      properties:
        name:
          type: string
    HiveWrapper:
      $ref: '#/components/schemas/Hive'
        "#;

        let spec = OpenApiSpec::from_string(yaml, Some("yaml")).expect("spec parses");

        let apiary = spec.get_schema("#/components/schemas/Apiary").expect("resolve apiary schema");
        assert!(matches!(apiary.schema.schema_kind, SchemaKind::Type(Type::Object(_))));

        let wrapper = spec
            .get_schema("#/components/schemas/HiveWrapper")
            .expect("resolve wrapper schema");
        assert!(matches!(wrapper.schema.schema_kind, SchemaKind::Type(Type::Object(_))));
    }
}

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

    /// A proxy-generated spec with no `responses` on its operations must load.
    /// Reported on #79: 63 of 70 operations lacked the field and the whole run
    /// aborted with `missing field \`responses\``.
    #[test]
    fn spec_without_operation_responses_loads() {
        let raw = r#"{
            "openapi": "3.0.0",
            "info": { "title": "proxy-generated", "version": "1.0.0" },
            "paths": {
                "/orders": {
                    "get": { "summary": "list" },
                    "post": {
                        "summary": "create",
                        "requestBody": {
                            "content": { "application/json": { "schema": { "type": "object" } } }
                        }
                    }
                }
            }
        }"#;

        let spec = OpenApiSpec::from_string(raw, Some("json"))
            .expect("a spec missing `responses` should still load for bench/load use");

        let item = spec.spec.paths.paths.get("/orders").expect("path present");
        let ReferenceOr::Item(item) = item else {
            panic!("expected inline path item");
        };
        assert!(item.get.is_some(), "GET survived the repair");
        assert!(item.post.is_some(), "POST survived the repair");
        assert!(
            item.post.as_ref().unwrap().request_body.is_some(),
            "requestBody must be preserved — it is what request generation actually reads"
        );
    }

    /// The repair must only add the mandatory field, never touch a spec that
    /// already declares responses.
    #[test]
    fn existing_responses_are_left_alone() {
        let mut raw: serde_json::Value = serde_json::from_str(
            r#"{"paths": {"/a": {"get": {"responses": {"200": {"description": "ok"}}}}}}"#,
        )
        .unwrap();
        let before = raw.clone();
        assert_eq!(fill_missing_operation_responses(&mut raw), 0);
        assert_eq!(raw, before, "a conformant spec must be byte-identical after the pass");
    }

    /// Non-operation keys under a path item (parameters, servers, $ref) must not
    /// be mistaken for operations.
    #[test]
    fn non_operation_keys_are_not_touched() {
        let mut raw: serde_json::Value = serde_json::from_str(
            r#"{"paths": {"/a": {"parameters": [], "servers": [], "get": {}}}}"#,
        )
        .unwrap();
        assert_eq!(fill_missing_operation_responses(&mut raw), 1, "only `get` is an operation");
        let path = &raw["paths"]["/a"];
        assert!(path["parameters"].is_array(), "parameters untouched");
        assert!(path["servers"].is_array(), "servers untouched");
        assert!(path["get"]["responses"].is_object(), "get repaired");
    }
}

#[cfg(test)]
mod oas31_type_array_tests {
    use super::*;
    use openapiv3::{SchemaKind, Type};

    /// Srikanth #79 (i): OAS 3.1 `type: ["string", "null"]` must load, because
    /// that is what LLM-generated specs emit and `openapiv3` cannot deserialize
    /// a sequence into a string `type`.
    #[test]
    fn oas31_nullable_type_array_loads() {
        let raw = r#"{
            "openapi": "3.1.0",
            "info": { "title": "limit", "version": "1" },
            "paths": {
                "/companies": {
                    "post": {
                        "responses": { "200": { "description": "ok" } },
                        "requestBody": {
                            "content": {
                                "application/json": {
                                    "schema": {
                                        "type": "object",
                                        "properties": {
                                            "taxId": { "type": ["string", "null"] }
                                        },
                                        "required": ["taxId"]
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "components": {
                "schemas": {
                    "ResourceBase": {
                        "type": "object",
                        "properties": {
                            "nickname": { "type": ["null", "string"] }
                        }
                    }
                }
            }
        }"#;

        let spec = OpenApiSpec::from_string(raw, Some("json"))
            .expect("OAS 3.1 type: [string, null] must load for bench use");

        let schema = spec
            .resolve_schema_ref("#/components/schemas/ResourceBase")
            .expect("ResourceBase present");
        let SchemaKind::Type(Type::Object(obj)) = schema.schema_kind else {
            panic!("ResourceBase should be an object after the type-array coerce");
        };
        let nickname = obj.properties.get("nickname").expect("nickname property");
        let ReferenceOr::Item(nickname) = nickname else {
            panic!("nickname should be inline");
        };
        assert!(
            nickname.schema_data.nullable,
            "`null` in the 3.1 type union becomes OAS 3.0 nullable"
        );
        assert!(
            matches!(nickname.schema_kind, SchemaKind::Type(Type::String(_))),
            "remaining primitive is string"
        );
    }

    /// `required` is a string array too. The walker must not treat it as `type`.
    #[test]
    fn required_arrays_are_not_rewritten() {
        let mut raw: serde_json::Value = serde_json::from_str(
            r#"{
                "components": {
                    "schemas": {
                        "A": { "type": "object", "required": ["a", "b"] }
                    }
                }
            }"#,
        )
        .unwrap();
        let before = raw.clone();
        assert_eq!(coerce_json_schema_type_arrays(&mut raw), 0);
        assert_eq!(raw, before, "required arrays must stay arrays of strings");
    }

    /// A lone `["string"]` (legal OAS 3.1) becomes a 3.0 string type, with no
    /// `nullable` flag invented.
    #[test]
    fn singleton_type_array_becomes_string() {
        let mut raw: serde_json::Value =
            serde_json::from_str(r#"{"properties": {"id": {"type": ["string"]}}}"#).unwrap();
        assert_eq!(coerce_json_schema_type_arrays(&mut raw), 1);
        assert_eq!(raw["properties"]["id"]["type"], "string");
        assert!(raw["properties"]["id"].get("nullable").is_none());
    }
}