@contractkit/openapi-to-ck 0.10.2 → 0.11.0

package/src/normalize.ts

@@ -6,20 +6,96 @@ import type { WarningCollector } from './warnings.js';
  * 3.1-like shape. Swagger 2.0 and OpenAPI 3.0 documents are transformed
  * so that downstream code only needs to handle one schema dialect.
  *
- * Uses @scalar/openapi-parser's `upgrade()` for the heavy lifting when
- * available, with manual fallbacks for edge cases.
+ * The transformation is hand-written. An earlier note here claimed `@scalar/openapi-parser`'s
+ * `upgrade()` did the heavy lifting; it never did, and that dependency has been dropped.
+ *
+ * After version normalization, `dereferenceComponents` inlines `$ref`s to reusable non-schema
+ * components, so the rest of the pipeline sees only inline parameter, response, request-body and
+ * header objects. Schema `$ref`s are deliberately left intact — they become `.ck` model refs.
  */
 export function normalize(doc: Record<string, unknown>, warnings: WarningCollector): NormalizedDocument {
     const version = detectVersion(doc);
 
-    if (version === '2.0') {
-        return normalizeSwagger2(doc, warnings);
-    }
-    if (version === '3.0') {
-        return normalizeOas30(doc as unknown as NormalizedDocument, warnings);
+    const normalized =
+        version === '2.0'
+            ? normalizeSwagger2(doc, warnings)
+            : version === '3.0'
+              ? normalizeOas30(doc as unknown as NormalizedDocument, warnings)
+              : // 3.1+ — already in target shape
+                (doc as unknown as NormalizedDocument);
+
+    dereferenceComponents(normalized, warnings);
+    return normalized;
+}
+
+// ─── Component $ref inlining ──────────────────────────────────────────────
+
+/** The component sections whose `$ref`s are inlined. `schemas` is deliberately absent. */
+const DEREF_SECTIONS = ['parameters', 'requestBodies', 'responses', 'headers'] as const;
+
+/** Guards against a `$ref` chain that loops back on itself. */
+const MAX_REF_DEPTH = 10;
+
+/**
+ * Inline `$ref`s to reusable non-schema components.
+ *
+ * Only `#/components/schemas/*` refs survive conversion — they become `.ck` model references.
+ * Everything else (`parameters`, `requestBodies`, `responses`, `headers`) has no `.ck`
+ * counterpart, and nothing downstream resolves it: a `$ref`'d parameter used to reach
+ * `parameterToNode` with no `name` and print as `undefined: string`, which *parses*, so the
+ * corruption was silent. Resolving here means the rest of the pipeline only ever sees inline
+ * objects.
+ *
+ * Sibling keys are kept and win over the target's, matching how OpenAPI 3.1 treats a `$ref`
+ * alongside other properties.
+ */
+function dereferenceComponents(doc: NormalizedDocument, warnings: WarningCollector): void {
+    const components = doc.components as Record<string, Record<string, unknown>> | undefined;
+
+    const resolve = (node: unknown, path: string, depth = 0): unknown => {
+        if (!node || typeof node !== 'object') return node;
+        if (Array.isArray(node)) return node.map(item => resolve(item, path, depth));
+
+        const obj = node as Record<string, unknown>;
+        const ref = obj.$ref;
+        if (typeof ref === 'string') {
+            const match = /^#\/components\/([^/]+)\/(.+)$/.exec(ref);
+            const section = match?.[1];
+            // Schema refs are the ones that survive into `.ck`; leave them for `extractRefName`.
+            if (section && section !== 'schemas' && (DEREF_SECTIONS as readonly string[]).includes(section)) {
+                if (depth >= MAX_REF_DEPTH) {
+                    warnings.warn(path, `$ref chain too deep to resolve: ${ref}`);
+                    return obj;
+                }
+                const target = components?.[section]?.[decodeRefToken(match[2]!)];
+                if (target === undefined) {
+                    warnings.warn(path, `unresolved $ref '${ref}' — the component is not defined`);
+                    return obj;
+                }
+                const siblings = { ...obj };
+                delete siblings.$ref;
+                const resolved = resolve(target, path, depth + 1);
+                return { ...(resolved as Record<string, unknown>), ...siblings };
+            }
+            return obj;
+        }
+
+        const out: Record<string, unknown> = {};
+        for (const [key, value] of Object.entries(obj)) {
+            // A schema subtree can hold `$ref`s of its own, all of them schema refs.
+            out[key] = key === 'schema' || key === 'schemas' ? value : resolve(value, `${path}/${key}`, depth);
+        }
+        return out;
+    };
+
+    for (const [path, pathItem] of Object.entries(doc.paths ?? {})) {
+        doc.paths![path] = resolve(pathItem, `#/paths/${path}`) as typeof pathItem;
     }
-    // 3.1+ — already in target shape
-    return doc as unknown as NormalizedDocument;
+}
+
+/** Undo the `~1`/`~0` escaping a JSON pointer uses for `/` and `~`. */
+function decodeRefToken(token: string): string {
+    return decodeURIComponent(token).replace(/~1/g, '/').replace(/~0/g, '~');
 }
 
 function detectVersion(doc: Record<string, unknown>): '2.0' | '3.0' | '3.1' {
@@ -88,7 +164,7 @@ function normalizePathItem2(
     globalProduces: string[],
     warnings: WarningCollector,
 ): Record<string, unknown> {
-    const methods = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options'];
+    const methods = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options', 'trace'];
     const normalized: Record<string, unknown> = {};
 
     // Path-level parameters
@@ -277,7 +353,7 @@ function normalizeOas30(doc: NormalizedDocument, _warnings: WarningCollector): N
 }
 
 function normalizePathItemSchemas(pathItem: Record<string, unknown>): void {
-    const methods = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options'];
+    const methods = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options', 'trace'];
     for (const method of methods) {
         const op = pathItem[method] as Record<string, unknown> | undefined;
         if (!op) continue;

package/src/paths-to-ast.ts

@@ -24,8 +24,28 @@ import type { SchemaContext } from './schema-to-ast.js';
 import type { WarningCollector } from './warnings.js';
 
 const LOC: SourceLocation = { file: '', line: 0 };
+
+/** A plain `type/subtype`, which is all `mimeType` in the grammar accepts. */
+const MIME_RE = /^[a-z0-9][a-z0-9.+_-]*\/[a-z0-9][a-z0-9.+_-]*$/i;
+
+/**
+ * Reduce a summary to something `nameText` can hold.
+ *
+ * `nameText = (~("\n" | "}" | " #" | "\t#") any)+` — the value runs to end of line and stops at
+ * a closing brace or a whitespace-preceded `#`. An OpenAPI summary respects none of that, and an
+ * unsanitized one would mis-parse the rest of the operation.
+ */
+function toNameText(summary: string): string {
+    return summary
+        .replace(/[}#]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
 const HTTP_METHODS: HttpMethod[] = ['get', 'post', 'put', 'patch', 'delete'];
 
+/** Methods a spec may declare that `httpMethod` in the grammar has no keyword for. */
+const UNSUPPORTED_METHODS = ['head', 'options', 'trace'] as const;
+
 // ─── Public API ───────────────────────────────────────────────────────────
 
 export interface PathsContext {
@@ -37,6 +57,8 @@ export interface PathsContext {
     extractedModels: ModelNode[];
     /** Global security from the spec (for detecting explicit overrides). */
     globalSecurity?: Record<string, string[]>[];
+    /** How bodied 4xx/5xx responses are imported. See `ConvertOptions.errorResponses`. */
+    errorResponses: 'documented' | 'emitted';
 }
 
 /**
@@ -69,6 +91,13 @@ function pathItemToRoute(path: string, pathItem: NormalizedPathItem, ctx: PathsC
     // Collect path-level parameters
     const pathParams = (pathItem.parameters ?? []).filter(p => p.in === 'path');
 
+    for (const method of UNSUPPORTED_METHODS) {
+        // A grammar limitation, not a converter one — `.ck` has no keyword for these verbs.
+        if ((pathItem as Record<string, unknown>)[method]) {
+            ctx.warnings.warn(`#/paths/${encodePathSegment(path)}/${method}`, `\`${method}\` operations have no .ck equivalent; dropped`);
+        }
+    }
+
     for (const method of HTTP_METHODS) {
         const op = pathItem[method];
         if (!op) continue;
@@ -121,6 +150,14 @@ function operationToNode(method: HttpMethod, op: NormalizedOperation, path: stri
         node.sdk = op.operationId;
     }
 
+    // summary → `name:`, the human-readable label the key exists for. `description` stays the
+    // doc comment; when only a summary is given it becomes the name and is not doubled as prose.
+    if (op.summary) {
+        const name = toNameText(op.summary);
+        if (name) node.name = name;
+        else ctx.warnings.warn(`${pathPrefix}/summary`, 'summary has no content `.ck` can carry as a name; dropped');
+    }
+
     // Description
     if (op.description && ctx.includeComments) {
         node.description = op.description;
@@ -136,10 +173,19 @@ function operationToNode(method: HttpMethod, op: NormalizedOperation, path: stri
     const headerParams: OpParamNode[] = [];
 
     for (const param of op.parameters ?? []) {
+        // `dereferenceComponents` inlines `#/components/parameters/*` before this runs, so a
+        // parameter with no name is one nothing could resolve. Emitting it would print
+        // `undefined: string`, which parses — silent corruption is worse than a dropped param.
+        if (!param?.name) {
+            ctx.warnings.warn(`${pathPrefix}/parameters`, 'skipped a parameter with no name (an unresolved $ref?)');
+            continue;
+        }
         if (param.in === 'query') {
             queryParams.push(parameterToNode(param, schemaCtx));
         } else if (param.in === 'header') {
             headerParams.push(parameterToNode(param, schemaCtx));
+        } else if (param.in === 'cookie') {
+            ctx.warnings.warn(`${pathPrefix}/parameters/${param.name}`, 'cookie parameters have no `.ck` equivalent; dropped');
         }
     }
 
@@ -158,15 +204,22 @@ function operationToNode(method: HttpMethod, op: NormalizedOperation, path: stri
     // Responses
     const responses = op.responses ?? {};
     for (const [code, resp] of Object.entries(responses)) {
+        // Strictly numeric: `parseInt('4XX')` is 4, which would silently invent a status code.
+        if (!/^\d{3}$/.test(code)) {
+            // `default`, `2XX`, `4XX` — the response block is keyed by a numeric status.
+            ctx.warnings.warn(`${pathPrefix}/responses/${code}`, `response key '${code}' is not a numeric status code; dropped`);
+            continue;
+        }
         const statusCode = parseInt(code, 10);
-        if (isNaN(statusCode)) continue;
         const respNode = responseToNode(statusCode, resp, op.operationId ?? `${method}${toPascalCase(path)}`, schemaCtx, ctx);
         node.responses.push(respNode);
     }
 
-    // Security
-    if (op.security !== undefined) {
-        node.security = convertSecurity(op.security);
+    // Security. A spec-level `security` applies to every operation that does not override it;
+    // it used to be collected and never read, so a globally-secured spec imported as unsecured.
+    const security = op.security ?? ctx.globalSecurity;
+    if (security !== undefined) {
+        node.security = convertSecurity(security);
     }
 
     return node;
@@ -238,19 +291,22 @@ function requestBodyToNode(
     const content = reqBody.content;
     if (!content) return undefined;
 
-    const supported = new Set<string>(['application/json', 'application/x-www-form-urlencoded', 'multipart/form-data']);
     const bodies: OpRequestNode['bodies'] = [];
 
     for (const [contentType, mediaType] of Object.entries(content)) {
-        if (!supported.has(contentType) || !mediaType?.schema) continue;
+        // `.ck` accepts any RFC 6838 `type/subtype`, so there is no reason to narrow a spec to
+        // the three content types this used to allow. What it cannot carry is a parameterised
+        // (`; charset=`) or wildcard mime, since `mimeType` is two `mimeChar+` runs.
+        if (!MIME_RE.test(contentType)) {
+            ctx.warnings.warn(`${schemaCtx.path}/requestBody/content`, `content type '${contentType}' is not a plain type/subtype; skipped`);
+            continue;
+        }
+        if (!mediaType?.schema) continue;
         const { typeNode, model } = extractInlineModel(mediaType.schema, `${toPascalCase(operationName)}Request`, schemaCtx);
         if (model) {
             ctx.extractedModels.push(model);
         }
-        bodies.push({
-            contentType: contentType as OpRequestNode['bodies'][number]['contentType'],
-            bodyType: typeNode,
-        });
+        bodies.push({ contentType, bodyType: typeNode });
     }
 
     if (bodies.length === 0) return undefined;
@@ -259,6 +315,23 @@ function requestBodyToNode(
 
 // ─── Responses ────────────────────────────────────────────────────────────
 
+/**
+ * Whether an imported status should be marked `(documented)` rather than service-produced.
+ *
+ * Only applies to a status that carries a block, because that is the only case where the
+ * modifier does anything: `isEmitted` in core treats a block as "the service produces this", and
+ * `isRedundantDocumented` warns when `(documented)` is put on a bare bodyless non-2xx, where the
+ * status is already not emitted. 3xx is left alone — `observableResponses` already covers
+ * everything below 400, so the marker would change nothing a client sees, and a spec'd redirect
+ * body is plausibly service-produced.
+ */
+function shouldDocument(statusCode: number, braced: boolean, resp: NormalizedResponse, ctx: PathsContext): boolean {
+    if (!braced) return false;
+    // A spec this project emitted says so outright; prefer it over guessing from the status.
+    if (resp['x-contractkit-emit'] === 'documented') return true;
+    return statusCode >= 400 && ctx.errorResponses === 'documented';
+}
+
 function responseToNode(
     statusCode: number,
     resp: NormalizedResponse,
@@ -267,7 +340,12 @@ function responseToNode(
     ctx: PathsContext,
 ): OpResponseNode {
     const headers = convertResponseHeaders(resp.headers, schemaCtx);
-    const empty = (): OpResponseNode => ({ statusCode, bodies: [], ...(headers ? { headers, hasBlock: true } : {}) });
+    const documented = (braced: boolean) => (shouldDocument(statusCode, braced, resp, ctx) ? { emit: 'documented' as const } : {});
+    const empty = (): OpResponseNode => ({
+        statusCode,
+        bodies: [],
+        ...(headers ? { headers, hasBlock: true, ...documented(true) } : {}),
+    });
 
     if (!resp.content) return empty();
 
@@ -291,6 +369,7 @@ function responseToNode(
         bodies,
         hasBlock: true,
         ...(headers ? { headers } : {}),
+        ...documented(true),
     };
 }
 
@@ -334,6 +413,8 @@ function makeSchemaCtx(ctx: PathsContext, path: string): SchemaContext {
         namedSchemas: ctx.namedSchemas as Record<string, never>,
         extractedModels: ctx.extractedModels,
         inlineCounter: 0,
+        // A response body, request body, param or header names an already-imported model.
+        insideModel: false,
     };
 }
 

package/src/plugin.ts

@@ -8,12 +8,16 @@ interface ImportArgs {
     specPath: string;
     output: string;
     split: 'single' | 'by-tag';
+    includeComments: boolean;
+    errorResponses: 'documented' | 'emitted';
 }
 
 function parseImportArgs(argv: string[]): ImportArgs {
     let specPath = '';
     let output = '.';
     let split: 'single' | 'by-tag' = 'by-tag';
+    let includeComments = true;
+    let errorResponses: 'documented' | 'emitted' = 'documented';
 
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i]!;
@@ -22,12 +26,17 @@ function parseImportArgs(argv: string[]): ImportArgs {
         } else if (arg === '--split') {
             const val = argv[++i];
             if (val === 'single' || val === 'by-tag') split = val;
+        } else if (arg === '--no-comments') {
+            includeComments = false;
+        } else if (arg === '--error-responses') {
+            const val = argv[++i];
+            if (val === 'documented' || val === 'emitted') errorResponses = val;
         } else if (!arg.startsWith('-')) {
             specPath = arg;
         }
     }
 
-    return { specPath, output, split };
+    return { specPath, output, split, includeComments, errorResponses };
 }
 
 const USAGE = `Usage: contractkit import-openapi <spec-path> [options]
@@ -40,6 +49,11 @@ Arguments:
 Options:
   -o, --output <dir>   Output directory for .ck files (default: current directory)
       --split <mode>   How to split output: "by-tag" (one file per tag) or "single" (default: by-tag)
+      --no-comments    Skip OpenAPI descriptions instead of emitting them as # comments
+      --error-responses <mode>
+                       How to import a 4xx/5xx that declares a body: "documented" (default)
+                       marks it \`404(documented):\`, so the SDK throws it and the generated
+                       router does not write it; "emitted" imports it as service-produced
   -h, --help           Show this help message`;
 
 const plugin: ContractKitPlugin = {
@@ -61,7 +75,8 @@ const plugin: ContractKitPlugin = {
             const result = await convertOpenApiToCk({
                 input: resolve(parsed.specPath),
                 split: parsed.split,
-                includeComments: true,
+                includeComments: parsed.includeComments,
+                errorResponses: parsed.errorResponses,
                 onWarning: (w: Warning) => {
                     const prefix = w.severity === 'warn' ? '⚠' : 'ℹ';
                     console.warn(`  ${prefix}  ${w.path}: ${w.message}`);

package/src/schema-to-ast.ts

@@ -6,8 +6,20 @@ import type { WarningCollector } from './warnings.js';
 // ─── Conversion Context ───────────────────────────────────────────────────
 
 export interface SchemaContext {
-    /** Schema names involved in circular references — use lazy() for these. */
+    /** Schema names involved in circular references — see {@link insideModel}. */
     circularRefs: Set<string>;
+    /**
+     * Whether the type being built sits inside a `contract` body. Default `true`.
+     *
+     * `lazy()` exists to break a definition cycle: `topoSortModels` in the TypeScript plugin
+     * emits dependencies before dependents and can only fall back to source order for a cycle,
+     * so a reference from one cycle member to another has to be deferred. A reference from an
+     * operation — a response body, request body, param, or response header — is not part of any
+     * such cycle: it names a model the generated module has already imported and fully
+     * evaluated. Wrapping it achieves nothing and makes every contract importing a
+     * self-referential schema noisier than it needs to be.
+     */
+    insideModel: boolean;
     /** Warning collector for unsupported features. */
     warnings: WarningCollector;
     /** Current JSON pointer path (for warnings). */
@@ -28,12 +40,17 @@ const LOC: SourceLocation = { file: '', line: 0 };
 
 const FORMAT_TO_SCALAR: Record<string, ScalarTypeNode['name']> = {
     email: 'email',
+    'idn-email': 'email',
     uri: 'url',
+    'uri-reference': 'url',
+    iri: 'url',
+    'iri-reference': 'url',
     url: 'url',
     uuid: 'uuid',
     date: 'date',
     'date-time': 'datetime',
     time: 'time',
+    duration: 'duration',
     binary: 'binary',
     int64: 'bigint',
 };
@@ -95,6 +112,9 @@ function schemaToModel(name: string, schema: NormalizedSchema, ctx: SchemaContex
             kind: 'model',
             name,
             fields,
+            // `additionalProperties: true` says unknown keys are allowed, which is `mode(loose)`.
+            // `false` and absent both match `.ck`'s `strict` default, so neither needs a mode.
+            ...(schema.additionalProperties === true ? { mode: 'loose' as const } : {}),
             description,
             loc: LOC,
         };
@@ -116,11 +136,13 @@ function schemaToModel(name: string, schema: NormalizedSchema, ctx: SchemaContex
  * Convert an OpenAPI schema to a ContractTypeNode.
  */
 export function schemaToTypeNode(schema: NormalizedSchema, ctx: SchemaContext): ContractTypeNode {
+    warnUnrepresentableConstraints(schema, ctx);
+
     // $ref
     if (schema.$ref) {
         const refName = extractRefName(schema.$ref);
         if (refName) {
-            if (ctx.circularRefs.has(refName)) {
+            if (ctx.insideModel && ctx.circularRefs.has(refName)) {
                 return { kind: 'lazy', inner: { kind: 'ref', name: refName } };
             }
             return { kind: 'ref', name: refName };
@@ -231,7 +253,7 @@ function stringSchemaToType(schema: NormalizedSchema): ContractTypeNode {
         if (schema.minLength !== undefined) mods.min = schema.minLength;
         if (schema.maxLength !== undefined) mods.max = schema.maxLength;
     }
-    if (schema.pattern) mods.regex = `/${schema.pattern}/`;
+    if (schema.pattern) mods.regex = schema.pattern;
     if (schema.format && !FORMAT_TO_SCALAR[schema.format]) mods.format = schema.format;
 
     return { kind: 'scalar', name: 'string', ...mods };
@@ -372,12 +394,28 @@ function toDiscriminatedUnion(schemas: NormalizedSchema[], discriminator: string
     return { kind: 'discriminatedUnion', discriminator, members };
 }
 
+/** JSON Schema keywords with no `.ck` counterpart, warned about rather than silently dropped. */
+const UNREPRESENTABLE_KEYWORDS = ['exclusiveMinimum', 'exclusiveMaximum', 'multipleOf', 'uniqueItems'] as const;
+
 function warnUnsupported(schema: NormalizedSchema, ctx: SchemaContext): void {
     if (schema.xml) ctx.warnings.warn(ctx.path, 'xml metadata is not supported, skipping');
     if (schema.externalDocs) ctx.warnings.info(ctx.path, 'externalDocs is not supported, skipping');
     if (schema.not) ctx.warnings.warn(ctx.path, 'not keyword is not supported, skipping');
 }
 
+/**
+ * Report constraints `.ck` has no vocabulary for.
+ *
+ * Its scalar and array arguments are `min`, `max`, `len`, `regex` and `format`. Folding
+ * `exclusiveMinimum` into `min=` would be an off-by-one lie and `multipleOf` has no analogue at
+ * all, so the constraint is reported as lost rather than approximated.
+ */
+function warnUnrepresentableConstraints(schema: NormalizedSchema, ctx: SchemaContext): void {
+    for (const keyword of UNREPRESENTABLE_KEYWORDS) {
+        if (schema[keyword] !== undefined) ctx.warnings.warn(ctx.path, `${keyword} has no .ck equivalent, dropping the constraint`);
+    }
+}
+
 /**
  * Extract a named model from an inline object schema (used for request/response bodies).
  */
@@ -393,7 +431,9 @@ export function extractInlineModel(
 
     // If it's an object with properties, extract as a named model
     if (schema.properties || (schema.type === 'object' && schema.additionalProperties === undefined)) {
-        const fields = schemaPropertiesToFields(schema, ctx);
+        // The extracted model is a `contract` body like any other, so references inside it are
+        // subject to the same ordering problem an authored one would be.
+        const fields = schemaPropertiesToFields(schema, { ...ctx, insideModel: true });
         const model: ModelNode = {
             kind: 'model',
             name: suggestedName,
@@ -423,9 +463,13 @@ export function sanitizeName(name: string, warnings: WarningCollector): string {
         .map(part => part.charAt(0).toUpperCase() + part.slice(1))
         .join('');
 
-    if (cleaned !== name) {
-        warnings.info(`#/components/schemas/${name}`, `Schema name sanitized: "${name}" → "${cleaned}"`);
+    // `identStart` excludes digits, so a schema named "3DModel" would sanitize to something the
+    // parser rejects. Prefix rather than drop the digit, which would collide names.
+    const safe = /^[0-9]/.test(cleaned) ? `_${cleaned}` : cleaned;
+
+    if (safe !== name) {
+        warnings.info(`#/components/schemas/${name}`, `Schema name sanitized: "${name}" → "${safe}"`);
     }
 
-    return cleaned || 'UnnamedSchema';
+    return safe || 'UnnamedSchema';
 }

package/src/tag-splitter.ts

@@ -1,4 +1,4 @@
-import type { CkRootNode, ModelNode, OpRouteNode, ContractTypeNode } from '@contractkit/core';
+import type { CkRootNode, ModelNode, OpRouteNode, ContractTypeNode, ParamSource } from '@contractkit/core';
 
 /**
  * Split models and routes into per-tag CkRootNode instances.
@@ -132,21 +132,26 @@ function collectRouteRefs(route: OpRouteNode, refs: Set<string>): void {
     }
 }
 
-function collectParamSourceRefs(source: unknown, refs: Set<string>): void {
-    if (typeof source === 'string') {
-        refs.add(source);
-        return;
-    }
-    if (Array.isArray(source)) {
-        for (const param of source) {
-            if (param && typeof param === 'object' && 'type' in param) {
-                collectTypeRefs(param.type as ContractTypeNode, refs);
-            }
-        }
-        return;
-    }
-    if (source && typeof source === 'object' && 'kind' in source) {
-        collectTypeRefs(source as ContractTypeNode, refs);
+/**
+ * Collect the model names a `params`/`query`/`headers` source refers to.
+ *
+ * `ParamSource` is a tagged union, and this was written against the shape it had before that:
+ * a bare string, an array of params, or a type node. Only `kind: 'ref'` still worked, and only
+ * by coincidence — it happens to look like a `ModelRefTypeNode`. `'params'` and `'type'` fell
+ * through to `collectTypeRefs`, whose switch has neither case, so a model reached only from a
+ * query or header block collected no tags at all and was filed under `shared.ck`.
+ */
+function collectParamSourceRefs(source: ParamSource, refs: Set<string>): void {
+    switch (source.kind) {
+        case 'ref':
+            refs.add(source.name);
+            return;
+        case 'params':
+            for (const param of source.nodes) collectTypeRefs(param.type, refs);
+            return;
+        case 'type':
+            collectTypeRefs(source.node, refs);
+            return;
     }
 }
 

package/src/types.ts

@@ -7,6 +7,20 @@ export interface ConvertOptions {
     split?: 'single' | 'by-tag';
     /** Emit OpenAPI descriptions as # comments. Default: true. */
     includeComments?: boolean;
+    /**
+     * How a 4xx/5xx response that declares a body is imported. Default: `'documented'`.
+     *
+     * OpenAPI cannot say whether the handler *returns* a status or merely documents it, but
+     * `.ck` distinguishes the two and every generator downstream depends on the answer. Writing
+     * `404: { … }` means the service produces it: the generated router writes it and the SDKs
+     * hand it back as a value. `404(documented): { … }` means the body is the error contract —
+     * the SDK throws it as an `SdkError` and the service is not responsible for returning it,
+     * which is what an error response almost always is.
+     *
+     * `'emitted'` reproduces the pre-existing behaviour, where every declared status was imported
+     * as service-produced.
+     */
+    errorResponses?: 'documented' | 'emitted';
     /** Called for each warning during conversion. */
     onWarning?: (warning: Warning) => void;
 }
@@ -57,6 +71,10 @@ export interface NormalizedSchema {
     maximum?: number;
     minItems?: number;
     maxItems?: number;
+    exclusiveMinimum?: number | boolean;
+    exclusiveMaximum?: number | boolean;
+    multipleOf?: number;
+    uniqueItems?: boolean;
     discriminator?: { propertyName?: string; mapping?: Record<string, string> };
     xml?: unknown;
     externalDocs?: unknown;
@@ -71,6 +89,11 @@ export interface NormalizedDocument {
     components?: {
         schemas?: Record<string, NormalizedSchema>;
         securitySchemes?: Record<string, unknown>;
+        /** Reusable component objects, inlined by `dereferenceComponents` before conversion. */
+        parameters?: Record<string, NormalizedParameter>;
+        requestBodies?: Record<string, NormalizedRequestBody>;
+        responses?: Record<string, NormalizedResponse>;
+        headers?: Record<string, NormalizedHeader>;
     };
     security?: Record<string, string[]>[];
     servers?: { url: string; description?: string }[];
@@ -120,6 +143,11 @@ export interface NormalizedRequestBody {
 
 export interface NormalizedResponse {
     description?: string;
+    /**
+     * Set by `@contractkit/plugin-openapi` to carry the emitted-vs-documented distinction, which
+     * OpenAPI itself cannot express. Honoured ahead of the status-code heuristic on import.
+     */
+    'x-contractkit-emit'?: 'documented';
     content?: Record<string, { schema?: NormalizedSchema }>;
     /** OpenAPI Header Objects keyed by header name (case-insensitive on the wire). */
     headers?: Record<string, NormalizedHeader>;