@contractkit/openapi-to-ck 0.10.1 → 0.11.0

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

@@ -6,13 +6,13 @@ $ tsup src/index.ts src/plugin.ts --format esm --sourcemap --dts && tsc --emitDe
 CLI Target: esnext
 ESM Build start
 ESM dist/index.js              498.00 B
-ESM dist/plugin.js             2.51 KB
-ESM dist/chunk-JPI3AQ7V.js     51.50 KB
+ESM dist/plugin.js             3.28 KB
+ESM dist/chunk-Z53MK4FM.js     44.82 KB
 ESM dist/index.js.map          71.00 B
-ESM dist/plugin.js.map         4.95 KB
-ESM dist/chunk-JPI3AQ7V.js.map 120.62 KB
-ESM ⚡️ Build success in 243ms
+ESM dist/plugin.js.map         6.11 KB
+ESM dist/chunk-Z53MK4FM.js.map 111.74 KB
+ESM ⚡️ Build success in 185ms
 DTS Build start
-DTS ⚡️ Build success in 8914ms
-DTS dist/index.d.ts  9.00 KB
+DTS ⚡️ Build success in 5204ms
+DTS dist/index.d.ts  12.51 KB
 DTS dist/plugin.d.ts 128.00 B

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

@@ -3,32 +3,36 @@ $ vitest run --coverage
  RUN  v4.1.5 /home/runner/work/ContractKit/ContractKit/packages/openapi-to-ck
       Coverage enabled with v8
 
- ✓ tests/schema-to-ast.test.ts (36 tests) 123ms
- ✓ tests/normalize.test.ts (6 tests) 41ms
- ✓ tests/tag-splitter.test.ts (5 tests) 71ms
- ✓ tests/ast-to-ck.test.ts (45 tests) 243ms
- ✓ tests/convert.test.ts (17 tests) 346ms
- ✓ tests/circular-refs.test.ts (8 tests) 32ms
+ ✓ tests/schema-to-ast.test.ts (37 tests) 86ms
+ ✓ tests/ast-to-ck.test.ts (45 tests) 119ms
+ ✓ tests/convert.test.ts (17 tests) 1283ms
+ ✓ tests/coverage.test.ts (17 tests) 418ms
+ ✓ tests/normalize.test.ts (6 tests) 39ms
+ ✓ tests/component-refs.test.ts (4 tests) 67ms
+ ✓ tests/kitchen-sink.test.ts (7 tests) 996ms
+ ✓ tests/error-responses.test.ts (5 tests) 130ms
+ ✓ tests/circular-refs.test.ts (8 tests) 17ms
+ ✓ tests/tag-splitter.test.ts (5 tests) 17ms
 
- Test Files  6 passed (6)
-      Tests  117 passed (117)
-   Start at  17:32:00
-   Duration  7.22s (transform 2.75s, setup 0ms, import 9.95s, tests 857ms, environment 1ms)
+ Test Files  10 passed (10)
+      Tests  151 passed (151)
+   Start at  16:35:30
+   Duration  8.18s (transform 2.04s, setup 0ms, import 14.38s, tests 3.17s, environment 1ms)
 
  % Coverage report from v8
