@contractkit/prettier-plugin 0.13.0 → 0.14.1

package/src/print-operation.ts

@@ -177,7 +177,7 @@ function printOperationKey(op: OpOperationNode, key: OpBodyKey): string[] {
             return lines;
         }
         case 'responses':
-            return op.responses.length > 0 ? printResponseBlock(op.responses) : [];
+            return op.responses.length > 0 ? printResponseBlock(op.responses, op.responsesTrailingComments) : [];
     }
 }
 
@@ -189,6 +189,9 @@ function printOperation(op: OpOperationNode): string[] {
     // 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;
+    // Standalone prose above the verb, kept apart from the doc comment when the verb carries an
+    // inline one. Emitted first so it stays above the line it was written above.
+    for (const c of op.leadingComments ?? []) lines.push(`${I1}# ${c}`);
     if (op.description && !inlineDescription) {
         for (const line of op.description.split('\n')) lines.push(`${I1}# ${line}`);
     }
@@ -199,10 +202,22 @@ function printOperation(op: OpOperationNode): string[] {
     // 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));
+    // A comment run whose key turned out to print nothing has nowhere to sit; rather than drop it,
+    // it falls through to the trailing run at the end of the body.
+    const orphaned: string[] = [];
     for (const key of [...order, ...rest]) {
-        lines.push(...printOperationKey(op, key));
+        const keyLines = printOperationKey(op, key);
+        const comments = op.bodyLeadingComments?.[key] ?? [];
+        if (keyLines.length === 0) {
+            orphaned.push(...comments);
+            continue;
+        }
+        for (const c of comments) lines.push(`${I2}# ${c}`);
+        lines.push(...keyLines);
     }
 
+    for (const c of [...orphaned, ...(op.bodyTrailingComments ?? [])]) lines.push(`${I2}# ${c}`);
+
     lines.push(`${I1}}`);
     return lines;
 }
@@ -311,8 +326,11 @@ function formatSignatureValue(value: string): string {
 
 /**
  * Print a `security:` declaration. Returns `["${indent}security: none"]` for the public-endpoint
- * sentinel, a multi-line block when `policy` is set, or an empty array when there's nothing
- * meaningful to emit.
+ * sentinel, a multi-line block when `policy` is set or the block carries comments, or an empty
+ * array when there is nothing meaningful to emit.
+ *
+ * A block holding only comments still prints: the rationale for a policy floor is the reason
+ * authors write in here, and collapsing the braces away would delete it.
  *
  * @param indent indentation for the `security` keyword line
  * @param innerIndent indentation for field lines inside the block
@@ -320,11 +338,19 @@ function formatSignatureValue(value: string): string {
 export function printSecurity(security: SecurityNode, indent = I2, innerIndent = I3): string[] {
     if (security === SECURITY_NONE) return [`${indent}security: none`];
     const fields = security as SecurityFields;
-    if (fields.policy === undefined) return [];
+    const leading = fields.leadingComments ?? [];
+    const trailing = fields.trailingComments ?? [];
+    // A block with no policy still has to be emitted when it carries comments, or the author's
+    // rationale disappears along with the empty braces.
+    if (fields.policy === undefined && leading.length === 0 && trailing.length === 0) return [];
     const lines = [`${indent}security: {`];
-    const comment = fields.policyDescription ? ` # ${fields.policyDescription}` : '';
-    const value = fields.policy === false ? 'none' : fields.policy;
-    lines.push(`${innerIndent}policy: ${value}${comment}`);
+    for (const c of leading) lines.push(`${innerIndent}# ${c}`);
+    if (fields.policy !== undefined) {
+        const comment = fields.policyDescription ? ` # ${fields.policyDescription}` : '';
+        const value = fields.policy === false ? 'none' : fields.policy;
+        lines.push(`${innerIndent}policy: ${value}${comment}`);
+    }
+    for (const c of trailing) lines.push(`${innerIndent}# ${c}`);
     lines.push(`${indent}}`);
     return lines;
 }
@@ -377,21 +403,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 (resp.inline && hasBody && !hasHeaders && !optOut && resp.bodyType!.kind !== 'inlineObject') {
+        // `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 }`.
-            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));
+            // 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) {
@@ -403,12 +441,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/format-plugin.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect } from 'vitest';
+import * as prettier from 'prettier';
+import plugin from '../src/index.js';
+
+/**
+ * End-to-end checks that go through prettier itself rather than calling `printCk` directly.
+ *
+ * `printCk` terminates the file with a newline, so a printer-level test cannot see whether the
+ * plugin's doc wrapper preserves it — the plugin used to `trimEnd()` the printed source and
+ * return it without re-adding the terminator, so every formatted `.ck` file lost its trailing
+ * newline. These tests exercise the layer where that happened.
+ */
+
+function format(source: string): Promise<string> {
+    return prettier.format(source, { parser: 'contract-ck', plugins: [plugin] });
+}
+
+describe('prettier plugin — end to end', () => {
+    it('ends the formatted file with exactly one newline', async () => {
+        const source = `contract Pet: {
+    name: string
+}
+`;
+        const out = await format(source);
+        expect(out).toBe(source);
+        expect(out.endsWith('\n')).toBe(true);
+        expect(out.endsWith('\n\n')).toBe(false);
+    });
+
+    it('adds the trailing newline when the source lacks one', async () => {
+        const out = await format('contract Pet: {\n    name: string\n}');
+        expect(out).toBe('contract Pet: {\n    name: string\n}\n');
+    });
+
+    it('does not accumulate blank lines when run twice', async () => {
+        const source = `contract Pet: {
+    name: string
+}
+`;
+        expect(await format(await format(source))).toBe(source);
+    });
+});

package/tests/print-ck.test.ts

@@ -453,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' } }] }],
                 }),
             ]),
         ]);
