@haddowg/json-api-codegen 1.5.0 → 1.6.1

package/dist/cli.d.mts

@@ -1,4 +1,4 @@
-import { r as CodegenConfig } from "./index-B0BIVXUz.mjs";
+import { r as CodegenConfig } from "./index-CjNGhJJH.mjs";
 
 //#region src/cli.d.ts
 declare const USAGE = "Usage: json-api-codegen --input <url|file> --output <file> [--server <name>] [--schemas <url|file>] [--check]";

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { n as generate, r as schemasOutputPath, t as check } from "./src-G1x-BbMp.mjs";
+import { n as generate, r as schemasOutputPath, t as check } from "./src-CKsM7dXw.mjs";
 import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 //#region src/cli.ts

package/dist/{index-B0BIVXUz.d.mts → index-CjNGhJJH.d.mts}

@@ -77,12 +77,11 @@ interface OpenApiDocument {
 //#endregion
 //#region src/build-descriptor.d.ts
 declare class DescriptorBuilder {
-  private readonly doc;
   private readonly schemas;
   private readonly paths;
   /** Lazily-built wire-type -> collection-level paginator kind (for per-relation divergence, D6a). */
   private typePaginators?;
-  constructor(doc: OpenApiDocument);
+  constructor(source: OpenApiDocument);
   /**
    * The collection-level paginator kind for a WIRE type (`tracks`), memoised. Resolves each
    * resource schema's wire type (its `type.const`) to the paginator of its collection GET — the
@@ -261,7 +260,7 @@ declare function buildAtomic(doc: OpenApiDocument): AtomicDescriptor | null;
 /** Below this the document predates the structures this codegen reads. */
 declare const MINIMUM_CONTRACT = 1;
 /** Above this the document carries structures this codegen does not read. */
-declare const MAXIMUM_CONTRACT = 8;
+declare const MAXIMUM_CONTRACT = 9;
 /**
  * Check the document's `info.x-generator.contract` against the range this codegen reads. A
  * document older than the range throws; a newer one returns a warning, because its new
@@ -282,7 +281,6 @@ interface VerbCollision {
  */
 declare function detectVerbCollisions(descriptor: ApiDescriptor): VerbCollision[];
 declare class Emitter {
-  private readonly doc;
   private readonly descriptor;
   private readonly atomic;
   private readonly schemas;
@@ -297,6 +295,10 @@ declare class Emitter {
    * already-named attribute type. Populated as interfaces are emitted.
    */
   private readonly emittedInterfaces;
+  /** Enum component name -> the alias name it's emitted under. */
+  private readonly enumNames;
+  /** Type names already spoken for: the module's own, the per-type interfaces and enum aliases. */
+  private readonly takenNames;
   /** Component names mid-expansion in {@link tsType} — a cycle guard for self/mutually-referential `$ref`s. */
   private readonly expanding;
   /**
@@ -307,7 +309,13 @@ declare class Emitter {
   private readonly actionAliasNames;
   /** Provenance of the source document, stamped into the generated header for drift tracking. */
   private readonly provenance;
-  constructor(doc: OpenApiDocument, descriptor: ApiDescriptor, atomic: AtomicDescriptor | null);
+  private readonly doc;
+  constructor(source: OpenApiDocument, descriptor: ApiDescriptor, atomic: AtomicDescriptor | null);
+  /**
+   * The alias an enum component is emitted under: its own name when that's a usable type name,
+   * else one derived from it (with a warning), kept clear of every other name in the module.
+   */
+  private enumName;
   /** Map each declared wire type back to the `Base` of its resource schema. */
   private indexBases;
   emit(): string;
@@ -503,7 +511,7 @@ declare function hashJson(value: unknown): string;
 declare function deriveProvenance(doc: OpenApiDocument): Provenance;
 /**
  * Render the provenance record as the JSDoc header lines stamped into a generated artifact
- * (each already prefixed with ` * `). Deterministic: no timestamp, so re-generating from the
+ * (each already prefixed with ` * `), with the document's text kept to one comment line. Deterministic: no timestamp, so re-generating from the
  * same spec yields byte-identical output.
  */
 declare function provenanceLines(provenance: Provenance): string[];
@@ -566,4 +574,4 @@ declare function generate(config: CodegenConfig): Promise<string>;
 declare function check(config: CodegenConfig): Promise<CheckResult>;
 //#endregion
 export { InfoObject as A, MAXIMUM_CONTRACT as C, buildAtomic as D, DescriptorBuilder as E, PathItemObject as F, RequestBodyObject as I, ResponseObject as L, OpenApiDocument as M, OperationObject as N, buildDescriptor as O, ParameterObject as P, SchemaObject as R, emit as S, checkContract as T, emitErrorCodes as _, generate as a, VerbCollision as b, deriveProvenance as c, emitSchemas as d, SchemaBundle as f, ErrorCatalogue as g, DocumentedErrorCode as h, check as i, MediaTypeObject as j, HttpMethod as k, hashJson as l, readSchemas as m, CheckResult as n, schemasOutputPath as o, readDocument as p, CodegenConfig as r, Provenance as s, ArtifactDrift as t, provenanceLines as u, readErrorCatalogue as v, MINIMUM_CONTRACT as w, detectVerbCollisions as x, Emitter as y, SchemaOrBool as z };
-//# sourceMappingURL=index-B0BIVXUz.d.mts.map
+//# sourceMappingURL=index-CjNGhJJH.d.mts.map

package/dist/index-CjNGhJJH.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-CjNGhJJH.d.mts","names":[],"sources":["../src/openapi.ts","../src/build-descriptor.ts","../src/contract.ts","../src/emit.ts","../src/error-codes.ts","../src/reader.ts","../src/emit-schemas.ts","../src/provenance.ts","../src/index.ts"],"mappings":";;;;;;AAQA;;;;UAAiB,YAAA;EACf,IAAA;EACA,IAAA;EACA,KAAA;EACA,MAAA;EACA,WAAA;EACA,IAAA;EACA,UAAA,GAAa,MAAA,SAAe,YAAA;EAC5B,KAAA,GAAQ,YAAA;EACR,QAAA;EACA,KAAA,YAAiB,YAAA;EACjB,KAAA,YAAiB,YAAA;EACjB,KAAA,YAAiB,YAAA;EACjB,iBAAA;EACA,qBAAA;EAAA,CACC,GAAA;AAAA;;KAIS,YAAA,GAAe,YAAY;AAAA,UAEtB,eAAA;EACf,MAAA,GAAS,YAAY;AAAA;AAAA,UAGN,iBAAA;EACf,OAAA,GAAU,MAAM,SAAS,eAAA;EACzB,QAAA;AAAA;AAAA,UAGe,cAAA;EACf,OAAA,GAAU,MAAM,SAAS,eAAA;AAAA;AAAA,UAGV,eAAA;EACf,IAAA;EACA,EAAA;EACA,IAAA;EACA,MAAA,GAAS,YAAY;EACrB,KAAA;EACA,OAAA;EAnB8B;EAqB9B,WAAA;AAAA;AAAA,UAGe,eAAA;EACf,WAAA;EACA,UAAA,YAAsB,eAAA;EACtB,WAAA,GAAc,iBAAA;EACd,SAAA,GAAY,MAAA,SAAe,cAAA;AAAA;AAAA,KAGjB,UAAA;AAAA,KAEA,cAAA,GAAiB,OAAA,CAAQ,MAAA,CAAO,UAAA,EAAY,eAAA;AAAA,UAEvC,UAAA;EACf,KAAA;EACA,OAAA;EA5Be;EA8Bf,aAAA;IAAkB,QAAA;EAAA;AAAA;AAAA,UAGH,eAAA;EACf,OAAA;EACA,IAAA,GAAO,UAAA;EACP,OAAA;IAAqB,GAAA;EAAA;EACrB,KAAA,GAAQ,MAAA,SAAe,cAAA;EACvB,UAAA;IACE,OAAA,GAAU,MAAA,SAAe,YAAA;EAAA;AAAA;;;cCFhB,iBAAA;EAAA,iBACM,OAAA;EAAA,iBACA,KAAA;;UAET,cAAA;cAEI,MAAA,EAAQ,eAAA;EDjEZ;;;;;EAAA,QC4EA,aAAA;EAaR,KAAA,IAAS,aAAA;ED/FT;;;;;ECwJA,WAAA,IAAe,gBAAA;EDnJF;;;;;EAAA,QCkKL,YAAA;ED/JS;EAAA,QC2KT,YAAA;EAAA,QASA,UAAA;EDlLR;;;;;;AAGY;EAHZ,QCwMQ,SAAA;EDjMc;;;AAAe;EAAf,QC+Pd,kBAAA;ED7PsB;;;AACT;AAGvB;;EAJgC,QCoRtB,iBAAA;ED/QQ;;;;;;AACR;EADQ,QC4TR,iBAAA;EDxTqB;;;;;;;AACW;AAG1C;;EAJ+B,QC2VrB,oBAAA;EDnVa;;;;;;;EAAA,QCiZb,OAAA;ED7YR;;AAAW;AAGb;;EAHE,QCudQ,eAAA;EDldc;EAAA,QCued,SAAA;EDremB;EAAA,QC8enB,iBAAA;ED9eU;EAAA,QC4fV,qBAAA;ED/fR;;;;;EAAA,QC8kBQ,UAAA;ED3kBI;;;AAA6B;AAG3C;;;EAHc,QC0lBJ,eAAA;EDvlBY;EAAA,QC8nBZ,cAAA;ED5nBgB;EAAA,QCyoBhB,cAAA;EAAA,QAaA,QAAA;EDtpB8C;;;;;EAAA,QCuqB9C,cAAA;EAAA,QAmCA,cAAA;ED1sBkC;EAAA,QCguBlC,cAAA;EAAA,QAWA,mBAAA;ED3uB6D;EAAA,QCmvB7D,SAAA;EDjvBiB;;;;;;;EAAA,QC6vBjB,WAAA;EDzvBkB;AAG5B;;;;;;EAH4B,QCuyBlB,WAAA;ED9xBI;;;;;;;;;;;;;EAAA,QCo0BJ,SAAA;EDp0BmB;;AAAY;;;;ACFzC;;;EDE6B,QCo1BnB,UAAA;EAxzBC;;;;;EAAA,QAq0BD,QAAA;EA/1BA;;;;;;EAAA,QA62BA,UAAA;EAAA,QAeA,SAAA;EAAA,QAIA,cAAA;EAAA,QAIA,aAAA;AAAA;;iBAiMM,eAAA,CAAgB,GAAA,EAAK,eAAA,GAAkB,aAAa;;iBAKpD,WAAA,CAAY,GAAA,EAAK,eAAA,GAAkB,gBAAgB;;;;cCtpCtD,gBAAA;AFKb;AAAA,cEFa,gBAAA;;;;;;;iBAQG,aAAA,CAAc,GAAoB,EAAf,eAAe;;;;UCOjC,aAAA;EACf,IAAA;EACA,QAAQ;AAAA;;;;;iBAsBM,oBAAA,CAAqB,UAAA,EAAY,aAAA,GAAgB,aAAa;AAAA,cA8IjE,OAAA;EAAA,iBAoCQ,UAAA;EAAA,iBACA,MAAA;EAAA,iBApCF,OAAA;EHjLjB;EAAA,iBGmLiB,UAAA;EHjLjB;EAAA,iBGmLiB,SAAA;EHjLjB;;;;;;EAAA,iBGwLiB,iBAAA;EHrLA;EAAA,iBGuLA,SAAA;EHtLA;EAAA,iBGwLA,UAAA;EHvLA;EAAA,iBGyLA,SAAA;EHvLjB;;;AACY;AAId;EALE,iBG6LiB,gBAAA;;mBAMA,UAAA;EAAA,iBAEA,GAAA;cAGf,MAAA,EAAQ,eAAA,EACS,UAAA,EAAY,aAAA,EACZ,MAAA,EAAQ,gBAAA;EHnMG;;;AACT;EADS,QG0NtB,QAAA;EHtNwB;EAAA,QGgPxB,UAAA;EAcR,IAAA;EAAA,QA+BQ,MAAA;EAAA,QAWA,OAAA;EHvSiB;EAAA,QGoTjB,kBAAA;EHnTA;AAAA;AAGV;;;;;EAHU,QGmUA,wBAAA;EH/TiB;;AAAe;AAG1C;;;;EAH2B,QGuWjB,iBAAA;EHlWR;;;;;;;;EAAA,QG4YQ,cAAA;EHnYO;;;;;;;;;;EAAA,QGuaP,cAAA;EHrac;EAAA,QGobd,WAAA;EHnbM;;;;;AAC2B;EAD3B,QGocN,eAAA;EHhcY;EAAA,QGseZ,gBAAA;EHteY;AAAA;AAEtB;;;EAFsB,QGmgBZ,eAAA;EHjgB8C;EAAA,QG2hB9C,MAAA;EH3hBmB;EAAA,QG4kBnB,UAAA;EAAA,QAaA,iBAAA;EHzlBmB;EAAA,QGknBnB,UAAA;EAAA,QAoBA,SAAA;EHtoB8C;EAAA,QGipB9C,WAAA;EHjpB6D;AAEvE;;;;EAFuE,QGwqB7D,OAAA;EHpqBR;;;;AAE0B;AAG5B;EALE,QGqrBQ,aAAA;;;;;;;UAaA,kBAAA;EHvrBU;EAAA,QGitBV,WAAA;EHrtBR;EAAA,QG2tBQ,OAAA;EAAA,QA0BA,YAAA;AAAA;;;;;iBAwBM,IAAA,CACd,GAAA,EAAK,eAAA,EACL,UAAA,EAAY,aAAA,EACZ,MAAA,GAAQ,gBAAA;;;;UCl1BO,mBAAA;EACf,IAAA;EJA2B;EIE3B,WAAA;EJK4B;EIH5B,QAAA;AAAA;;UAIe,cAAA;EJIE;EIFjB,KAAA,EAAO,mBAAA;EJEsB;;;;EIG7B,QAAA,EAAU,GAAG;AAAA;;;;;;;iBAuCC,kBAAA,CAAmB,GAAA,EAAK,eAAA,GAAkB,cAAc;;;;;;;;iBAiFxD,cAAA,CAAe,SAAyB,EAAd,cAAc;;;;KCzI5C,YAAA,GAAe,MAAM,SAAS,YAAA;;;;;iBA+CpB,YAAA,CAAa,KAAA,WAAgB,OAAO,CAAC,eAAA;;;;;;iBASrC,WAAA,CAAY,KAAA,WAAgB,OAAO,CAAC,YAAA;;;;;ALtD1D;;;;;;;;;;;;;iBMUgB,WAAA,CAAY,MAAoB,EAAZ,YAAY;;;;;ANVhD;;;;UOEiB,UAAA;EPMP;EAAA,SOJC,MAAA;EPOQ;EAAA,SOLR,MAAA;EPMoB;EAAA,SOJpB,IAAA;AAAA;;iBAwBK,QAAA,CAAS,KAAc;;;;;;iBAYvB,gBAAA,CAAiB,GAAA,EAAK,eAAA,GAAkB,UAAU;;;;;;iBAelD,eAAA,CAAgB,UAAsB,EAAV,UAAU;;;UCjCrC,aAAA;ERjBf;EQmBA,KAAA;ERlBiB;EQoBjB,MAAA;ERnBiB;EQqBjB,MAAA;ERpBiB;EQsBjB,OAAA;ERpBA;;;AACY;AAId;EQqBE,KAAA;AAAA;;UAIe,aAAA;ERvBA;EQyBf,IAAA;;EAEA,QAAQ;AAAA;ARvBV;AAAA,UQ2BiB,WAAA;EACf,EAAA;EACA,SAAA,EAAW,aAAa;AAAA;;;;;iBAOV,iBAAA,CAAkB,MAAc;AR/BhD;;;;;;;;AAC0C;AAG1C;;;;;AAJA,iBQmGsB,QAAA,CAAS,MAAA,EAAQ,aAAA,GAAgB,OAAO;;;;;;;iBAgBxC,KAAA,CAAM,MAAA,EAAQ,aAAA,GAAgB,OAAA,CAAQ,WAAA"}

package/dist/index.d.mts

@@ -1,2 +1,2 @@
-import { A as InfoObject, C as MAXIMUM_CONTRACT, D as buildAtomic, E as DescriptorBuilder, F as PathItemObject, I as RequestBodyObject, L as ResponseObject, M as OpenApiDocument, N as OperationObject, O as buildDescriptor, P as ParameterObject, R as SchemaObject, S as emit, T as checkContract, _ as emitErrorCodes, a as generate, b as VerbCollision, c as deriveProvenance, d as emitSchemas, f as SchemaBundle, g as ErrorCatalogue, h as DocumentedErrorCode, i as check, j as MediaTypeObject, k as HttpMethod, l as hashJson, m as readSchemas, n as CheckResult, o as schemasOutputPath, p as readDocument, r as CodegenConfig, s as Provenance, t as ArtifactDrift, u as provenanceLines, v as readErrorCatalogue, w as MINIMUM_CONTRACT, x as detectVerbCollisions, y as Emitter, z as SchemaOrBool } from "./index-B0BIVXUz.mjs";
+import { A as InfoObject, C as MAXIMUM_CONTRACT, D as buildAtomic, E as DescriptorBuilder, F as PathItemObject, I as RequestBodyObject, L as ResponseObject, M as OpenApiDocument, N as OperationObject, O as buildDescriptor, P as ParameterObject, R as SchemaObject, S as emit, T as checkContract, _ as emitErrorCodes, a as generate, b as VerbCollision, c as deriveProvenance, d as emitSchemas, f as SchemaBundle, g as ErrorCatalogue, h as DocumentedErrorCode, i as check, j as MediaTypeObject, k as HttpMethod, l as hashJson, m as readSchemas, n as CheckResult, o as schemasOutputPath, p as readDocument, r as CodegenConfig, s as Provenance, t as ArtifactDrift, u as provenanceLines, v as readErrorCatalogue, w as MINIMUM_CONTRACT, x as detectVerbCollisions, y as Emitter, z as SchemaOrBool } from "./index-CjNGhJJH.mjs";
 export { ArtifactDrift, CheckResult, CodegenConfig, DescriptorBuilder, type DocumentedErrorCode, Emitter, type ErrorCatalogue, type HttpMethod, type InfoObject, MAXIMUM_CONTRACT, MINIMUM_CONTRACT, type MediaTypeObject, type OpenApiDocument, type OperationObject, type ParameterObject, type PathItemObject, type Provenance, type RequestBodyObject, type ResponseObject, type SchemaBundle, type SchemaObject, type SchemaOrBool, type VerbCollision, buildAtomic, buildDescriptor, check, checkContract, deriveProvenance, detectVerbCollisions, emit, emitErrorCodes, emitSchemas, generate, hashJson, provenanceLines, readDocument, readErrorCatalogue, readSchemas, schemasOutputPath };

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { _ as checkContract, a as readSchemas, b as buildDescriptor, c as detectVerbCollisions, d as hashJson, f as provenanceLines, g as MINIMUM_CONTRACT, h as MAXIMUM_CONTRACT, i as readDocument, l as emit, m as readErrorCatalogue, n as generate, o as emitSchemas, p as emitErrorCodes, r as schemasOutputPath, s as Emitter, t as check, u as deriveProvenance, v as DescriptorBuilder, y as buildAtomic } from "./src-G1x-BbMp.mjs";
+import { _ as checkContract, a as readSchemas, b as buildDescriptor, c as detectVerbCollisions, d as hashJson, f as provenanceLines, g as MINIMUM_CONTRACT, h as MAXIMUM_CONTRACT, i as readDocument, l as emit, m as readErrorCatalogue, n as generate, o as emitSchemas, p as emitErrorCodes, r as schemasOutputPath, s as Emitter, t as check, u as deriveProvenance, v as DescriptorBuilder, y as buildAtomic } from "./src-CKsM7dXw.mjs";
 export { DescriptorBuilder, Emitter, MAXIMUM_CONTRACT, MINIMUM_CONTRACT, buildAtomic, buildDescriptor, check, checkContract, deriveProvenance, detectVerbCollisions, emit, emitErrorCodes, emitSchemas, generate, hashJson, provenanceLines, readDocument, readErrorCatalogue, readSchemas, schemasOutputPath };

package/dist/{src-G1x-BbMp.mjs → src-CKsM7dXw.mjs}

@@ -3,6 +3,64 @@ import { dirname } from "node:path";
 import { ATOMIC_EXT, CANONICAL_PAGE_KEYS, HANDLE_RESERVED } from "@haddowg/json-api-client";
 import { createHash } from "node:crypto";
 import { parse } from "yaml";
+//#region src/unwrap-refs.ts
+/**
+* Keywords that annotate a schema without constraining it. A single-entry `allOf` wrapper is
+* read as its `$ref` only when the wrapper carries nothing else, plus any `x-` extension.
+*/
+const ANNOTATIONS = /* @__PURE__ */ new Set([
+	"title",
+	"description",
+	"example",
+	"examples",
+	"default",
+	"deprecated",
+	"readOnly",
+	"writeOnly",
+	"$comment"
+]);
+const unwrapped = /* @__PURE__ */ new WeakMap();
+/**
+* The document with every `{ allOf: [{ $ref }], ...annotations }` node rewritten as
+* `{ $ref, ...annotations }`. From generator contract 9 the projector wraps a `$ref` that
+* carries an `example`, `examples` or `default` this way, because OAS 3.0 tooling ignores a
+* `$ref`'s siblings. Reading the wrapper as its `$ref` keeps every lookup that follows a `$ref`
+* working, and keeps the annotations for the TSDoc. The input is not modified.
+*/
+function unwrapRefs(doc) {
+	let out = unwrapped.get(doc);
+	if (out === void 0) {
+		out = unwrapNode(doc);
+		unwrapped.set(doc, out);
+		unwrapped.set(out, out);
+	}
+	return out;
+}
+function unwrapNode(node) {
+	if (Array.isArray(node)) return node.map(unwrapNode);
+	if (typeof node !== "object" || node === null) return node;
+	const out = {};
+	for (const [key, value] of Object.entries(node)) out[key] = unwrapNode(value);
+	const ref = wrappedRef(out);
+	if (ref === void 0) return out;
+	const { allOf: _allOf, ...annotations } = out;
+	return {
+		$ref: ref,
+		...annotations
+	};
+}
+/** The `$ref` a node wraps in a single-entry `allOf`, when that is all the node constrains. */
+function wrappedRef(node) {
+	const allOf = node["allOf"];
+	if (!Array.isArray(allOf) || allOf.length !== 1 || "$ref" in node) return;
+	const entry = allOf[0];
+	if (typeof entry !== "object" || entry === null) return;
+	const keys = Object.keys(entry);
+	const ref = entry["$ref"];
+	if (keys.length !== 1 || typeof ref !== "string") return;
+	return Object.keys(node).every((key) => key === "allOf" || ANNOTATIONS.has(key) || key.startsWith("x-")) ? ref : void 0;
+}
+//#endregion
 //#region src/build-descriptor.ts
 const REF_PREFIX$2 = "#/components/schemas/";
 const JSON_API_MEDIA_TYPE$1 = "application/vnd.api+json";
@@ -33,13 +91,12 @@ function typeKeys(type) {
 	return (Array.isArray(type) ? type : [type]).filter((t) => t !== "null");
 }
 var DescriptorBuilder = class {
-	doc;
 	schemas;
 	paths;
 	/** Lazily-built wire-type -> collection-level paginator kind (for per-relation divergence, D6a). */
 	typePaginators;
-	constructor(doc) {
-		this.doc = doc;
+	constructor(source) {
+		const doc = unwrapRefs(source);
 		this.schemas = doc.components?.schemas ?? {};
 		this.paths = doc.paths ?? {};
 	}
@@ -848,7 +905,7 @@ function stampedMenu(schema, stamp, warn) {
 /** Below this the document predates the structures this codegen reads. */
 const MINIMUM_CONTRACT = 1;
 /** Above this the document carries structures this codegen does not read. */
-const MAXIMUM_CONTRACT = 8;
+const MAXIMUM_CONTRACT = 9;
 /**
 * Check the document's `info.x-generator.contract` against the range this codegen reads. A
 * document older than the range throws; a newer one returns a warning, because its new
@@ -858,8 +915,108 @@ const MAXIMUM_CONTRACT = 8;
 function checkContract(doc) {
 	const contract = doc.info?.["x-generator"]?.contract;
 	if (typeof contract !== "number") return;
-	if (contract < 1) throw new Error(`the document declares contract ${contract}, which predates what this codegen reads (it supports 1 to 8). Use an older codegen release, or regenerate the document from a newer server.`);
-	if (contract > 8) return `the document declares contract ${contract} and this codegen reads up to 8. It describes capabilities that were not generated; upgrade the codegen to pick them up.`;
+	if (contract < 1) throw new Error(`the document declares contract ${contract}, which predates what this codegen reads (it supports 1 to 9). Use an older codegen release, or regenerate the document from a newer server.`);
+	if (contract > 9) return `the document declares contract ${contract} and this codegen reads up to 9. It describes capabilities that were not generated; upgrade the codegen to pick them up.`;
+}
+//#endregion
+//#region src/source.ts
+/**
+* Helpers for writing strings read from the OpenAPI document into generated TypeScript. Every
+* name, literal and comment the emitters take from the document goes through one of these.
+*/
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+/** Line terminators as JavaScript counts them. */
+const LINE_BREAK = /\r\n|[\n\r\u2028\u2029]/;
+/** A string as a TS string literal. U+2028/U+2029 are escaped too, which JSON leaves raw. */
+function stringLiteral(value) {
+	return JSON.stringify(value).replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+}
+/** True when a string is a bare identifier. */
+function isIdentifier(value) {
+	return IDENTIFIER.test(value);
+}
+/**
+* A property key for an object literal or an interface: bare when it's an identifier, quoted
+* otherwise. `__proto__` is written as a computed key, which a runtime literal keeps as an own
+* property instead of setting the prototype.
+*/
+function propertyKey(name) {
+	if (name === "__proto__") return `[${stringLiteral(name)}]`;
+	return isIdentifier(name) ? name : stringLiteral(name);
+}
+/** Text that can sit inside a block comment: any `*\/` is broken up so it can't close it. */
+function commentText(text) {
+	return text.replace(/\*\//g, "* /");
+}
+/** {@link commentText} split into lines, for a multi-line block comment. */
+function commentLines(text) {
+	return commentText(text).split(LINE_BREAK);
+}
+/** {@link commentText} on one line, for a single comment line such as the provenance header. */
+function commentLine(text) {
+	return commentText(text).split(LINE_BREAK).join(" ");
+}
+/** Words a type alias can't be named: reserved words and the built-in type names. */
+const RESERVED_TYPE_NAMES = /* @__PURE__ */ new Set([
+	"any",
+	"bigint",
+	"boolean",
+	"break",
+	"case",
+	"catch",
+	"class",
+	"const",
+	"continue",
+	"debugger",
+	"default",
+	"delete",
+	"do",
+	"else",
+	"enum",
+	"export",
+	"extends",
+	"false",
+	"finally",
+	"for",
+	"function",
+	"if",
+	"implements",
+	"import",
+	"in",
+	"instanceof",
+	"interface",
+	"let",
+	"never",
+	"new",
+	"null",
+	"number",
+	"object",
+	"package",
+	"private",
+	"protected",
+	"public",
+	"return",
+	"static",
+	"string",
+	"super",
+	"switch",
+	"symbol",
+	"this",
+	"throw",
+	"true",
+	"try",
+	"typeof",
+	"undefined",
+	"unknown",
+	"var",
+	"void",
+	"while",
+	"with",
+	"yield"
+]);
+/** True when `name` can be used as is for an exported type. */
+function isTypeName(name) {
+	return isIdentifier(name) && !RESERVED_TYPE_NAMES.has(name);
 }
 //#endregion
 //#region src/error-codes.ts
@@ -924,24 +1081,20 @@ function readErrorCatalogue(doc) {
 /** A TSDoc block for one code: its description, then each example detail as an `@example`. */
 function codeDoc(entry, indent) {
 	const lines = [];
-	if (entry.description !== void 0) lines.push(...entry.description.split("\n"));
+	if (entry.description !== void 0) lines.push(...commentLines(entry.description));
 	for (const example of entry.examples) {
 		if (lines.length > 0) lines.push("");
 		const text = typeof example === "string" ? example : JSON.stringify(example);
-		lines.push(...`@example ${text}`.split("\n"));
+		lines.push(...commentLines(`@example ${text}`));
 	}
 	if (lines.length === 0) return;
-	if (lines.length === 1) return `${indent}/** ${lines[0].replace(/\*\//g, "* /")} */`;
+	if (lines.length === 1) return `${indent}/** ${lines[0]} */`;
 	return [
 		`${indent}/**`,
-		...lines.map((line) => `${indent} * ${line.replace(/\*\//g, "* /")}`.trimEnd()),
+		...lines.map((line) => `${indent} * ${line}`.trimEnd()),
 		`${indent} */`
 	].join("\n");
 }
-/** A bare object key when the code is a valid identifier, else a quoted one. */
-function codeKey(code) {
-	return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(code) ? code : JSON.stringify(code);
-}
 /**
 * Emit `ErrorCodes`, a const object keyed by every documented code with its TSDoc on the key
 * (editors show TSDoc on an object key, not on a string-literal union member), the `ErrorCode`
@@ -964,7 +1117,7 @@ function emitErrorCodes(catalogue) {
 		"export const ErrorCodes = {",
 		...catalogue.codes.flatMap((entry) => {
 			const doc = codeDoc(entry, "  ");
-			const member = `  ${codeKey(entry.code)}: ${JSON.stringify(entry.code)},`;
+			const member = `  ${propertyKey(entry.code)}: ${stringLiteral(entry.code)},`;
 			return doc === void 0 ? [member] : [doc, member];
 		}),
 		"} as const",
@@ -976,7 +1129,7 @@ function emitErrorCodes(catalogue) {
 		"export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes]"
 	].join("\n");
 	const statusLines = [...catalogue.byStatus].map(([status, codes]) => {
-		const members = codes.map((c) => JSON.stringify(c));
+		const members = codes.map((c) => stringLiteral(c));
 		const line = `  ${status}: ${members.length === 0 ? "never" : members.join(" | ")}`;
 		return line.length <= 100 ? line : `  ${status}:\n${members.map((m) => `    | ${m}`).join("\n")}`;
 	});
@@ -1033,12 +1186,12 @@ function deriveProvenance(doc) {
 }
 /**
 * Render the provenance record as the JSDoc header lines stamped into a generated artifact
-* (each already prefixed with ` * `). Deterministic: no timestamp, so re-generating from the
+* (each already prefixed with ` * `), with the document's text kept to one comment line. Deterministic: no timestamp, so re-generating from the
 * same spec yields byte-identical output.
 */
 function provenanceLines(provenance) {
-	const lines = [` * Source spec: ${provenance.source}`, ` * Spec hash:   ${provenance.hash}`];
-	if (provenance.server !== void 0) lines.splice(1, 0, ` * Server:      ${provenance.server}`);
+	const lines = [` * Source spec: ${commentLine(provenance.source)}`, ` * Spec hash:   ${provenance.hash}`];
+	if (provenance.server !== void 0) lines.splice(1, 0, ` * Server:      ${commentLine(provenance.server)}`);
 	return lines;
 }
 //#endregion
@@ -1083,17 +1236,25 @@ function isSchema(value) {
 function pascalCase(value) {
 	return value.split(/[^a-zA-Z0-9]+/).filter((part) => part.length > 0).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
 }
-/** Emit a JSON-string literal (used for keys that aren't bare identifiers and enum members). */
-function quote(value) {
-	return JSON.stringify(value);
-}
-/** True when a string is a safe bare object-key identifier. */
-function isIdentifier(value) {
-	return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(value);
-}
-function objectKey(value) {
-	return isIdentifier(value) ? value : quote(value);
+/** The identifier stem for a wire type's interfaces, `Type`-prefixed when it would start with a digit. */
+function typeStem(type) {
+	const pascal = pascalCase(type);
+	return /^[A-Za-z]/.test(pascal) ? pascal : `Type${pascal}`;
 }
+/** Names the generated module declares or relies on, which an enum alias must not take. */
+const MODULE_NAMES = [
+	"ActionTypes",
+	"ApiDescriptor",
+	"Attributes",
+	"ClientOptions",
+	"ErrorCode",
+	"ErrorCodeByStatus",
+	"ErrorCodeGuard",
+	"ErrorCodes",
+	"Record",
+	"ResourceMap",
+	"WriteAttributes"
+];
 /**
 * Render a description as a JSDoc comment at the given indent — single-line when it fits,
 * a block otherwise. Returns `undefined` for empty text. Neutralises any `*\/` so a
@@ -1102,7 +1263,7 @@ function objectKey(value) {
 function jsDoc(text, indent) {
 	const trimmed = text?.trim();
 	if (!trimmed) return;
-	const lines = trimmed.replace(/\*\//g, "* /").split("\n");
+	const lines = commentLines(trimmed);
 	if (lines.length === 1) return `${indent}/** ${lines[0]} */`;
 	return [
 		`${indent}/**`,
@@ -1158,7 +1319,6 @@ function memberDoc(schema) {
 	return description ? `${description}\n\n${tags.join("\n")}` : tags.join("\n");
 }
 var Emitter = class {
-	doc;
 	descriptor;
 	atomic;
 	schemas;
@@ -1173,6 +1333,10 @@ var Emitter = class {
 	* already-named attribute type. Populated as interfaces are emitted.
 	*/
 	emittedInterfaces = /* @__PURE__ */ new Set();
+	/** Enum component name -> the alias name it's emitted under. */
+	enumNames = /* @__PURE__ */ new Map();
+	/** Type names already spoken for: the module's own, the per-type interfaces and enum aliases. */
+	takenNames;
 	/** Component names mid-expansion in {@link tsType} — a cycle guard for self/mutually-referential `$ref`s. */
 	expanding = /* @__PURE__ */ new Set();
 	/**
@@ -1183,13 +1347,47 @@ var Emitter = class {
 	actionAliasNames = /* @__PURE__ */ new Map();
 	/** Provenance of the source document, stamped into the generated header for drift tracking. */
 	provenance;
-	constructor(doc, descriptor, atomic) {
-		this.doc = doc;
+	doc;
+	constructor(source, descriptor, atomic) {
 		this.descriptor = descriptor;
 		this.atomic = atomic;
-		this.schemas = doc.components?.schemas ?? {};
+		this.doc = unwrapRefs(source);
+		this.schemas = this.doc.components?.schemas ?? {};
 		this.baseByType = this.indexBases();
-		this.provenance = deriveProvenance(doc);
+		this.provenance = deriveProvenance(source);
+		this.takenNames = new Set(MODULE_NAMES);
+		for (const type of Object.keys(descriptor)) {
+			const stem = typeStem(type);
+			for (const suffix of [
+				"Attributes",
+				"CreateAttributes",
+				"UpdateAttributes"
+			]) this.takenNames.add(`${stem}${suffix}`);
+			for (const action of Object.keys(descriptor[type]?.actions ?? {})) {
+				this.takenNames.add(`${stem}${pascalCase(action)}Input`);
+				this.takenNames.add(`${stem}${pascalCase(action)}Output`);
+			}
+		}
+	}
+	/**
+	* The alias an enum component is emitted under: its own name when that's a usable type name,
+	* else one derived from it (with a warning), kept clear of every other name in the module.
+	*/
+	enumName(component) {
+		const known = this.enumNames.get(component);
+		if (known !== void 0) return known;
+		let name = component;
+		if (!isTypeName(component) || this.takenNames.has(component)) {
+			const pascal = pascalCase(component);
+			let stem = /^[A-Za-z]/.test(pascal) ? pascal : `Enum${pascal}`;
+			if (!isTypeName(stem) || this.takenNames.has(stem)) stem = `${stem}Enum`;
+			name = stem;
+			for (let n = 2; this.takenNames.has(name); n++) name = `${stem}${n}`;
+			console.warn(`Enum component ${stringLiteral(component)} can't be used as a TypeScript type name; emitting it as ${name}.`);
+		}
+		this.takenNames.add(name);
+		this.enumNames.set(component, name);
+		return name;
 	}
 	/** Map each declared wire type back to the `Base` of its resource schema. */
 	indexBases() {
@@ -1250,7 +1448,7 @@ var Emitter = class {
 		const base = this.baseByType.get(type);
 		const props = base ? this.schemas[`${base}Attributes`]?.properties : void 0;
 		const fields = Object.keys(this.descriptor[type].attributes);
-		return this.renderInterface(`${pascalCase(type)}Attributes`, props, fields, () => true);
+		return this.renderInterface(`${typeStem(type)}Attributes`, props, fields, () => true);
 	}
 	/**
 	* The per-type WRITE attribute interfaces — `<Pascal>CreateAttributes` and
@@ -1262,7 +1460,7 @@ var Emitter = class {
 	writeAttributeInterfaces(type) {
 		const base = this.baseByType.get(type);
 		if (base === void 0) return [];
-		const pascal = pascalCase(type);
+		const pascal = typeStem(type);
 		const out = [];
 		const create = this.schemas[`${base}CreateAttributes`];
 		if (create !== void 0) {
@@ -1289,7 +1487,7 @@ var Emitter = class {
 		for (const type of Object.keys(this.descriptor)) {
 			const actions = this.descriptor[type]?.actions;
 			if (actions === void 0) continue;
-			const pascal = pascalCase(type);
+			const pascal = typeStem(type);
 			for (const [actionName, action] of Object.entries(actions)) {
 				const member = `${pascal}${pascalCase(actionName)}`;
 				const names = {};
@@ -1333,9 +1531,9 @@ var Emitter = class {
 				const members = [];
 				if (names.input !== void 0) members.push(`input: ${names.input}`);
 				if (names.output !== void 0) members.push(`output: ${names.output}`);
-				actionLines.push(`    ${objectKey(actionName)}: { ${members.join("; ")} }`);
+				actionLines.push(`    ${propertyKey(actionName)}: { ${members.join("; ")} }`);
 			}
-			typeLines.push(`  ${objectKey(type)}: {\n${actionLines.join("\n")}\n  }`);
+			typeLines.push(`  ${propertyKey(type)}: {\n${actionLines.join("\n")}\n  }`);
 		}
 		if (typeLines.length === 0) return "export interface ActionTypes {}";
 		return `export interface ActionTypes {\n${typeLines.join("\n")}\n}`;
@@ -1383,10 +1581,10 @@ var Emitter = class {
 			if (schema.oneOf !== void 0) for (const arm of schema.oneOf) {
 				const kind = isSchema(arm.properties?.["kind"]) ? arm.properties["kind"].const : void 0;
 				const members = this.pageMemberLimits(arm, "      ");
-				if (typeof kind === "string" && members.length > 0) body.push(`    ${objectKey(kind)}: {\n${members.join("\n")}\n    },`);
+				if (typeof kind === "string" && members.length > 0) body.push(`    ${propertyKey(kind)}: {\n${members.join("\n")}\n    },`);
 			}
 			else body = this.pageMemberLimits(schema, "    ");
-			if (body.length > 0) typeLines.push(`  ${objectKey(type)}: {\n${body.join("\n")}\n  },`);
+			if (body.length > 0) typeLines.push(`  ${propertyKey(type)}: {\n${body.join("\n")}\n  },`);
 		}
 		return `${[
 			"/**",
@@ -1411,7 +1609,7 @@ var Emitter = class {
 			if (limits.length === 0) continue;
 			const doc = jsDoc(memberDoc(prop), indent);
 			if (doc !== void 0) lines.push(doc);
-			lines.push(`${indent}${objectKey(name)}: { ${limits.join(", ")} },`);
+			lines.push(`${indent}${propertyKey(name)}: { ${limits.join(", ")} },`);
 		}
 		return lines;
 	}
@@ -1428,7 +1626,7 @@ var Emitter = class {
 			const doc = isSchema(schema) ? jsDoc(memberDoc(schema), "  ") : void 0;
 			if (doc) lines.push(doc);
 			const optional = required(field) ? "" : "?";
-			lines.push(`  ${objectKey(field)}${optional}: ${tsType}`);
+			lines.push(`  ${propertyKey(field)}${optional}: ${tsType}`);
 		}
 		this.emittedInterfaces.add(name);
 		if (lines.length === 0) return `export interface ${name} {}`;
@@ -1441,7 +1639,7 @@ var Emitter = class {
 			const resolved = target ? this.schemas[target] : void 0;
 			if (target && resolved && Array.isArray(resolved.enum)) {
 				this.usedEnums.set(target, resolved);
-				return target;
+				return this.enumName(target);
 			}
 			if (target && this.emittedInterfaces.has(target)) return target;
 			if (resolved === void 0 || target === void 0 || this.expanding.has(target)) return "unknown";
@@ -1466,7 +1664,7 @@ var Emitter = class {
 	}
 	/** The non-nullable TS type for the declared JSON type(s). */
 	baseTsType(schema, types) {
-		if (Array.isArray(schema.enum) && schema.enum.length > 0) return schema.enum.map((value) => quote(String(value))).join(" | ");
+		if (Array.isArray(schema.enum) && schema.enum.length > 0) return schema.enum.map((value) => stringLiteral(String(value))).join(" | ");
 		if (types.length === 0) return "unknown";
 		const mapped = types.map((t) => this.scalarOrComposite(schema, t));
 		return [...new Set(mapped)].join(" | ");
@@ -1491,7 +1689,7 @@ var Emitter = class {
 		for (const [name, prop] of Object.entries(props)) {
 			if (!isSchema(prop)) continue;
 			const optional = required.has(name) ? "" : "?";
-			members.push(`${objectKey(name)}${optional}: ${this.tsType(prop)}`);
+			members.push(`${propertyKey(name)}${optional}: ${this.tsType(prop)}`);
 		}
 		if (members.length === 0) return "Record<string, unknown>";
 		return `{ ${members.join("; ")} }`;
@@ -1508,7 +1706,8 @@ var Emitter = class {
 		if (this.usedEnums.size === 0) return;
 		return [...this.usedEnums.keys()].sort().map((name) => {
 			const schema = this.usedEnums.get(name);
-			const alias = `export type ${name} = ${(schema.enum ?? []).map((value) => quote(String(value))).join(" | ")}`;
+			const union = (schema.enum ?? []).map((value) => stringLiteral(String(value))).join(" | ");
+			const alias = `export type ${this.enumName(name)} = ${union}`;
 			const doc = jsDoc(this.enumDoc(schema), "");
 			return doc ? `${doc}\n${alias}` : alias;
 		}).join("\n\n");
@@ -1531,7 +1730,7 @@ var Emitter = class {
 	* argument to the runtime factory).
 	*/
 	attributesMap() {
-		return `export interface Attributes {\n${Object.keys(this.descriptor).map((type) => `  ${objectKey(type)}: ${pascalCase(type)}Attributes`).join("\n")}\n}`;
+		return `export interface Attributes {\n${Object.keys(this.descriptor).map((type) => `  ${propertyKey(type)}: ${typeStem(type)}Attributes`).join("\n")}\n}`;
 	}
 	/**
 	* Emit the `WriteAttributes` interface mapping each writable wire type to its
@@ -1546,11 +1745,11 @@ var Emitter = class {
 			const hasCreate = base !== void 0 && this.schemas[`${base}CreateAttributes`] !== void 0;
 			const hasUpdate = base !== void 0 && this.schemas[`${base}UpdateAttributes`] !== void 0;
 			if (!hasCreate && !hasUpdate) continue;
-			const pascal = pascalCase(type);
+			const pascal = typeStem(type);
 			const members = [];
 			if (hasCreate) members.push(`create: ${pascal}CreateAttributes`);
 			if (hasUpdate) members.push(`update: ${pascal}UpdateAttributes`);
-			lines.push(`  ${objectKey(type)}: { ${members.join("; ")} }`);
+			lines.push(`  ${propertyKey(type)}: { ${members.join("; ")} }`);
 		}
 		if (lines.length === 0) return "export interface WriteAttributes {}";
 		return `export interface WriteAttributes {\n${lines.join("\n")}\n}`;
@@ -1570,9 +1769,9 @@ var Emitter = class {
 		if (value !== null && typeof value === "object") {
 			const entries = Object.entries(value);
 			if (entries.length === 0) return "{}";
-			return `{\n${entries.map(([key, v]) => `${inner}${objectKey(key)}: ${this.literal(v, depth + 1)}`).join(",\n")}\n${indent}}`;
+			return `{\n${entries.map(([key, v]) => `${inner}${propertyKey(key)}: ${this.literal(v, depth + 1)}`).join(",\n")}\n${indent}}`;
 		}
-		return JSON.stringify(value);
+		return typeof value === "string" ? stringLiteral(value) : JSON.stringify(value);
 	}
 	boundFactory() {
 		return [
@@ -1631,7 +1830,7 @@ function header(bundle) {
 	].join("\n");
 }
 function body(bundle) {
-	return `export const schemas = ${JSON.stringify(bundle, null, 2)} as const`;
+	return `export const schemas = ${JSON.stringify(bundle, null, 2).replace(/^(\s*)"__proto__":/gm, "$1[\"__proto__\"]:").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029")} as const`;
 }
 //#endregion
 //#region src/reader.ts
@@ -1775,4 +1974,4 @@ async function check(config) {
 //#endregion
 export { checkContract as _, readSchemas as a, buildDescriptor as b, detectVerbCollisions as c, hashJson as d, provenanceLines as f, MINIMUM_CONTRACT as g, MAXIMUM_CONTRACT as h, readDocument as i, emit as l, readErrorCatalogue as m, generate as n, emitSchemas as o, emitErrorCodes as p, schemasOutputPath as r, Emitter as s, check as t, deriveProvenance as u, DescriptorBuilder as v, buildAtomic as y };
 
-//# sourceMappingURL=src-G1x-BbMp.mjs.map
+//# sourceMappingURL=src-CKsM7dXw.mjs.map