oaspec/openapi/external_loader

Support for external $ref values that point at component definitions in a sibling YAML/JSON file — ./other.yaml#/components/schemas/Foo style. Walks components.schemas, pulls referenced schemas from the target file into the main spec, and rewrites the refs to local form.

Supported shapes:

• top-level component schema entries (components.schemas.Foo: $ref: ...)
• ObjectSchema property values (properties.field: $ref: ...)
• ArraySchema item values (items: $ref: ...)
• ObjectSchema additionalProperties values (additionalProperties: $ref: ...)
• composition branches (oneOf, anyOf, allOf variant refs)
• components.parameters.*.schema: $ref: ... (parameter schema only)
• components.parameters.*.content.*.schema: $ref: ...
• components.request_bodies.*.content.*.schema: $ref: ...
• components.responses.*.content.*.schema: $ref: ...
• operation-level parameters[*].schema / parameters[*].content.*.schema on both paths.<path>.parameters and paths.<path>.<method>.parameters
• operation-level requestBody.content.*.schema
• operation-level responses.<code>.content.*.schema
• components.headers.*.schema and every Response.headers.*.schema (both under components.responses and operation-level responses)
• refs inside components.path_items.* (reusable PathItem definitions, walked via the same rewrite_path_item helper used at the top level)
• refs inside operation.callbacks.*.entries.* PathItems (recursive)
• whole-object external refs for components.parameters, components.requestBodies, components.responses, and components.pathItems (e.g., $ref: './other.yaml#/components/parameters/Foo')
• one level of alias chaining inside the same external file (LegacyX: $ref: "#/components/schemas/X" in the external file). Cross-file chains collapse naturally because parse_file runs the resolver on every loaded file before handing it back, so a target that is itself an external ref is already inline by the time we look it up.

Out of scope (see issue #98 parent):

• alias chains longer than one hop inside the same file
• HTTP/HTTPS URLs
• cyclic external refs (e.g., A.yaml → B.yaml → A.yaml) would loop forever; callers are expected to maintain acyclic file graphs.

Name collisions — when an external ref would overwrite an existing local schema, or when two external refs pull in the same fragment name from different files — are surfaced as Diagnostic errors rather than silently dropping one side.

pub fn base_dir_of(path: String) -> option.Option(String)

pub fn resolve_external_component_refs(
  spec: spec.OpenApiSpec(spec.Unresolved),
  base_dir: option.Option(String),
  parse_file: fn(String) -> Result(
    spec.OpenApiSpec(spec.Unresolved),
    diagnostic.Diagnostic,
  ),
) -> Result(
  spec.OpenApiSpec(spec.Unresolved),
  diagnostic.Diagnostic,
)