@contractkit/openapi-to-ck 0.10.1 → 0.11.0

package/tests/fixtures/kitchen-sink-3.1.json

@@ -0,0 +1,100 @@
+{
+    "openapi": "3.1.0",
+    "info": { "title": "Kitchen Sink", "version": "1.0.0" },
+    "security": [{ "apiKey": [] }],
+    "paths": {
+        "/widgets/{widgetId}": {
+            "parameters": [{ "$ref": "#/components/parameters/WidgetId" }],
+            "get": {
+                "operationId": "getWidget",
+                "summary": "Fetch a widget } with # awkward chars",
+                "description": "Long prose.\nAcross several lines.",
+                "tags": ["widgets"],
+                "parameters": [
+                    { "$ref": "#/components/parameters/Expand" },
+                    { "name": "sid", "in": "cookie", "schema": { "type": "string" } }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "ok",
+                        "content": {
+                            "application/json": { "schema": { "$ref": "#/components/schemas/Widget" } },
+                            "text/csv": { "schema": { "type": "string" } }
+                        },
+                        "headers": { "X-Rate-Limit": { "$ref": "#/components/headers/RateLimit" } }
+                    },
+                    "204": { "description": "no content" },
+                    "304": { "description": "not modified" },
+                    "404": { "$ref": "#/components/responses/NotFound" },
+                    "429": { "description": "slow down" },
+                    "503": { "description": "unavailable", "headers": { "Retry-After": { "schema": { "type": "integer" } } } },
+                    "default": { "description": "dropped" },
+                    "4XX": { "description": "also dropped" }
+                }
+            },
+            "head": { "responses": { "200": { "description": "ok" } } },
+            "trace": { "responses": { "200": { "description": "ok" } } }
+        },
+        "/widgets": {
+            "post": {
+                "operationId": "createWidget",
+                "tags": ["widgets"],
+                "security": [],
+                "requestBody": {
+                    "content": {
+                        "application/json": { "schema": { "$ref": "#/components/schemas/Widget" } },
+                        "application/vnd.api+json": { "schema": { "type": "object", "properties": { "data": { "type": "string" } } } },
+                        "text/plain; charset=utf-8": { "schema": { "type": "string" } }
+                    }
+                },
+                "responses": { "201": { "description": "created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Widget" } } } } }
+            }
+        }
+    },
+    "components": {
+        "securitySchemes": { "apiKey": { "type": "apiKey", "name": "X-Key", "in": "header" } },
+        "parameters": {
+            "WidgetId": { "name": "widgetId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } },
+            "Expand": { "name": "expand", "in": "query", "description": "expand nested", "schema": { "type": "boolean" } }
+        },
+        "headers": { "RateLimit": { "description": "requests left", "schema": { "type": "integer" } } },
+        "responses": {
+            "NotFound": { "description": "missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }
+        },
+        "schemas": {
+            "Widget": {
+                "type": "object",
+                "description": "A widget.\nDocumented across lines.",
+                "required": ["id", "kind"],
+                "properties": {
+                    "id": { "type": "string", "format": "uuid", "readOnly": true },
+                    "secret": { "type": "string", "writeOnly": true },
+                    "kind": { "type": "string", "enum": ["basic", "on hold", "a \"quoted\" kind"] },
+                    "datePattern": { "type": "string", "pattern": "^\\d{2}/\\d{2}$" },
+                    "ttl": { "type": "string", "format": "duration" },
+                    "contact": { "type": "string", "format": "idn-email" },
+                    "site": { "type": "string", "format": "uri-reference" },
+                    "size": { "type": "integer", "exclusiveMinimum": 0, "multipleOf": 5 },
+                    "tags": { "type": "array", "items": { "type": "string" }, "minItems": 1, "uniqueItems": true },
+                    "legacy": { "type": "string", "deprecated": true },
+                    "nickname": { "type": ["string", "null"] },
+                    "parent": { "$ref": "#/components/schemas/Widget" },
+                    "shape": { "$ref": "#/components/schemas/Shape" }
+                }
+            },
+            "TimestampedWidget": {
+                "allOf": [{ "$ref": "#/components/schemas/Widget" }, { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time" } } }]
+            },
+            "Shape": {
+                "oneOf": [{ "$ref": "#/components/schemas/Circle" }, { "$ref": "#/components/schemas/Square" }],
+                "discriminator": { "propertyName": "kind" }
+            },
+            "Circle": { "type": "object", "properties": { "kind": { "const": "circle" }, "r": { "type": "number" } } },
+            "Square": { "type": "object", "properties": { "kind": { "const": "square" }, "side": { "type": "number" } } },
+            "Bag": { "type": "object", "properties": { "id": { "type": "string" } }, "additionalProperties": true },
+            "Sealed": { "type": "object", "properties": { "id": { "type": "string" } }, "additionalProperties": false },
+            "3DModel": { "type": "object", "properties": { "mesh": { "type": "string" } } },
+            "ApiError": { "type": "object", "properties": { "message": { "type": "string" } } }
+        }
+    }
+}

package/tests/helpers.ts

@@ -1,3 +1,6 @@
+import { parseCk, DiagnosticCollector } from '@contractkit/core';
+import { convertOpenApiToCk } from '../src/convert.js';
+import type { ConvertOptions, Warning } from '../src/types.js';
 import type {
     CkRootNode,
     ModelNode,
@@ -157,3 +160,40 @@ export function opRoute(path: string, operations: OpOperationNode[], overrides?:
     if (overrides?.params !== undefined) normalized.params = normalizeParamSource(overrides.params);
     return { path, operations, loc: loc(), ...normalized };
 }
+
+// ─── Conversion round-trip ────────────────────────────────────────────────
+
+/**
+ * Convert a spec and parse the result back, asserting it is clean `.ck`.
+ *
+ * Substring assertions over the emitted text cannot tell "the output parses but means the wrong
+ * thing" from "the output is correct" — which is exactly the class of bug that let every error
+ * response import as service-produced. Asserting on the parsed AST states the meaning instead of
+ * the formatting, and re-parsing catches source the printer cannot actually express.
+ */
+export async function convertAndParse(options: ConvertOptions & { file?: string }): Promise<{ root: CkRootNode; ck: string; warnings: Warning[] }> {
+    const file = options.file ?? 'api.ck';
+    const result = await convertOpenApiToCk({ split: 'single', ...options });
+    const ck = result.files.get(file);
+    if (ck === undefined) {
+        throw new Error(`no ${file} in output; got: ${[...result.files.keys()].join(', ')}`);
+    }
+    const diag = new DiagnosticCollector();
+    const root = parseCk(ck, file, diag);
+    if (diag.hasErrors()) {
+        throw new Error(`generated ${file} does not parse:\n${diag.getAll().map(d => `  ${d.line}: ${d.message}`).join('\n')}\n\n${ck}`);
+    }
+    return { root, ck, warnings: result.warnings };
+}
+
+/** The single operation of a single-route conversion. */
+export function onlyOperation(root: CkRootNode): OpOperationNode {
+    return root.routes[0]!.operations[0]!;
+}
+
+/** Look up one response by status code. */
+export function responseFor(op: OpOperationNode, statusCode: number): OpResponseNode {
+    const resp = op.responses.find(r => r.statusCode === statusCode);
+    if (!resp) throw new Error(`no ${statusCode} response; got ${op.responses.map(r => r.statusCode).join(', ')}`);
+    return resp;
+}

package/tests/kitchen-sink.test.ts

@@ -0,0 +1,116 @@
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { emittedResponses, observableResponses, thrownResponses } from '@contractkit/core';
+import { convertAndParse, onlyOperation, responseFor } from './helpers.js';
+import { convertOpenApiToCk } from '../src/convert.js';
+
+const fixturesDir = resolve(dirname(fileURLToPath(import.meta.url)), 'fixtures');
+const spec = () => JSON.parse(readFileSync(resolve(fixturesDir, 'kitchen-sink-3.1.json'), 'utf-8'));
+
+/**
+ * One spec exercising the constructs that have historically broken on import — patterns with a
+ * `/`, enum values with quotes, `$ref`'d components, descriptions with newlines, statuses that
+ * must not be service-produced, schema names that are not identifiers.
+ *
+ * The text snapshot is what makes the next grammar or printer change visible in review; the
+ * assertions below it state the meaning the generators will read.
+ */
+describe('kitchen sink', () => {
+    it('produces .ck that parses', async () => {
+        const { ck } = await convertAndParse({ input: spec() });
+        await expect(ck).toMatchFileSnapshot('./__snapshots__/kitchen-sink.ck');
+    });
+
+    it('splits by tag without losing a file', async () => {
+        const result = await convertOpenApiToCk({ input: spec(), split: 'by-tag' });
+        expect(result.warnings.filter(w => w.message.includes('does not parse'))).toEqual([]);
+        expect([...result.files.keys()].sort()).toMatchInlineSnapshot(`
+          [
+            "shared.ck",
+            "widgets.ck",
+          ]
+        `);
+    });
+
+    it('gets the response semantics right', async () => {
+        const { root } = await convertAndParse({ input: spec() });
+        const get = onlyOperation(root);
+
+        // The service writes 200 and 204. A bare `304:` is documented, not produced — something
+        // upstream emits it — but a client still observes it, which is why it is in neither the
+        // emitted nor the thrown set.
+        expect(emittedResponses(get).map(r => r.statusCode)).toEqual([200, 204]);
+        expect(observableResponses(get).map(r => r.statusCode)).toEqual([200, 204, 304]);
+        expect(thrownResponses(get).map(r => r.statusCode)).toEqual([404, 429, 503]);
+
+        expect(responseFor(get, 200).bodies.map(b => b.contentType)).toEqual(['application/json', 'text/csv']);
+        // `Widget` is self-referential, but a response body names an already-imported model —
+        // there is no definition cycle here for `lazy()` to break.
+        expect(responseFor(get, 200).bodies[0]!.bodyType).toEqual({ kind: 'ref', name: 'Widget' });
+        expect(responseFor(get, 200).headers!.map(h => h.name)).toEqual(['X-Rate-Limit']);
+        // A `$ref`'d response resolves to the schema behind it.
+        expect(responseFor(get, 404).bodies[0]!.bodyType).toEqual({ kind: 'ref', name: 'ApiError' });
+    });
+
+    it('carries the values that used to emit unparseable source', async () => {
+        const { root } = await convertAndParse({ input: spec() });
+        const widget = root.models.find(m => m.name === 'Widget')!;
+        const typeOf = (name: string) => widget.fields.find(f => f.name === name)!.type;
+
+        expect(typeOf('datePattern')).toEqual({ kind: 'scalar', name: 'string', regex: '^\\d{2}/\\d{2}$' });
+        expect(typeOf('kind')).toEqual({ kind: 'enum', values: ['basic', 'on hold', 'a "quoted" kind'] });
+        expect(typeOf('ttl')).toEqual({ kind: 'scalar', name: 'duration' });
+        expect(typeOf('contact')).toEqual({ kind: 'scalar', name: 'email' });
+        expect(typeOf('site')).toEqual({ kind: 'scalar', name: 'url' });
+        // A self-reference is a cycle, so it must be lazy or the Zod schema cannot be built.
+        expect(typeOf('parent')).toEqual({ kind: 'lazy', inner: { kind: 'ref', name: 'Widget' } });
+    });
+
+    it('reports everything it had to drop', async () => {
+        const { warnings } = await convertAndParse({ input: spec() });
+        const messages = warnings.map(w => w.message);
+        for (const expected of [
+            '`head` operations',
+            '`trace` operations',
+            "'default' is not a numeric status code",
+            "'4XX' is not a numeric status code",
+            'cookie parameters',
+            'not a plain type/subtype',
+            'exclusiveMinimum',
+            'multipleOf',
+            'uniqueItems',
+        ]) {
+            expect(messages.some(m => m.includes(expected)), `expected a warning containing ${expected}`).toBe(true);
+        }
+    });
+
+    it('handles the model shapes', async () => {
+        const { root } = await convertAndParse({ input: spec() });
+        const byName = (n: string) => root.models.find(m => m.name === n)!;
+
+        expect(byName('TimestampedWidget').bases).toEqual(['Widget']);
+        expect(byName('Shape').type).toEqual({ kind: 'discriminatedUnion', discriminator: 'kind', members: [{ kind: 'ref', name: 'Circle' }, { kind: 'ref', name: 'Square' }] });
+        expect(byName('Bag').mode).toBe('loose');
+        expect(byName('Sealed').mode).toBeUndefined();
+        expect(byName('_3DModel')).toBeDefined();
+        // Extracted from the inline `application/vnd.api+json` request schema. Models extracted
+        // during path conversion used to be referenced by the operations and never emitted.
+        expect(byName('CreateWidgetRequest').fields.map(f => f.name)).toEqual(['data']);
+
+        const widget = byName('Widget');
+        expect(widget.fields.find(f => f.name === 'id')!.visibility).toBe('readonly');
+        expect(widget.fields.find(f => f.name === 'secret')!.visibility).toBe('writeonly');
+        expect(widget.fields.find(f => f.name === 'legacy')!.deprecated).toBe(true);
+        expect(widget.fields.find(f => f.name === 'nickname')!.nullable).toBe(true);
+    });
+
+    it('imports the operation label and the spec-level security override', async () => {
+        const { root } = await convertAndParse({ input: spec() });
+        // `}` and ` #` would have closed the operation block early.
+        expect(onlyOperation(root).name).toBe('Fetch a widget with awkward chars');
+        const post = root.routes.find(r => r.path === '/widgets')!.operations[0]!;
+        expect(post.security).toBe('none');
+    });
+});

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

@@ -13,6 +13,7 @@ function makeCtx(overrides?: Partial<SchemaContext>): SchemaContext {
         namedSchemas: {},
         extractedModels: [],
         inlineCounter: 0,
+        insideModel: true,
         ...overrides,
     };
 }
@@ -66,7 +67,7 @@ describe('schemaToTypeNode', () => {
 
         it('converts string with pattern', () => {
             const result = schemaToTypeNode({ type: 'string', pattern: '^[a-z]+$' }, makeCtx());
-            expect(result).toEqual({ kind: 'scalar', name: 'string', regex: '/^[a-z]+$/' });
+            expect(result).toEqual({ kind: 'scalar', name: 'string', regex: '^[a-z]+$' });
         });
 
         it('converts integer → int', () => {
@@ -224,11 +225,19 @@ describe('schemaToTypeNode', () => {
             expect(result).toEqual({ kind: 'ref', name: 'User' });
         });
 
-        it('wraps circular $ref in lazy', () => {
+        it('wraps a circular $ref in lazy inside a contract body', () => {
             const ctx = makeCtx({ circularRefs: new Set(['TreeNode']) });
             const result = schemaToTypeNode({ $ref: '#/components/schemas/TreeNode' }, ctx);
             expect(result).toEqual({ kind: 'lazy', inner: { kind: 'ref', name: 'TreeNode' } });
         });
+
+        it('leaves a circular $ref bare outside a contract body', () => {
+            // `lazy()` breaks a definition cycle between contracts. An operation names a model
+            // the generated module has already imported, so there is no cycle to break.
+            const ctx = makeCtx({ circularRefs: new Set(['TreeNode']), insideModel: false });
+            const result = schemaToTypeNode({ $ref: '#/components/schemas/TreeNode' }, ctx);
+            expect(result).toEqual({ kind: 'ref', name: 'TreeNode' });
+        });
     });
 
     describe('nullable', () => {