@contractkit/prettier-plugin 0.12.2 → 0.14.0

package/.turbo/turbo-build$colon$ci.log

@@ -5,9 +5,9 @@ $ tsup src/index.ts --format esm --sourcemap --dts && tsc --emitDeclarationOnly
 CLI tsup v8.5.1
 CLI Target: esnext
 ESM Build start
-ESM dist/index.js     21.38 KB
-ESM dist/index.js.map 52.77 KB
-ESM ⚡️ Build success in 206ms
+ESM dist/index.js     26.17 KB
+ESM dist/index.js.map 65.66 KB
+ESM ⚡️ Build success in 231ms
 DTS Build start
-DTS ⚡️ Build success in 5108ms
-DTS dist/index.d.ts 726.00 B
+DTS ⚡️ Build success in 4442ms
+DTS dist/index.d.ts 1.13 KB

package/.turbo/turbo-test$colon$ci.log

@@ -3,21 +3,24 @@ $ vitest run --coverage
  RUN  v4.1.5 /home/runner/work/ContractKit/ContractKit/apps/prettier-plugin
       Coverage enabled with v8
 
- ✓ tests/print-ck.test.ts (75 tests) 570ms
+ ✓ tests/print-ck.test.ts (81 tests) 923ms
+ ✓ tests/round-trip.test.ts (34 tests) 2390ms
+     ✓ formats test.ck to itself  690ms
+     ✓ formatting is a fixed point for source #0  1192ms
 
- Test Files  1 passed (1)
-      Tests  75 passed (75)
-   Start at  17:06:39
-   Duration  6.62s (transform 2.00s, setup 0ms, import 4.69s, tests 570ms, environment 0ms)
+ Test Files  2 passed (2)
+      Tests  115 passed (115)
+   Start at  16:09:43
+   Duration  8.00s (transform 3.22s, setup 0ms, import 8.69s, tests 3.31s, environment 0ms)
 
  % Coverage report from v8
 -------------------|---------|----------|---------|---------|-------------------
 File               | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
 -------------------|---------|----------|---------|---------|-------------------
-All files          |    71.2 |    63.72 |   81.25 |    77.8 |                   
+All files          |   76.13 |    71.15 |   85.36 |   82.04 |                   
  indent.ts         |     100 |      100 |     100 |     100 |                   
- print-ck.ts       |   89.18 |     83.8 |     100 |   98.14 | 70                
- print-contract.ts |   45.71 |     37.5 |      50 |   46.66 | 17,47-78          
- ...t-operation.ts |   73.98 |    65.04 |   92.85 |   83.95 | ...88,296-307,339 
- print-type.ts     |   58.69 |    56.73 |   63.63 |      60 | ...02-103,148-151 
+ print-ck.ts       |   89.09 |    87.56 |     100 |   97.36 | 91-92             
+ print-contract.ts |   45.71 |    38.23 |      50 |   46.66 | 20,52-85          
+ ...t-operation.ts |   78.41 |    70.42 |      95 |   86.75 | ...37,354,362-373 
+ print-type.ts     |   64.13 |    63.46 |   63.63 |   66.66 | ...02-103,148-151 
 -------------------|---------|----------|---------|---------|-------------------

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # @contractkit/prettier-plugin-contractkit
 