@@ -493,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' },
@@ -519,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' } }],
                         },
                     ],

package/tests/round-trip.test.ts

@@ -111,6 +111,86 @@ contract Pet: {
 });
 
 describe('round-trip — comments in the options block', () => {
+    it('keeps a header comment above the options keyword', () => {
+        const source = `# ContractKit contracts for billing.
+# Owned by the payments team.
+options {
+    keys: {
+        area: billing
+    }
+}
+
+contract Pet: {
+    id: uuid
+}
+`;
+        expect(format(source)).toBe(source);
+    });
+
+    it('keeps a trailing comment on an options entry, braces and all', () => {
+        // The value used to swallow the comment and stop at the first `}`, which closed the
+        // block early and silently mis-parsed everything after it.
+        const source = `options {
+    keys: {
+        area: billing # interpolated elsewhere as {{area}}
+    }
+    services: {
+        PetService: "#modules/pet/pet.service.js"
+    }
+}
+
+contract Pet: {
+    id: uuid
+}
+`;
+        expect(format(source)).toBe(source);
+    });
+
+    it('keeps an unquoted subpath value unquoted', () => {
+        // Both forms parse to the same string, so the parser records which one the author wrote;
+        // without that the formatter normalizes every value to the quoted form.
+        const source = `options {
+    services: {
+        PetService: #modules/pet/pet.service.js
+    }
+}
+
+contract Pet: {
+    id: uuid
+}
+`;
+        expect(format(source)).toBe(source);
+    });
+
+    it('keeps a quoted value quoted', () => {
+        const source = `options {
+    services: {
+        PetService: "#modules/pet/pet.service.js"
+    }
+}
+
+contract Pet: {
+    id: uuid
+}
+`;
+        expect(format(source)).toBe(source);
+    });
+
+    it('keeps both forms side by side, with their comments', () => {
+        const source = `options {
+    services: {
+        Bare: #modules/a/a.service.js # unquoted
+        Quoted: "#modules/b/b.service.js" # quoted
+    }
+}
+
+contract Pet: {
+    id: uuid
+}
+`;
+        expect(format(source)).toBe(source);
+    });
+
     it('keeps a comment above a sub-block', () => {
         const source = `options {
     # where these come from
@@ -245,6 +325,352 @@ describe('round-trip — layout', () => {
         }
     }
 }
+`;
+        expect(format(source)).toBe(source);
+    });
+
+    it('keeps an empty status block, which means emitted with no body', () => {
+        const source = `operation /art/{id}: {
+    get: {
+        response: {
+            200: { application/json: Art }
+            304: {}
+        }
+    }
+}
+`;
+        expect(format(source)).toBe(source);
+    });
+
+    it('keeps a bare status bare', () => {
+        const source = `operation /art/{id}: {
+    get: {
+        response: {
+            200: { application/json: Art }
+            304:
+        }
+    }
+}
+`;
+        expect(format(source)).toBe(source);
+    });
+
+    it('keeps the documented modifier on a status', () => {
+        const source = `operation /pet: {
+    get: {
+        response: {
+            200: { application/json: Pet }
+            404(documented): { application/json: Problem }
+            410(documented):
+        }
+    }
+}
+`;
+        expect(format(source)).toBe(source);
+    });
+
+    it('keeps every declared mime for a status, in source order', () => {
+        const source = `operation /art/{id}: {
+    get: {
+        response: {
+            200: {
+                image/png: binary
+                image/jpeg: binary
+                headers: {
+                    etag?: string
+                }
+            }
+        }
+    }
+}
+`;
+        expect(format(source)).toBe(source);
+    });
+
+    it('keeps several mimes on one line when the source has them there', () => {
+        const source = `operation /art/{id}: {
+    get: {
+        response: {
+            200: { image/png: binary image/jpeg: binary }
+        }
+    }
+}
+`;
+        expect(format(source)).toBe(source);
+    });
+});
+
+// ─── Comments in the response block ──────────────────────────────────────────
+
+describe('round-trip — comments in the response block', () => {
+    it('keeps a comment run above a status code', () => {
+        const source = `operation /art/{id}: {
+    get: {
+        response: {
+            # One declared mime per format, because the router pins ctx.type from this line
+            # and a service cannot vary it per request.
+            200: {
+                image/png: binary
+            }
+            # Produced by the conditional-GET middleware, not by the handler.
+            304:
+        }
+    }
+}
+`;
+        expect(format(source)).toBe(source);
+    });
+
+    it('keeps a comment above a mime line inside a status block', () => {
+        const source = `operation /art/{id}: {
+    get: {
+        response: {
+            200: {
+                # served straight from object storage
+                image/png: binary
+            }
+        }
+    }
+}
+`;
+        expect(format(source)).toBe(source);
+    });
+
+    it('keeps a comment above a headers block', () => {
+        const source = `operation /art/{id}: {
+    get: {
+        response: {
+            200: {
+                image/png: binary
+                # set by the CDN, echoed here so the SDK types it
+                headers: {
+                    etag?: string
+                }
+            }
+        }
+    }
+}
+`;
+        expect(format(source)).toBe(source);
+    });
+
+    it('keeps trailing comments before either closing brace', () => {
+        const source = `operation /art/{id}: {
+    get: {
+        response: {
+            200: {
+                image/png: binary
+                # TODO: add image/avif once the encoder lands
+            }
+            # TODO: document the 429 the rate limiter returns
+        }
+    }
+}
+`;
+        expect(format(source)).toBe(source);
+    });
+});
+
+// ─── Security blocks ─────────────────────────────────────────────────────────
+
+/**
+ * A `security { }` block is where authors record *why* a policy floor sits where it does, so the
+ * prose in and around it is load-bearing. Every position here used to be deleted outright on
+ * format: the parser skipped standalone comments inside the block, dropped comment runs above a
+ * body key, and let a comment run above a verb lose to the verb's own inline doc comment.
+ */
+describe('round-trip — security block comments', () => {
+    it('keeps a comment above the policy line in the options block', () => {
+        const source = `options {
+    security: {
+        # The floor for every operation in this file.
+        # Reads override it downward at their own verb.
+        policy: platform.manage
+    }
+}
+`;
+        expect(format(source)).toBe(source);
+    });
+
+    it('keeps a comment after the policy line, before the closing brace', () => {
+        const source = `options {
+    security: {
+        policy: platform.manage
+        # Object-scoped permissions cannot be named here yet.
+    }
+}
+`;
+        expect(format(source)).toBe(source);
+    });
+
+    it('distinguishes an inline policy comment from one on the next line', () => {
+        const source = `options {
+    security: {
+        # Why this floor
+        policy: platform.manage # the operator gate
+    }
+}
+`;
+        expect(format(source)).toBe(source);
+    });
+
+    it('keeps a comment above a security block inside an operation body', () => {
+        const source = `operation /plugins: {
+    get: {
+        name: List plugins
+        # A read, so it drops to the view floor.
+        security: {
+            policy: platform.view
+        }
+        response: {
+            200:
+        }
+    }
+}
+`;
+        expect(format(source)).toBe(source);
+    });
+
+    it('keeps a comment above a security: none line', () => {
+        const source = `operation /plugins/callback: {
+    get: {
+        name: OAuth callback
+        # The provider redirects a browser here, so it cannot carry a session.
+        security: none
+        response: {
+            200:
+        }
+    }
+}
+`;
+        expect(format(source)).toBe(source);
+    });
+
+    it('keeps a comment run above a verb that also has an inline doc comment', () => {
+        const source = `operation /plugins/{id}/logs: {
+    params: {
+        id: uuid
+    }
+    # Log output is whatever the plugin chose to write, including upstream error
+    # bodies. Treat it as operator-only until the log store can promise otherwise.
+    get: { # Returns the plugin's buffered log lines
+        name: Get plugin logs
+        response: {
+            200:
+        }
+    }
+}
+`;
+        expect(format(source)).toBe(source);
+    });
+
+    it('keeps a comment left after the last key in an operation body', () => {
+        const source = `operation /plugins: {
+    get: {
+        name: List plugins
+        response: {
+            200:
+        }
+        # TODO: gate this behind the object-scoped permission once it exists
+    }
+}
+`;
+        expect(format(source)).toBe(source);
+    });
+});
+
+// ─── Declaration-boundary comments ───────────────────────────────────────────
+
+/**
+ * A comment between two top-level declarations is ambiguous: it can be an inline comment trailing
+ * the one above, a doc comment for the one below, or a standalone block. A declaration could not
+ * see what preceded it, so `ModelBody`'s optional trailing comment claimed the *next* line's
+ * comment — deleting a doc comment, or silently re-filing it as the previous contract's
+ * description. `Root` places these now, by comparing source lines.
+ */
+describe('round-trip — comments between declarations', () => {
+    it('keeps a doc comment on a contract that follows a one-line alias contract', () => {
+        const source = `contract ConfigFieldType: enum(string, url, secret)
+
+# One choice of a \`select\` config field
+contract ConfigFieldOption: {
+    value: string
+}
+`;
+        expect(format(source)).toBe(source);
+    });
+
+    it('keeps an inline comment on an alias contract where it was written', () => {
+        const source = `contract PluginStatus: enum(discovered, active) # Lifecycle state
+
+contract ConfigFieldOption: {
+    value: string
+}
+`;
+        expect(format(source)).toBe(source);
+    });
+
+    it('tells an inline comment apart from the doc comment below it', () => {
+        const source = `contract PluginStatus: enum(discovered, active) # Lifecycle state
+
+# One choice of a \`select\` config field
+contract ConfigFieldOption: {
+    value: string
+}
+`;
+        expect(format(source)).toBe(source);
+    });
+
+    it('keeps an inline comment on the last declaration in the file', () => {
+        const source = `contract PluginStatus: enum(discovered, active) # Lifecycle state
+`;
+        expect(format(source)).toBe(source);
+    });
+
+    it('keeps a comment after the last declaration', () => {
+        const source = `contract PluginStatus: enum(discovered, active)
+
+# TODO: add the archived state once the store supports it
+`;
+        expect(format(source)).toBe(source);
+    });
+});
+
+// ─── Field comments ──────────────────────────────────────────────────────────
+
+describe('round-trip — field comments', () => {
+    it('keeps a comment on a nested inline object opening brace', () => {
+        const source = `contract FidoFactorAttestation: {
+    rp: { # The relying party
+        name: string # The relying party name
+    }
+}
+`;
+        expect(format(source)).toBe(source);
+    });
+
+    it('keeps a nested brace comment that repeats the contract header wording', () => {
+        // The header comment is reclaimed from the field list by matching text; when a nested
+        // field carried the same wording, the reclaim deleted the wrong one.
+        const source = `contract FidoFactorAttestation: { # The FIDO factor attestation information
+    rp: { # The FIDO factor attestation information
+        name: string # The relying party name
+    }
+}
+`;
+        expect(format(source)).toBe(source);
+    });
+
+    it('keeps a trailing comment on a field whose enum type wraps', () => {
+        const source = `contract LineupEntry: {
+    segmentState?: enum(
+        planned,
+        rendering,
+        ready,
+        failed,
+        gone
+    ) # How far along the segment is
+}
 `;
         expect(format(source)).toBe(source);
     });