fix: preserve declared response headers in operation metadata

packages/forge/openapi-resolver.test.ts

@@ -3,6 +3,57 @@ import { test } from 'node:test';
 import { Forge } from './forge.ts';
 import { populateOperationMap, resolveOperation } from './openapi-resolver.ts';
 
+test('response metadata preserves inline and referenced headers', () => {
+  populateOperationMap({
+    paths: {
+      '/uploads': {
+        post: {
+          operationId: 'create-upload',
+          responses: {
+            '201': { $ref: '#/components/responses/UploadCreated' },
+            '204': { description: 'No content' },
+          },
+        },
+      },
+    },
+    components: {
+      schemas: { UploadUrl: { type: 'string', format: 'uri' } },
+      headers: {
+        UploadLocation: {
+          description: 'Upload URL',
+          required: true,
+          schema: { $ref: '#/components/schemas/UploadUrl' },
+        },
+      },
+      responses: {
+        UploadCreated: {
+          description: 'Created',
+          headers: {
+            Location: { $ref: '#/components/headers/UploadLocation' },
+            'Upload-Version': { schema: { type: 'string' } },
+          },
+        },
+      },
+    },
+  });
+
+  const operation = resolveOperation('create-upload');
+  assert.ok(operation);
+  assert.deepEqual(operation.responses['201'], {
+    description: 'Created',
+    content: {},
+    headers: {
+      Location: {
+        description: 'Upload URL',
+        required: true,
+        schema: { type: 'string', format: 'uri' },
+      },
+      'Upload-Version': { schema: { type: 'string' } },
+    },
+  });
+  assert.deepEqual(operation.responses['204'], { description: 'No content', content: {} });
+});
+
 test('parameter metadata separates resolved type from schema identity', () => {
   populateOperationMap({
     paths: {

packages/forge/openapi-resolver.ts

@@ -65,6 +65,7 @@ interface Operation {
 interface ResponseObject {
   $ref?: string;
   description?: string;
+  headers?: Record<string, ResponseHeaderInfo & { $ref?: string }>;
   /** Keyed by media type: `"application/json"`, `"application/pdf"`, `"text/plain"`, ... */
   content?: Record<string, { schema?: SchemaRef } | undefined>;
 }
@@ -285,6 +286,13 @@ export interface ResponseInfo {
    * Empty object when the spec declares the status with no `content` (e.g. `204`).
    */
   content: Record<string, ResponseBodyInfo>;
+  headers?: Record<string, ResponseHeaderInfo>;
+}
+
+export interface ResponseHeaderInfo {
+  description?: string;
+  required?: boolean;
+  schema?: SchemaRef;
 }
 
 /**
@@ -1501,6 +1509,18 @@ function extractResponses(responses: Operation['responses']): Record<string, Res
       info.description = response.description;
     }
 
+    if (response.headers) {
+      info.headers = {};
+      for (const [name, rawHeader] of Object.entries(response.headers)) {
+        const header = resolveDocRef(rawHeader);
+        info.headers[name] = {
+          ...(header.description === undefined ? {} : { description: header.description }),
+          ...(header.required === undefined ? {} : { required: header.required }),
+          ...(header.schema === undefined ? {} : { schema: resolveSchemaRef(header.schema) }),
+        };
+      }
+    }
+
     if (response.content) {
       for (const [mediaType, body] of Object.entries(response.content)) {
         if (!body) continue;