+## 0.14.0
+
+### Minor Changes
+
+- 85d7566: Let an operation emit more than one status, and a status serve more than one content type.
+
+    A status code could previously declare only one mime — the parser warned `Duplicate response body` and dropped the rest — and the generated router pinned both `ctx.status` and `ctx.type` to whichever response happened to be listed first with a body. An endpoint serving several formats had to declare one lying mime and let browsers sniff, and a service had no way to say which status it produced.
+
+    A status now holds every declared `mime: Type` line (`OpResponseNode.bodies`). When there is more than one, the service picks at runtime and the router sets `ctx.type` from the returned `contentType`. When an operation produces more than one status, the service returns a union discriminated on `status` and the handler switches on it, so each status writes only its own headers, mime and body. Both SDKs mirror the router: the TypeScript and Python clients return a matching union, report which mime came back, and pass the non-2xx statuses they expect to the shared fetch so a declared `304` no longer surfaces as an error. `SdkError` now takes a body type parameter, and each operation exports a `…ErrorBody` alias for the statuses that stay on the throw path.
+
+    Which statuses the service produces is derived from the declaration: **a status is emitted if it has a block, or is 2xx.** An empty block (`304: {}`) says the service returns that status carrying nothing; a bare `304:` says it is documented and something else produces it. `404(documented): { … }` is the one modifier, forcing a block-carrying status back out.
+
+    Two long-standing bugs in the same area go with it. The formatter deleted any comment written inside a `response` block — above a status code, above a mime line, above a `headers:` block, or before a closing brace — so `pnpm format` silently threw away the notes explaining why a contract looks the way it does; all four positions now round-trip. And the generated router declared a `_ZodBinary` helper for a binary _response_ body, which is a plain `Buffer` annotation with no schema behind it, leaving an unused const that tripped `noUnusedLocals` downstream; helpers are now chosen from the code that was actually generated, the same way imports already were.
+
+    **If you are already on a pre-release version, two things change under you.** A contract that declares a body on an error status — `404: { application/json: Problem }` alongside a `200` — now returns it from the service instead of throwing, and the SDK return type becomes a union; add `(documented)` to that status to keep the previous behaviour. Contracts whose error statuses are bodyless (`400:`, `404:`) are unaffected. Anything reading the AST directly should move from `OpResponseNode.contentType`/`bodyType` to `bodies`, which replaces them.
+
+- 90d19ee: Allow a comment above `options`, and a trailing comment on an options entry.
+
+    A `#` comment above a `contract` or `operation` has always been fine, but one above the `options` keyword was a parse error — a file header is a natural thing to write, and writing it broke the build. `OptionsBlock` now owns the leading `comment*`. It lives there rather than on `Root` deliberately: on `Root` its greedy match would swallow the doc comment above a `contract` in a file that has no options block at all.
+
+    A trailing comment on a `keys`/`services` entry was worse than unsupported: it was swallowed into the value, and because an unquoted value ends at the first `}`, a comment containing one — `# interpolated as {{area}}` — closed the block early and silently mis-parsed the rest of the file. The value now ends at whitespace-then-`#`, and the comment is retained so the formatter round-trips it. A `#` with no space before it still belongs to the value, so the unquoted subpath form (`PetService: #modules/pet/pet.service.js`) is unaffected.
+
+    The TextMate grammar had the matching gap: its unquoted-value pattern accepted identifiers only, so an unquoted subpath fell through to the comment pattern and was coloured as though the parser ignored it.
+
+    An unquoted value also stays unquoted. The AST now records which entries were authored bare, so the formatter reproduces that choice instead of normalizing every value to the quoted form. The flag is formatting-only — both forms parse to the same string — and a value that could not be read back bare is still quoted, which covers values built programmatically rather than parsed.
+
+### Patch Changes
+
+- Updated dependencies [85d7566]
+- Updated dependencies [90d19ee]
+    - @contractkit/core@0.25.0
+
+## 0.13.0
+
+### Minor Changes
+
+- 23e4beb: Fix the formatter rewriting `.ck` files it should have left alone. Running Prettier on a contract folded standalone `#` comment blocks into a trailing comment on the following declaration (`# ─── Pet endpoints ───` became `operation /pet: { # ─── Pet endpoints ───`), reordered operation body keys into a canonical order, dropped blank lines between operations, and expanded single-line response bodies like `200: { application/json: Pet }` onto three lines. An inline contract comment (`contract Pet: { # A pet`) was also attributed to the first field, so it printed twice.
+
+    The parser now records the author's layout alongside the semantics — comment placement (`leadingComments`, `descriptionInline`), operation body key order (`keyOrder`), blank lines (`blankLineBefore`), and single-line response blocks (`inline`) — and the printer reproduces it. A `#` comment separated from the declaration below it by a blank line is a standalone divider rather than a doc comment; one written directly above is a doc comment and is emitted above the declaration, not on its header line.
+
+    Comments may now also sit directly inside an `options { ... }` block, between its sub-blocks, where the grammar previously rejected them.
+
+    These AST fields are additive and optional; codegen plugins ignore them.
+
+### Patch Changes
+
+- Updated dependencies [23e4beb]
+    - @contractkit/core@0.24.0
+
 ## 0.12.2
 
 ### Patch Changes

package/README.md

@@ -33,12 +33,10 @@ Most editors with a Prettier integration (VS Code, JetBrains, Neovim) pick the p
 
 ## What it does
 
