@contractkit/openapi-to-ck 0.9.0 → 0.9.2

package/src/ast-to-ck.ts

@@ -16,13 +16,48 @@ import type {
 
 const INDENT = '    '; // 4 spaces
 
+/** Matches a bare identifier that needs no quoting (mirrors serializeDefault). */
+const IDENT_RE = /^[a-zA-Z_$][a-zA-Z0-9_$\-.]*$/;
+
+/**
+ * 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.
+ */
+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).
+ */
+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. */
     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).
+ */
 export function astToCk(root: CkRootNode, options: SerializeOptions = {}): string {
     const { includeComments = true } = options;
     const ctx: Ctx = { includeComments };
@@ -114,7 +149,7 @@ function serializeModel(model: ModelNode, ctx: Ctx): string {
     }
 
     const prefix = prefixes.length > 0 ? prefixes.join(' ') + ' ' : '';
-    const comment = ctx.includeComments && model.description ? ` # ${model.description}` : '';
+    const comment = ctx.includeComments && model.description ? ` # ${singleLineComment(model.description)}` : '';
 
     // Type alias: contract Name: typeExpression
     if (model.type) {
@@ -151,7 +186,7 @@ function serializeField(field: FieldNode, depth: number, ctx: Ctx): string {
     }
 
     const defaultVal = field.default !== undefined ? ` = ${serializeDefault(field.default)}` : '';
-    const comment = ctx.includeComments && field.description ? ` # ${field.description}` : '';
+    const comment = ctx.includeComments && field.description ? ` # ${singleLineComment(field.description)}` : '';
 
     return `${indent}${field.name}${optional}: ${deprecated}${visibility}${typeStr}${defaultVal}${comment}`;
 }
@@ -173,6 +208,12 @@ function serializeDefault(value: string | number | boolean): string {
 
 // ─── 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':
@@ -184,7 +225,7 @@ export function serializeType(type: ContractTypeNode): string {
         case 'record':
             return `record(${serializeType(type.key)}, ${serializeType(type.value)})`;
         case 'enum':
-            return `enum(${type.values.join(', ')})`;
+            return `enum(${type.values.map(quoteEnumValue).join(', ')})`;
         case 'literal':
             return serializeLiteral(type);
         case 'union':
@@ -251,7 +292,7 @@ function serializeRoute(route: OpRouteNode, ctx: Ctx): string {
     const lines: string[] = [];
 
     const modStr = serializeModifiers(route.modifiers);
-    const comment = ctx.includeComments && route.description ? ` # ${route.description}` : '';
+    const comment = ctx.includeComments && route.description ? ` # ${singleLineComment(route.description)}` : '';
     lines.push(`operation${modStr} ${route.path}: {${comment}`);
 
     // Route-level params
@@ -276,7 +317,7 @@ function serializeRoute(route: OpRouteNode, ctx: Ctx): string {
 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}` : '';
+    const comment = ctx.includeComments && op.description ? ` # ${singleLineComment(op.description)}` : '';
     lines.push(`${indent}${op.method}${modStr}: {${comment}`);
 
     const inner = INDENT.repeat(depth + 1);
@@ -293,7 +334,7 @@ function serializeOperation(lines: string[], op: OpOperationNode, depth: number,
 
     // Signature
     if (op.signature) {
-        const sigComment = ctx.includeComments && op.signatureDescription ? ` # ${op.signatureDescription}` : '';
+        const sigComment = ctx.includeComments && op.signatureDescription ? ` # ${singleLineComment(op.signatureDescription)}` : '';
         if (op.signaturePolicy) {
             lines.push(`${inner}signature: {`);
             lines.push(`${inner}    options: ${op.signature}${sigComment}`);
@@ -363,7 +404,7 @@ function serializeParamSource(lines: string[], keyword: string, source: ParamSou
             typeStr = `${typeStr} | null`;
         }
         const defaultVal = param.default !== undefined ? ` = ${serializeDefault(param.default)}` : '';
-        const comment = ctx.includeComments && param.description ? ` # ${param.description}` : '';
+        const comment = ctx.includeComments && param.description ? ` # ${singleLineComment(param.description)}` : '';
         lines.push(`${INDENT.repeat(depth + 1)}${param.name}${optional}: ${typeStr}${defaultVal}${comment}`);
     }
     lines.push(`${indent}}`);
@@ -393,7 +434,7 @@ function serializeResponses(lines: string[], responses: OpResponseNode[], depth:
                 lines.push(`${INDENT.repeat(depth + 2)}headers: {`);
                 for (const h of resp.headers!) {
                     const opt = h.optional ? '?' : '';
-                    const trail = h.description ? ` # ${h.description}` : '';
+                    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)}}`);
@@ -415,7 +456,7 @@ function serializeSecurityBlock(lines: string[], security: SecurityNode, depth:
 
     const sec = security as SecurityFields;
     if (sec.policy !== undefined) {
-        const comment = ctx.includeComments && sec.policyDescription ? ` # ${sec.policyDescription}` : '';
+        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}`);

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

@@ -1,4 +1,5 @@
 import { describe, it, expect } from 'vitest';
+import { parseCk, DiagnosticCollector } from '@contractkit/core';
 import { astToCk, serializeType } from '../src/ast-to-ck.js';
 import {
     ckRoot,
@@ -449,3 +450,79 @@ describe('full document', () => {
         expect(result).toContain('        service: LedgerService.listAccounts');
     });
 });
+
+// ─── Round-trip regressions ─────────────────────────────────────────────────
+
+/** Parse `.ck` source and return true when it re-parses with no errors. */
+function parsesCleanly(source: string): boolean {
+    const diag = new DiagnosticCollector();
+    parseCk(source, 'roundtrip.ck', diag);
+    return !diag.hasErrors();
+}
+
+describe('round-trip: multi-line descriptions', () => {
+    it('flattens a multi-line model description into a single-line trailing comment', () => {
+        const root = ckRoot({
+            models: [model('User', [field('id', scalarType('uuid'))], { description: 'A user.\nSpans multiple\nlines.' })],
+        });
+        const result = astToCk(root);
+        expect(result).toContain('contract User: { # A user. Spans multiple lines.');
+        // The comment line must not contain an embedded newline that leaks source.
+        const commentLine = result.split('\n').find(l => l.includes('contract User'))!;
+        expect(commentLine).toBe('contract User: { # A user. Spans multiple lines.');
+    });
+
+    it('flattens a multi-line field description', () => {
+        const root = ckRoot({
+            models: [model('User', [field('id', scalarType('uuid'), { description: 'The\nuser\nID' })])],
+        });
+        const result = astToCk(root);
+        expect(result).toContain('    id: uuid # The user ID');
+    });
+
+    it('re-parses cleanly with multi-line descriptions on model and field', () => {
+        const root = ckRoot({
+            models: [
+                model(
+                    'User',
+                    [
+                        field('id', scalarType('uuid'), { visibility: 'readonly', description: 'The user ID.\nGenerated server-side.' }),
+                        field('name', scalarType('string'), { description: 'Display name.\r\n\r\nCan contain\ttabs.' }),
+                    ],
+                    { description: 'A user record.\nMultiple paragraphs here.\n\nEven blank lines.' },
+                ),
+            ],
+        });
+        const result = astToCk(root);
+        expect(parsesCleanly(result)).toBe(true);
+    });
+});
+
+describe('round-trip: enum values needing quotes', () => {
+    it('quotes enum values that contain spaces', () => {
+        expect(serializeType(enumType('Not Started', 'In Progress', 'Done'))).toBe('enum("Not Started", "In Progress", Done)');
+    });
+
+    it('leaves bare-identifier enum values unquoted', () => {
+        expect(serializeType(enumType('asc', 'desc'))).toBe('enum(asc, desc)');
+    });
+
+    it('falls back to single quotes when the value contains a double quote', () => {
+        expect(serializeType(enumType('a "quoted" value'))).toBe(`enum('a "quoted" value')`);
+    });
+
+    it('keeps double quotes when the value contains both quote styles', () => {
+        // `.ck` string literals have no escape sequences, so a value with both
+        // quote styles cannot round-trip; the serializer keeps double quotes.
+        expect(serializeType(enumType(`a "b" 'c'`))).toBe(`enum("a "b" 'c'")`);
+    });
+
+    it('re-parses cleanly with space-containing enum values', () => {
+        const root = ckRoot({
+            models: [model('Task', [field('status', enumType('Not Started', 'in progress', 'Done'))])],
+        });
+        const result = astToCk(root);
+        expect(result).toContain('status: enum("Not Started", "in progress", Done)');
+        expect(parsesCleanly(result)).toBe(true);
+    });
+});

package/coverage/base.css

@@ -1,224 +0,0 @@
-body, html {
-  margin:0; padding: 0;
-  height: 100%;
-}
-body {
-    font-family: Helvetica Neue, Helvetica, Arial;
-    font-size: 14px;
-    color:#333;
-}
-.small { font-size: 12px; }
-*, *:after, *:before {
-  -webkit-box-sizing:border-box;
-     -moz-box-sizing:border-box;
-          box-sizing:border-box;
-  }
-h1 { font-size: 20px; margin: 0;}
-h2 { font-size: 14px; }
-pre {
-    font: 12px/1.4 Consolas, "Liberation Mono", Menlo, Courier, monospace;
-    margin: 0;
-    padding: 0;
-    -moz-tab-size: 2;
-    -o-tab-size:  2;
-    tab-size: 2;
-}
-a { color:#0074D9; text-decoration:none; }
-a:hover { text-decoration:underline; }
-.strong { font-weight: bold; }
-.space-top1 { padding: 10px 0 0 0; }
-.pad2y { padding: 20px 0; }
-.pad1y { padding: 10px 0; }
-.pad2x { padding: 0 20px; }
-.pad2 { padding: 20px; }
-.pad1 { padding: 10px; }
-.space-left2 { padding-left:55px; }
-.space-right2 { padding-right:20px; }
-.center { text-align:center; }
-.clearfix { display:block; }
-.clearfix:after {
-  content:'';
-  display:block;
-  height:0;
-  clear:both;
-  visibility:hidden;
-  }
-.fl { float: left; }
-@media only screen and (max-width:640px) {
-  .col3 { width:100%; max-width:100%; }
-  .hide-mobile { display:none!important; }
-}
-
-.quiet {
-  color: #7f7f7f;
-  color: rgba(0,0,0,0.5);
-}
-.quiet a { opacity: 0.7; }
-
-.fraction {
-  font-family: Consolas, 'Liberation Mono', Menlo, Courier, monospace;
-  font-size: 10px;
-  color: #555;
-  background: #E8E8E8;
-  padding: 4px 5px;
-  border-radius: 3px;
-  vertical-align: middle;
-}
-
-div.path a:link, div.path a:visited { color: #333; }
-table.coverage {
-  border-collapse: collapse;
-  margin: 10px 0 0 0;
-  padding: 0;
-}
-
-table.coverage td {
-  margin: 0;
-  padding: 0;
-  vertical-align: top;
-}
-table.coverage td.line-count {
-    text-align: right;
-    padding: 0 5px 0 20px;
-}
-table.coverage td.line-coverage {
-    text-align: right;
-    padding-right: 10px;
-    min-width:20px;
-}
-
-table.coverage td span.cline-any {
-    display: inline-block;
-    padding: 0 5px;
-    width: 100%;
-}
-.missing-if-branch {
-    display: inline-block;
-    margin-right: 5px;
-    border-radius: 3px;
-    position: relative;
-    padding: 0 4px;
-    background: #333;
-    color: yellow;
-}
-
-.skip-if-branch {
-    display: none;
-    margin-right: 10px;
-    position: relative;
-    padding: 0 4px;
-    background: #ccc;
-    color: white;
-}
-.missing-if-branch .typ, .skip-if-branch .typ {
-    color: inherit !important;
-}
-.coverage-summary {
-  border-collapse: collapse;
-  width: 100%;
-}
-.coverage-summary tr { border-bottom: 1px solid #bbb; }
-.keyline-all { border: 1px solid #ddd; }
-.coverage-summary td, .coverage-summary th { padding: 10px; }
-.coverage-summary tbody { border: 1px solid #bbb; }
-.coverage-summary td { border-right: 1px solid #bbb; }
-.coverage-summary td:last-child { border-right: none; }
-.coverage-summary th {
-  text-align: left;
-  font-weight: normal;
-  white-space: nowrap;
-}
-.coverage-summary th.file { border-right: none !important; }
-.coverage-summary th.pct { }
-.coverage-summary th.pic,
-.coverage-summary th.abs,
-.coverage-summary td.pct,
-.coverage-summary td.abs { text-align: right; }
-.coverage-summary td.file { white-space: nowrap;  }
-.coverage-summary td.pic { min-width: 120px !important;  }
-.coverage-summary tfoot td { }
-
-.coverage-summary .sorter {
-    height: 10px;
-    width: 7px;
-    display: inline-block;
-    margin-left: 0.5em;
-    background: url(sort-arrow-sprite.png) no-repeat scroll 0 0 transparent;
-}
-.coverage-summary .sorted .sorter {
-    background-position: 0 -20px;
-}
-.coverage-summary .sorted-desc .sorter {
-    background-position: 0 -10px;
-}
-.status-line {  height: 10px; }
-/* yellow */
-.cbranch-no { background: yellow !important; color: #111; }
-/* dark red */
-.red.solid, .status-line.low, .low .cover-fill { background:#C21F39 }
-.low .chart { border:1px solid #C21F39 }
-.highlighted,
-.highlighted .cstat-no, .highlighted .fstat-no, .highlighted .cbranch-no{
-  background: #C21F39 !important;
-}
-/* medium red */
-.cstat-no, .fstat-no, .cbranch-no, .cbranch-no { background:#F6C6CE }
-/* light red */
-.low, .cline-no { background:#FCE1E5 }
-/* light green */
-.high, .cline-yes { background:rgb(230,245,208) }
-/* medium green */
-.cstat-yes { background:rgb(161,215,106) }
-/* dark green */
-.status-line.high, .high .cover-fill { background:rgb(77,146,33) }
-.high .chart { border:1px solid rgb(77,146,33) }
-/* dark yellow (gold) */
-.status-line.medium, .medium .cover-fill { background: #f9cd0b; }
-.medium .chart { border:1px solid #f9cd0b; }
-/* light yellow */
-.medium { background: #fff4c2; }
-
-.cstat-skip { background: #ddd; color: #111; }
-.fstat-skip { background: #ddd; color: #111 !important; }
-.cbranch-skip { background: #ddd !important; color: #111; }
-
-span.cline-neutral { background: #eaeaea; }
-
-.coverage-summary td.empty {
-    opacity: .5;
-    padding-top: 4px;
-    padding-bottom: 4px;
-    line-height: 1;
-    color: #888;
-}
-
-.cover-fill, .cover-empty {
-  display:inline-block;
-  height: 12px;
-}
-.chart {
-  line-height: 0;
-}
-.cover-empty {
-    background: white;
-}
-.cover-full {
-    border-right: none !important;
-}
-pre.prettyprint {
-    border: none !important;
-    padding: 0 !important;
-    margin: 0 !important;
-}
-.com { color: #999 !important; }
-.ignore-none { color: #999; font-weight: normal; }
-
-.wrapper {
-  min-height: 100%;
-  height: auto !important;
-  height: 100%;
-  margin: 0 auto -48px;
-}
-.footer, .push {
-  height: 48px;
-}

package/coverage/block-navigation.js

@@ -1,87 +0,0 @@
-/* eslint-disable */
-var jumpToCode = (function init() {
-    // Classes of code we would like to highlight in the file view
-    var missingCoverageClasses = ['.cbranch-no', '.cstat-no', '.fstat-no'];
-
-    // Elements to highlight in the file listing view
-    var fileListingElements = ['td.pct.low'];
-
-    // We don't want to select elements that are direct descendants of another match
-    var notSelector = ':not(' + missingCoverageClasses.join('):not(') + ') > '; // becomes `:not(a):not(b) > `
-
-    // Selector that finds elements on the page to which we can jump
-    var selector =
-        fileListingElements.join(', ') +
-        ', ' +
-        notSelector +
-        missingCoverageClasses.join(', ' + notSelector); // becomes `:not(a):not(b) > a, :not(a):not(b) > b`
-
-    // The NodeList of matching elements
-    var missingCoverageElements = document.querySelectorAll(selector);
-
-    var currentIndex;
-
-    function toggleClass(index) {
-        missingCoverageElements
-            .item(currentIndex)
-            .classList.remove('highlighted');
-        missingCoverageElements.item(index).classList.add('highlighted');
-    }
-
-    function makeCurrent(index) {
-        toggleClass(index);
-        currentIndex = index;
-        missingCoverageElements.item(index).scrollIntoView({
-            behavior: 'smooth',
-            block: 'center',
-            inline: 'center'
-        });
-    }
-
-    function goToPrevious() {
-        var nextIndex = 0;
-        if (typeof currentIndex !== 'number' || currentIndex === 0) {
-            nextIndex = missingCoverageElements.length - 1;
-        } else if (missingCoverageElements.length > 1) {
-            nextIndex = currentIndex - 1;
-        }
-
-        makeCurrent(nextIndex);
-    }
-
-    function goToNext() {
-        var nextIndex = 0;
-
-        if (
-            typeof currentIndex === 'number' &&
-            currentIndex < missingCoverageElements.length - 1
-        ) {
-            nextIndex = currentIndex + 1;
-        }
-
-        makeCurrent(nextIndex);
-    }
-
-    return function jump(event) {
-        if (
-            document.getElementById('fileSearch') === document.activeElement &&
-            document.activeElement != null
-        ) {
-            // if we're currently focused on the search input, we don't want to navigate
-            return;
-        }
-
-        switch (event.which) {
-            case 78: // n
-            case 74: // j
-                goToNext();
-                break;
-            case 66: // b
-            case 75: // k
-            case 80: // p
-                goToPrevious();
-                break;
-        }
-    };
-})();
-window.addEventListener('keydown', jumpToCode);