@contractkit/openapi-to-ck 0.7.1

package/dist/tag-splitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag-splitter.d.ts","sourceRoot":"","sources":["../src/tag-splitter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAoB,MAAM,mBAAmB,CAAC;AAE9F;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,SAAS,EAAE,GAAG,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAyFnI;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,QAAQ,GAAE,MAAc,GAAG,UAAU,CAShH"}

package/dist/types.d.ts

@@ -0,0 +1,137 @@
+export interface ConvertOptions {
+    /** File path, JSON/YAML string, or pre-parsed OpenAPI document object. */
+    input: string | Record<string, unknown>;
+    /** Output mode: single .ck file or split by OpenAPI tag. Default: 'by-tag'. */
+    split?: 'single' | 'by-tag';
+    /** Emit OpenAPI descriptions as # comments. Default: true. */
+    includeComments?: boolean;
+    /** Called for each warning during conversion. */
+    onWarning?: (warning: Warning) => void;
+}
+export interface ConvertResult {
+    /** Map of filename -> .ck source text. */
+    files: Map<string, string>;
+    /** All warnings collected during conversion. */
+    warnings: Warning[];
+}
+export interface Warning {
+    /** JSON pointer path into the OpenAPI spec (e.g. "#/components/schemas/Foo"). */
+    path: string;
+    /** Human-readable description of the issue. */
+    message: string;
+    /** Severity level. */
+    severity: 'info' | 'warn';
+}
+/** Normalized OpenAPI 3.1 schema object (subset of fields we use). */
+export interface NormalizedSchema {
+    type?: string | string[];
+    format?: string;
+    items?: NormalizedSchema;
+    prefixItems?: NormalizedSchema[];
+    properties?: Record<string, NormalizedSchema>;
+    additionalProperties?: boolean | NormalizedSchema;
+    required?: string[];
+    enum?: unknown[];
+    const?: unknown;
+    oneOf?: NormalizedSchema[];
+    anyOf?: NormalizedSchema[];
+    allOf?: NormalizedSchema[];
+    $ref?: string;
+    nullable?: boolean;
+    readOnly?: boolean;
+    writeOnly?: boolean;
+    deprecated?: boolean;
+    default?: unknown;
+    description?: string;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    minimum?: number;
+    maximum?: number;
+    minItems?: number;
+    maxItems?: number;
+    discriminator?: {
+        propertyName?: string;
+        mapping?: Record<string, string>;
+    };
+    xml?: unknown;
+    externalDocs?: unknown;
+    not?: unknown;
+}
+/** Normalized OpenAPI 3.1 document (post-upgrade, post-dereference). */
+export interface NormalizedDocument {
+    openapi: string;
+    info: {
+        title: string;
+        version: string;
+        description?: string;
+    };
+    paths?: Record<string, NormalizedPathItem>;
+    components?: {
+        schemas?: Record<string, NormalizedSchema>;
+        securitySchemes?: Record<string, unknown>;
+    };
+    security?: Record<string, string[]>[];
+    servers?: {
+        url: string;
+        description?: string;
+    }[];
+    tags?: {
+        name: string;
+        description?: string;
+    }[];
+}
+export interface NormalizedPathItem {
+    summary?: string;
+    description?: string;
+    parameters?: NormalizedParameter[];
+    get?: NormalizedOperation;
+    post?: NormalizedOperation;
+    put?: NormalizedOperation;
+    patch?: NormalizedOperation;
+    delete?: NormalizedOperation;
+    head?: NormalizedOperation;
+    options?: NormalizedOperation;
+    trace?: NormalizedOperation;
+}
+export interface NormalizedOperation {
+    operationId?: string;
+    summary?: string;
+    description?: string;
+    tags?: string[];
+    parameters?: NormalizedParameter[];
+    requestBody?: NormalizedRequestBody;
+    responses?: Record<string, NormalizedResponse>;
+    security?: Record<string, string[]>[];
+    deprecated?: boolean;
+}
+export interface NormalizedParameter {
+    name: string;
+    in: 'path' | 'query' | 'header' | 'cookie';
+    required?: boolean;
+    description?: string;
+    deprecated?: boolean;
+    schema?: NormalizedSchema;
+}
+export interface NormalizedRequestBody {
+    description?: string;
+    required?: boolean;
+    content?: Record<string, {
+        schema?: NormalizedSchema;
+    }>;
+}
+export interface NormalizedResponse {
+    description?: string;
+    content?: Record<string, {
+        schema?: NormalizedSchema;
+    }>;
+    /** OpenAPI Header Objects keyed by header name (case-insensitive on the wire). */
+    headers?: Record<string, NormalizedHeader>;
+}
+export interface NormalizedHeader {
+    description?: string;
+    required?: boolean;
+    deprecated?: boolean;
+    schema?: NormalizedSchema;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/warnings.d.ts

@@ -0,0 +1,10 @@
+import type { Warning } from './types.js';
+export declare class WarningCollector {
+    readonly warnings: Warning[];
+    private onWarning?;
+    constructor(onWarning?: (w: Warning) => void);
+    warn(path: string, message: string): void;
+    info(path: string, message: string): void;
+    private add;
+}
+//# sourceMappingURL=warnings.d.ts.map

package/dist/warnings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"warnings.d.ts","sourceRoot":"","sources":["../src/warnings.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,qBAAa,gBAAgB;IACzB,QAAQ,CAAC,QAAQ,EAAE,OAAO,EAAE,CAAM;IAClC,OAAO,CAAC,SAAS,CAAC,CAAuB;gBAE7B,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,IAAI;IAI5C,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAIzC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAIzC,OAAO,CAAC,GAAG;CAId"}

package/eslint.config.js

@@ -0,0 +1,6 @@
+//  @ts-check
+
+import base from '@repo/config-eslint/base.js';
+
+/** @type {import("eslint").Linter.Config[]} */
+export default [...base];

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@contractkit/openapi-to-ck",
+  "version": "0.7.1",
+  "description": "Convert OpenAPI specs (2.0/3.0/3.1) to Contract Kit .ck files",
+  "author": {
+    "name": "Marooned Software",
+    "url": "https://github.com/MaroonedSoftware/contractkit"
+  },
+  "bugs": {
+    "url": "https://github.com/MaroonedSoftware/contractkit/issues"
+  },
+  "homepage": "https://github.com/MaroonedSoftware/contractkit/packages/openapi-to-ck#readme",
+  "keywords": [
+    "contractkit",
+    "openapi"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MaroonedSoftware/contractkit.git"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./plugin": "./dist/plugin.js"
+  },
+  "dependencies": {
+    "@scalar/openapi-parser": "^0.26.1",
+    "yaml": "^2.8.3",
+    "@contractkit/core": "0.11.0"
+  },
+  "devDependencies": {
+    "@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",
+    "build:ci": "eslint --max-warnings=0 && pnpm run build",
+    "lint": "eslint --fix",
+    "format": "prettier --write .",
+    "test": "vitest run",
+    "test:ci": "vitest run --coverage"
+  }
+}

