@contractkit/openapi-to-ck 0.10.2 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractkit/openapi-to-ck",
-  "version": "0.10.2",
+  "version": "0.12.0",
   "description": "Convert OpenAPI specs (2.0/3.0/3.1) to Contract Kit .ck files",
   "license": "MIT",
   "author": {
@@ -28,13 +28,12 @@
     "./plugin": "./dist/plugin.js"
   },
   "dependencies": {
-    "@scalar/openapi-parser": "^0.26.1",
     "yaml": "^2.8.3",
-    "@contractkit/core": "0.26.1"
+    "@contractkit/core": "0.28.0"
   },
   "devDependencies": {
-    "@repo/config-typescript": "0.1.0",
-    "@repo/config-eslint": "0.3.1"
+    "@repo/config-eslint": "0.3.1",
+    "@repo/config-typescript": "0.1.0"
   },
   "scripts": {
     "build": "tsup src/index.ts src/plugin.ts --format esm --sourcemap --dts && tsc --emitDeclarationOnly --declaration",

package/src/ast-to-ck.ts

@@ -1,467 +1,43 @@
-import type {
-    CkRootNode,
-    ModelNode,
-    FieldNode,
-    ContractTypeNode,
-    OpRouteNode,
-    OpOperationNode,
-    OpRequestNode,
-    OpResponseNode,
-    ParamSource,
-    SecurityNode,
-    SecurityFields,
-    ObjectMode,
-    RouteModifier,
-} from '@contractkit/core';
-
-const INDENT = '    '; // 4 spaces
-
-/** Matches a bare identifier that needs no quoting (mirrors serializeDefault). */
-const IDENT_RE = /^[a-zA-Z_$][a-zA-Z0-9_$\-.]*$/;
+import type { CkRootNode } from '@contractkit/core';
+import { printCk, printType } from '@contractkit/core';
 
 /**
- * Flatten a description to a single line so it is safe to embed in a trailing
- * `# ...` comment. OpenAPI descriptions routinely contain newlines; an embedded
- * newline would terminate the comment and dump the rest as raw `.ck` source.
+ * `.ck` serialization for the OpenAPI importer.
+ *
+ * This module used to carry its own printer. `.ck` had two of them — this one and the prettier
+ * plugin's — and only the prettier copy was covered by the round-trip tests that the
+ * `ck-grammar-change` checklist points at, so this one silently fell behind the grammar: it
+ * ignored `hasBlock` and the `(documented)` response modifier, could not emit `mcp:`,
+ * `plugins:`, `name:`, `override`, `format(output=)` or options-level header globals, and
+ * emitted unparseable source for a regex containing `/` or an enum value containing both quote
+ * styles.
+ *
+ * The printer now lives in `@contractkit/core` next to `parseCk`, and this module is a thin
+ * adapter over it. A grammar change has one printer to update.
  */
-function singleLineComment(text: string): string {
-    return text.replace(/\s+/g, ' ').trim();
-}
 
 /**
- * Serialize an enum value as a `.ck` enum argument. Bare identifiers are emitted
- * as-is; anything else (spaces, punctuation) is wrapped in a string literal.
- * `.ck` string literals have no escape sequences, so when the value contains a
- * double quote we fall back to single quotes (and vice versa).
+ * Options controlling how a {@link CkRootNode} is rendered to `.ck` source.
+ *
+ * @deprecated `includeComments` is a no-op and is kept only so existing callers still compile.
+ * Comments are controlled upstream: `ConvertOptions.includeComments` gates every `description`
+ * assignment in `schema-to-ast.ts` and `paths-to-ast.ts`, so when it is off the descriptions are
+ * absent from the AST and there is nothing left for the printer to suppress.
  */
-function quoteEnumValue(value: string): string {
-    if (IDENT_RE.test(value)) return value;
-    if (!value.includes('"')) return `"${value}"`;
-    if (!value.includes("'")) return `'${value}'`;
-    // Value contains both quote styles; `.ck` cannot escape, so keep double
-    // quotes and preserve the inner ones as best we can.
-    return `"${value}"`;
-}
-
-// ─── Public API ───────────────────────────────────────────────────────────
-
-/** Options controlling how a {@link CkRootNode} is rendered to `.ck` source. */
 export interface SerializeOptions {
-    /** Emit descriptions as inline # comments. Default: true. */
+    /** No-op. See the deprecation note on {@link SerializeOptions}. */
     includeComments?: boolean;
 }
 
 /**
- * Serialize a `.ck` AST back to formatted `.ck` source text. Emits the options
- * block first, then every model, then every route, separated by blank lines and
- * terminated with a trailing newline. Descriptions become trailing `# ...`
- * comments unless `options.includeComments` is `false`. The output is designed
- * to re-parse cleanly via `parseCk` (see round-trip tests).
+ * Serialize a `.ck` AST back to formatted `.ck` source text.
+ *
+ * Delegates to `printCk`, which prints from a `CkRootNode` alone — no Ohm CST and no original
+ * source — so programmatically built nodes print correctly.
  */
-export function astToCk(root: CkRootNode, options: SerializeOptions = {}): string {
-    const { includeComments = true } = options;
-    const ctx: Ctx = { includeComments };
-    const parts: string[] = [];
-
-    // Options block
-    const optionsBlock = serializeOptions(root);
-    if (optionsBlock) parts.push(optionsBlock);
-
-    // Models
-    for (const model of root.models) {
-        parts.push(serializeModel(model, ctx));
-    }
-
-    // Routes
-    for (const route of root.routes) {
-        parts.push(serializeRoute(route, ctx));
-    }
-
-    return parts.join('\n\n') + '\n';
+export function astToCk(root: CkRootNode, _options: SerializeOptions = {}): string {
+    return printCk(root);
 }
 
-// ─── Context ──────────────────────────────────────────────────────────────
-
-interface Ctx {
-    includeComments: boolean;
-}
-
-// ─── Options block ────────────────────────────────────────────────────────
-
-function serializeOptions(root: CkRootNode): string | null {
-    const hasKeys = Object.keys(root.meta).length > 0;
-    const hasServices = root.services && Object.keys(root.services).length > 0;
-    const hasSecurity = root.security !== undefined;
-
-    if (!hasKeys && !hasServices && !hasSecurity) return null;
-
-    const lines: string[] = ['options {'];
-
-    if (hasKeys) {
-        lines.push(`${INDENT}keys: {`);
-        for (const [key, value] of Object.entries(root.meta)) {
-            lines.push(`${INDENT}${INDENT}${key}: ${value}`);
-        }
-        lines.push(`${INDENT}}`);
-    }
-
-    if (hasServices) {
-        lines.push(`${INDENT}services: {`);
-        for (const [name, path] of Object.entries(root.services)) {
-            lines.push(`${INDENT}${INDENT}${name}: "${path}"`);
-        }
-        lines.push(`${INDENT}}`);
-    }
-
-    if (hasSecurity) {
-        lines.push(`${INDENT}security: {`);
-        if (root.security === 'none') {
-            lines.push(`${INDENT}${INDENT}none`);
-        } else {
-            const sec = root.security as SecurityFields;
-            if (sec.policy !== undefined) {
-                const value = sec.policy === false ? 'none' : sec.policy;
-                lines.push(`${INDENT}${INDENT}policy: ${value}`);
-            }
-        }
-        lines.push(`${INDENT}}`);
-    }
-
-    lines.push('}');
-    return lines.join('\n');
-}
-
-// ─── Models ───────────────────────────────────────────────────────────────
-
-function serializeModel(model: ModelNode, ctx: Ctx): string {
-    const parts: string[] = [];
-
-    // Modifiers: format(input=snake) mode(loose) deprecated
-    const prefixes: string[] = [];
-    if (model.inputCase && model.inputCase !== 'camel') {
-        prefixes.push(`format(input=${model.inputCase})`);
-    }
-    if (model.mode && model.mode !== 'strict') {
-        prefixes.push(`mode(${model.mode})`);
-    }
-    if (model.deprecated) {
-        prefixes.push('deprecated');
-    }
-
-    const prefix = prefixes.length > 0 ? prefixes.join(' ') + ' ' : '';
-    const comment = ctx.includeComments && model.description ? ` # ${singleLineComment(model.description)}` : '';
-
-    // Type alias: contract Name: typeExpression
-    if (model.type) {
-        parts.push(`contract ${prefix}${model.name}: ${serializeType(model.type)}${comment}`);
-        return parts.join('');
-    }
-
-    // Inheritance: contract Name: Base1 & Base2 & { ... }
-    if (model.bases && model.bases.length > 0) {
-        parts.push(`contract ${prefix}${model.name}: ${model.bases.join(' & ')} & {${comment}`);
-    } else {
-        parts.push(`contract ${prefix}${model.name}: {${comment}`);
-    }
-
-    for (const field of model.fields) {
-        parts.push(serializeField(field, 1, ctx));
-    }
-
-    parts.push('}');
-    return parts.join('\n');
-}
-
-function serializeField(field: FieldNode, depth: number, ctx: Ctx): string {
-    const indent = INDENT.repeat(depth);
-    const optional = field.optional ? '?' : '';
-    const visibility = field.visibility !== 'normal' ? `${field.visibility} ` : '';
-    const deprecated = field.deprecated ? 'deprecated ' : '';
-
-    let typeStr = serializeType(field.type);
-
-    // Nullable fields: if the type doesn't already contain null, append `| null`
-    if (field.nullable && !typeContainsNull(field.type)) {
-        typeStr = `${typeStr} | null`;
-    }
-
-    const defaultVal = field.default !== undefined ? ` = ${serializeDefault(field.default)}` : '';
-    const comment = ctx.includeComments && field.description ? ` # ${singleLineComment(field.description)}` : '';
-
-    return `${indent}${field.name}${optional}: ${deprecated}${visibility}${typeStr}${defaultVal}${comment}`;
-}
-
-function typeContainsNull(type: ContractTypeNode): boolean {
-    if (type.kind === 'scalar' && type.name === 'null') return true;
-    if (type.kind === 'union') return type.members.some(typeContainsNull);
-    return false;
-}
-
-function serializeDefault(value: string | number | boolean): string {
-    if (typeof value === 'string') {
-        // If it looks like an identifier (e.g. enum value), don't quote it
-        if (/^[a-zA-Z_$][a-zA-Z0-9_$\-.]*$/.test(value)) return value;
-        return `"${value}"`;
-    }
-    return String(value);
-}
-
-// ─── Types ────────────────────────────────────────────────────────────────
-
-/**
- * Serialize a single {@link ContractTypeNode} to its inline `.ck` type
- * expression (e.g. `array(User, min=1)`, `string | int`, `enum(asc, desc)`).
- * Recurses through composite types; enum values are quoted as needed via
- * {@link quoteEnumValue}.
- */
-export function serializeType(type: ContractTypeNode): string {
-    switch (type.kind) {
-        case 'scalar':
-            return serializeScalar(type);
-        case 'array':
-            return serializeArray(type);
-        case 'tuple':
-            return `tuple(${type.items.map(serializeType).join(', ')})`;
-        case 'record':
-            return `record(${serializeType(type.key)}, ${serializeType(type.value)})`;
-        case 'enum':
-            return `enum(${type.values.map(quoteEnumValue).join(', ')})`;
-        case 'literal':
-            return serializeLiteral(type);
-        case 'union':
-            return type.members.map(serializeType).join(' | ');
-        case 'discriminatedUnion':
-            return `discriminated(by=${type.discriminator}, ${type.members.map(serializeType).join(' | ')})`;
-        case 'intersection':
-            return type.members.map(serializeType).join(' & ');
-        case 'ref':
-            return type.name;
-        case 'inlineObject':
-            return serializeInlineObject(type);
-        case 'lazy':
-            return `lazy(${serializeType(type.inner)})`;
-    }
-}
-
-function serializeScalar(type: {
-    name: string;
-    min?: number | bigint | string;
-    max?: number | bigint | string;
-    len?: number;
-    regex?: string;
-    format?: string;
-}): string {
-    const args: string[] = [];
-    if (type.len !== undefined) args.push(`length=${type.len}`);
-    if (type.min !== undefined) args.push(typeof type.min === 'string' ? `min="${type.min}"` : `min=${type.min}`);
-    if (type.max !== undefined) args.push(typeof type.max === 'string' ? `max="${type.max}"` : `max=${type.max}`);
-    if (type.regex !== undefined) args.push(`regex=${type.regex}`);
-    if (type.format !== undefined) args.push(`format=${type.format}`);
-
-    if (args.length === 0) return type.name;
-    return `${type.name}(${args.join(', ')})`;
-}
-
-function serializeArray(type: { item: ContractTypeNode; min?: number; max?: number }): string {
-    const args: string[] = [serializeType(type.item)];
-    if (type.min !== undefined) args.push(`min=${type.min}`);
-    if (type.max !== undefined) args.push(`max=${type.max}`);
-    return `array(${args.join(', ')})`;
-}
-
-function serializeLiteral(type: { value: string | number | boolean }): string {
-    if (typeof type.value === 'string') return `literal("${type.value}")`;
-    return `literal(${type.value})`;
-}
-
-function serializeInlineObject(type: { fields: FieldNode[]; mode?: ObjectMode }): string {
-    const modePrefix = type.mode ? `mode(${type.mode}) ` : '';
-    if (type.fields.length === 0) return `${modePrefix}{}`;
-
-    const lines: string[] = [`${modePrefix}{`];
-    for (const field of type.fields) {
-        lines.push(serializeField(field, 2, { includeComments: true }));
-    }
-    lines.push(`${INDENT}}`);
-    return lines.join('\n');
-}
-
-// ─── Routes ───────────────────────────────────────────────────────────────
-
-function serializeRoute(route: OpRouteNode, ctx: Ctx): string {
-    const lines: string[] = [];
-
-    const modStr = serializeModifiers(route.modifiers);
-    const comment = ctx.includeComments && route.description ? ` # ${singleLineComment(route.description)}` : '';
-    lines.push(`operation${modStr} ${route.path}: {${comment}`);
-
-    // Route-level params
-    if (route.params) {
-        serializeParamSource(lines, 'params', route.params, route.paramsMode, 1, ctx);
-    }
-
-    // Route-level security
-    if (route.security !== undefined) {
-        serializeSecurityBlock(lines, route.security, 1, ctx);
-    }
-
-    // Operations
-    for (const op of route.operations) {
-        serializeOperation(lines, op, 1, ctx);
-    }
-
-    lines.push('}');
-    return lines.join('\n');
-}
-
-function serializeOperation(lines: string[], op: OpOperationNode, depth: number, ctx: Ctx): string[] {
-    const indent = INDENT.repeat(depth);
-    const modStr = serializeModifiers(op.modifiers);
-    const comment = ctx.includeComments && op.description ? ` # ${singleLineComment(op.description)}` : '';
-    lines.push(`${indent}${op.method}${modStr}: {${comment}`);
-
-    const inner = INDENT.repeat(depth + 1);
-
-    // Service
-    if (op.service) {
-        lines.push(`${inner}service: ${op.service}`);
-    }
-
-    // SDK
-    if (op.sdk) {
-        lines.push(`${inner}sdk: ${op.sdk}`);
-    }
-
-    // Signature
-    if (op.signature) {
-        const sigComment = ctx.includeComments && op.signatureDescription ? ` # ${singleLineComment(op.signatureDescription)}` : '';
-        if (op.signaturePolicy) {
-            lines.push(`${inner}signature: {`);
-            lines.push(`${inner}    options: ${op.signature}${sigComment}`);
-            lines.push(`${inner}    policy: ${op.signaturePolicy}`);
-            lines.push(`${inner}}`);
-        } else {
-            lines.push(`${inner}signature: ${op.signature}${sigComment}`);
-        }
-    }
-
-    // Security
-    if (op.security !== undefined) {
-        serializeSecurityBlock(lines, op.security, depth + 1, ctx);
-    }
-
-    // Query
-    if (op.query) {
-        serializeParamSource(lines, 'query', op.query, op.queryMode, depth + 1, ctx);
-    }
-
-    // Headers
-    if (op.headers) {
-        serializeParamSource(lines, 'headers', op.headers, op.headersMode, depth + 1, ctx);
-    }
-
-    // Request
-    if (op.request) {
-        serializeRequest(lines, op.request, depth + 1);
-    }
-
-    // Responses
-    if (op.responses.length > 0) {
-        serializeResponses(lines, op.responses, depth + 1);
-    }
-
-    lines.push(`${indent}}`);
-    return lines;
-}
-
-function serializeModifiers(modifiers?: RouteModifier[]): string {
-    if (!modifiers || modifiers.length === 0) return '';
-    return `(${modifiers.join(', ')})`;
-}
-
-function serializeParamSource(lines: string[], keyword: string, source: ParamSource, mode: ObjectMode | undefined, depth: number, ctx: Ctx): void {
-    const indent = INDENT.repeat(depth);
-
-    // String reference: `query: TypeName`
-    if (source.kind === 'ref') {
-        lines.push(`${indent}${keyword}: ${source.name}`);
-        return;
-    }
-
-    // ContractTypeNode reference
-    if (source.kind === 'type') {
-        lines.push(`${indent}${keyword}: ${serializeType(source.node)}`);
-        return;
-    }
-
-    // Inline param declarations: `params: { name: type }`
-    const modeStr = mode ? `mode(${mode}) ` : '';
-    lines.push(`${indent}${keyword}: ${modeStr}{`);
-    for (const param of source.nodes) {
-        const optional = param.optional ? '?' : '';
-        let typeStr = serializeType(param.type);
-        if (param.nullable && !typeContainsNull(param.type)) {
-            typeStr = `${typeStr} | null`;
-        }
-        const defaultVal = param.default !== undefined ? ` = ${serializeDefault(param.default)}` : '';
-        const comment = ctx.includeComments && param.description ? ` # ${singleLineComment(param.description)}` : '';
-        lines.push(`${INDENT.repeat(depth + 1)}${param.name}${optional}: ${typeStr}${defaultVal}${comment}`);
-    }
-    lines.push(`${indent}}`);
-}
-
-function serializeRequest(lines: string[], request: OpRequestNode, depth: number): void {
-    const indent = INDENT.repeat(depth);
-    lines.push(`${indent}request: {`);
-    for (const body of request.bodies) {
-        lines.push(`${INDENT.repeat(depth + 1)}${body.contentType}: ${serializeType(body.bodyType)}`);
-    }
-    lines.push(`${indent}}`);
-}
-
-function serializeResponses(lines: string[], responses: OpResponseNode[], depth: number): void {
-    const indent = INDENT.repeat(depth);
-    lines.push(`${indent}response: {`);
-    for (const resp of responses) {
-        const bodies = resp.bodies;
-        const hasHeaders = resp.headers && resp.headers.length > 0;
-        if (bodies.length > 0 || hasHeaders) {
-            lines.push(`${INDENT.repeat(depth + 1)}${resp.statusCode}: {`);
-            for (const body of bodies) {
-                lines.push(`${INDENT.repeat(depth + 2)}${body.contentType}: ${serializeType(body.bodyType)}`);
-            }
-            if (hasHeaders) {
-                lines.push(`${INDENT.repeat(depth + 2)}headers: {`);
-                for (const h of resp.headers!) {
-                    const opt = h.optional ? '?' : '';
-                    const trail = h.description ? ` # ${singleLineComment(h.description)}` : '';
-                    lines.push(`${INDENT.repeat(depth + 3)}${h.name}${opt}: ${serializeType(h.type)}${trail}`);
-                }
-                lines.push(`${INDENT.repeat(depth + 2)}}`);
-            }
-            lines.push(`${INDENT.repeat(depth + 1)}}`);
-        } else {
-            lines.push(`${INDENT.repeat(depth + 1)}${resp.statusCode}:`);
-        }
-    }
-    lines.push(`${indent}}`);
-}
-
-function serializeSecurityBlock(lines: string[], security: SecurityNode, depth: number, ctx: Ctx): void {
-    const indent = INDENT.repeat(depth);
-    if (security === 'none') {
-        lines.push(`${indent}security: none`);
-        return;
-    }
-
-    const sec = security as SecurityFields;
-    if (sec.policy !== undefined) {
-        const comment = ctx.includeComments && sec.policyDescription ? ` # ${singleLineComment(sec.policyDescription)}` : '';
-        const value = sec.policy === false ? 'none' : sec.policy;
-        lines.push(`${indent}security: {`);
-        lines.push(`${INDENT.repeat(depth + 1)}policy: ${value}${comment}`);
-        lines.push(`${indent}}`);
-    } else {
-        lines.push(`${indent}security: {}`);
-    }
-}
+/** Render a `ContractTypeNode` to its `.ck` source string. Re-exported from core. */
+export const serializeType = printType;

package/src/convert.ts

@@ -11,12 +11,13 @@ import { splitByTag, mergeIntoSingle } from './tag-splitter.js';
 import { astToCk } from './ast-to-ck.js';
 import type { NormalizedSchema } from './types.js';
 import type { ModelNode } from '@contractkit/core';
+import { parseCk, decomposeCk, validateRefs, DiagnosticCollector } from '@contractkit/core';
 
 /**
  * Convert an OpenAPI spec (2.0, 3.0, or 3.1) to Contract Kit .ck source files.
  */
 export async function convertOpenApiToCk(options: ConvertOptions): Promise<ConvertResult> {
-    const { split = 'by-tag', includeComments = true } = options;
+    const { split = 'by-tag', includeComments = true, errorResponses = 'documented' } = options;
     const warnings = new WarningCollector(options.onWarning);
 
     // Step 1: Parse the input into a document object
@@ -41,6 +42,7 @@ export async function convertOpenApiToCk(options: ConvertOptions): Promise<Conve
         namedSchemas: schemas,
         extractedModels,
         inlineCounter: 0,
+        insideModel: true,
     };
 
     const models = schemasToModels(schemas, schemaCtx);
@@ -53,24 +55,76 @@ export async function convertOpenApiToCk(options: ConvertOptions): Promise<Conve
         namedSchemas: schemas,
         extractedModels,
         globalSecurity: doc.security,
+        errorResponses,
     });
 
