@contractkit/prettier-plugin 0.12.2 → 0.13.0

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) : [];
     }
-    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_$]*$/;
@@ -318,7 +384,10 @@ function printResponseBlock(responses: OpResponseNode[]): string[] {
         const hasBody = resp.contentType && resp.bodyType;
         const hasHeaders = resp.headers && resp.headers.length > 0;
         const optOut = resp.headersOptOut;
-        if (hasBody || hasHeaders || optOut) {
+        if (resp.inline && hasBody && !hasHeaders && !optOut && resp.bodyType!.kind !== 'inlineObject') {
+            // Written on one line in the source, so keep it there: `200: { application/json: Pet }`.
+            lines.push(`${I3}${resp.statusCode}: { ${resp.contentType}: ${printType(resp.bodyType!)} }`);
+        } else if (hasBody || hasHeaders || optOut) {
             lines.push(`${I3}${resp.statusCode}: {`);
             if (hasBody) {
                 lines.push(...printContentTypeLine(resp.contentType!, resp.bodyType!, I4));

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: {');
     });
 });
 
@@ -531,6 +533,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();

package/tests/round-trip.test.ts

@@ -0,0 +1,268 @@
+import { describe, it, expect } from 'vitest';
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { printCk } from '../src/print-ck.js';
+import { parseCk, DiagnosticCollector } from '@contractkit/core';
+
+/**
+ * Formatting a `.ck` file must not change it.
+ *
+ * The prettier plugin used to fold standalone `#` comment blocks into trailing comments on the
+ * following declaration, reorder operation body keys, drop blank lines between operations, and
+ * expand single-line response bodies — all of which silently rewrote a user's file on
+ * `pnpm format`. These tests pin the guarantee: parse → print is the identity on well-formed
+ * source, and printing is idempotent.
+ */
+
+function format(source: string, file = 'test.ck'): string {
+    const diag = new DiagnosticCollector();
+    const ast = parseCk(source, file, diag);
+    expect(diag.hasErrors()).toBe(false);
+    return printCk(ast);
+}
+
+// ─── Repository contracts ────────────────────────────────────────────────────
+
+const CONTRACTS_DIR = new URL('../../../contracts', import.meta.url).pathname;
+const ckFiles = readdirSync(CONTRACTS_DIR).filter(f => f.endsWith('.ck'));
+
+describe('round-trip — repository .ck files', () => {
+    it('finds .ck files to check', () => {
+        expect(ckFiles.length).toBeGreaterThan(0);
+    });
+
+    for (const name of ckFiles) {
+        it(`formats ${name} to itself`, () => {
+            const source = readFileSync(join(CONTRACTS_DIR, name), 'utf8');
+            expect(format(source, name)).toBe(source);
+        });
+    }
+});
+
+// ─── Constructs that previously round-tripped lossily ────────────────────────
+
+describe('round-trip — comment placement', () => {
+    it('keeps a standalone comment block above the declaration it precedes', () => {
+        const source = `# ─── Pet endpoints ───
+
+operation /pet: {
+    get: {
+        response: {
+            200:
+        }
+    }
+}
+`;
+        expect(format(source)).toBe(source);
+    });
+
+    it('keeps a contract doc comment on its own line', () => {
+        const source = `# A pet for sale
+contract Pet: {
+    id: int
+}
+`;
+        expect(format(source)).toBe(source);
+    });
+
+    it('keeps a contract doc comment inline when written inline', () => {
+        const source = `contract Pet: { # A pet for sale
+    id: int
+}
+`;
+        expect(format(source)).toBe(source);
+    });
+
+    it('distinguishes a divider from the doc comment below it', () => {
+        const source = `# ─── Models ───
+
+# A pet for sale
+contract Pet: {
+    id: int
+}
+`;
+        expect(format(source)).toBe(source);
+    });
+
+    it('keeps an operation doc comment on its own line', () => {
+        const source = `operation /pet: {
+    # update an existing pet
+    put: {
+        response: {
+            200:
+        }
+    }
+}
+`;
+        expect(format(source)).toBe(source);
+    });
+
+    it('keeps an operation doc comment inline when written inline', () => {
+        const source = `operation /pet: {
+    put: { # update an existing pet
+        response: {
+            200:
+        }
+    }
+}
+`;
+        expect(format(source)).toBe(source);
+    });
+});
+
+describe('round-trip — comments in the options block', () => {
+    it('keeps a comment above a sub-block', () => {
+        const source = `options {
+    # where these come from
+    keys: {
+        area: ledger
+    }
+}
+`;
+        expect(format(source)).toBe(source);
+    });
+
+    it('keeps a comment run above the sub-block it precedes', () => {
+        const source = `options {
+    keys: {
+        area: ledger
+    }
+    # service wiring
+    # one per module
+    services: {
+        UserService: "#src/user.js"
+    }
+}
+`;
+        expect(format(source)).toBe(source);
+    });
+
+    it('keeps a trailing comment before the closing brace', () => {
+        const source = `options {
+    keys: {
+        area: ledger
+    }
+    # nothing below
+}
+`;
+        expect(format(source)).toBe(source);
+    });
+
+    it('keeps an options block that holds nothing but a comment', () => {
+        const source = `options {
+    # a note
+}
+`;
+        expect(format(source)).toBe(source);
+    });
+});
+
+describe('round-trip — operation body key order', () => {
+    it('does not reorder keys into a canonical order', () => {
+        const source = `operation /pet: {
+    put: {
+        sdk: updatePet
+        service: PetService.update
+        response: {
+            200:
+        }
+    }
+}
+`;
+        expect(format(source)).toBe(source);
+    });
+
+    it('preserves the opposite order just as faithfully', () => {
+        const source = `operation /pet: {
+    put: {
+        service: PetService.update
+        sdk: updatePet
+        response: {
+            200:
+        }
+    }
+}
+`;
+        expect(format(source)).toBe(source);
+    });
+});
+
+describe('round-trip — layout', () => {
+    it('keeps blank lines between operations', () => {
+        const source = `operation /pet: {
+    get: {
+        response: {
+            200:
+        }
+    }
+
+    post: {
+        response: {
+            201:
+        }
+    }
+}
+`;
+        expect(format(source)).toBe(source);
+    });
+
+    it('keeps operations packed when the source has no blank line', () => {
+        const source = `operation /pet: {
+    get: {
+        response: {
+            200:
+        }
+    }
+    post: {
+        response: {
+            201:
+        }
+    }
+}
+`;
+        expect(format(source)).toBe(source);
+    });
+
+    it('keeps a single-line response body on one line', () => {
+        const source = `operation /pet: {
+    get: {
+        response: {
+            200: { application/json: Pet }
+        }
+    }
+}
+`;
+        expect(format(source)).toBe(source);
+    });
+
+    it('keeps an expanded response body expanded', () => {
+        const source = `operation /pet: {
+    get: {
+        response: {
+            200: {
+                application/json: Pet
+            }
+        }
+    }
+}
+`;
+        expect(format(source)).toBe(source);
+    });
+});
+
+// ─── Idempotence ─────────────────────────────────────────────────────────────
+
+describe('round-trip — idempotence', () => {
+    const sources = [
+        ...ckFiles.map(name => readFileSync(join(CONTRACTS_DIR, name), 'utf8')),
+        // Non-canonical spacing: formatting once must reach a fixed point.
+        `operation /pet: {\n    get: {\n        response: {\n            200:\n        }\n    }\n}\n`,
+    ];
+
+    for (const [i, source] of sources.entries()) {
+        it(`formatting is a fixed point for source #${i}`, () => {
+            const once = format(source);
+            expect(format(once)).toBe(once);
+        });
+    }
+});