package/src/ast-to-ck.ts

@@ -0,0 +1,417 @@
+import type {
+    CkRootNode,
+    ModelNode,
+    FieldNode,
+    ContractTypeNode,
+    OpRouteNode,
+    OpOperationNode,
+    OpRequestNode,
+    OpResponseNode,
+    ParamSource,
+    SecurityNode,
+    SecurityFields,
+    ObjectMode,
+    RouteModifier,
+} from '@contractkit/core';
+
+const INDENT = '    '; // 4 spaces
+
+// ─── Public API ───────────────────────────────────────────────────────────
+
+export interface SerializeOptions {
+    /** Emit descriptions as inline # comments. Default: true. */
+    includeComments?: boolean;
+}
+
+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';
+}
+
+// ─── 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.roles && sec.roles.length > 0) {
+                lines.push(`${INDENT}${INDENT}roles: [${sec.roles.join(', ')}]`);
+            }
+        }
+        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 ? ` # ${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 ? ` # ${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 ────────────────────────────────────────────────────────────────
+
+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.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 ? ` # ${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 ? ` # ${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 ? ` # ${op.signatureDescription}` : '';
+        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 ? ` # ${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 hasBody = resp.bodyType && resp.contentType;
+        const hasHeaders = resp.headers && resp.headers.length > 0;
+        if (hasBody || hasHeaders) {
+            lines.push(`${INDENT.repeat(depth + 1)}${resp.statusCode}: {`);
+            if (hasBody) {
+                lines.push(`${INDENT.repeat(depth + 2)}${resp.contentType}: ${serializeType(resp.bodyType!)}`);
+            }
+            if (hasHeaders) {
+                lines.push(`${INDENT.repeat(depth + 2)}headers: {`);
+                for (const h of resp.headers!) {
+                    const opt = h.optional ? '?' : '';
+                    const trail = h.description ? ` # ${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.roles && sec.roles.length > 0) {
+        const rolesComment = ctx.includeComments && sec.rolesDescription ? ` # ${sec.rolesDescription}` : '';
+        lines.push(`${indent}security: {`);
+        lines.push(`${INDENT.repeat(depth + 1)}roles: [${sec.roles.join(', ')}]${rolesComment}`);
+        lines.push(`${indent}}`);
+    } else {
+        lines.push(`${indent}security: {}`);
+    }
+}