--------------------|---------|----------|---------|---------|-------------------------------------------------------------
-File               | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s                                           
--------------------|---------|----------|---------|---------|-------------------------------------------------------------
-All files          |    81.5 |    71.07 |   94.82 |   84.21 |                                                             
- src               |   81.27 |    71.27 |   93.68 |   83.86 |                                                             
-  ast-to-ck.ts     |   91.73 |    83.93 |     100 |   92.89 | 117-127,204,305,360,393-394,404,465                         
-  circular-refs.ts |     100 |       90 |     100 |     100 | 20-23                                                       
-  convert.ts       |   77.19 |     87.5 |      80 |   77.77 | 83-98,112-117                                               
-  normalize.ts     |   62.96 |     56.6 |      80 |   63.33 | 79,121-163,237-255,270-271,280-309,346,350,358              
-  paths-to-ast.ts  |   85.07 |    66.99 |     100 |   91.45 | 101,126,131,141-142,150,193,207,248,323                     
-  schema-to-ast.ts |   84.69 |       75 |   95.65 |   87.65 | 128-129,151,159,173,196-197,205-206,311-314,353-360,396-404 
-  tag-splitter.ts  |      70 |    55.88 |   81.81 |   76.47 | 63-71,137-138,141-146,162-163,171-178                       
-  warnings.ts      |     100 |      100 |     100 |     100 |                                                             
- tests             |   86.84 |    65.38 |     100 |   93.54 |                                                             
-  helpers.ts       |   86.84 |    65.38 |     100 |   93.54 | 139-140                                                     
--------------------|---------|----------|---------|---------|-------------------------------------------------------------
+-------------------|---------|----------|---------|---------|----------------------------------------------------------
+File               | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s                                        
+-------------------|---------|----------|---------|---------|----------------------------------------------------------
+All files          |   83.11 |    73.51 |   94.78 |   85.87 |                                                          
+ src               |   83.18 |    74.02 |   95.45 |   85.52 |                                                          
+  ast-to-ck.ts     |     100 |      100 |     100 |     100 |                                                          
+  circular-refs.ts |     100 |       90 |     100 |     100 | 20-23                                                    
+  convert.ts       |   79.01 |    78.78 |   88.88 |   81.08 | 123-124,137-152,166-171                                  
+  normalize.ts     |   67.52 |     61.2 |   85.71 |   67.59 | 67-68,80,155,197-239,313-331,346-347,356-385,422,426,434 
+  paths-to-ast.ts  |   90.68 |    77.23 |     100 |   96.45 | 130,158,168,246,260                                      
+  schema-to-ast.ts |   89.41 |    80.81 |     100 |   92.21 | 150-151,173,181,195,218-219,227-228,375-382              
+  tag-splitter.ts  |   85.71 |    78.94 |    90.9 |   89.02 | 71,153-154,167-168,179-183                               
+  warnings.ts      |     100 |      100 |     100 |     100 |                                                          
+ tests             |   82.14 |     64.7 |   92.59 |   91.11 |                                                          
+  helpers.ts       |   82.14 |     64.7 |   92.59 |   91.11 | 142-143,179,184                                          
+-------------------|---------|----------|---------|---------|----------------------------------------------------------

package/CHANGELOG.md

@@ -1,5 +1,122 @@
 # @contractkit/openapi-to-ck
 
