pyopenapi-gen 2.7.2__py3-none-any.whl

pyopenapi_gen/core/parsing/schema_parser.py

@@ -0,0 +1,804 @@
+"""
+Core schema parsing logic, transforming a schema node into an IRSchema object.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any, Callable, List, Mapping, Set, Tuple
+
+from pyopenapi_gen import IRSchema
+from pyopenapi_gen.core.utils import NameSanitizer
+
+from .context import ParsingContext
+from .keywords.all_of_parser import _process_all_of
+from .keywords.any_of_parser import _parse_any_of_schemas
+from .keywords.one_of_parser import _parse_one_of_schemas
+from .unified_cycle_detection import CycleAction
+
+logger = logging.getLogger(__name__)
+
+# Environment variables for configurable limits, with defaults
+try:
+    MAX_CYCLES = int(os.environ.get("PYOPENAPI_MAX_CYCLES", "0"))  # Default 0 means no explicit cycle count limit
+except ValueError:
+    MAX_CYCLES = 0
+try:
+    ENV_MAX_DEPTH = int(os.environ.get("PYOPENAPI_MAX_DEPTH", "150"))  # Default 150
+except ValueError:
+    ENV_MAX_DEPTH = 150  # Fallback to 150 if env var is invalid
+
+
+def _resolve_ref(
+    ref_path_str: str,
+    parent_schema_name: str | None,  # Name of the schema containing this $ref
+    context: ParsingContext,
+    max_depth_override: int | None,  # Propagated from the main _parse_schema call
+    allow_self_reference_for_parent: bool,
+) -> IRSchema:
+    """Resolves a $ref string, handling cycles and depth for the referenced schema."""
+    ref_name_parts = ref_path_str.split("/")
+    if not (ref_name_parts and ref_name_parts[-1]):
+        logger.warning(
+            f"Malformed $ref path '{ref_path_str}' encountered while parsing "
+            f"parent '{parent_schema_name or 'anonymous'}'."
+        )
+        return IRSchema(
+            name=None,  # Anonymous placeholder for a bad ref
+            description=f"Malformed $ref: {ref_path_str}",
+            _from_unresolved_ref=True,
+        )
+    ref_name = ref_name_parts[-1]
+
+    # 1. Check if already parsed (fully or as a placeholder)
+    if ref_name in context.parsed_schemas and not context.parsed_schemas[ref_name]._max_depth_exceeded_marker:
+        # Re-using already parsed schema from context
+        return context.parsed_schemas[ref_name]
+
+    # 2. Get the raw schema node for the reference
+    ref_node = context.raw_spec_schemas.get(ref_name)
+    if ref_node is None:
+        logger.warning(
+            f"Cannot resolve $ref '{ref_path_str}' for parent '{parent_schema_name or 'anonymous'}'. "
+            f"Target '{ref_name}' not in raw_spec_schemas. Returning placeholder."
+        )
+        return IRSchema(
+            name=NameSanitizer.sanitize_class_name(ref_name),
+            _from_unresolved_ref=True,
+            description=f"Unresolved $ref: {ref_path_str} (target not found)",
+        )
+
+    # Delegate all cycle detection and context management to _parse_schema
+    # The unified system in _parse_schema will handle all cycle detection, depth limits, and context management
+    return _parse_schema(
+        ref_name,
+        ref_node,
+        context,
+        max_depth_override,
+        allow_self_reference=allow_self_reference_for_parent,
+    )
+
+
+def _parse_composition_keywords(
+    node: Mapping[str, Any],
+    name: str | None,
+    context: ParsingContext,
+    max_depth: int,
+    parse_fn: Callable[[str | None, Mapping[str, Any] | None, ParsingContext, int | None], IRSchema],
+) -> Tuple[List[IRSchema] | None, List[IRSchema] | None, List[IRSchema] | None, dict[str, IRSchema], Set[str], bool]:
+    """Parse composition keywords (anyOf, oneOf, allOf) from a schema node.
+
+    Contracts:
+        Pre-conditions:
+            - node is a valid Mapping
+            - context is a valid ParsingContext instance
+            - max_depth >= 0
+            - parse_fn is a callable for parsing schemas
+        Post-conditions:
+            - Returns a tuple of (any_of_schemas, one_of_schemas, all_of_components,
+              properties, required_fields, is_nullable)
+    """
+    any_of_schemas: List[IRSchema] | None = None
+    one_of_schemas: List[IRSchema] | None = None
+    parsed_all_of_components: List[IRSchema] | None = None
+    merged_properties: dict[str, IRSchema] = {}
+    merged_required_set: Set[str] = set()
+    is_nullable: bool = False
+
+    if "anyOf" in node:
+        parsed_sub_schemas, nullable_from_sub, _ = _parse_any_of_schemas(node["anyOf"], context, max_depth, parse_fn)
+        any_of_schemas = parsed_sub_schemas
+        is_nullable = is_nullable or nullable_from_sub
+
+    if "oneOf" in node:
+        parsed_sub_schemas, nullable_from_sub, _ = _parse_one_of_schemas(node["oneOf"], context, max_depth, parse_fn)
+        one_of_schemas = parsed_sub_schemas
+        is_nullable = is_nullable or nullable_from_sub
+
+    if "allOf" in node:
+        merged_properties, merged_required_set, parsed_all_of_components = _process_all_of(
+            node, name, context, parse_fn, max_depth=max_depth
+        )
+    else:
+        merged_required_set = set(node.get("required", []))
+
+    return any_of_schemas, one_of_schemas, parsed_all_of_components, merged_properties, merged_required_set, is_nullable
+
+
+def _parse_properties(
+    properties_node: Mapping[str, Any],
+    parent_schema_name: str | None,
+    existing_properties: dict[str, IRSchema],  # Properties already merged, e.g., from allOf
+    context: ParsingContext,
+    max_depth_override: int | None,
+    allow_self_reference: bool,
+) -> dict[str, IRSchema]:
+    """Parses the 'properties' block of a schema node."""
+    parsed_props: dict[str, IRSchema] = existing_properties.copy()
+
+    for prop_name, prop_schema_node in properties_node.items():
+        if not isinstance(prop_name, str) or not prop_name:
+            logger.warning(
+                f"Skipping property with invalid name '{prop_name}' in schema '{parent_schema_name or 'anonymous'}'."
+            )
+            continue
+
+        if prop_name in parsed_props:  # Already handled by allOf or a previous definition, skip
+            continue
+
+        if isinstance(prop_schema_node, Mapping) and "$ref" in prop_schema_node:
+            parsed_props[prop_name] = _resolve_ref(
+                prop_schema_node["$ref"], parent_schema_name, context, max_depth_override, allow_self_reference
+            )
+        else:
+            # Inline object promotion or direct parsing of property schema
+            is_inline_object_node = (
+                isinstance(prop_schema_node, Mapping)
+                and prop_schema_node.get("type") == "object"
+                and "$ref" not in prop_schema_node
+                and (
+                    "properties" in prop_schema_node or "description" in prop_schema_node
+                )  # Heuristic for actual object def
+            )
+
+            if is_inline_object_node and parent_schema_name:
+                # Promote inline object to its own schema
+                promoted_schema_name = f"{parent_schema_name}{NameSanitizer.sanitize_class_name(prop_name)}"
+                promoted_ir_schema = _parse_schema(
+                    promoted_schema_name,
+                    prop_schema_node,
+                    context,
+                    max_depth_override,
+                    allow_self_reference,
+                )
+                # The property itself becomes a reference to this new schema
+                property_ref_ir = IRSchema(
+                    name=prop_name,  # The actual property name
+                    type=promoted_ir_schema.name,  # Type is the name of the promoted schema
+                    description=promoted_ir_schema.description or prop_schema_node.get("description"),
+                    is_nullable=(prop_schema_node.get("nullable", False) or promoted_ir_schema.is_nullable),
+                    _refers_to_schema=promoted_ir_schema,
+                    default=prop_schema_node.get("default"),
+                    example=prop_schema_node.get("example"),
+                )
+                parsed_props[prop_name] = property_ref_ir
+                # Add the newly created promoted schema to parsed_schemas if it's not a placeholder from error/cycle
+                if (
+                    promoted_schema_name
+                    and not promoted_ir_schema._from_unresolved_ref
+                    and not promoted_ir_schema._max_depth_exceeded_marker
+                    and not promoted_ir_schema._is_circular_ref
+                ):
+                    context.parsed_schemas[promoted_schema_name] = promoted_ir_schema
+            else:
+                # Directly parse other inline types (string, number, array of simple types, etc.)
+                # or objects that are not being promoted (e.g. if parent_schema_name is None)
+
+                # Check if this is a simple primitive type that should NOT be promoted to a separate schema
+                is_simple_primitive = (
+                    isinstance(prop_schema_node, Mapping)
+                    and prop_schema_node.get("type") in ["string", "integer", "number", "boolean"]
+                    and "$ref" not in prop_schema_node
+                    and "properties" not in prop_schema_node
+                    and "allOf" not in prop_schema_node
+                    and "anyOf" not in prop_schema_node
+                    and "oneOf" not in prop_schema_node
+                    and "items" not in prop_schema_node
+                    and "enum" not in prop_schema_node  # Enums should still be promoted
+                )
+
+                # Check if this is a simple array that should NOT be promoted to a separate schema
+                # This includes:
+                # 1. Arrays of referenced types (items has $ref)
+                # 2. Arrays of primitive types (items has type: string, integer, number, boolean)
+                items_node = prop_schema_node.get("items", {}) if isinstance(prop_schema_node, Mapping) else {}
+                is_primitive_items = (
+                    isinstance(items_node, Mapping)
+                    and items_node.get("type") in ["string", "integer", "number", "boolean"]
+                    and "$ref" not in items_node
+                    and "properties" not in items_node
+                    and "allOf" not in items_node
+                    and "anyOf" not in items_node
+                    and "oneOf" not in items_node
+                )
+                # Items with no type/ref/composition (malformed schema) should resolve to Any
+                is_typeless_items = (
+                    isinstance(items_node, Mapping)
+                    and not items_node.get("type")
+                    and "$ref" not in items_node
+                    and "properties" not in items_node
+                    and "allOf" not in items_node
+                    and "anyOf" not in items_node
+                    and "oneOf" not in items_node
+                )
+                is_simple_array = (
+                    isinstance(prop_schema_node, Mapping)
+                    and prop_schema_node.get("type") == "array"
+                    and "$ref" not in prop_schema_node
+                    and "properties" not in prop_schema_node
+                    and "allOf" not in prop_schema_node
+                    and "anyOf" not in prop_schema_node
+                    and "oneOf" not in prop_schema_node
+                    and isinstance(prop_schema_node.get("items"), Mapping)
+                    and (
+                        "$ref" in items_node  # Array of referenced types
+                        or is_primitive_items  # Array of primitive types
+                        or is_typeless_items  # Array with malformed items (no type) - resolves to List[Any]
+                    )
+                )
+
+                # Use a sanitized version of prop_name as context name for this sub-parse
+                prop_context_name = NameSanitizer.sanitize_class_name(prop_name)
+
+                # For simple primitives and simple arrays, avoid creating separate schemas
+                if (is_simple_primitive or is_simple_array) and prop_context_name in context.parsed_schemas:
+                    # There's a naming conflict - use a unique name to avoid confusion
+                    prop_context_name = f"_primitive_{prop_name}_{id(prop_schema_node)}"
+
+                # For simple primitives and simple arrays, don't assign names to prevent
+                # them from being registered as standalone schemas
+                # Note: Inline enums DO get names so they're registered properly
+                schema_name_for_parsing = None if (is_simple_primitive or is_simple_array) else prop_context_name
+
+                parsed_prop_schema_ir = _parse_schema(
+                    schema_name_for_parsing,  # Use None for simple types to prevent standalone registration
+                    prop_schema_node,
+                    context,
+                    max_depth_override,
+                    allow_self_reference,
+                )
+                # If the parsed schema retained the contextual name and it was registered,
+                # it implies it might be a complex anonymous type that got registered.
+                # In such cases, the property should *refer* to it.
+                # Otherwise, the parsed_prop_schema_ir *is* the property's schema directly.
+                #
+                # However, we should NOT create references for simple primitives or simple arrays
+                # as they should remain inline to avoid unnecessary schema proliferation.
+                should_create_reference = (
+                    schema_name_for_parsing is not None  # Only if we assigned a name
+                    and parsed_prop_schema_ir.name == schema_name_for_parsing
+                    and context.is_schema_parsed(schema_name_for_parsing)
+                    and context.get_parsed_schema(schema_name_for_parsing) is parsed_prop_schema_ir
+                    and (
+                        parsed_prop_schema_ir.type == "object"
+                        or (parsed_prop_schema_ir.type == "array" and not is_simple_array)
+                    )
+                    and not parsed_prop_schema_ir._from_unresolved_ref
+                    and not parsed_prop_schema_ir._max_depth_exceeded_marker
+                    and not parsed_prop_schema_ir._is_circular_ref
+                    and not is_simple_primitive
+                )
+
+                if should_create_reference:
+                    prop_is_nullable = False
+                    if isinstance(prop_schema_node, Mapping):
+                        if "nullable" in prop_schema_node:
+                            prop_is_nullable = prop_schema_node["nullable"]
+                        elif isinstance(prop_schema_node.get("type"), list) and "null" in prop_schema_node["type"]:
+                            prop_is_nullable = True
+                    elif parsed_prop_schema_ir.is_nullable:
+                        prop_is_nullable = True
+
+                    property_holder_ir = IRSchema(
+                        name=prop_name,  # The actual property name
+                        # Type is the name of the (potentially registered) anonymous schema
+                        type=parsed_prop_schema_ir.name,
+                        description=prop_schema_node.get("description", parsed_prop_schema_ir.description),
+                        is_nullable=prop_is_nullable,
+                        default=prop_schema_node.get("default"),
+                        example=prop_schema_node.get("example"),
+                        enum=prop_schema_node.get("enum") if not parsed_prop_schema_ir.enum else None,
+                        items=parsed_prop_schema_ir.items if parsed_prop_schema_ir.type == "array" else None,
+                        format=parsed_prop_schema_ir.format,
+                        _refers_to_schema=parsed_prop_schema_ir,
+                    )
+                    parsed_props[prop_name] = property_holder_ir
+                else:
+                    # Simpler type, or error placeholder. Assign directly but ensure original prop_name is used.
+                    # Also, try to respect original node's description, default, example, nullable if available.
+                    final_prop_ir = parsed_prop_schema_ir
+                    # Always assign the property name - this is the property's name in the parent object
+                    final_prop_ir.name = prop_name
+                    if isinstance(prop_schema_node, Mapping):
+                        final_prop_ir.description = prop_schema_node.get(
+                            "description", parsed_prop_schema_ir.description
+                        )
+                        final_prop_ir.default = prop_schema_node.get("default", parsed_prop_schema_ir.default)
+                        final_prop_ir.example = prop_schema_node.get("example", parsed_prop_schema_ir.example)
+                        current_prop_node_nullable = prop_schema_node.get("nullable", False)
+                        type_list_nullable = (
+                            isinstance(prop_schema_node.get("type"), list) and "null" in prop_schema_node["type"]
+                        )
+                        final_prop_ir.is_nullable = (
+                            final_prop_ir.is_nullable or current_prop_node_nullable or type_list_nullable
+                        )
+                        # If the sub-parse didn't pick up an enum (e.g. for simple types), take it from prop_schema_node
+                        if not final_prop_ir.enum and "enum" in prop_schema_node:
+                            final_prop_ir.enum = prop_schema_node["enum"]
+
+                    parsed_props[prop_name] = final_prop_ir
+    return parsed_props
+
+
+def _parse_schema(
+    schema_name: str | None,
+    schema_node: Mapping[str, Any] | None,
+    context: ParsingContext,
+    max_depth_override: int | None = None,
+    allow_self_reference: bool = False,
+) -> IRSchema:
+    """
+    Parse a schema node and return an IRSchema object.
+    """
+    # Pre-conditions
+    if context is None:
+        raise ValueError("Context cannot be None for _parse_schema")
+
+    # Set allow_self_reference flag on unified context
+    context.unified_cycle_context.allow_self_reference = allow_self_reference
+
+    # Use unified cycle detection system
+    detection_result = context.unified_enter_schema(schema_name)
+
+    # Handle different detection results
+    if detection_result.action == CycleAction.RETURN_EXISTING:
+        # Schema already completed - return existing
+        context.unified_exit_schema(schema_name)  # Balance the enter call
+        if schema_name:
+            existing_schema = context.unified_cycle_context.parsed_schemas.get(schema_name)
+            if existing_schema:
+                return existing_schema
+            # Fallback to legacy parsed_schemas if not in unified context
+            existing_schema = context.parsed_schemas.get(schema_name)
+            if existing_schema:
+                return existing_schema
+            # If schema marked as existing but not found anywhere, it might be a state management issue
+            # Reset the state and continue with normal parsing
+            from .unified_cycle_detection import SchemaState
+
+            context.unified_cycle_context.schema_states[schema_name] = SchemaState.NOT_STARTED
+        # Don't call unified_exit_schema again, continue to normal parsing
+
+    elif detection_result.action == CycleAction.RETURN_PLACEHOLDER:
+        # Schema is already a placeholder - return it
+        context.unified_exit_schema(schema_name)  # Balance the enter call
+        if detection_result.placeholder_schema:
+            placeholder: IRSchema = detection_result.placeholder_schema
+            return placeholder
+        elif schema_name and schema_name in context.parsed_schemas:
+            return context.parsed_schemas[schema_name]
+        else:
+            # Fallback to empty schema
+            return IRSchema(name=NameSanitizer.sanitize_class_name(schema_name) if schema_name else None)
+
+    elif detection_result.action == CycleAction.CREATE_PLACEHOLDER:
+        # Cycle or depth limit detected - return the created placeholder
+        context.unified_exit_schema(schema_name)  # Balance the enter call
+        created_placeholder: IRSchema = detection_result.placeholder_schema
+        return created_placeholder
+
+    # If we reach here, detection_result.action == CycleAction.CONTINUE_PARSING
+
+    try:  # Ensure exit_schema is called
+        if schema_node is None:
+            # Create empty schema for null schema nodes
+            # Do NOT set generation_name - null schemas should resolve to Any inline, not generate separate files
+            return IRSchema(name=NameSanitizer.sanitize_class_name(schema_name) if schema_name else None)
+
+        if not isinstance(schema_node, Mapping):
+            raise TypeError(
+                f"Schema node for '{schema_name or 'anonymous'}' must be a Mapping (e.g., dict), got {type(schema_node)}"
+            )
+
+        # If the current schema_node itself is a $ref, resolve it.
+        if "$ref" in schema_node:
+            # schema_name is the original name we are trying to parse (e.g., 'Pet')
+            # schema_node is {"$ref": "#/components/schemas/ActualPet"}
+            # We want to resolve "ActualPet", but the resulting IRSchema should ideally
+            # retain the name 'Pet' if appropriate,
+            # or _resolve_ref handles naming if ActualPet itself is parsed.
+            # The `parent_schema_name` for _resolve_ref here is `schema_name` itself.
+            resolved_schema = _resolve_ref(
+                schema_node["$ref"], schema_name, context, max_depth_override, allow_self_reference
+            )
+
+            # Store the resolved schema under the current schema_name if it has a name
+            # This ensures that synthetic names like "ChildrenItem" are properly stored
+            # However, don't create duplicate entries for pure references to existing schemas
+            if (
+                schema_name
+                and resolved_schema
+                and resolved_schema.name  # Resolved schema has a real name
+                and resolved_schema.name != schema_name  # Different from synthetic name
+                and resolved_schema.name in context.parsed_schemas
+            ):  # Already exists in context
+                # This is a pure reference to an existing schema, don't create duplicate
+                pass
+            elif schema_name and resolved_schema and schema_name not in context.parsed_schemas:
+                context.parsed_schemas[schema_name] = resolved_schema
+
+            return resolved_schema
+
+        extracted_type: str | None = None
+        is_nullable_from_type_field = False
+        raw_type_field = schema_node.get("type")
+
+        if isinstance(raw_type_field, str):
+            # Handle non-standard type values that might appear
+            if raw_type_field in ["Any", "any"]:
+                # Convert 'Any' to None - will be handled as object later
+                extracted_type = None
+                logger.warning(
+                    f"Schema{f' {schema_name}' if schema_name else ''} uses non-standard type 'Any'. "
+                    "Converting to 'object'. Use standard OpenAPI types: string, number, integer, boolean, array, object."
+                )
+            elif raw_type_field == "None":
+                # Convert 'None' string to null handling
+                extracted_type = "null"
+                logger.warning(
+                    f"Schema{f' {schema_name}' if schema_name else ''} uses type 'None'. "
+                    'Converting to nullable object. Use \'type: ["object", "null"]\' for nullable types.'
+                )
+            else:
+                extracted_type = raw_type_field
+        elif isinstance(raw_type_field, list):
+            if "null" in raw_type_field:
+                is_nullable_from_type_field = True
+            non_null_types = [t for t in raw_type_field if t != "null"]
+            if non_null_types:
+                extracted_type = non_null_types[0]
+                if len(non_null_types) > 1:
+                    pass
+            elif is_nullable_from_type_field:
+                extracted_type = "null"
+
+        any_of_irs, one_of_irs, all_of_components_irs, props_from_comp, req_from_comp, nullable_from_comp = (
+            _parse_composition_keywords(
+                schema_node,
+                schema_name,
+                context,
+                ENV_MAX_DEPTH,
+                lambda n, sn, c, md: _parse_schema(n, sn, c, md, allow_self_reference),
+            )
+        )
+
+        # Check for direct nullable field (OpenAPI 3.0 Swagger extension)
+        is_nullable_from_node = schema_node.get("nullable", False)
+        is_nullable_overall = is_nullable_from_type_field or nullable_from_comp or is_nullable_from_node
+        final_properties_for_ir: dict[str, IRSchema] = {}
+        current_final_type = extracted_type
+        if not current_final_type:
+            if props_from_comp or "allOf" in schema_node or "properties" in schema_node:
+                current_final_type = "object"
+            elif any_of_irs or one_of_irs:
+                # Keep None for composition types - they'll be handled by resolver
+                current_final_type = None
+            elif "enum" in schema_node:
+                # Enum without explicit type - infer from enum values
+                enum_values = schema_node.get("enum", [])
+                if enum_values:
+                    first_val = enum_values[0]
+                    if isinstance(first_val, str):
+                        current_final_type = "string"
+                    elif isinstance(first_val, (int, float)):
+                        current_final_type = "number"
+                    elif isinstance(first_val, bool):
+                        current_final_type = "boolean"
+                    else:
+                        # Fallback to object for complex enum values
+                        current_final_type = "object"
+                else:
+                    current_final_type = "string"  # Default for empty enums
+            else:
+                # No type specified and no clear indicators - default to object
+                # This is safer than 'Any' and matches OpenAPI spec defaults
+                current_final_type = "object"
+
+        if current_final_type == "null":
+            # Explicit null type - mark as nullable but use object type
+            is_nullable_overall = True
+            current_final_type = "object"
+
+        if current_final_type == "object":
+            # Properties from allOf have already been handled by _parse_composition_keywords
+            # and are in props_from_comp. We pass these as existing_properties.
+            if "properties" in schema_node:
+                final_properties_for_ir = _parse_properties(
+                    schema_node["properties"],
+                    schema_name,
+                    props_from_comp,  # these are from allOf merge
+                    context,
+                    max_depth_override,
+                    allow_self_reference,
+                )
+            else:
+                final_properties_for_ir = props_from_comp.copy()  # No direct properties, only from allOf
+
+            # final_required_set: Set[str] = set() # This was old logic, req_from_comp covers allOf
+            # if "properties" in schema_node: # This loop is now inside _parse_properties effectively
+            # ... existing property parsing loop removed ...
+        final_required_fields_set = req_from_comp.copy()
+        if "required" in schema_node and isinstance(schema_node["required"], list):
+            final_required_fields_set.update(schema_node["required"])
+
+        items_ir: IRSchema | None = None
+        if current_final_type == "array":
+            items_node = schema_node.get("items")
+            if items_node:
+                # Avoid generating synthetic names for $ref items - let the ref resolve naturally
+                # This prevents false cycle detection when AgentListResponse -> $ref: AgentListResponseItem
+                if isinstance(items_node, Mapping) and "$ref" in items_node:
+                    # For $ref items, pass None as schema_name to let _resolve_ref handle the naming
+                    item_schema_name_for_recursive_parse = None
+                elif isinstance(items_node, Mapping) and items_node.get("type") in [
+                    "string",
+                    "integer",
+                    "number",
+                    "boolean",
+                ]:
+                    # Primitive items should NOT get names - they should remain inline as List[str] etc.
+                    item_schema_name_for_recursive_parse = None
+                elif (
+                    isinstance(items_node, Mapping)
+                    and not items_node.get("type")
+                    and not items_node.get("$ref")
+                    and not items_node.get("allOf")
+                    and not items_node.get("anyOf")
+                    and not items_node.get("oneOf")
+                    and not items_node.get("properties")
+                ):
+                    # Items with no type, $ref, or composition (e.g., just {nullable: true}) - treat as Any
+                    # This is a malformed schema pattern, log a warning and use null type (resolves to Any)
+                    nullable_only = items_node.get("nullable", False) and len(items_node) == 1
+                    if nullable_only:
+                        logger.warning(
+                            f"Array items with only 'nullable: true' and no type "
+                            f"found{f' in {schema_name}' if schema_name else ''}. "
+                            "This is likely a malformed OpenAPI schema. Using 'Any' as item type. "
+                            "Consider adding 'type: string' or appropriate type to your OpenAPI spec."
+                        )
+                    else:
+                        logger.warning(
+                            f"Array items with no 'type' field found{f' in {schema_name}' if schema_name else ''}. "
+                            "Using 'Any' as item type. "
+                            "Consider adding 'type' to your OpenAPI spec for better type safety."
+                        )
+                    # Create a null-type schema that will resolve to Any
+                    items_ir = IRSchema(type="null", is_nullable=items_node.get("nullable", False))
+                elif isinstance(items_node, Mapping) and items_node.get("type") == "null":
+                    # Explicit null type for items - resolve to Any | None
+                    items_ir = IRSchema(type="null", is_nullable=True)
+                else:
+                    # For inline items, generate a synthetic name
+                    base_name_for_item = schema_name or "AnonymousArray"
+                    item_schema_name_for_recursive_parse = NameSanitizer.sanitize_class_name(
+                        f"{base_name_for_item}Item"
+                    )
+
+                    # Ensure unique names for anonymous array items to avoid schema overwrites
+                    # Only check for collision if this specific name already exists
+                    if not schema_name and item_schema_name_for_recursive_parse in context.parsed_schemas:
+                        counter = 2  # Start from 2 since original is 1
+                        original_name = item_schema_name_for_recursive_parse
+                        while item_schema_name_for_recursive_parse in context.parsed_schemas:
+                            item_schema_name_for_recursive_parse = f"{original_name}{counter}"
+                            counter += 1
+
+                # Only parse items if items_ir wasn't directly set above (for null/Any cases)
+                if items_ir is None:
+                    actual_item_ir = _parse_schema(
+                        item_schema_name_for_recursive_parse,
+                        items_node,
+                        context,
+                        max_depth_override,
+                        allow_self_reference,
+                    )
+
+                    is_promoted_inline_object = (
+                        isinstance(items_node, Mapping)
+                        and items_node.get("type") == "object"
+                        and "$ref" not in items_node
+                        and actual_item_ir.name == item_schema_name_for_recursive_parse
+                    )
+
+                    if is_promoted_inline_object:
+                        ref_holder_ir = IRSchema(
+                            name=None,
+                            type=actual_item_ir.name,
+                            description=actual_item_ir.description or items_node.get("description"),
+                        )
+                        ref_holder_ir._refers_to_schema = actual_item_ir
+                        items_ir = ref_holder_ir
+                    else:
+                        items_ir = actual_item_ir
+            else:
+                # Array without items specification - use object as safer default
+                # Log warning to help developers fix their specs
+                logger.warning(
+                    f"Array type without 'items' specification found{f' in {schema_name}' if schema_name else ''}. "
+                    "Using 'object' as item type. Consider adding 'items' to your OpenAPI spec for better type safety."
+                )
+                items_ir = IRSchema(type="object")
+
+        schema_ir_name_attr = NameSanitizer.sanitize_class_name(schema_name) if schema_name else None
+
+        # Parse additionalProperties field
+        additional_properties_value: bool | IRSchema | None = None
+        if "additionalProperties" in schema_node:
+            additional_props_node = schema_node["additionalProperties"]
+            if isinstance(additional_props_node, bool):
+                additional_properties_value = additional_props_node
+            elif isinstance(additional_props_node, dict):
+                # Parse the additionalProperties schema
+                additional_properties_value = _parse_schema(
+                    None,  # No name for additional properties schema
+                    additional_props_node,
+                    context,
+                    max_depth_override,
+                    allow_self_reference,
+                )
+
+        schema_ir = IRSchema(
+            name=schema_ir_name_attr,
+            type=current_final_type,
+            properties=final_properties_for_ir,
+            any_of=any_of_irs,
+            one_of=one_of_irs,
+            all_of=all_of_components_irs,
+            required=sorted(list(final_required_fields_set)),
+            description=schema_node.get("description"),
+            format=schema_node.get("format") if isinstance(schema_node.get("format"), str) else None,
+            enum=schema_node.get("enum") if isinstance(schema_node.get("enum"), list) else None,
+            default=schema_node.get("default"),
+            example=schema_node.get("example"),
+            is_nullable=is_nullable_overall,
+            items=items_ir,
+            additional_properties=additional_properties_value,
+        )
+
+        # Re-parse items for complex array types that need special handling
+        # Skip if items was already set to null type (typeless items that resolve to Any)
+        if (
+            schema_ir.type == "array"
+            and isinstance(schema_node.get("items"), Mapping)
+            and not (schema_ir.items and schema_ir.items.type == "null")  # Skip if already set to null/Any
+        ):
+            raw_items_node = schema_node["items"]
+            item_schema_context_name_for_reparse: str | None
+
+            # Avoid generating synthetic names for $ref items - let the ref resolve naturally
+            if "$ref" in raw_items_node:
+                item_schema_context_name_for_reparse = None
+            elif raw_items_node.get("type") in ["string", "integer", "number", "boolean"]:
+                # Primitive items should NOT get names - they should remain inline as List[str] etc.
+                item_schema_context_name_for_reparse = None
+            elif (
+                not raw_items_node.get("type")
+                and "$ref" not in raw_items_node
+                and "allOf" not in raw_items_node
+                and "anyOf" not in raw_items_node
+                and "oneOf" not in raw_items_node
+                and "properties" not in raw_items_node
+            ):
+                # Typeless items (e.g., just {nullable: true}) - don't create synthetic name
+                # These will resolve to Any type - but this case should be caught above
+                item_schema_context_name_for_reparse = None
+            else:
+                base_name_for_reparse_item = schema_name or "AnonymousArray"
+                item_schema_context_name_for_reparse = NameSanitizer.sanitize_class_name(
+                    f"{base_name_for_reparse_item}Item"
+                )
+
+                # Ensure unique names for anonymous array items to avoid schema overwrites
+                # Only check for collision if this specific name already exists
+                if not schema_name and item_schema_context_name_for_reparse in context.parsed_schemas:
+                    counter = 2  # Start from 2 since original is 1
+                    original_name = item_schema_context_name_for_reparse
+                    while item_schema_context_name_for_reparse in context.parsed_schemas:
+                        item_schema_context_name_for_reparse = f"{original_name}{counter}"
+                        counter += 1
+
+            direct_reparsed_item_ir = _parse_schema(
+                item_schema_context_name_for_reparse, raw_items_node, context, max_depth_override, allow_self_reference
+            )
+
+            is_promoted_inline_object_in_reparse_block = (
+                isinstance(raw_items_node, Mapping)
+                and raw_items_node.get("type") == "object"
+                and "$ref" not in raw_items_node
+                and direct_reparsed_item_ir.name == item_schema_context_name_for_reparse
+            )
+
+            if is_promoted_inline_object_in_reparse_block:
+                ref_holder_for_reparse_ir = IRSchema(
+                    name=None,
+                    type=direct_reparsed_item_ir.name,
+                    description=direct_reparsed_item_ir.description or raw_items_node.get("description"),
+                )
+                ref_holder_for_reparse_ir._refers_to_schema = direct_reparsed_item_ir
+                schema_ir.items = ref_holder_for_reparse_ir
+            else:
+                schema_ir.items = direct_reparsed_item_ir
+
+        if schema_name and schema_name in context.parsed_schemas:
+            existing_in_context = context.parsed_schemas[schema_name]
+
+            if existing_in_context._is_circular_ref and existing_in_context is not schema_ir:
+                return existing_in_context
+
+        # Don't register synthetic primitive type schemas as standalone schemas
+        # They should remain inline to avoid unnecessary schema proliferation
+        # BUT: Top-level schemas defined in components/schemas should always be registered,
+        # even if they are primitive types
+        # NOTE: Schemas with enums are NOT primitives - they need to be generated as enum classes
+        is_primitive_schema = schema_ir.type in ["string", "integer", "number", "boolean"] and not schema_ir.enum
+        is_top_level_schema = schema_name and schema_name in context.raw_spec_schemas
+        is_synthetic_primitive = is_primitive_schema and not is_top_level_schema
+        should_register = (
+            schema_name
+            and not schema_ir._from_unresolved_ref
+            and not schema_ir._max_depth_exceeded_marker
+            and not is_synthetic_primitive
+        )
+        if should_register and schema_name:
+            context.parsed_schemas[schema_name] = schema_ir
+
+        # Set generation_name and final_module_stem for schemas that will be generated as separate files
+        # Skip for synthetic primitives (inline types) - they should remain without these attributes
+        # so the type resolver doesn't try to import them as separate modules
+        # Note: Boolean enums are handled inline as Literal[True/False] and should not be extracted
+        should_set_generation_names = (
+            schema_ir.name
+            and not is_synthetic_primitive
+            and not (schema_ir.type == "boolean" and schema_ir.enum)  # Boolean enums are inline Literal types
+        )
+        if should_set_generation_names and schema_ir.name:  # Extra check to help mypy narrow the type
+            schema_ir.generation_name = NameSanitizer.sanitize_class_name(schema_ir.name)
+            schema_ir.final_module_stem = NameSanitizer.sanitize_module_name(schema_ir.name)
+
+        # Check if this schema was involved in any detected cycles and mark it accordingly
+        # This must happen before returning the schema
+        if schema_name:
+            for cycle_info in context.unified_cycle_context.detected_cycles:
+                if (
+                    cycle_info.cycle_path
+                    and cycle_info.cycle_path[0] == schema_name
+                    and cycle_info.cycle_path[-1] == schema_name
+                ):
+                    # This schema is the start and end of a cycle
+                    # Only mark as circular if it's a direct self-reference (via immediate intermediate schema)
+                    # or if the test case specifically expects this behavior (array items)
+                    is_direct_self_ref = len(cycle_info.cycle_path) == 2
+                    is_array_item_self_ref = len(cycle_info.cycle_path) == 3 and "Item" in cycle_info.cycle_path[1]
+
+                    if is_direct_self_ref or is_array_item_self_ref:
+                        schema_ir._is_circular_ref = True
+                        schema_ir._from_unresolved_ref = True
+                        schema_ir._circular_ref_path = " -> ".join(cycle_info.cycle_path)
+                    break
+
+        return schema_ir
+
+    finally:
+        context.unified_exit_schema(schema_name)