-The printer round-trips the parser's AST back into canonical `.ck` source:
+The printer round-trips the parser's AST back into `.ck` source:
 
 - 4-space indentation (matches Prettier's default `tabWidth`)
 - Canonical modifier order on fields: `override → deprecated → readonly|writeonly`
-- Stable ordering of `options` block items, route bodies, and operation blocks
-- Inline `# comment` placement preserved on field/operation/status lines
 - Multi-base inheritance: `contract C: A & B & { ... }` with the inline block always last
 - Multi-line unions: a leading `|` is preserved on type aliases like `contract X: A | B | C`
 - Discriminated unions render as `discriminated(by=field, A | B | C)`
@@ -46,6 +44,21 @@ The printer round-trips the parser's AST back into canonical `.ck` source:
 
 The plugin honours Prettier's `printWidth` for line-wrapping decisions where applicable, but most CK constructs format to a fixed multi-line shape regardless of width.
 
+## What it preserves
+
+Formatting a well-formed `.ck` file leaves it byte-identical. The formatter deliberately does **not** impose a canonical layout where the language allows more than one form — it reproduces what the author wrote:
+
+- **Comment placement.** A `#` block separated from the declaration below it by a blank line stays a standalone divider; one directly above becomes that declaration's doc comment and is re-emitted above it, not folded onto the header line. A comment written inline (`contract Pet: { # ...`) stays inline.
+- **Operation body key order.** `sdk` before `service` stays that way; the printer never sorts a user's keys into a canonical order.
+- **Blank lines** between operations inside a route.
+- **Single-line response blocks.** `200: { application/json: Pet }` is not expanded, and an expanded block is not collapsed. A status declaring several mimes on one line stays on one line too.
+- **Comments inside a `response` block**, in all four positions: above a status code, above a `mime: Type` line, above a `headers:` block, and before either closing brace.
+- **An empty status block.** `304: {}` and `304:` mean different things to codegen — the first says the service returns that status with no body — so neither is normalized into the other.
+- **Comments in the `options` block**, including a header comment above the `options` keyword and a trailing comment on a `keys`/`services` entry.
+- **Unquoted options values.** `PetService: #modules/pet/pet.service.js` stays bare and a quoted value stays quoted. Both parse to the same string, so the parser records which form was written; a value that could not be read back bare is quoted regardless.
+
+This is covered by `tests/round-trip.test.ts`, which formats every `.ck` file under `contracts/` and asserts the output is unchanged, plus checks that formatting is a fixed point. Anything that makes the printer normalize rather than preserve will fail it.
+
 ## Source layout
 
 | Path | Purpose |

package/dist/index.js

@@ -150,7 +150,7 @@ function printModelDecl(model, printWidth = 80) {
   if (model.type !== void 0) {
     return printTypeAlias(model, printWidth);
   }
-  const commentSuffix = model.description ? ` # ${model.description}` : "";
+  const commentSuffix = model.description && model.descriptionInline ? ` # ${model.description}` : "";
   const modifiers = [
     model.deprecated ? "deprecated" : "",
     model.inputCase || model.outputCase ? `format(${[
@@ -177,7 +177,7 @@ function printModelDecl(model, printWidth = 80) {
 __name(printModelDecl, "printModelDecl");
 function printTypeAlias(model, printWidth) {
   const type = model.type;
-  const commentSuffix = model.description ? ` # ${model.description}` : "";
+  const commentSuffix = model.description && model.descriptionInline ? ` # ${model.description}` : "";
   const modifiers = [
     model.deprecated ? "deprecated" : "",
     model.inputCase || model.outputCase ? `format(${[
@@ -222,8 +222,7 @@ function flushBlocks(out, blocks, idx, beforeLine, _indent = "") {
 __name(flushBlocks, "flushBlocks");
 function printRoute(route, blocks, idx, nextRouteStart) {
   const lines = [];
-  const commentSuffix = route.description ? ` # ${route.description}` : "";
-  lines.push(`${route.path}: {${commentSuffix}`);
+  lines.push(`${route.path}: {`);
   if (route.params !== void 0) {
     lines.push(...printParamsBlock(route.params, I1, route.paramsMode));
   }
@@ -231,6 +230,7 @@ function printRoute(route, blocks, idx, nextRouteStart) {
     lines.push(...printSecurity(route.security, I1, I2));
   }
   for (const op of route.operations) {
+    if (op.blankLineBefore && lines.length > 1) lines.push("");
     flushBlocks(lines, blocks, idx, op.loc.line, I1);
     lines.push(...printOperation(op));
   }
@@ -270,53 +270,131 @@ function printParamsBlock(source, indent, mode) {
   ];
 }
 __name(printParamsBlock, "printParamsBlock");
-function printOperation(op) {
-  const lines = [];
-  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}`);
+var CANONICAL_KEY_ORDER = [
+  "name",
+  "service",
+  "sdk",
+  "mcp",
+  "signature",
+  "security",
+  "plugins",
+  "query",
+  "headers",
+  "request",
+  "responses"
+];
+function printOperationKey(op, key) {
+  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 !== void 0 ? 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 !== void 0) 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 !== void 0 ? printQueryOrHeaders("query", op.query, op.queryMode) : [];
+    case "headers":
+      if (op.requestHeadersOptOut) return [
+        `${I2}headers: none`
+      ];
+      return op.headers !== void 0 ? 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}}`);
-  }
-  if (op.query !== void 0) lines.push(...printQueryOrHeaders("query", op.query, op.queryMode));
-  if (op.requestHeadersOptOut) {
-    lines.push(`${I2}headers: none`);
-  } else if (op.headers !== void 0) {
-    lines.push(...printQueryOrHeaders("headers", op.headers, op.headersMode));
+    case "responses":
+      return op.responses.length > 0 ? printResponseBlock(op.responses, op.responsesTrailingComments) : [];
   }
-  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}}`);
+}
+__name(printOperationKey, "printOperationKey");
+function printOperation(op) {
+  const lines = [];
+  const modPart = op.modifiers?.length ? `(${op.modifiers[0]})` : "";
+  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}`);
+  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;
 }
 __name(printOperation, "printOperation");
