@contractkit/prettier-plugin 0.12.1 → 0.13.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     20.80 KB
-ESM dist/index.js.map 49.78 KB
-ESM ⚡️ Build success in 150ms
+ESM dist/index.js     24.87 KB
+ESM dist/index.js.map 62.23 KB
+ESM ⚡️ Build success in 191ms
 DTS Build start
-DTS ⚡️ Build success in 3942ms
-DTS dist/index.d.ts 630.00 B
+DTS ⚡️ Build success in 4964ms
+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 (61 tests) 340ms
+ ✓ tests/print-ck.test.ts (81 tests) 676ms
+ ✓ tests/round-trip.test.ts (20 tests) 1570ms
+     ✓ formats test.ck to itself  587ms
+     ✓ formatting is a fixed point for source #0  769ms
 
- Test Files  1 passed (1)
-      Tests  61 passed (61)
-   Start at  15:55:38
-   Duration  5.72s (transform 1.85s, setup 0ms, import 4.00s, tests 340ms, environment 0ms)
+ Test Files  2 passed (2)
+      Tests  101 passed (101)
+   Start at  15:07:02
+   Duration  7.40s (transform 3.64s, setup 0ms, import 9.29s, tests 2.25s, environment 0ms)
 
  % Coverage report from v8
 -------------------|---------|----------|---------|---------|-------------------
 File               | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
 -------------------|---------|----------|---------|---------|-------------------
-All files          |   68.83 |     59.1 |   74.19 |   75.07 |                   
+All files          |   75.62 |    69.04 |   84.21 |   81.34 |                   
  indent.ts         |     100 |      100 |     100 |     100 |                   
- print-ck.ts       |   89.85 |       80 |     100 |   98.03 | 59                
- print-contract.ts |   41.93 |    30.35 |      50 |   42.85 | 10,37-68          
- ...t-operation.ts |   73.96 |    64.67 |   92.85 |   83.78 | ...74,282-293,325 
- print-type.ts     |   47.12 |    46.87 |   45.45 |   48.61 | ...10,139,142-145 
+ print-ck.ts       |   88.34 |       85 |     100 |   97.18 | 80-81             
+ print-contract.ts |   45.71 |    38.23 |      50 |   46.66 | 20,52-85          
+ ...t-operation.ts |   78.32 |    69.46 |   94.44 |   86.12 | ...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,30 @@
 # @contractkit/prettier-plugin-contractkit
 
+## 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
+
+- 2bf01f1: Preserve trailing comments instead of dropping them on format: a comment as the last line of a contract/model body, an operation/route body, an inline object type, or an options `keys`/`services` block now round-trips.
+- Updated dependencies [2bf01f1]
+    - @contractkit/core@0.23.0
+
 ## 0.12.1
 
 ### 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,17 @@ 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.
+
+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

@@ -106,7 +106,11 @@ function printField(field, indent, printWidth = 80) {
 }
 __name(printField, "printField");
 function printInlineObjectExpanded(obj, indent, printWidth = 80) {
-  return obj.fields.map((f) => printField(f, indent, printWidth));
+  const lines = obj.fields.map((f) => printField(f, indent, printWidth));
+  for (const comment of obj.trailingComments ?? []) {
+    lines.push(`${indent}# ${comment}`);
+  }
+  return lines;
 }
 __name(printInlineObjectExpanded, "printInlineObjectExpanded");
 function formatEnumValue(v) {
@@ -146,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(${[
@@ -164,13 +168,16 @@ function printModelDecl(model, printWidth = 80) {
   for (const field of model.fields) {
     lines.push(printField(field, INDENT, printWidth));
   }
+  for (const comment of model.trailingComments ?? []) {
+    lines.push(`${INDENT}# ${comment}`);
+  }
   lines.push("}");
   return lines.join("\n");
 }
 __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(${[
@@ -215,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));
   }
@@ -224,10 +230,14 @@ 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));
   }
   flushBlocks(lines, blocks, idx, nextRouteStart, I1);
+  for (const comment of route.trailingComments ?? []) {
+    lines.push(`${I1}# ${comment}`);
+  }
   lines.push("}");
   return lines.join("\n");
 }
@@ -260,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) : [];
   }
-  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, '\\"');
@@ -451,7 +539,9 @@ function printResponseBlock(responses) {
     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") {
+      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));
@@ -483,39 +573,55 @@ function quoteOptionsValue(value) {
   return /^[a-zA-Z_$][a-zA-Z0-9_$\-.]*$/.test(value) ? value : `"${value}"`;
 }
 __name(quoteOptionsValue, "quoteOptionsValue");
+function emitOptionsEntries(lines, entries, comments) {
+  const I22 = INDENT + INDENT;
+  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)}`);
+  }
+  for (const c of comments?.trailing ?? []) lines.push(`${I22}# ${c}`);
+}
+__name(emitOptionsEntries, "emitOptionsEntries");
 function printOptionsBlock(ast) {
   const hasMeta = Object.keys(ast.meta).length > 0;
   const hasServices = Object.keys(ast.services).length > 0;
   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 = [
     "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: {`);
-    for (const [key, value] of Object.entries(ast.meta)) {
-      lines.push(`${INDENT}${INDENT}${key}: ${quoteOptionsValue(value)}`);
-    }
+    emitOptionsEntries(lines, ast.meta, ast.optionsComments?.keys);
     lines.push(`${INDENT}}`);
   }
   if (hasServices) {
+    emitLeading("services");
     lines.push(`${INDENT}services: {`);
-    for (const [key, value] of Object.entries(ast.services)) {
-      lines.push(`${INDENT}${INDENT}${key}: ${quoteOptionsValue(value)}`);
-    }
+    emitOptionsEntries(lines, ast.services, ast.optionsComments?.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");
 }
@@ -543,7 +649,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 = {
@@ -552,11 +658,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;