+    // Models extracted from inline request/response body schemas arrive during step 6, after
+    // `schemasToModels` has already read the array — without this they are referenced by the
+    // generated operations and never defined.
+    const known = new Set(models.map(m => m.name));
+    for (const extracted of extractedModels) {
+        if (known.has(extracted.name)) continue;
+        known.add(extracted.name);
+        models.push(extracted);
+    }
+
     // Step 7: Split or merge
     const files = new Map<string, string>();
 
     if (split === 'by-tag') {
         const ckRoots = splitByTag(models, routes, routeTags);
         for (const [filename, root] of ckRoots) {
-            files.set(filename, astToCk(root, { includeComments }));
+            files.set(filename, astToCk(root));
         }
     } else {
         const root = mergeIntoSingle(models, routes);
-        files.set('api.ck', astToCk(root, { includeComments }));
+        files.set('api.ck', astToCk(root));
     }
 
+    // Step 8: Check what we are about to hand back actually compiles
+    checkGeneratedFiles(files, warnings);
+
     return { files, warnings: warnings.warnings };
 }
 
+/**
+ * Re-parse the generated files and report anything that does not survive.
+ *
+ * The converter builds core AST nodes and prints them, so a bug in either half produces `.ck`
+ * that will not compile — and, because the output is written straight to disk, the first sign of
+ * it is an error in the user's own build. Spec content is more adversarial than anything a
+ * hand-written contract contains (patterns full of punctuation, descriptions full of newlines,
+ * schema names that are not identifiers), so it is worth the round trip to find out here.
+ *
+ * Reference validation runs across all the files together, because `by-tag` deliberately splits
+ * a model into one file and its users into another. Parsing alone is not enough: a reference to
+ * a contract that was never emitted is perfectly good syntax, which is exactly how the importer
+ * shipped operations pointing at inline body models it had dropped.
+ */
+function checkGeneratedFiles(files: Map<string, string>, warnings: WarningCollector): void {
+    const diag = new DiagnosticCollector();
+    const roots = [];
+    for (const [filename, text] of files) {
+        const before = diag.getAll().length;
+        const root = parseCk(text, filename, diag);
+        if (diag.getAll().length === before) roots.push(root);
+    }
+
+    if (roots.length === files.size) {
+        const decomposed = roots.map(decomposeCk);
+        validateRefs(
+            decomposed.map(d => d.contract),
+            decomposed.map(d => d.op),
+            diag,
+        );
+    }
+
+    for (const d of diag.getAll()) {
+        if (d.severity !== 'error') continue;
+        warnings.warn(d.file, `generated .ck is not valid (line ${d.line}): ${d.message}`);
+    }
+}
+
 // ─── Input Parsing ────────────────────────────────────────────────────────
 
 async function parseInput(input: string | Record<string, unknown>): Promise<Record<string, unknown>> {