Qualify external header schema refs in generated response headers (oapi-codegen#2463)

Closes: oapi-codegen#2060

When a response header is an external `$ref` (it lives in another file
mapped via import-mapping) and that header's schema is itself a `$ref`
to a named type, the generated response-headers struct referenced the
type by a bare local name (e.g. `ETag ETagSchema`) instead of the
imported one (`ETag externalRef0.ETagSchema`). Because the named type is
only generated into the imported package, the referencing package failed
to compile with an undefined `ETagSchema`.

The header's schema `$ref` is written relative to the external file
(e.g. `#/components/schemas/ETagSchema`), so `GenerateGoSchema` resolves
it against the root spec as a bare local name. Since the header component
carries its own `$ref` telling us which file it came from, qualify the
schema with that external package via `ensureExternalRefsInSchema`,
mirroring how response content schemas are already handled. This is
guarded on the schema being a reference so an external header with an
inline primitive schema (e.g. `type: string`) is not mangled into
`externalRef0.string`.

The fix corrects both the strict-server `<Op><Status>ResponseHeaders`
struct and the client response wrapper's header fields introduced in
oapi-codegen#2462.

Adds internal/test/references/multipackage/header_ref exercising an
external header ref with a ref'd schema across strict-server and client
generation; the committed generated files must compile as part of the
test module, which guards against the undefined-symbol regression.

Co-authored-by: Claude Fable 5 <[email protected]>

Author: mromaszewicz

internal/test/references/multipackage/header_ref/common/spec.yaml

@@ -0,0 +1,17 @@
+# From issue-2060: common spec providing an externally referenced header whose
+# schema is a $ref to a named type in this same package.
+openapi: "3.0.4"
+info:
+  title: Common
+  version: "0.0.1"
+paths: {}
+components:
+  schemas:
+    ETagSchema:
+      type: string
+      description: RFC 7232 entity tag
+  headers:
+    ETag:
+      description: Entity tag header
+      schema:
+        $ref: "#/components/schemas/ETagSchema"

internal/test/references/multipackage/header_ref/config.api.yaml

@@ -0,0 +1,12 @@
+# yaml-language-server: $schema=../../../../../configuration-schema.json
+package: api
+generate:
+  chi-server: true
+  strict-server: true
+  client: true
+  models: true
+import-mapping:
+  ./common/spec.yaml: github.com/oapi-codegen/oapi-codegen/v2/internal/test/references/multipackage/header_ref/gen/common
+output: gen/api/api.gen.go
+output-options:
+  skip-prune: true

internal/test/references/multipackage/header_ref/config.common.yaml

@@ -0,0 +1,7 @@
+# yaml-language-server: $schema=../../../../../configuration-schema.json
+package: common
+generate:
+  models: true
+output: gen/common/common.gen.go
+output-options:
+  skip-prune: true

internal/test/references/multipackage/header_ref/doc.go

@@ -0,0 +1,11 @@
+// Package headerref is a regression test for issue-2060: a response header
+// that is an external `$ref` whose schema is itself a `$ref` to a named type
+// must qualify that type with the imported package (e.g.
+// externalRef0.ETagSchema), both in the strict-server response headers struct
+// and in the typed client response wrappers. Before the fix the header field
+// referenced an undefined local type and the generated package failed to
+// compile.
+package headerref
+
+//go:generate go run github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen --config=config.common.yaml common/spec.yaml
+//go:generate go run github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen --config=config.api.yaml spec.yaml