+## 0.11.0
+
+### Minor Changes
+
+- 7b3b270: Import 4xx/5xx responses that declare a body as `(documented)`
+
+    **This changes the output of re-running the importer.** OpenAPI cannot say whether a handler
+    _returns_ a status or merely documents it, but `.ck` distinguishes the two and every generator
+    depends on the answer. Every declared status used to be imported as service-produced: a spec
+    declaring `404: {application/json: Error}` became `404: { … }`, which made the generated Koa
+    handler responsible for returning the 404 and made the TypeScript and Python SDKs hand it back
+    as a value rather than throwing.
+
+    A bodied 4xx or 5xx now imports as `404(documented): { … }` — the body is the error contract, the
+    SDK throws it as an `SdkError`, and the service is not responsible for producing it. 2xx and 3xx
+    are unchanged, as is a bare bodyless error status (marking those would be redundant, and core
+    warns about it).
+
+    Pass `errorResponses: 'emitted'`, or `--error-responses emitted` on the command line, to restore
+    the previous behaviour.
+
+    Also in this release:
+    - `$ref`s to `#/components/parameters`, `requestBodies`, `responses` and `headers` are now
+      resolved. A `$ref`'d parameter previously reached the printer with no name and emitted
+      `undefined: string` — which parses, so nothing reported it. Anything still unresolvable is
+      warned about and skipped instead of emitted.
+    - Every generated file is re-parsed before it is returned, and a file that does not parse is
+      reported as a warning rather than written out silently.
+    - The command line gained `--no-comments`, which was documented but never implemented.
+
+    Coverage, in the same release:
+    - `name:` is imported from an operation's `summary`, which used to be dropped entirely.
+    - Request bodies keep any RFC 6838 `type/subtype` content type. The importer previously allowed
+      only JSON, form-urlencoded and multipart, silently discarding everything else, even though the
+      grammar has accepted any mime since vendor MIME support landed.
+    - `format: duration` maps to the `duration` scalar, and the `idn-email`, `uri-reference`, `iri`
+      and `iri-reference` formats map alongside their existing counterparts.
+    - `additionalProperties: true` imports as `mode(loose)`.
+    - A spec-level `security` requirement now applies to operations that do not override it; it was
+      collected and never read, so a globally unsecured spec imported as secured.
+    - Constructs with no `.ck` equivalent are warned about rather than dropped in silence: `head`,
+      `options` and `trace` operations, non-numeric response keys (`default`, `4XX`), cookie
+      parameters, unparameterised mime types, and the `exclusiveMinimum`, `exclusiveMaximum`,
+      `multipleOf` and `uniqueItems` constraints. A `4XX` response key previously became status `4`,
+      because `parseInt` stops at the first non-digit.
+
+### Patch Changes
+
+- fd62377: Fix tag splitting, schema-name sanitization, and stale docs
+    - A model reached only from a `params`, `query` or `headers` block was filed under `shared.ck`
+      instead of its own tag's file. `collectParamSourceRefs` was written against the shape
+      `ParamSource` had before it became a tagged union, so only the `ref` case still worked — and
+      only by coincidence, since it happens to look like a model reference.
+    - A schema whose name starts with a digit (`3DModel`) produced an identifier the parser rejects.
+      It is now prefixed with `_`.
+    - `@scalar/openapi-parser` has been removed from the dependencies. It was never imported; the
+      normalization is hand-written, despite a comment claiming otherwise.
+    - The README documented an `openapi-to-ck --input …` command that does not exist. The command is
+      `import-openapi <spec-path>`, and the docs now cover `--no-comments`, `--error-responses`, and
+      what the converter warns about rather than dropping silently.
+
+- 841af6e: Only wrap a circular reference in `lazy()` where it breaks a real cycle
+
+    `lazy()` exists so that a reference between two contracts that depend on each other can be
+    deferred: `topoSortModels` emits dependencies before dependents and can only fall back to source
+    order for a cycle. A reference from an operation — a response body, request body, parameter, or
+    response header — names a model the generated module has already imported and fully evaluated,
+    so there is no cycle to break.
+
+    Every reference to a self-referential schema used to be wrapped, so importing a spec with a tree-
+    shaped model produced `application/json: lazy(Widget)` on every body mentioning it. References
+    inside a contract, including one extracted from an inline body schema, still wrap as before.
+
+    Also fixed: a model extracted from an inline request or response body schema was referenced by
+    the generated operation and never emitted, because the extracted-model list was read before path
+    conversion filled it. Any spec with an inline (non-`$ref`) body schema produced a contract
+    pointing at something that did not exist. The post-conversion self-check now runs reference
+    validation as well as parsing, which is what caught it — a reference to an undefined contract is
+    perfectly good syntax, so parsing alone could not.
+
+- aea5e21: Move the `.ck` printer into core, so the language has exactly one
+
+    `.ck` had two printers: the prettier plugin's `printCk` and a hand-rolled one inside
+    `openapi-to-ck`. Only the prettier copy was covered by the round-trip tests that the grammar
+    checklist points at, so the other silently fell behind the grammar — it ignored `hasBlock` and
+    the `(documented)` response modifier, could not emit `mcp:`, `plugins:`, `name:`, `override`,
+    `format(output=)` or options-level header globals, and emitted source that does not parse for a
+    regex containing `/` or an enum value carrying both quote styles.
+
+    `printCk` now lives in `@contractkit/core` next to `parseCk` and is exported from it. The
+    prettier plugin re-exports it unchanged, and `openapi-to-ck`'s `astToCk` is a thin adapter over
+    it, so all of the above now print correctly.
+
+    Three printing fixes come with the move, all of which affect `pnpm format` on existing files:
+    - A regex containing `/` prints as `regex="…"` instead of an unterminated regex literal.
+    - A string containing `"` prints single-quoted; one carrying both quote styles is degraded
+      rather than emitted unparseable (use the new `isUnquotable` to warn before printing).
+    - A description containing newlines is flattened when it prints as a trailing `# …` comment,
+      instead of leaking the remainder as raw source.
+
+    Files containing any of these currently cannot round-trip at all, so this is a fix rather than a
+    break. `openapi-to-ck` output changes shape in two ways: model descriptions now print as a
+    doc-comment block above the `contract` rather than as a trailing comment, and scalar constraints
+    use the canonical `len=` / positional `format` spellings.
+
+- Updated dependencies [aea5e21]
+- Updated dependencies [5dc2693]
+    - @contractkit/core@0.27.0
+
+## 0.10.2
+
+### Patch Changes
+
+- ca1c139: Declare the MIT license explicitly: every package now ships a `LICENSE` file in its published tarball and sets `"license": "MIT"` in its manifest, so license scanners and registries report the terms correctly.
+- Updated dependencies [ca1c139]
+    - @contractkit/core@0.26.1
+
 ## 0.10.1
 
 ### Patch Changes

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marooned Software
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -10,18 +10,19 @@ pnpm add -D @contractkit/openapi-to-ck
 
 ## Use as a CLI subcommand
 
-When the package is installed, the `@contractkit/cli` binary picks up an `openapi-to-ck` subcommand:
+When the package is installed, the `@contractkit/cli` binary picks up an `import-openapi` subcommand. The spec path is a positional argument:
 
 ```bash
-contractkit openapi-to-ck --input openapi.yaml --output contracts/
+contractkit import-openapi openapi.yaml --output contracts/
 ```
 
 | Flag | Description |
 | --- | --- |
