@contractkit/openapi-to-ck 0.10.2 → 0.11.0

package/tests/__snapshots__/kitchen-sink.ck

@@ -0,0 +1,102 @@
+# A widget.
+# Documented across lines.
+contract Widget: {
+    id: readonly uuid
+    secret?: writeonly string
+    kind: enum(basic, "on hold", 'a "quoted" kind')
+    datePattern?: string(regex="^\d{2}/\d{2}$")
+    ttl?: duration
+    contact?: email
+    site?: url
+    size?: int
+    tags?: array(string, min=1)
+    legacy?: deprecated string
+    nickname?: string | null
+    parent?: lazy(Widget)
+    shape?: Shape
+}
+
+contract TimestampedWidget: Widget & {
+    createdAt?: datetime
+}
+
+contract Shape: discriminated(by=kind, Circle | Square)
+
+contract Circle: {
+    kind?: literal("circle")
+    r?: number
+}
+
+contract Square: {
+    kind?: literal("square")
+    side?: number
+}
+
+contract mode(loose) Bag: {
+    id?: string
+}
+
+contract Sealed: {
+    id?: string
+}
+
+contract _3DModel: {
+    mesh?: string
+}
+
+contract ApiError: {
+    message?: string
+}
+
+contract CreateWidgetRequest: {
+    data?: string
+}
+
+operation /widgets/{widgetId}: {
+    params: {
+        widgetId: uuid
+    }
+    get: { # Long prose. Across several lines.
+        name: Fetch a widget with awkward chars
+        sdk: getWidget
+        query: {
+            expand?: boolean # expand nested
+        }
+        response: {
+            200: {
+                application/json: Widget
+                text/csv: string
+                headers: {
+                    X-Rate-Limit?: int # requests left
+                }
+            }
+            204:
+            304:
+            404(documented): {
+                application/json: ApiError
+            }
+            429:
+            503(documented): {
+                headers: {
+                    Retry-After?: int
+                }
+            }
+        }
+    }
+}
+
+operation /widgets: {
+    post: {
+        sdk: createWidget
+        security: none
+        request: {
+            application/json: Widget
+            application/vnd.api+json: CreateWidgetRequest
+        }
+        response: {
+            201: {
+                application/json: Widget
+            }
+        }
+    }
+}

package/tests/ast-to-ck.test.ts

@@ -1,6 +1,7 @@
 import { describe, it, expect } from 'vitest';
 import { parseCk, DiagnosticCollector } from '@contractkit/core';
 import { astToCk, serializeType } from '../src/ast-to-ck.js';