+function mcpHintTokens(mcp) {
+  const tokens = [];
+  if (mcp.readOnlyHint !== void 0) tokens.push(mcp.readOnlyHint ? "readOnly" : "nonReadOnly");
+  if (mcp.idempotentHint !== void 0) tokens.push(mcp.idempotentHint ? "idempotent" : "nonIdempotent");
+  if (mcp.destructiveHint !== void 0) tokens.push(mcp.destructiveHint ? "destructive" : "nonDestructive");
+  if (mcp.openWorldHint !== void 0) tokens.push(mcp.openWorldHint ? "openWorld" : "closedWorld");
+  return tokens;
+}
+__name(mcpHintTokens, "mcpHintTokens");
+function printMcpBlock(mcp) {
+  const lines = [
+    `${I2}mcp: {`
+  ];
+  if (mcp.name !== void 0) lines.push(`${I3}name: "${escapeString(mcp.name)}"`);
+  if (mcp.title !== void 0) lines.push(`${I3}title: "${escapeString(mcp.title)}"`);
+  if (mcp.description !== void 0) 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;
+}
+__name(printMcpBlock, "printMcpBlock");
 var IDENT_RE = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
 function escapeString(s) {
   return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
@@ -453,19 +531,29 @@ function printContentTypeLine(contentType, bodyType, lineIndent) {
   ];
 }
 __name(printContentTypeLine, "printContentTypeLine");