-| `--input <path>` | Path to an OpenAPI YAML or JSON file. |
-| `--output <dir>` | Directory to write `.ck` files into. |
+| `<spec-path>` | Positional. Path to an OpenAPI YAML or JSON file. |
+| `-o, --output <dir>` | Directory to write `.ck` files into. Defaults to the current directory. |
 | `--split <single \| by-tag>` | Output mode. `by-tag` (default) writes one file per OpenAPI tag; `single` writes one combined file. |
 | `--no-comments` | Don't emit OpenAPI descriptions as `#` comments. |
+| `--error-responses <documented \| emitted>` | How to import a 4xx/5xx that declares a body. See [Error responses](#error-responses). |
 
 ## Programmatic use
 
@@ -32,6 +33,7 @@ const { files, warnings } = await convertOpenApiToCk({
     input: 'openapi.yaml',          // file path, JSON/YAML string, or pre-parsed object
     split: 'by-tag',                // 'single' | 'by-tag'  (default: 'by-tag')
     includeComments: true,          // emit OpenAPI descriptions as # comments (default: true)
+    errorResponses: 'documented',   // 'documented' | 'emitted'  (default: 'documented')
     onWarning: w => console.warn(w),
 });
 
@@ -41,7 +43,17 @@ for (const [filename, source] of files) {
 }
 ```
 
-`Warning` entries carry a JSON-pointer-style `path` into the OpenAPI spec, a human-readable `message`, and a `severity` of `'info' | 'warn'`.
+`Warning` entries carry a JSON-pointer-style `path` into the OpenAPI spec, a human-readable `message`, and a `severity` of `'info' | 'warn'`. Anything the spec declares that `.ck` cannot express is reported this way rather than dropped in silence — `head`/`options`/`trace` operations, non-numeric response keys such as `default` or `4XX`, cookie parameters, content types that are not a plain `type/subtype`, and the `exclusiveMinimum`, `exclusiveMaximum`, `multipleOf` and `uniqueItems` constraints. Every generated file is also re-parsed before it is returned, so output that would not compile arrives as a warning instead of as a broken file on disk.
+
+## Error responses
+
+OpenAPI cannot say whether a service *produces* a status or merely documents it. `.ck` draws that distinction, and it decides what the generated router writes and whether the SDKs return a status or throw it.
+
+By default a 4xx or 5xx that declares a body is imported as `404(documented): { ... }`: the body is the error contract, the SDKs throw it as an `SdkError`, and the service is not responsible for returning it. 2xx and 3xx are imported as service-produced, as is a bare bodyless error status — marking those would be redundant.
+
+Pass `errorResponses: 'emitted'` to import every declared status as service-produced instead.
+
+A spec generated by `@contractkit/plugin-openapi` carries `x-contractkit-emit` on responses that were marked `(documented)`, and that is honoured ahead of the status-code default — so a `.ck` → OpenAPI → `.ck` round trip preserves the distinction exactly, including on a 2xx.
 
 ## What's converted
 
@@ -53,7 +65,13 @@ for (const [filename, source] of files) {
 | `requestBody.content[mime].schema` | `request: { mime: Type }` |
 | `responses[code].content[mime].schema` | `response: { code: { mime: Type } }` |
 | `responses[code].headers` | per-status `headers: { name: type }` |
-| `allOf` | `&` intersection on `contract` declarations |
+| `responses[code]` for a bodied 4xx/5xx | `code(documented): { ... }` (see [Error responses](#error-responses)) |
+| `summary` | `name:` |
+| `operationId` | `sdk:` |
+| `deprecated` | `get(deprecated)` |
+| `security: []`, at spec or operation level | `security: none` |
+| `additionalProperties: true` | `mode(loose)` |
+| `allOf` | `&` inheritance on `contract` declarations |
 | `oneOf` + `discriminator` | `discriminated(by=field, A \| B)` |
 | `oneOf` / `anyOf` (no discriminator) | `\|` union |
 | `enum`, `pattern`, `minimum/maximum`, `minLength/maxLength` | type constraint args |
@@ -71,8 +89,12 @@ import {
     detectCircularRefs,     // find $ref cycles
     extractRefName,         // "#/components/schemas/Foo" → "Foo"
     sanitizeName,           // turn an arbitrary string into a valid CK identifier
-    normalize,              // upgrade 2.0/3.0 → 3.1 + dereference
-    astToCk,                // ContractKit AST → `.ck` source string
+    normalize,              // upgrade 2.0/3.0 → 3.1 + inline non-schema component $refs
+    astToCk,                // ContractKit AST → `.ck` source string (delegates to core's printCk)
     serializeType,          // ContractTypeNode → `.ck` type expression
 } from '@contractkit/openapi-to-ck';
 ```
+
+`astToCk` and `serializeType` are thin adapters over `printCk` and `printType` from
+`@contractkit/core`. `.ck` has one printer, shared with the prettier plugin, so a grammar change
+lands in one place; call the core functions directly if you have no reason to go through here.

package/dist/ast-to-ck.d.ts

@@ -1,22 +1,38 @@
-import type { CkRootNode, ContractTypeNode } from '@contractkit/core';
-/** Options controlling how a {@link CkRootNode} is rendered to `.ck` source. */
+import type { CkRootNode } from '@contractkit/core';
+import { printType } from '@contractkit/core';
+/**
+ * `.ck` serialization for the OpenAPI importer.
+ *
+ * This module used to carry its own printer. `.ck` had two of them — this one and the prettier
+ * plugin's — and only the prettier copy was covered by the round-trip tests that the
+ * `ck-grammar-change` checklist points at, so this one silently fell behind the grammar: it
+ * ignored `hasBlock` and the `(documented)` response modifier, could not emit `mcp:`,
+ * `plugins:`, `name:`, `override`, `format(output=)` or options-level header globals, and
+ * emitted unparseable source for a regex containing `/` or an enum value containing both quote
+ * styles.
+ *
+ * The printer now lives in `@contractkit/core` next to `parseCk`, and this module is a thin
+ * adapter over it. A grammar change has one printer to update.
+ */
+/**
+ * Options controlling how a {@link CkRootNode} is rendered to `.ck` source.
+ *
+ * @deprecated `includeComments` is a no-op and is kept only so existing callers still compile.
+ * Comments are controlled upstream: `ConvertOptions.includeComments` gates every `description`
+ * assignment in `schema-to-ast.ts` and `paths-to-ast.ts`, so when it is off the descriptions are
+ * absent from the AST and there is nothing left for the printer to suppress.
+ */
 export interface SerializeOptions {
-    /** Emit descriptions as inline # comments. Default: true. */
+    /** No-op. See the deprecation note on {@link SerializeOptions}. */
     includeComments?: boolean;
 }
 /**
- * Serialize a `.ck` AST back to formatted `.ck` source text. Emits the options
- * block first, then every model, then every route, separated by blank lines and
- * terminated with a trailing newline. Descriptions become trailing `# ...`
- * comments unless `options.includeComments` is `false`. The output is designed
- * to re-parse cleanly via `parseCk` (see round-trip tests).
- */
-export declare function astToCk(root: CkRootNode, options?: SerializeOptions): string;
-/**
- * Serialize a single {@link ContractTypeNode} to its inline `.ck` type
- * expression (e.g. `array(User, min=1)`, `string | int`, `enum(asc, desc)`).
- * Recurses through composite types; enum values are quoted as needed via
- * {@link quoteEnumValue}.
+ * Serialize a `.ck` AST back to formatted `.ck` source text.
+ *
+ * Delegates to `printCk`, which prints from a `CkRootNode` alone — no Ohm CST and no original
+ * source — so programmatically built nodes print correctly.
  */
-export declare function serializeType(type: ContractTypeNode): string;
+export declare function astToCk(root: CkRootNode, _options?: SerializeOptions): string;
+/** Render a `ContractTypeNode` to its `.ck` source string. Re-exported from core. */
+export declare const serializeType: typeof printType;
 //# sourceMappingURL=ast-to-ck.d.ts.map

package/dist/ast-to-ck.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ast-to-ck.d.ts","sourceRoot":"","sources":["../src/ast-to-ck.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,UAAU,EAGV,gBAAgB,EAUnB,MAAM,mBAAmB,CAAC;AAiC3B,gFAAgF;AAChF,MAAM,WAAW,gBAAgB;IAC7B,6DAA6D;IAC7D,eAAe,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,GAAE,gBAAqB,GAAG,MAAM,CAoBhF;AAkID;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM,CA2B5D"}
+{"version":3,"file":"ast-to-ck.d.ts","sourceRoot":"","sources":["../src/ast-to-ck.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAW,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEvD;;;;;;;;;;;;;GAaG;AAEH;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC7B,mEAAmE;IACnE,eAAe,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,GAAE,gBAAqB,GAAG,MAAM,CAEjF;AAED,qFAAqF;AACrF,eAAO,MAAM,aAAa,kBAAY,CAAC"}