+import { isUnquotable } from '@contractkit/core';
 import {
     ckRoot,
     model,
@@ -38,8 +39,10 @@ describe('serializeType', () => {
 
     it('serializes scalar types with constraints', () => {
         expect(serializeType(scalarType('string', { min: 1, max: 100 }))).toBe('string(min=1, max=100)');
-        expect(serializeType(scalarType('string', { len: 3 }))).toBe('string(length=3)');
-        expect(serializeType(scalarType('string', { regex: '/^[a-z]+$/' }))).toBe('string(regex=/^[a-z]+$/)');
+        expect(serializeType(scalarType('string', { len: 3 }))).toBe('string(len=3)');
+        expect(serializeType(scalarType('string', { regex: '^[a-z]+$' }))).toBe('string(regex=/^[a-z]+$/)');
+        // A pattern containing the `/` delimiter cannot be a regex literal, so it prints quoted.
+        expect(serializeType(scalarType('string', { regex: '^\\d{2}/\\d{2}$' }))).toBe('string(regex="^\\d{2}/\\d{2}$")');
         expect(serializeType(scalarType('int', { min: 0 }))).toBe('int(min=0)');
         expect(serializeType(scalarType('int', { min: 0, max: 100 }))).toBe('int(min=0, max=100)');
     });
@@ -122,16 +125,21 @@ describe('model serialization', () => {
             models: [model('User', [field('id', scalarType('uuid'), { description: 'The user ID' })], { description: 'A user' })],
         });
         const result = astToCk(root);
-        expect(result).toContain('contract User: { # A user');
+        // A model description is a doc-comment block above the declaration; a field description
+        // is a trailing comment. That asymmetry is the printer's, and matches how `.ck` sources
+        // are written by hand.
+        expect(result).toContain('# A user\ncontract User: {');
         expect(result).toContain('    id: uuid # The user ID');
     });
 
-    it('omits comments when includeComments is false', () => {
+    it('prints no comments when the AST carries no descriptions', () => {
+        // `includeComments: false` is honoured upstream — `schema-to-ast.ts` and `paths-to-ast.ts`
+        // never set `description` when it is off — so by the time the printer runs there is
+        // nothing to suppress. `convert.test.ts` covers the flag end to end.
         const root = ckRoot({
-            models: [model('User', [field('id', scalarType('uuid'), { description: 'The user ID' })], { description: 'A user' })],
+            models: [model('User', [field('id', scalarType('uuid'))])],
         });
-        const result = astToCk(root, { includeComments: false });
-        expect(result).not.toContain('#');
+        expect(astToCk(root)).not.toContain('#');
     });
 
     it('serializes model with default values', () => {
@@ -442,7 +450,7 @@ describe('full document', () => {
         expect(result).toContain('LedgerService: "#src/modules/ledger/ledger.service.js"');
 
         // Model
-        expect(result).toContain('contract LedgerAccount: { # A ledger account');
+        expect(result).toContain('# A ledger account\ncontract LedgerAccount: {');
         expect(result).toContain('    id: readonly uuid # The account ID');
 
         // Route
@@ -461,15 +469,18 @@ function parsesCleanly(source: string): boolean {
 }
 
 describe('round-trip: multi-line descriptions', () => {
-    it('flattens a multi-line model description into a single-line trailing comment', () => {
+    it('splits a multi-line model description across doc-comment lines', () => {
         const root = ckRoot({
             models: [model('User', [field('id', scalarType('uuid'))], { description: 'A user.\nSpans multiple\nlines.' })],
         });
         const result = astToCk(root);
-        expect(result).toContain('contract User: { # A user. Spans multiple lines.');
-        // The comment line must not contain an embedded newline that leaks source.
-        const commentLine = result.split('\n').find(l => l.includes('contract User'))!;
-        expect(commentLine).toBe('contract User: { # A user. Spans multiple lines.');
+        expect(result).toContain('# A user.\n# Spans multiple\n# lines.\ncontract User: {');
+        // Every emitted comment must stay on one line — an embedded newline would terminate the
+        // comment and leak the remainder as raw source.
+        for (const line of result.split('\n')) {
+            if (line.trimStart().startsWith('#')) expect(line).not.toContain('\n');
+        }
+        expect(parsesCleanly(result)).toBe(true);
     });
 
     it('flattens a multi-line field description', () => {
@@ -511,10 +522,16 @@ describe('round-trip: enum values needing quotes', () => {
         expect(serializeType(enumType('a "quoted" value'))).toBe(`enum('a "quoted" value')`);
     });
 
-    it('keeps double quotes when the value contains both quote styles', () => {
-        // `.ck` string literals have no escape sequences, so a value with both
-        // quote styles cannot round-trip; the serializer keeps double quotes.
-        expect(serializeType(enumType(`a "b" 'c'`))).toBe(`enum("a "b" 'c'")`);
+    it('still emits parseable source when the value contains both quote styles', () => {
+        // `.ck` string literals have no escape sequences, so a value carrying both quote styles
+        // is unrepresentable. It cannot come from `parseCk` for that same reason, so this only
+        // arises from a programmatically built AST — the printer degrades the value rather than
+        // emit source that will not parse. `isUnquotable` lets a producer warn before that.
+        expect(isUnquotable(`a "b" 'c'`)).toBe(true);
+        const root = ckRoot({
+            models: [model('Task', [field('status', enumType(`a "b" 'c'`))])],
+        });
+        expect(parsesCleanly(astToCk(root))).toBe(true);
     });
 
     it('re-parses cleanly with space-containing enum values', () => {

package/tests/component-refs.test.ts

@@ -0,0 +1,114 @@
+import { describe, it, expect } from 'vitest';
+import { convertAndParse, onlyOperation, responseFor } from './helpers.js';
+
+/**
+ * Only `#/components/schemas/*` refs survive into `.ck` as model references. Every other
+ * component section has no `.ck` counterpart and nothing downstream resolved it, so a `$ref`'d
+ * parameter used to reach the printer with no name and emit `undefined: string` — which parses,
+ * making the corruption invisible.
+ */
+describe('component $ref inlining', () => {
+    const base = {
+        openapi: '3.1.0',
+        info: { title: 'T', version: '1.0' },
+        components: {
+            schemas: { Pet: { type: 'object', properties: { id: { type: 'string' } } } },
+            parameters: {
+                Limit: { name: 'limit', in: 'query', description: 'page size', schema: { type: 'integer' } },
+                TraceId: { name: 'x-trace-id', in: 'header', required: true, schema: { type: 'string' } },
+            },
+            headers: { RateLimit: { description: 'requests left', schema: { type: 'integer' } } },
+            responses: {
+                NotFound: { description: 'missing', content: { 'application/json': { schema: { $ref: '#/components/schemas/Pet' } } } },
+            },
+            requestBodies: {
+                PetBody: { content: { 'application/json': { schema: { $ref: '#/components/schemas/Pet' } } } },
+            },
+        },
+    };
+
+    it('inlines a $ref parameter instead of emitting a nameless one', async () => {
+        const { root, warnings } = await convertAndParse({
+            input: {
+                ...base,
+                paths: {
+                    '/pets': {
+                        get: {
+                            operationId: 'listPets',
+                            parameters: [{ $ref: '#/components/parameters/Limit' }, { $ref: '#/components/parameters/TraceId' }],
+                            responses: { '200': { description: 'ok' } },
+                        },
+                    },
+                },
+            },
+        });
+        const op = onlyOperation(root);
+        expect(op.query).toEqual(expect.objectContaining({ kind: 'params' }));
+        const query = op.query as { kind: 'params'; nodes: { name: string; optional: boolean }[] };
+        expect(query.nodes.map(n => n.name)).toEqual(['limit']);
+        expect(query.nodes[0]!.optional).toBe(true);
+
+        const headers = op.headers as { kind: 'params'; nodes: { name: string; optional: boolean }[] };
+        expect(headers.nodes.map(n => n.name)).toEqual(['x-trace-id']);
+        expect(headers.nodes[0]!.optional).toBe(false);
+
+        expect(warnings.filter(w => w.message.includes('no name'))).toHaveLength(0);
+    });
+
+    it('inlines a $ref response and request body, keeping the schema ref a model ref', async () => {
+        const { root, ck } = await convertAndParse({
+            input: {
+                ...base,
+                paths: {
+                    '/pets': {
+                        post: {
+                            operationId: 'createPet',
+                            requestBody: { $ref: '#/components/requestBodies/PetBody' },
+                            responses: { '201': { description: 'made' }, '404': { $ref: '#/components/responses/NotFound' } },
+                        },
+                    },
+                },
+            },
+        });
+        const op = onlyOperation(root);
+        expect(op.request!.bodies[0]!.bodyType).toEqual({ kind: 'ref', name: 'Pet' });
+        expect(responseFor(op, 404).bodies[0]!.bodyType).toEqual({ kind: 'ref', name: 'Pet' });
+        expect(ck).not.toContain('$ref');
+    });
+
+    it('inlines a $ref response header', async () => {
+        const { root } = await convertAndParse({
+            input: {
+                ...base,
+                paths: {
+                    '/pets': {
+                        get: {
+                            operationId: 'listPets',
+                            responses: { '200': { description: 'ok', headers: { 'X-Rate-Limit': { $ref: '#/components/headers/RateLimit' } } } },
+                        },
+                    },
+                },
+            },
+        });
+        expect(responseFor(onlyOperation(root), 200).headers!.map(h => h.name)).toEqual(['X-Rate-Limit']);
+    });
+
+    it('warns and drops rather than emitting a nameless parameter for an unresolvable $ref', async () => {
+        const { root, warnings } = await convertAndParse({
+            input: {
+                ...base,
+                paths: {
+                    '/pets': {
+                        get: {
+                            operationId: 'listPets',
+                            parameters: [{ $ref: '#/components/parameters/Nope' }],
+                            responses: { '200': { description: 'ok' } },
+                        },
+                    },
+                },
+            },
+        });
+        expect(warnings.some(w => w.message.includes("unresolved $ref '#/components/parameters/Nope'"))).toBe(true);
+        expect(onlyOperation(root).query).toBeUndefined();
+    });
+});

package/tests/coverage.test.ts

@@ -0,0 +1,246 @@
+import { describe, it, expect } from 'vitest';
+import { convertAndParse, onlyOperation, responseFor } from './helpers.js';
+import { schemaToTypeNode } from '../src/schema-to-ast.js';
+import { WarningCollector } from '../src/warnings.js';
+import type { SchemaContext } from '../src/schema-to-ast.js';
+
+function schemaCtx(warnings = new WarningCollector()): SchemaContext {
+    return { circularRefs: new Set(), warnings, path: '#/x', includeComments: true, namedSchemas: {}, extractedModels: [], inlineCounter: 0, insideModel: true };
+}
+
+const spec = (pathItem: Record<string, unknown>, extra: Record<string, unknown> = {}) => ({
+    openapi: '3.1.0',
+    info: { title: 'T', version: '1.0' },
+    paths: { '/pets': pathItem },
+    ...extra,
+});
+
+const ok = { '200': { description: 'ok' } };
+
+describe('operation name', () => {
+    it('takes `name:` from summary, keeping description as the doc comment', async () => {
+        const { root } = await convertAndParse({
+            input: spec({ get: { operationId: 'listPets', summary: 'List every pet', description: 'Long prose.', responses: ok } }),
+        });
+        const op = onlyOperation(root);
+        expect(op.name).toBe('List every pet');
+        expect(op.sdk).toBe('listPets');
+        expect(op.description).toBe('Long prose.');
+    });
+
+    it('sanitizes a summary that `nameText` could not carry', async () => {
+        // `nameText` runs to end of line and stops at `}` or a whitespace-preceded `#`. An
+        // unsanitized summary would close the operation block early and mis-parse the rest.
+        const { root } = await convertAndParse({
+            input: spec({ get: { operationId: 'x', summary: 'Close } the brace\nand # comment', responses: ok } }),
+        });
+        expect(onlyOperation(root).name).toBe('Close the brace and comment');
+    });
+});
+
+describe('request content types', () => {
+    it('keeps a content type outside the three that used to be allowed', async () => {
+        const { root } = await convertAndParse({
+            input: spec({
+                post: {
+                    operationId: 'upload',
+                    requestBody: { content: { 'text/csv': { schema: { type: 'string' } }, 'application/vnd.api+json': { schema: { type: 'object', properties: { a: { type: 'string' } } } } } },
+                    responses: ok,
+                },
+            }),
+        });
+        expect(onlyOperation(root).request!.bodies.map(b => b.contentType)).toEqual(['text/csv', 'application/vnd.api+json']);
+    });
+
+    it('warns and skips a mime the grammar cannot express', async () => {
+        const { warnings } = await convertAndParse({
+            input: spec({
+                post: { operationId: 'upload', requestBody: { content: { 'text/plain; charset=utf-8': { schema: { type: 'string' } } } }, responses: ok },
+            }),
+        });
+        expect(warnings.some(w => w.message.includes('not a plain type/subtype'))).toBe(true);
+    });
+});
+
+describe('warnings for constructs with no .ck equivalent', () => {
+    it('warns on head/options/trace rather than dropping them silently', async () => {
+        const { warnings } = await convertAndParse({
+            input: spec({ get: { operationId: 'x', responses: ok }, head: { responses: ok }, trace: { responses: ok } }),
+        });
+        expect(warnings.some(w => w.message.includes('`head` operations'))).toBe(true);
+        expect(warnings.some(w => w.message.includes('`trace` operations'))).toBe(true);
+    });
+
+    it('warns on a non-numeric response key', async () => {
+        const { warnings } = await convertAndParse({
+            input: spec({ get: { operationId: 'x', responses: { ...ok, default: { description: 'fallback' }, '4XX': { description: 'client' } } } }),
+        });
+        expect(warnings.some(w => w.message.includes("'default' is not a numeric status code"))).toBe(true);
+        expect(warnings.some(w => w.message.includes("'4XX' is not a numeric status code"))).toBe(true);
+    });
+
+    it('warns on a cookie parameter', async () => {
+        const { warnings } = await convertAndParse({
+            input: spec({ get: { operationId: 'x', parameters: [{ name: 'sid', in: 'cookie', schema: { type: 'string' } }], responses: ok } }),
+        });
+        expect(warnings.some(w => w.message.includes('cookie parameters'))).toBe(true);
+    });
+
+    it('warns on numeric constraints `.ck` cannot express', () => {
+        const warnings = new WarningCollector();
+        schemaToTypeNode({ type: 'integer', exclusiveMinimum: 0, multipleOf: 5 }, schemaCtx(warnings));
+        expect(warnings.warnings.map(w => w.message)).toEqual([
+            expect.stringContaining('exclusiveMinimum'),
+            expect.stringContaining('multipleOf'),
+        ]);
+    });
+});
+
+describe('schema coverage', () => {
+    it('maps duration and the uri/email format aliases', () => {
+        const ctx = schemaCtx();
+        expect(schemaToTypeNode({ type: 'string', format: 'duration' }, ctx)).toEqual({ kind: 'scalar', name: 'duration' });
+        expect(schemaToTypeNode({ type: 'string', format: 'idn-email' }, ctx)).toEqual({ kind: 'scalar', name: 'email' });
+        expect(schemaToTypeNode({ type: 'string', format: 'uri-reference' }, ctx)).toEqual({ kind: 'scalar', name: 'url' });
+    });
+
+    it('imports additionalProperties: true as mode(loose)', async () => {
+        const { root } = await convertAndParse({
+            input: spec({ get: { operationId: 'x', responses: ok } }, {
+                components: { schemas: { Bag: { type: 'object', properties: { id: { type: 'string' } }, additionalProperties: true } } },
+            }),
+        });
+        expect(root.models.find(m => m.name === 'Bag')!.mode).toBe('loose');
+    });
+
+    it('leaves additionalProperties: false at the strict default', async () => {
+        const { root } = await convertAndParse({
+            input: spec({ get: { operationId: 'x', responses: ok } }, {
+                components: { schemas: { Sealed: { type: 'object', properties: { id: { type: 'string' } }, additionalProperties: false } } },
+            }),
+        });
+        expect(root.models.find(m => m.name === 'Sealed')!.mode).toBeUndefined();
+    });
+});
+
+describe('spec-level security', () => {
+    // `.ck` treats an absent security block as "secured, default policy", so a non-empty OpenAPI
+    // requirement is the default and prints nothing. The case that carries information is the
+    // opposite one: a spec that is globally *unsecured*, which used to be dropped because
+    // `globalSecurity` was collected and never read.
+    it('applies a spec-level `security: []` to an operation that does not override it', async () => {
+        const { root } = await convertAndParse({
+            input: spec({ get: { operationId: 'x', responses: ok }, post: { operationId: 'y', security: [{ apiKey: [] }], responses: ok } }, {
+                security: [],
+                components: { securitySchemes: { apiKey: { type: 'apiKey', name: 'k', in: 'header' } } },
+            }),
+        });
+        const [get, post] = root.routes[0]!.operations;
+        expect(get!.security).toBe('none');
+        expect(post!.security).toBeUndefined();
+    });
+});
+
+describe('schema name sanitization', () => {
+    it('prefixes a name that would start with a digit', async () => {
+        // `identStart` excludes digits, so "3DModel" would otherwise emit a name the parser rejects.
+        const { root } = await convertAndParse({
+            input: spec({ get: { operationId: 'x', responses: ok } }, {
+                components: { schemas: { '3DModel': { type: 'object', properties: { id: { type: 'string' } } } } },
+            }),
+        });
+        expect(root.models.map(m => m.name)).toContain('_3DModel');
+    });
+});
+
+describe('tag splitting', () => {
+    it('files a model reached only from a query param under its own tag', async () => {
+        // `collectParamSourceRefs` was written against the pre-tagged-union `ParamSource`, so a
+        // `kind: 'params'` source collected nothing and the model fell through to shared.ck.
+        const result = await (await import('../src/convert.js')).convertOpenApiToCk({
+            input: {
+                openapi: '3.1.0',
+                info: { title: 'T', version: '1.0' },
+                paths: {
+                    '/pets': {
+                        get: {
+                            operationId: 'listPets',
+                            tags: ['pets'],
+                            parameters: [{ name: 'filter', in: 'query', schema: { $ref: '#/components/schemas/PetFilter' } }],
+                            responses: ok,
+                        },
+                    },
+                },
+                components: { schemas: { PetFilter: { type: 'object', properties: { status: { type: 'string' } } } } },
+            },
+            split: 'by-tag',
+        });
+        expect(result.files.get('pets.ck')).toContain('contract PetFilter:');
+        expect(result.files.has('shared.ck')).toBe(false);
+    });
+});
+
+describe('lazy() placement', () => {
+    const recursive = {
+        components: {
+            schemas: {
+                TreeNode: {
+                    type: 'object',
+                    properties: { id: { type: 'string' }, children: { type: 'array', items: { $ref: '#/components/schemas/TreeNode' } } },
+                },
+            },
+        },
+    };
+
+    it('wraps a self-reference inside the contract, but not the response body naming it', async () => {
+        const { root, ck } = await convertAndParse({
+            input: spec({
+                get: {
+                    operationId: 'getTree',
+                    responses: { '200': { description: 'ok', content: { 'application/json': { schema: { $ref: '#/components/schemas/TreeNode' } } } } },
+                },
+            }, recursive),
+        });
+
+        // Inside the contract the cycle is real and `topoSortModels` cannot order it.
+        const children = root.models.find(m => m.name === 'TreeNode')!.fields.find(f => f.name === 'children')!;
+        expect(children.type).toEqual({ kind: 'array', item: { kind: 'lazy', inner: { kind: 'ref', name: 'TreeNode' } } });
+
+        // In the operation the model is already imported and evaluated.
+        expect(responseFor(onlyOperation(root), 200).bodies[0]!.bodyType).toEqual({ kind: 'ref', name: 'TreeNode' });
+        expect(ck).toContain('application/json: TreeNode');
+    });
+
+    it('leaves request bodies, params and response headers bare too', async () => {
+        const { root } = await convertAndParse({
+            input: spec({
+                post: {
+                    operationId: 'putTree',
+                    parameters: [{ name: 'filter', in: 'query', schema: { $ref: '#/components/schemas/TreeNode' } }],
+                    requestBody: { content: { 'application/json': { schema: { $ref: '#/components/schemas/TreeNode' } } } },
+                    responses: ok,
+                },
+            }, recursive),
+        });
+        const op = onlyOperation(root);
+        expect(op.request!.bodies[0]!.bodyType).toEqual({ kind: 'ref', name: 'TreeNode' });
+        expect((op.query as { kind: 'params'; nodes: { type: unknown }[] }).nodes[0]!.type).toEqual({ kind: 'ref', name: 'TreeNode' });
+    });
+
+    it('still wraps inside a model extracted from an inline body schema', async () => {
+        // The extracted model is a contract body like any other.
+        const { root } = await convertAndParse({
+            input: spec({
+                post: {
+                    operationId: 'putTree',
+                    requestBody: {
+                        content: { 'application/json': { schema: { type: 'object', properties: { root: { $ref: '#/components/schemas/TreeNode' } } } } },
+                    },
+                    responses: ok,
+                },
+            }, recursive),
+        });
+        const extracted = root.models.find(m => m.name === 'PutTreeRequest')!;
+        expect(extracted.fields.find(f => f.name === 'root')!.type).toEqual({ kind: 'lazy', inner: { kind: 'ref', name: 'TreeNode' } });
+    });
+});

package/tests/error-responses.test.ts

@@ -0,0 +1,94 @@
+import { describe, it, expect } from 'vitest';
+import { emittedResponses, thrownResponses } from '@contractkit/core';
+import { convertAndParse, onlyOperation, responseFor } from './helpers.js';
+
+/**
+ * OpenAPI cannot say whether a handler *returns* a status or merely documents it; `.ck` can, and
+ * every generator downstream depends on the answer. A bodied `404` imported as service-produced
+ * makes the generated router responsible for writing it and makes the SDKs hand it back as a
+ * value instead of throwing — wrong for what is almost always an error contract.
+ *
+ * These assert on the parsed AST and on core's own response sets rather than on the emitted
+ * text, so they check the meaning the generators will see.
+ */
+
+function specWith(responses: Record<string, unknown>) {
+    return {
+        openapi: '3.1.0',
+        info: { title: 'T', version: '1.0' },
+        paths: { '/pets': { get: { operationId: 'listPets', responses } } },
+        components: {
+            schemas: {
+                Pet: { type: 'object', properties: { id: { type: 'string' } } },
+                Error: { type: 'object', properties: { message: { type: 'string' } } },
+            },
+        },
+    };
+}
+
+const json = (ref: string) => ({ description: 'd', content: { 'application/json': { schema: { $ref: `#/components/schemas/${ref}` } } } });
+
+describe('imported error responses', () => {
+    it('marks a bodied 4xx/5xx as documented, leaving 2xx emitted', async () => {
+        const { root, ck } = await convertAndParse({
+            input: specWith({ '200': json('Pet'), '404': json('Error'), '500': json('Error') }),
+        });
+        const op = onlyOperation(root);
+
+        expect(responseFor(op, 200).emit).toBeUndefined();
+        expect(responseFor(op, 404).emit).toBe('documented');
+        expect(responseFor(op, 500).emit).toBe('documented');
+
+        // The service produces only the 200; the error bodies reach a client as thrown errors.
+        expect(emittedResponses(op).map(r => r.statusCode)).toEqual([200]);
+        expect(thrownResponses(op).map(r => r.statusCode)).toEqual([404, 500]);
+
+        // The modifier is lexical — `404 (documented)` with a space is a parse error.
+        expect(ck).toContain('404(documented): {');
+    });
+
+    it('leaves a bare bodyless 4xx alone, so the modifier is never redundant', async () => {
+        const { root, ck } = await convertAndParse({
+            input: specWith({ '200': json('Pet'), '429': { description: 'slow down' } }),
+        });
+        const op = onlyOperation(root);
+
+        // Already not emitted without the marker; `isRedundantDocumented` would warn on it.
+        expect(responseFor(op, 429).emit).toBeUndefined();
+        expect(responseFor(op, 429).hasBlock).toBeFalsy();
+        expect(ck).not.toContain('429(documented)');
+        expect(thrownResponses(op).map(r => r.statusCode)).toEqual([429]);
+    });
+
+    it('leaves 3xx emitted, since a client observes it either way', async () => {
+        const { root } = await convertAndParse({
+            input: specWith({ '200': json('Pet'), '304': { description: 'not modified' } }),
+        });
+        const op = onlyOperation(root);
+        expect(responseFor(op, 304).emit).toBeUndefined();
+    });
+
+    it('documents a bodyless error status that carries only headers', async () => {
+        const { root } = await convertAndParse({
+            input: specWith({
+                '200': json('Pet'),
+                '503': { description: 'unavailable', headers: { 'Retry-After': { schema: { type: 'integer' } } } },
+            }),
+        });
+        const op = onlyOperation(root);
+        // Headers force a block, which without the marker would mean "the service produces this".
+        expect(responseFor(op, 503).emit).toBe('documented');
+        expect(thrownResponses(op).map(r => r.statusCode)).toEqual([503]);
+    });
+
+    it('reproduces the old behaviour under errorResponses: emitted', async () => {
+        const { root, ck } = await convertAndParse({
+            input: specWith({ '200': json('Pet'), '404': json('Error') }),
+            errorResponses: 'emitted',
+        });
+        const op = onlyOperation(root);
+        expect(responseFor(op, 404).emit).toBeUndefined();
+        expect(emittedResponses(op).map(r => r.statusCode)).toEqual([200, 404]);
+        expect(ck).not.toContain('(documented)');
+    });
+});