-function printResponseBlock(responses) {
+function printResponseBlock(responses, trailingComments) {
   const lines = [
     `${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));
+    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) {
+      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) {
+      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) {
@@ -477,11 +565,13 @@ function printResponseBlock(responses) {
         }
         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;
 }
@@ -489,15 +579,19 @@ __name(printResponseBlock, "printResponseBlock");
 
 // src/print-ck.ts
 var DEFAULT_PRINT_WIDTH = 80;
-function quoteOptionsValue(value) {
-  return /^[a-zA-Z_$][a-zA-Z0-9_$\-.]*$/.test(value) ? value : `"${value}"`;
+function quoteOptionsValue(value, wasUnquoted = false) {
+  if (/^[a-zA-Z_$][a-zA-Z0-9_$\-.]*$/.test(value)) return value;
+  const roundTripsBare = value.length > 0 && value === value.trim() && !/[\n\r}]/.test(value) && !/[ \t]#/.test(value) && !/^["']/.test(value);
+  return wasUnquoted && roundTripsBare ? value : `"${value}"`;
 }
 __name(quoteOptionsValue, "quoteOptionsValue");
-function emitOptionsEntries(lines, entries, comments) {
+function emitOptionsEntries(lines, entries, comments, unquoted) {
   const I22 = INDENT + INDENT;
+  const wasUnquoted = new Set(unquoted ?? []);
   for (const [key, value] of Object.entries(entries)) {
     for (const c of comments?.leading?.[key] ?? []) lines.push(`${I22}# ${c}`);
-    lines.push(`${I22}${key}: ${quoteOptionsValue(value)}`);
+    const inline = comments?.inline?.[key];
+    lines.push(`${I22}${key}: ${quoteOptionsValue(value, wasUnquoted.has(key))}${inline !== void 0 ? ` # ${inline}` : ""}`);
   }
   for (const c of comments?.trailing ?? []) lines.push(`${I22}# ${c}`);
 }
@@ -508,29 +602,41 @@ function printOptionsBlock(ast) {
   const hasSecurity = ast.security !== void 0;
   const hasRequestHeaders = (ast.requestHeaders?.length ?? 0) > 0;
   const hasResponseHeaders = (ast.responseHeaders?.length ?? 0) > 0;
-  if (!hasMeta && !hasServices && !hasSecurity && !hasRequestHeaders && !hasResponseHeaders) return null;
+  const hasBodyComments = ast.optionsComments?.body !== void 0;
+  if (!hasMeta && !hasServices && !hasSecurity && !hasRequestHeaders && !hasResponseHeaders && !hasBodyComments) return null;
   const lines = [
+    ...(ast.optionsComments?.leading ?? []).map((c) => `# ${c}`),
     "options {"
   ];
+  const body = ast.optionsComments?.body;
+  const emitLeading = /* @__PURE__ */ __name((scope) => {
+    for (const c of body?.leading?.[scope] ?? []) lines.push(`${INDENT}# ${c}`);
+  }, "emitLeading");
   if (hasMeta) {
+    emitLeading("keys");
     lines.push(`${INDENT}keys: {`);
-    emitOptionsEntries(lines, ast.meta, ast.optionsComments?.keys);
+    emitOptionsEntries(lines, ast.meta, ast.optionsComments?.keys, ast.optionsUnquoted?.keys);
     lines.push(`${INDENT}}`);
   }
   if (hasServices) {
+    emitLeading("services");
     lines.push(`${INDENT}services: {`);
-    emitOptionsEntries(lines, ast.services, ast.optionsComments?.services);
+    emitOptionsEntries(lines, ast.services, ast.optionsComments?.services, ast.optionsUnquoted?.services);
     lines.push(`${INDENT}}`);
   }
   if (hasRequestHeaders) {
+    emitLeading("request");
     lines.push(...printOptionsHeaderScope("request", ast.requestHeaders));
   }
   if (hasResponseHeaders) {
+    emitLeading("response");
     lines.push(...printOptionsHeaderScope("response", ast.responseHeaders));
   }
   if (hasSecurity) {
+    emitLeading("security");
     lines.push(...printSecurity(ast.security, INDENT, INDENT + INDENT));
   }
+  for (const c of body?.trailing ?? []) lines.push(`${INDENT}# ${c}`);
   lines.push("}");
   return lines.join("\n");
 }
@@ -558,7 +664,7 @@ function printCk(ast, printWidth = DEFAULT_PRINT_WIDTH) {
   if (options) parts.push(options);
   for (const model of ast.models) {
     if (parts.length > 0) parts.push("");
-    parts.push(`contract ${printModelDecl(model, printWidth)}`);
+    parts.push(printDeclLeadIn(model.leadingComments, model.descriptionInline ? void 0 : model.description) + `contract ${printModelDecl(model, printWidth)}`);
   }
   const emptyBlocks = [];
   const emptyIdx = {
@@ -567,11 +673,23 @@ function printCk(ast, printWidth = DEFAULT_PRINT_WIDTH) {
   for (const route of ast.routes) {
     if (parts.length > 0) parts.push("");
     const modPart = route.modifiers?.length ? `(${route.modifiers[0]})` : "";
-    parts.push(`operation${modPart} ${printRoute(route, emptyBlocks, emptyIdx, Infinity)}`);
+    parts.push(printDeclLeadIn(route.leadingComments, route.description) + `operation${modPart} ${printRoute(route, emptyBlocks, emptyIdx, Infinity)}`);
   }
   return parts.join("\n") + "\n";
 }
 __name(printCk, "printCk");
+function printDeclLeadIn(leadingComments, description) {
+  const lines = [];
+  if (leadingComments?.length) {
+    for (const c of leadingComments) lines.push(`# ${c}`);
+    lines.push("");
+  }
+  if (description) {
+    for (const line of description.split("\n")) lines.push(`# ${line}`);
+  }
+  return lines.length > 0 ? lines.join("\n") + "\n" : "";
+}
+__name(printDeclLeadIn, "printDeclLeadIn");
 
 // src/index.ts
 var { hardline, join } = builders;