@contractkit/prettier-plugin 0.12.2 → 0.14.0

package/src/print-contract.ts

@@ -5,11 +5,14 @@ import { INDENT } from './indent.js';
 // ─── Model declaration ───────────────────────────────────────────────────────
 
 /**
- * Render a `contract` body from its `Name: ...` onward (the `contract ` keyword is
- * prepended by the caller). Handles both the type-alias form (`Name: <type>`) and the
- * regular field-block form, including modifiers, base chain, and per-field printing.
- * Any `model.trailingComments` (comments after the last field, before `}`) are emitted
- * as indented `# text` lines so they round-trip.
+ * Render a `contract` body from its `Name: ...` onward (the `contract ` keyword and any
+ * doc comment written above the declaration are prepended by the caller). Handles both the
+ * type-alias form (`Name: <type>`) and the regular field-block form, including modifiers,
+ * base chain, and per-field printing. Any `model.trailingComments` (comments after the last
+ * field, before `}`) are emitted as indented `# text` lines so they round-trip.
+ *
+ * `model.description` is emitted here only when `model.descriptionInline` says the author wrote
+ * it on the header line; otherwise it belongs above the declaration and the caller emits it.
  */
 export function printModelDecl(model: ModelNode, printWidth: number = 80): string {
     // Type alias form: Name : typeExpression
@@ -18,7 +21,9 @@ export function printModelDecl(model: ModelNode, printWidth: number = 80): strin
     }
 
     // Regular model with fields (possibly inherited)
-    const commentSuffix = model.description ? ` # ${model.description}` : '';
+    // A doc comment written above the declaration is re-emitted there by the caller; only an
+    // inline one belongs on the header line.
+    const commentSuffix = model.description && model.descriptionInline ? ` # ${model.description}` : '';
     const modifiers = [
         model.deprecated ? 'deprecated' : '',
         model.inputCase || model.outputCase
@@ -45,7 +50,9 @@ export function printModelDecl(model: ModelNode, printWidth: number = 80): strin
 
 function printTypeAlias(model: ModelNode, printWidth: number): string {
     const type = model.type!;
-    const commentSuffix = model.description ? ` # ${model.description}` : '';
+    // A doc comment written above the declaration is re-emitted there by the caller; only an
+    // inline one belongs on the header line.
+    const commentSuffix = model.description && model.descriptionInline ? ` # ${model.description}` : '';
     const modifiers = [
         model.deprecated ? 'deprecated' : '',
         model.inputCase || model.outputCase

package/src/print-operation.ts

@@ -8,6 +8,8 @@ import type {
     ContractTypeNode,
     ObjectMode,
     PluginValue,
+    McpConfigNode,
+    OpBodyKey,
 } from '@contractkit/core';
 import { SECURITY_NONE } from '@contractkit/core';
 import { printType, formatDefault } from './print-type.js';
@@ -54,17 +56,20 @@ export function flushBlocks(out: string[], blocks: CommentBlock[], idx: { value:
 // ─── Route ───────────────────────────────────────────────────────────────────
 
 /**
- * Render an `operation` route body from its `path: {` onward (the `operation` keyword and
- * any modifier are prepended by the caller). Emits the params/security blocks and each HTTP
- * operation, interleaving orphan comment `blocks` at their original source positions — `idx`
- * tracks how far through `blocks` we've consumed, and `nextRouteStart` bounds the flush to
- * comments before the following route. Any `route.trailingComments` (comments after the last
- * operation, before `}`) are emitted before the closing brace so they round-trip.
+ * Render an `operation` route body from its `path: {` onward (the `operation` keyword, any
+ * modifier, and the route's leading comments are prepended by the caller). Emits the
+ * params/security blocks and each HTTP operation, interleaving orphan comment `blocks` at their
+ * original source positions — `idx` tracks how far through `blocks` we've consumed, and
+ * `nextRouteStart` bounds the flush to comments before the following route. Any
+ * `route.trailingComments` (comments after the last operation, before `}`) are emitted before
+ * the closing brace so they round-trip.
+ *
+ * Blank lines between operations come from each operation's `blankLineBefore`, so the author's
+ * spacing survives rather than being normalized to one rule or the other.
  */
 export function printRoute(route: OpRouteNode, blocks: CommentBlock[], idx: { value: number }, nextRouteStart: number): string {
     const lines: string[] = [];
-    const commentSuffix = route.description ? ` # ${route.description}` : '';
-    lines.push(`${route.path}: {${commentSuffix}`);
+    lines.push(`${route.path}: {`);
 
     if (route.params !== undefined) {
         lines.push(...printParamsBlock(route.params, I1, route.paramsMode));
@@ -75,6 +80,8 @@ export function printRoute(route: OpRouteNode, blocks: CommentBlock[], idx: { va
     }
 
     for (const op of route.operations) {
+        // Reproduce the author's spacing rather than imposing our own.
+        if (op.blankLineBefore && lines.length > 1) lines.push('');
         // Flush comment blocks that appear before this operation (inside the route)
         flushBlocks(lines, blocks, idx, op.loc.line, I1);
         lines.push(...printOperation(op));
@@ -119,55 +126,114 @@ function printParamsBlock(source: ParamSource, indent: string, mode?: ObjectMode
 
 // ─── HTTP operation ──────────────────────────────────────────────────────────
 
-function printOperation(op: OpOperationNode): string[] {
-    const lines: string[] = [];
-    const commentSuffix = op.description ? ` # ${op.description}` : '';
-    const modPart = op.modifiers?.length ? `(${op.modifiers[0]})` : '';
-    lines.push(`${I1}${op.method}${modPart}: {${commentSuffix}`);
-
-    if (op.name) lines.push(`${I2}name: ${op.name}`);
-    if (op.service) lines.push(`${I2}service: ${op.service}`);
-    if (op.sdk) lines.push(`${I2}sdk: ${op.sdk}`);
-    if (op.signature) {
-        const comment = op.signatureDescription ? ` # ${op.signatureDescription}` : '';
-        if (op.signaturePolicy) {
-            lines.push(`${I2}signature: {`);
-            lines.push(`${I3}options: ${formatSignatureValue(op.signature)}${comment}`);
-            lines.push(`${I3}policy: ${op.signaturePolicy}`);
+/** Order the body keys are emitted in when the node carries no source order (built programmatically). */
+const CANONICAL_KEY_ORDER: OpBodyKey[] = ['name', 'service', 'sdk', 'mcp', 'signature', 'security', 'plugins', 'query', 'headers', 'request', 'responses'];
+
+/** Render a single operation-body key. Returns `[]` when the operation doesn't carry that key. */
+function printOperationKey(op: OpOperationNode, key: OpBodyKey): string[] {
+    switch (key) {
+        case 'name':
+            return op.name ? [`${I2}name: ${op.name}`] : [];
+        case 'service':
+            return op.service ? [`${I2}service: ${op.service}`] : [];
+        case 'sdk':
+            return op.sdk ? [`${I2}sdk: ${op.sdk}`] : [];
+        case 'mcp':
+            if (op.mcp === true) return [`${I2}mcp: true`];
+            if (op.mcp === false) return [`${I2}mcp: false`];
+            return op.mcp ? printMcpBlock(op.mcp) : [];
+        case 'signature': {
+            if (!op.signature) return [];
+            const comment = op.signatureDescription ? ` # ${op.signatureDescription}` : '';
+            if (op.signaturePolicy) {
+                return [
+                    `${I2}signature: {`,
+                    `${I3}options: ${formatSignatureValue(op.signature)}${comment}`,
+                    `${I3}policy: ${op.signaturePolicy}`,
+                    `${I2}}`,
+                ];
+            }
+            return [`${I2}signature: ${formatSignatureValue(op.signature)}${comment}`];
+        }
+        case 'security':
+            return op.security !== undefined ? printSecurity(op.security) : [];
+        case 'plugins': {
+            if (!op.plugins || Object.keys(op.plugins).length === 0) return [];
+            const lines = [`${I2}plugins: {`];
+            for (const [k, val] of Object.entries(op.plugins)) lines.push(...printPluginEntry(k, val, I3));
             lines.push(`${I2}}`);
-        } else {
-            lines.push(`${I2}signature: ${formatSignatureValue(op.signature)}${comment}`);
+            return lines;
         }
-    }
-    if (op.security !== undefined) lines.push(...printSecurity(op.security));
-    if (op.plugins && Object.keys(op.plugins).length > 0) {
-        lines.push(`${I2}plugins: {`);
-        for (const [key, val] of Object.entries(op.plugins)) {
-            lines.push(...printPluginEntry(key, val, I3));
+        case 'query':
+            return op.query !== undefined ? printQueryOrHeaders('query', op.query, op.queryMode) : [];
+        case 'headers':
+            if (op.requestHeadersOptOut) return [`${I2}headers: none`];
+            return op.headers !== undefined ? printQueryOrHeaders('headers', op.headers, op.headersMode) : [];
+        case 'request': {
+            if (!op.request) return [];
+            const lines = [`${I2}request: {`];
+            for (const body of op.request.bodies) lines.push(...printContentTypeLine(body.contentType, body.bodyType, I3));
+            lines.push(`${I2}}`);
+            return lines;
         }
-        lines.push(`${I2}}`);
+        case 'responses':
+            return op.responses.length > 0 ? printResponseBlock(op.responses, op.responsesTrailingComments) : [];
     }
-    if (op.query !== undefined) lines.push(...printQueryOrHeaders('query', op.query, op.queryMode));
-    if (op.requestHeadersOptOut) {
-        lines.push(`${I2}headers: none`);
-    } else if (op.headers !== undefined) {
-        lines.push(...printQueryOrHeaders('headers', op.headers, op.headersMode));
-    }
-    if (op.request) {
-        lines.push(`${I2}request: {`);
-        for (const body of op.request.bodies) {
-            lines.push(...printContentTypeLine(body.contentType, body.bodyType, I3));
-        }
-        lines.push(`${I2}}`);
+}
+
+function printOperation(op: OpOperationNode): string[] {
+    const lines: string[] = [];
+    const modPart = op.modifiers?.length ? `(${op.modifiers[0]})` : '';
+
+    // A doc comment written above the method line goes back above it; only an inline one is
+    // re-emitted as a trailing `#` on the header. Nodes built programmatically carry no placement,
+    // and default to inline — the form most `.ck` sources use and one that round-trips as written.
+    const inlineDescription = op.descriptionInline ?? true;
+    if (op.description && !inlineDescription) {
+        for (const line of op.description.split('\n')) lines.push(`${I1}# ${line}`);
     }
-    if (op.responses.length > 0) {
-        lines.push(...printResponseBlock(op.responses));
+    const commentSuffix = op.description && inlineDescription ? ` # ${op.description}` : '';
+    lines.push(`${I1}${op.method}${modPart}: {${commentSuffix}`);
+
+    // Emit in source order when the parser recorded it, so formatting never reorders a user's keys.
+    // Any key the source order doesn't mention (e.g. added by a later AST pass) follows in canonical order.
+    const order = op.keyOrder ?? [];
+    const rest = CANONICAL_KEY_ORDER.filter(k => !order.includes(k));
+    for (const key of [...order, ...rest]) {
+        lines.push(...printOperationKey(op, key));
     }
 
     lines.push(`${I1}}`);
     return lines;
 }
 
+// ─── MCP block ───────────────────────────────────────────────────────────────
+
+/**
+ * Reconstruct the `hint:` token list from the four annotation booleans, in canonical
+ * order. Each set boolean contributes its positive or negative token; unset hints are omitted.
+ */
+function mcpHintTokens(mcp: McpConfigNode): string[] {
+    const tokens: string[] = [];
+    if (mcp.readOnlyHint !== undefined) tokens.push(mcp.readOnlyHint ? 'readOnly' : 'nonReadOnly');
+    if (mcp.idempotentHint !== undefined) tokens.push(mcp.idempotentHint ? 'idempotent' : 'nonIdempotent');
+    if (mcp.destructiveHint !== undefined) tokens.push(mcp.destructiveHint ? 'destructive' : 'nonDestructive');
+    if (mcp.openWorldHint !== undefined) tokens.push(mcp.openWorldHint ? 'openWorld' : 'closedWorld');
+    return tokens;
+}
+
+/** Print an `mcp: { ... }` settings block. Fields are emitted in canonical order; `hint:` is omitted when no hints are set. */
+function printMcpBlock(mcp: McpConfigNode): string[] {
+    const lines: string[] = [`${I2}mcp: {`];
+    if (mcp.name !== undefined) lines.push(`${I3}name: "${escapeString(mcp.name)}"`);
+    if (mcp.title !== undefined) lines.push(`${I3}title: "${escapeString(mcp.title)}"`);
+    if (mcp.description !== undefined) lines.push(`${I3}description: "${escapeString(mcp.description)}"`);
+    const tokens = mcpHintTokens(mcp);
+    if (tokens.length > 0) lines.push(`${I3}hint: ${tokens.join(', ')}`);
+    lines.push(`${I2}}`);
+    return lines;
+}
+
 // ─── Plugins block ───────────────────────────────────────────────────────────
 
 const IDENT_RE = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
@@ -311,18 +377,33 @@ function printContentTypeLine(contentType: string, bodyType: ContractTypeNode, l
 
 // ─── Response block ──────────────────────────────────────────────────────────
 
-function printResponseBlock(responses: OpResponseNode[]): string[] {
+function printResponseBlock(responses: OpResponseNode[], trailingComments?: string[]): string[] {
     const lines: string[] = [`${I2}response: {`];
 
     for (const resp of responses) {
-        const hasBody = resp.contentType && resp.bodyType;
+        for (const comment of resp.leadingComments ?? []) lines.push(`${I3}# ${comment}`);
+        const bodies = resp.bodies;
         const hasHeaders = resp.headers && resp.headers.length > 0;
         const optOut = resp.headersOptOut;
-        if (hasBody || hasHeaders || optOut) {
-            lines.push(`${I3}${resp.statusCode}: {`);
-            if (hasBody) {
-                lines.push(...printContentTypeLine(resp.contentType!, resp.bodyType!, I4));
+        // `404(documented):` — the modifier changes what codegen does, so it has to survive.
+        const code = resp.emit ? `${resp.statusCode}(${resp.emit})` : `${resp.statusCode}`;
+        const inlinable = resp.inline && bodies.length > 0 && !hasHeaders && !optOut && bodies.every(b => b.bodyType.kind !== 'inlineObject');
+        if (inlinable) {
+            // Written on one line in the source, so keep it there: `200: { application/json: Pet }`.
+            // Several mimes on that line stay on it too, space-separated as the grammar has them.
+            const inner = bodies.map(b => `${b.contentType}: ${printType(b.bodyType)}`).join(' ');
+            lines.push(`${I3}${code}: { ${inner} }`);
+        } else if (bodies.length === 0 && !hasHeaders && !optOut && resp.hasBlock) {
+            // An empty block means "emitted, no body" — collapsing it to `304:` would change
+            // the generated router, so it is not a formatting detail.
+            lines.push(`${I3}${code}: {}`);
+        } else if (bodies.length > 0 || hasHeaders || optOut || (resp.trailingComments?.length ?? 0) > 0) {
+            lines.push(`${I3}${code}: {`);
+            for (const body of bodies) {
+                for (const comment of body.leadingComments ?? []) lines.push(`${I4}# ${comment}`);
+                lines.push(...printContentTypeLine(body.contentType, body.bodyType, I4));
             }
+            for (const comment of resp.headersLeadingComments ?? []) lines.push(`${I4}# ${comment}`);
             if (optOut) {
                 lines.push(`${I4}headers: none`);
             } else if (hasHeaders) {
@@ -334,12 +415,14 @@ function printResponseBlock(responses: OpResponseNode[]): string[] {
                 }
                 lines.push(`${I4}}`);
             }
+            for (const comment of resp.trailingComments ?? []) lines.push(`${I4}# ${comment}`);
             lines.push(`${I3}}`);
         } else {
-            lines.push(`${I3}${resp.statusCode}:`);
+            lines.push(`${I3}${code}:`);
         }
     }
 
+    for (const comment of trailingComments ?? []) lines.push(`${I3}# ${comment}`);
     lines.push(`${I2}}`);
     return lines;
 }

package/tests/print-ck.test.ts

@@ -60,7 +60,9 @@ describe('printCk — route modifiers', () => {
 
     it('preserves description alongside modifier', () => {
         const ast = makeRoot([makeRoute('/users', [makeOp('get')], { modifiers: ['deprecated'], description: 'Old user list' })]);
-        expect(printCk(ast)).toContain('operation(deprecated) /users: { # Old user list');
+        // A route description is emitted above the declaration, not inline: a `#` after the `{`
+        // would re-parse as the first operation's description instead.
+        expect(printCk(ast)).toContain('# Old user list\noperation(deprecated) /users: {');
     });
 });
 
@@ -451,7 +453,7 @@ describe('printCk — request blocks', () => {
             makeRoute('/users', [
                 makeOp('post', {
                     request: { bodies: [{ contentType: 'application/vnd.api+json', bodyType: { kind: 'ref', name: 'CreateUser' } }] },
-                    responses: [{ statusCode: 201, contentType: 'application/vnd.api+json', bodyType: { kind: 'ref', name: 'User' } }],
+                    responses: [{ statusCode: 201, hasBlock: true, bodies: [{ contentType: 'application/vnd.api+json', bodyType: { kind: 'ref', name: 'User' } }] }],
                 }),
             ]),
         ]);
@@ -491,8 +493,8 @@ describe('printCk — response headers', () => {
                     responses: [
                         {
                             statusCode: 200,
-                            contentType: 'application/json',
-                            bodyType: { kind: 'ref', name: 'Transfer' },
+                            hasBlock: true,
+                            bodies: [{ contentType: 'application/json', bodyType: { kind: 'ref', name: 'Transfer' } }],
                             headers: [
                                 { name: 'preference-applied', optional: true, type: { kind: 'scalar', name: 'string' } },
                                 { name: 'etag', optional: false, type: { kind: 'scalar', name: 'string' }, description: 'cache validator' },
@@ -517,6 +519,8 @@ describe('printCk — response headers', () => {
                     responses: [
                         {
                             statusCode: 204,
+                            hasBlock: true,
+                            bodies: [],
                             headers: [{ name: 'x-deleted-at', optional: false, type: { kind: 'scalar', name: 'string' } }],
                         },
                     ],
@@ -531,6 +535,82 @@ describe('printCk — response headers', () => {
     });
 });
 
+describe('printCk — mcp field', () => {
+    function roundTrip(source: string): string {
+        const diag = new DiagnosticCollector();
+        const ast = parseCk(source, 'test.ck', diag);
+        expect(diag.hasErrors()).toBe(false);
+        return printCk(ast);
+    }
+
+    it('prints mcp: true', () => {
+        const ast = makeRoot([makeRoute('/users', [makeOp('get', { mcp: true })])]);
+        expect(printCk(ast)).toContain('        mcp: true');
+    });
+
+    it('prints explicit mcp: false', () => {
+        const ast = makeRoot([makeRoute('/users', [makeOp('get', { mcp: false })])]);
+        expect(printCk(ast)).toContain('        mcp: false');
+    });
+
+    it('omits mcp when undefined', () => {
+        const ast = makeRoot([makeRoute('/users', [makeOp('get')])]);
+        expect(printCk(ast)).not.toContain('mcp:');
+    });
+
+    it('prints mcp block with text fields and reconstructed hint list', () => {
+        const ast = makeRoot([
+            makeRoute('/routes', [
+                makeOp('post', {
+                    mcp: {
+                        name: 'searchRoutes',
+                        title: 'Search routes',
+                        description: 'Full-text search.',
+                        readOnlyHint: true,
+                        idempotentHint: true,
+                        destructiveHint: false,
+                        loc: makeLoc(),
+                    },
+                }),
+            ]),
+        ]);
+        const out = printCk(ast);
+        expect(out).toContain('        mcp: {');
+        expect(out).toContain('            name: "searchRoutes"');
+        expect(out).toContain('            title: "Search routes"');
+        expect(out).toContain('            description: "Full-text search."');
+        expect(out).toContain('            hint: readOnly, idempotent, nonDestructive');
+    });
+
+    it('round-trips mcp: true / false through parse', () => {
+        expect(roundTrip('operation /a: {\n    get: {\n        mcp: true\n    }\n}\n')).toContain('        mcp: true');
+        expect(roundTrip('operation /b: {\n    get: {\n        mcp: false\n    }\n}\n')).toContain('        mcp: false');
+    });
+
+    it('round-trips an mcp settings block through parse', () => {
+        const source = `\
+operation /routes: {
+    post: {
+        mcp: {
+            name: "searchRoutes"
+            title: "Search routes"
+            description: "Full-text search across routes."
+            hint: readOnly, idempotent, nonDestructive, closedWorld
+        }
+    }
+}
+`;
+        const out = roundTrip(source);
+        expect(out).toContain('        mcp: {');
+        expect(out).toContain('            name: "searchRoutes"');
+        expect(out).toContain('            hint: readOnly, idempotent, nonDestructive, closedWorld');
+        // Idempotent: printing the round-tripped output again is stable.
+        const diag = new DiagnosticCollector();
+        expect(printCk(parseCk(out, 'test.ck', diag))).toBe(out);
+        expect(diag.hasErrors()).toBe(false);
+    });
+});
+
 describe('printCk — options-level header globals (round-trip)', () => {
     function roundTrip(source: string): string {
         const diag = new DiagnosticCollector();