@haddowg/json-api-codegen 1.0.0

package/dist/src-B24cYyjM.mjs

@@ -0,0 +1,1278 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { ATOMIC_EXT, HANDLE_RESERVED } from "@haddowg/json-api-client";
+import { createHash } from "node:crypto";
+import { parse } from "yaml";
+//#region src/build-descriptor.ts
+const REF_PREFIX$1 = "#/components/schemas/";
+const JSON_API_MEDIA_TYPE$1 = "application/vnd.api+json";
+/** Sort a record's keys for deterministic, snapshot-stable output. */
+function sortRecord(record) {
+	const out = {};
+	for (const key of Object.keys(record).sort()) out[key] = record[key];
+	return out;
+}
+/** Resolve a local schema name from a `#/components/schemas/X` ref. */
+function refName$1(ref) {
+	return ref.startsWith(REF_PREFIX$1) ? ref.slice(21) : void 0;
+}
+function isSchema$1(value) {
+	return typeof value === "object" && value !== null;
+}
+/** The set of `type` keys a JSON type node declares, with `"null"` removed. */
+function typeKeys(type) {
+	if (type === void 0) return [];
+	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;
+		this.schemas = doc.components?.schemas ?? {};
+		this.paths = doc.paths ?? {};
+	}
+	/**
+	* 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
+	* baseline a per-relation related-endpoint paginator is compared against (D6a).
+	*/
+	typePaginator(wireType) {
+		if (this.typePaginators === void 0) {
+			this.typePaginators = /* @__PURE__ */ new Map();
+			for (const [name, schema] of Object.entries(this.schemas)) {
+				const type = this.resourceType(name, schema);
+				if (type !== void 0) this.typePaginators.set(type, this.paginator(name.slice(0, -8)));
+			}
+		}
+		return this.typePaginators.get(wireType) ?? "none";
+	}
+	build() {
+		const out = {};
+		for (const [name, schema] of Object.entries(this.schemas)) {
+			const wireType = this.resourceType(name, schema);
+			if (wireType === void 0) continue;
+			const base = name.slice(0, -8);
+			const collection = this.collectionPath(base);
+			const actions = collection ? this.actions(collection) : {};
+			const descriptor = {
+				attributes: this.attributes(base),
+				relations: this.relations(schema, collection),
+				paths: this.operationPaths(base),
+				paginator: this.paginator(base),
+				clientId: this.clientId(base)
+			};
+			const countable = this.countable(collection);
+			if (countable !== void 0) descriptor.countable = countable;
+			const includable = this.includable(collection);
+			if (includable !== void 0) descriptor.includable = includable;
+			const sortable = this.sortable(collection);
+			if (sortable !== void 0) descriptor.sortable = sortable;
+			const filterable = this.filterable(collection);
+			if (filterable !== void 0) descriptor.filterable = filterable;
+			if (Object.keys(actions).length > 0) descriptor.actions = actions;
+			if (Object.keys(schema.properties ?? {}).every((prop) => prop === "type") && Object.keys(descriptor.paths).length === 0) continue;
+			out[wireType] = descriptor;
+		}
+		return sortRecord(out);
+	}
+	/**
+	* The server-level Atomic Operations capability: the path whose `POST` requestBody
+	* declares the atomic ext media type ({@link ATOMIC_EXT}). `null` when no such endpoint
+	* exists. Server-level, so it rides {@link buildAtomic}, not the per-type descriptor.
+	*/
+	buildAtomic() {
+		for (const [path, item] of Object.entries(this.paths)) {
+			const content = item.post?.requestBody?.content ?? {};
+			if (Object.keys(content).some(isAtomicMediaType)) return { path };
+		}
+		return null;
+	}
+	/**
+	* A resource schema is one whose name ends in `Resource` (but not
+	* `ResourceIdentifier`) and carries `properties.type.const` (a string) — that const
+	* is the descriptor key (the wire type). Never inferred from the schema name.
+	*/
+	resourceType(name, schema) {
+		if (!name.endsWith("Resource") || name.endsWith("ResourceIdentifier")) return;
+		const constValue = schema.properties?.["type"];
+		if (isSchema$1(constValue) && typeof constValue.const === "string") return constValue.const;
+	}
+	/** Follow a `$ref` to its identifier/resource schema and read `properties.type.const`. */
+	resolveConst(ref) {
+		const target = refName$1(ref);
+		if (target === void 0) return;
+		const typeProp = this.schemas[target]?.properties?.["type"];
+		return isSchema$1(typeProp) && typeof typeProp.const === "string" ? typeProp.const : void 0;
+	}
+	attributes(base) {
+		const props = this.schemas[`${base}Attributes`]?.properties;
+		if (props === void 0) return {};
+		const out = {};
+		for (const [name, prop] of Object.entries(props)) if (isSchema$1(prop)) out[name] = formatHint(prop);
+		return sortRecord(out);
+	}
+	relations(resource, collection) {
+		const relProps = isSchema$1(resource.properties?.["relationships"]) ? resource.properties["relationships"].properties : void 0;
+		if (relProps === void 0) return {};
+		const out = {};
+		for (const [name, prop] of Object.entries(relProps)) {
+			if (!isSchema$1(prop) || typeof prop.$ref !== "string") continue;
+			const component = this.schemas[refName$1(prop.$ref) ?? ""];
+			const descriptor = component ? this.relationFromComponent(component) : void 0;
+			if (descriptor === void 0) {
+				console.warn(`json-api codegen: relationship "${name}" has an unrecognized linkage shape; dropping it from the descriptor.`);
+				continue;
+			}
+			out[name] = collection === void 0 ? descriptor : this.withRelationExposure(descriptor, collection, name);
+		}
+		return sortRecord(out);
+	}
+	/**
+	* The per-relation mutation capability, derived from the HTTP methods the relationship
+	* endpoint (`{collection}/{id}/relationships/{rel}`) advertises. For a to-many:
+	* `add` <- POST, `remove` <- DELETE, `replace` <- PATCH. For a to-one: `set` <- PATCH.
+	* Only `true` verbs are emitted (a missing verb is simply absent). Returns `undefined`
+	* when the relation exposes no relationship endpoint at all.
+	*/
+	relationMutations(collection, rel, cardinality) {
+		const item = this.paths[`${collection}/{id}/relationships/${rel}`];
+		if (item === void 0) return;
+		const mutations = {};
+		if (cardinality === "many") {
+			if (item.post) mutations.add = true;
+			if (item.delete) mutations.remove = true;
+			if (item.patch) mutations.replace = true;
+		} else if (item.patch) mutations.set = true;
+		return mutations;
+	}
+	/**
+	* Attach the per-relation endpoint-exposure signal to a relation descriptor (D24). The bundle
+	* can suppress a relation's related or relationship endpoint (`withoutRelatedEndpoint()` /
+	* `withoutRelationshipEndpoint()`, ADR 0027), which the OpenAPI reflects by simply omitting that
+	* relation's path — but codegen synthesizes generic `{rel}` templates, erasing the per-relation
+	* distinction. So mark `related: false` / `relationship: false` when this relation's specific
+	* path is absent, and ALWAYS emit an explicit `mutations` object (the verb flags when the
+	* relationship endpoint exists, else `{}`) so the client gates a suppressed relation OFF rather
+	* than failing open (offering `.get()`/`.related()`/mutations that 404).
+	*/
+	withRelationExposure(descriptor, collection, name) {
+		const out = { ...descriptor };
+		const relatedGet = this.operation(`${collection}/{id}/${name}`, "get");
+		if (relatedGet === void 0) out.related = false;
+		const mutations = this.relationMutations(collection, name, descriptor.cardinality);
+		if (mutations === void 0) {
+			out.relationship = false;
+			out.mutations = {};
+		} else out.mutations = mutations;
+		const countable = withCountParam(relatedGet) ?? withCountParam(this.operation(`${collection}/{id}/relationships/${name}`, "get"));
+		if (countable !== void 0) out.countable = countable;
+		if (descriptor.cardinality === "many") {
+			const relatedKind = this.paginatorKindOf(relatedGet) === "none" ? this.paginatorKindOf(this.operation(`${collection}/{id}/relationships/${name}`, "get")) : this.paginatorKindOf(relatedGet);
+			const relatedType = descriptor.types[0];
+			const typeKind = relatedType !== void 0 ? this.typePaginator(relatedType) : "none";
+			if (relatedKind !== "none" && relatedKind !== typeKind) out.paginator = relatedKind;
+		}
+		return out;
+	}
+	/**
+	* Collect the custom actions for a type from its `{collection}/-actions/{name}` and
+	* `{collection}/{id}/-actions/{name}` paths. The action name is the last segment; scope
+	* is `resource` when the path carries `/{id}/`, else `collection`. `input` is `document`
+	* (a JSON:API requestBody), `none` (no requestBody) or `raw` (a non-JSON:API body);
+	* `output` is `document` (a 2xx returns a JSON:API document) or `none` (only `204`).
+	*/
+	actions(collection) {
+		const out = {};
+		const collectionPrefix = `${collection}/-actions/`;
+		const resourcePrefix = `${collection}/{id}/-actions/`;
+		for (const [path, item] of Object.entries(this.paths)) {
+			let scope;
+			let name;
+			if (path.startsWith(resourcePrefix)) {
+				scope = "resource";
+				name = path.slice(resourcePrefix.length);
+			} else if (path.startsWith(collectionPrefix)) {
+				scope = "collection";
+				name = path.slice(collectionPrefix.length);
+			} else continue;
+			if (name.length === 0 || name.includes("/")) continue;
+			const picked = pickOperation(item);
+			if (picked === void 0) {
+				console.warn(`json-api codegen: custom action path "${path}" advertises no usable operation; skipping.`);
+				continue;
+			}
+			const { method, op } = picked;
+			const input = actionInput(op);
+			const output = actionOutput(op);
+			const action = {
+				scope,
+				path,
+				input,
+				output
+			};
+			if (method !== "post") action.method = method.toUpperCase();
+			if (input === "document") {
+				const inputType = this.documentPrimary(actionRequestRef(op))?.type;
+				if (inputType !== void 0) action.inputType = inputType;
+			}
+			if (output === "document") {
+				const primary = this.documentPrimary(this.firstOkJsonApiRef(op));
+				if (primary !== void 0) {
+					action.outputType = primary.type;
+					action.outputCardinality = primary.cardinality;
+				}
+			}
+			if (input === "raw") {
+				const contentType = rawContentType(op);
+				if (contentType !== void 0) action.contentType = contentType;
+			}
+			out[name] = action;
+		}
+		return sortRecord(out);
+	}
+	/**
+	* The wire type (and cardinality) of a document component's primary `data` — a `$ref` to a
+	* resource, an inline object carrying `properties.type.const` (a create-request body), or an
+	* array of resource/identifier refs (a collection). `undefined` when the type can't be resolved.
+	*/
+	documentPrimary(ref) {
+		if (typeof ref !== "string") return;
+		const component = refName$1(ref);
+		const data = component === void 0 ? void 0 : this.schemas[component]?.properties?.["data"];
+		if (!isSchema$1(data)) return;
+		if (isSchema$1(data.items)) {
+			const itemRef = data.items.$ref;
+			const many = typeof itemRef === "string" ? this.resolveConst(itemRef) : void 0;
+			return many === void 0 ? void 0 : {
+				type: many,
+				cardinality: "many"
+			};
+		}
+		const one = this.dataConst(data);
+		return one === void 0 ? void 0 : {
+			type: one,
+			cardinality: "one"
+		};
+	}
+	/** The wire type of a single `data` schema — a `$ref` to a resource, or an inline `type.const`. */
+	dataConst(data) {
+		if (typeof data.$ref === "string") return this.resolveConst(data.$ref);
+		const typeProp = data.properties?.["type"];
+		return isSchema$1(typeProp) && typeof typeProp.const === "string" ? typeProp.const : void 0;
+	}
+	/** The `$ref` of the first 2xx JSON:API response body on an operation (the output document). */
+	firstOkJsonApiRef(op) {
+		for (const [code, response] of Object.entries(op.responses ?? {})) {
+			if (!code.startsWith("2")) continue;
+			const ref = response.content?.[JSON_API_MEDIA_TYPE$1]?.schema?.$ref;
+			if (typeof ref === "string") return ref;
+		}
+	}
+	/** Resolve a relationship component's `data` into a {@link RelationDescriptor}. */
+	relationFromComponent(component) {
+		const data = component.properties?.["data"];
+		if (!isSchema$1(data)) return;
+		if (data.type === "array") {
+			const items = data.items;
+			if (items === void 0) return;
+			if (typeof items.$ref === "string") {
+				const type = this.resolveConst(items.$ref);
+				return type === void 0 ? void 0 : {
+					cardinality: "many",
+					types: [type],
+					pivot: false
+				};
+			}
+			if (Array.isArray(items.allOf)) {
+				const type = this.constFromAllOf(items.allOf);
+				if (type === void 0) return;
+				const relation = {
+					cardinality: "many",
+					types: [type],
+					pivot: true
+				};
+				const pivotFields = this.pivotFieldsFromAllOf(items.allOf);
+				if (pivotFields !== void 0) relation.pivotFields = pivotFields;
+				return relation;
+			}
+			if (Array.isArray(items.anyOf)) return {
+				cardinality: "many",
+				types: this.constsFromRefs(items.anyOf),
+				pivot: false
+			};
+			return;
+		}
+		if (Array.isArray(data.anyOf)) {
+			const types = [];
+			let pivot = false;
+			let pivotFields;
+			for (const entry of data.anyOf) if (typeof entry.$ref === "string") {
+				const type = this.resolveConst(entry.$ref);
+				if (type !== void 0) types.push(type);
+			} else if (Array.isArray(entry.allOf)) {
+				const type = this.constFromAllOf(entry.allOf);
+				if (type !== void 0) {
+					types.push(type);
+					pivot = true;
+					pivotFields = this.pivotFieldsFromAllOf(entry.allOf);
+				}
+			} else if (Array.isArray(entry.anyOf)) types.push(...this.constsFromRefs(entry.anyOf));
+			if (types.length === 0) return;
+			const relation = {
+				cardinality: "one",
+				types,
+				pivot
+			};
+			if (pivotFields !== void 0) relation.pivotFields = pivotFields;
+			return relation;
+		}
+	}
+	/**
+	* Extract the pivot field-shape from a pivot `allOf` — the entry carrying
+	* `properties.meta.properties.pivot.properties` (a `belongsToMany` member's `meta.pivot`), as a
+	* field-name → wire-format-hint map (D33). Returns `undefined` when the allOf carries no pivot
+	* property block.
+	*/
+	pivotFieldsFromAllOf(allOf) {
+		for (const entry of allOf) {
+			const meta = entry.properties?.["meta"];
+			const pivot = isSchema$1(meta) ? meta.properties?.["pivot"] : void 0;
+			const props = isSchema$1(pivot) ? pivot.properties : void 0;
+			if (props === void 0) continue;
+			const out = {};
+			for (const [name, schema] of Object.entries(props)) if (isSchema$1(schema)) out[name] = formatHint(schema);
+			return Object.keys(out).length > 0 ? sortRecord(out) : void 0;
+		}
+	}
+	/** Pull the related type from the `$ref` entry of an `allOf` (the pivot shape). */
+	constFromAllOf(allOf) {
+		for (const entry of allOf) if (typeof entry.$ref === "string") {
+			const type = this.resolveConst(entry.$ref);
+			if (type !== void 0) return type;
+		}
+	}
+	/** Resolve every `$ref` entry in a list to its wire type. */
+	constsFromRefs(entries) {
+		const types = [];
+		for (const entry of entries) if (typeof entry.$ref === "string") {
+			const type = this.resolveConst(entry.$ref);
+			if (type !== void 0) types.push(type);
+		}
+		return types;
+	}
+	clientId(base) {
+		const create = this.schemas[`${base}CreateRequest`];
+		const data = isSchema$1(create?.properties?.["data"]) ? create.properties["data"] : void 0;
+		if (data === void 0) return "forbidden";
+		if (data.properties?.["id"] === false) return "forbidden";
+		return data.required?.includes("id") ? "required" : "optional";
+	}
+	/**
+	* Find the collection path for a type, then derive each per-operation path that
+	* actually exists. The collection path P is the one whose POST requestBody refs
+	* `<Base>CreateRequest`, else the GET whose 200 response refs `<Base>Collection`.
+	*/
+	operationPaths(base) {
+		const collection = this.collectionPath(base);
+		const out = {};
+		if (collection === void 0) return out;
+		if (this.operation(collection, "get")) out["fetchMany"] = collection;
+		if (this.operation(collection, "post")) out["create"] = collection;
+		const item = `${collection}/{id}`;
+		if (this.operation(item, "get")) out["fetchOne"] = item;
+		if (this.operation(item, "patch")) out["update"] = item;
+		if (this.operation(item, "delete")) out["delete"] = item;
+		if (this.hasRelatedPath(collection)) out["fetchRelated"] = `${collection}/{id}/{rel}`;
+		if (this.hasRelationshipPath(collection)) out["fetchRelationship"] = `${collection}/{id}/relationships/{rel}`;
+		return sortRecord(out);
+	}
+	collectionPath(base) {
+		let byCollection;
+		for (const [path, item] of Object.entries(this.paths)) {
+			const post = item.post;
+			if (post && refEndsWith(this.requestBodyRef(post), `${base}CreateRequest`)) return path;
+			if (byCollection === void 0 && !path.includes("/{id}/") && refEndsWith(this.okResponseRef(item.get), `${base}Collection`)) byCollection = path;
+		}
+		return byCollection;
+	}
+	/** Any `P/{id}/<rel>` related path (excludes relationships/ and custom `-actions`). */
+	hasRelatedPath(collection) {
+		const prefix = `${collection}/{id}/`;
+		return Object.keys(this.paths).some((path) => {
+			if (!path.startsWith(prefix)) return false;
+			const rest = path.slice(prefix.length);
+			return rest.length > 0 && !rest.includes("/") && !rest.startsWith("-");
+		});
+	}
+	hasRelationshipPath(collection) {
+		const prefix = `${collection}/{id}/relationships/`;
+		return Object.keys(this.paths).some((path) => path.startsWith(prefix) && !path.slice(prefix.length).includes("/"));
+	}
+	/** Detect the paginator kind from the fetchMany operation's query parameter names. */
+	paginator(base) {
+		const collection = this.collectionPath(base);
+		return this.paginatorKindOf(this.operation(collection ?? "", "get"), collection);
+	}
+	/**
+	* Detect the paginator kind an operation advertises from its `page[...]` query parameter names.
+	* `page[number]`+`page[size]` = `page`; `page[offset]`+`page[limit]` = `offset`; either cursor
+	* bound (`page[after]`/`page[before]`) = `cursor` (link-driven, D44); anything else = `none`.
+	* `label` (a path, for the drift warning) names the endpoint when page params match no known kind.
+	*/
+	paginatorKindOf(op, label) {
+		const names = this.queryParamNames(op);
+		if (names.has("page[number]") && names.has("page[size]")) return "page";
+		if (names.has("page[offset]") && names.has("page[limit]")) return "offset";
+		if (names.has("page[after]") || names.has("page[before]")) return "cursor";
+		if (label !== void 0 && [...names].some((name) => name.startsWith("page["))) console.warn(`json-api codegen: endpoint "${label}" advertises page parameters matching no known paginator kind; treating it as unpaginated.`);
+		return "none";
+	}
+	/**
+	* The `withCount` capability (Countable profile) for a type's COLLECTION read (`list`): the
+	* count tokens (`schema.items.enum`) + the negotiation profile (`x-profile`) carried by the
+	* collection GET's `withCount` query parameter. Returns `undefined` when the collection
+	* doesn't exist or advertises no `withCount`. The profile URI is never hardcoded — it is read
+	* from the parameter's `x-profile`.
+	*
+	* Deliberately scoped to the collection GET only. The per-endpoint token sets differ
+	* (a collection counts e.g. `tracks`; a related/relationship endpoint counts `_self_` and its
+	* own relations), so a single per-type `countable` can only honestly describe one endpoint.
+	* The fluent surface exposes `withCount` on `list` (the collection), so `countable` mirrors
+	* that endpoint — a related-GET fallback would advertise tokens `list` cannot legally send.
+	*/
+	countable(collection) {
+		if (collection === void 0) return;
+		return withCountParam(this.operation(collection, "get"));
+	}
+	/**
+	* The relation paths the read endpoints accept in `include` — the `include` query
+	* parameter's `schema.items.enum` (already including nested dotted paths) on the collection
+	* GET. Returns `undefined` when the collection advertises no `include` (nothing includable).
+	*
+	* Read from the collection GET to mirror {@see sortable}/{@see filterable}: the whole builder
+	* is collection-centric (a type with no collection path gets no `paths` at all), and the bundle
+	* advertises the same `include` enum on the collection and single-resource GETs.
+	*/
+	includable(collection) {
+		if (collection === void 0) return;
+		const tokens = paramItemsEnum(this.operation(collection, "get"), "include");
+		return tokens !== void 0 && tokens.length > 0 ? tokens : void 0;
+	}
+	/**
+	* The sort tokens the COLLECTION read accepts — the `sort` query parameter's
+	* `schema.items.enum` (signed field names) on the collection GET. Returns `undefined` when
+	* the collection advertises no `sort` parameter (sorting unsupported).
+	*/
+	sortable(collection) {
+		if (collection === void 0) return;
+		const tokens = paramItemsEnum(this.operation(collection, "get"), "sort");
+		return tokens !== void 0 && tokens.length > 0 ? tokens : void 0;
+	}
+	/**
+	* The filter keys the COLLECTION read accepts in `filter[...]` (the `filter[<key>]` parameter
+	* names, `<key>` extracted), sorted for deterministic output. Returns `undefined` when the
+	* collection advertises no `filter[...]` parameters (filtering unsupported). Value shapes are
+	* deliberately not captured — `filter` values stay `unknown` (out of scope for v0.1).
+	*/
+	filterable(collection) {
+		if (collection === void 0) return;
+		const keys = [];
+		for (const param of this.operation(collection, "get")?.parameters ?? []) {
+			const name = param.name;
+			if (typeof name === "string" && name.startsWith("filter[") && name.endsWith("]")) keys.push(name.slice(7, -1));
+		}
+		return keys.length > 0 ? keys.sort() : void 0;
+	}
+	queryParamNames(op) {
+		const names = /* @__PURE__ */ new Set();
+		for (const param of op?.parameters ?? []) if (typeof param.name === "string") names.add(param.name);
+		return names;
+	}
+	operation(path, method) {
+		return this.paths[path]?.[method];
+	}
+	requestBodyRef(op) {
+		return op?.requestBody?.content?.["application/vnd.api+json"]?.schema?.$ref;
+	}
+	okResponseRef(op) {
+		return op?.responses?.["200"]?.content?.["application/vnd.api+json"]?.schema?.$ref;
+	}
+};
+/** A schema's wire format hint: explicit `format`, else the JSON type, else a ref-enum is `string`. */
+function formatHint(schema) {
+	if (typeof schema.format === "string") return schema.format;
+	const types = typeKeys(schema.type);
+	if (types.length > 0) return types[0];
+	if (typeof schema.$ref === "string") return "string";
+	return "unknown";
+}
+function refEndsWith(ref, suffix) {
+	return ref !== void 0 && refName$1(ref) === suffix;
+}
+/**
+* Read the {@link CountableDescriptor} off an operation's `withCount` query parameter: the
+* count tokens from its `schema.items.enum` and the negotiation profile from `x-profile`.
+* Returns `undefined` when the operation has no `withCount` parameter, or when one is present
+* but carries no `x-profile` (a `withCount` we can't tell a client how to negotiate). An empty
+* or absent token enum yields `[]` tokens (the profile alone is still actionable).
+*/
+function withCountParam(op) {
+	for (const param of op?.parameters ?? []) {
+		if (param.name !== "withCount") continue;
+		const profile = param["x-profile"];
+		if (typeof profile !== "string") return;
+		const enumValues = param.schema?.items?.enum;
+		return {
+			tokens: Array.isArray(enumValues) ? enumValues.filter((v) => typeof v === "string") : [],
+			profile
+		};
+	}
+}
+/**
+* The string members of an array-valued query parameter's `schema.items.enum` (the shape the
+* `include` and `sort` parameters use). Returns `undefined` when the operation carries no
+* parameter of that name, or one whose schema declares no enum.
+*/
+function paramItemsEnum(op, paramName) {
+	for (const param of op?.parameters ?? []) {
+		if (param.name !== paramName) continue;
+		const enumValues = param.schema?.items?.enum;
+		return Array.isArray(enumValues) ? enumValues.filter((v) => typeof v === "string") : void 0;
+	}
+}
+/**
+* True for the Atomic Operations ext media type — `application/vnd.api+json` carrying the
+* atomic `ext` parameter ({@link ATOMIC_EXT}). Tolerant of quoting/whitespace so any of
+* `ext="…"` / `ext=…` matches.
+*/
+function isAtomicMediaType(mediaType) {
+	return mediaType.startsWith(JSON_API_MEDIA_TYPE$1) && mediaType.includes(ATOMIC_EXT);
+}
+/** The HTTP methods an action operation may be advertised under, in resolution preference order. */
+const ACTION_METHODS = [
+	"post",
+	"get",
+	"put",
+	"patch",
+	"delete"
+];
+/**
+* The single operation an action is invoked over: POST when advertised (the common default), else
+* the first advertised method. `undefined` when the path item carries no operation at all.
+*/
+function pickOperation(item) {
+	const available = ACTION_METHODS.filter((method) => item[method] !== void 0);
+	const method = available.includes("post") ? "post" : available[0];
+	if (method === void 0) return;
+	const op = item[method];
+	return op === void 0 ? void 0 : {
+		method,
+		op
+	};
+}
+/** The body shape a custom action accepts: a JSON:API document, none, or a raw payload. */
+function actionInput(op) {
+	const content = op.requestBody?.content;
+	if (content === void 0 || Object.keys(content).length === 0) return "none";
+	return JSON_API_MEDIA_TYPE$1 in content ? "document" : "raw";
+}
+/** The `$ref` of an action's JSON:API request body (a `document` input), or `undefined`. */
+function actionRequestRef(op) {
+	const ref = op.requestBody?.content?.[JSON_API_MEDIA_TYPE$1]?.schema?.$ref;
+	return typeof ref === "string" ? ref : void 0;
+}
+/** The declared media type of a `raw`-input action — the first non-JSON:API content type. */
+function rawContentType(op) {
+	const content = op.requestBody?.content;
+	if (content === void 0) return;
+	return Object.keys(content).find((mediaType) => mediaType !== JSON_API_MEDIA_TYPE$1);
+}
+/**
+* What a custom action returns from its first 2xx response: a `meta`-only document (a `$ref` to the
+* shared `MetaDocument` — no `data`), a resource `document` (any other JSON:API body), or `none`
+* (only a `204`).
+*/
+function actionOutput(op) {
+	for (const [code, response] of Object.entries(op.responses ?? {})) {
+		if (!code.startsWith("2")) continue;
+		const schema = response.content?.[JSON_API_MEDIA_TYPE$1]?.schema;
+		if (schema === void 0) continue;
+		return typeof schema.$ref === "string" && refName$1(schema.$ref) === "MetaDocument" ? "meta" : "document";
+	}
+	return "none";
+}
+/** Build the {@link ApiDescriptor} from a parsed OpenAPI document. */
+function buildDescriptor(doc) {
+	return new DescriptorBuilder(doc).build();
+}
+/** Detect the server-level Atomic Operations capability (`null` when none). */
+function buildAtomic(doc) {
+	return new DescriptorBuilder(doc).buildAtomic();
+}
+//#endregion
+//#region src/provenance.ts
+/**
+* Canonicalise a JSON value with object keys sorted recursively, so the content hash is
+* insensitive to key ordering in the served document (two byte-different-but-equivalent
+* specs hash the same). Arrays keep their order (it is significant in OpenAPI).
+*/
+function canonicalise(value) {
+	if (Array.isArray(value)) return value.map(canonicalise);
+	if (value !== null && typeof value === "object") {
+		const out = {};
+		for (const key of Object.keys(value).sort()) out[key] = canonicalise(value[key]);
+		return out;
+	}
+	return value;
+}
+/** A SHA-256 over an arbitrary JSON value (canonicalised), truncated to 16 hex chars (64 bits). */
+function hashJson(value) {
+	return createHash("sha256").update(JSON.stringify(canonicalise(value))).digest("hex").slice(0, 16);
+}
+/**
+* Derive the provenance record for a source OpenAPI document. The `source` identifier is
+* `<info.title> <info.version>` (each part `unknown` when absent); the `hash` is a stable
+* content hash of the whole document.
+*/
+function deriveProvenance(doc) {
+	return {
+		source: `${doc.info?.title ?? "unknown"} ${doc.info?.version ?? "unknown"}`,
+		server: doc.servers?.[0]?.url,
+		hash: hashJson(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
+* 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}`);
+	return lines;
+}
+//#endregion
+//#region src/emit.ts
+const REF_PREFIX = "#/components/schemas/";
+const JSON_API_MEDIA_TYPE = "application/vnd.api+json";
+/** A loose JSON:API document shape — the fallback an action body/result types as when its component can't be resolved. */
+const LOOSE_DOCUMENT = "Record<string, unknown>";
+/**
+* The reserved relation names: the members the read handle actually shadows (kept in sync
+* via the runtime's {@link HANDLE_RESERVED}) plus the future Phase-3 write verbs. A relation
+* named like any of these must route through `.rel(name)`, so the codegen warns at build time.
+* (`type`/`id` from {@link HANDLE_RESERVED} can never be JSON:API relation names.)
+*/
+const RESERVED_VERBS = /* @__PURE__ */ new Set([
+	...HANDLE_RESERVED,
+	"update",
+	"delete",
+	"create",
+	"list",
+	"actions"
+]);
+/**
+* Find relations whose name shadows a reserved fluent-surface member (a handle accessor or a
+* future write verb). Such relations are routed via `.rel(name)`; the codegen warns at build time.
+*/
+function detectVerbCollisions(descriptor) {
+	const collisions = [];
+	for (const type of Object.keys(descriptor)) for (const relation of Object.keys(descriptor[type].relations)) if (RESERVED_VERBS.has(relation)) collisions.push({
+		type,
+		relation
+	});
+	return collisions;
+}
+function refName(ref) {
+	return ref.startsWith(REF_PREFIX) ? ref.slice(21) : void 0;
+}
+function isSchema(value) {
+	return typeof value === "object" && value !== null;
+}
+/** PascalCase a JSON:API wire type for use in a TS identifier (e.g. `public-profiles` -> `PublicProfiles`). */
+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);
+}
+/**
+* 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
+* description can never terminate the comment early.
+*/
+function jsDoc(text, indent) {
+	const trimmed = text?.trim();
+	if (!trimmed) return;
+	const lines = trimmed.replace(/\*\//g, "* /").split("\n");
+	if (lines.length === 1) return `${indent}/** ${lines[0]} */`;
+	return [
+		`${indent}/**`,
+		...lines.map((line) => `${indent} * ${line}`.trimEnd()),
+		`${indent} */`
+	].join("\n");
+}
+var Emitter = class {
+	doc;
+	descriptor;
+	atomic;
+	schemas;
+	/** Wire type -> the schema `Base` (the `<Base>Resource` name minus `Resource`). */
+	baseByType;
+	/** Enum component names referenced by an attribute, in first-seen order. */
+	usedEnums = /* @__PURE__ */ new Map();
+	/**
+	* Component-schema names whose dedicated interface is emitted (e.g. `AlbumsAttributes`,
+	* `AlbumsCreateAttributes`). A `$ref` to one of these resolves to the interface name
+	* rather than being re-expanded structurally — so an action envelope nests the precise,
+	* already-named attribute type. Populated as interfaces are emitted.
+	*/
+	emittedInterfaces = /* @__PURE__ */ new Set();
+	/** Component names mid-expansion in {@link tsType} — a cycle guard for self/mutually-referential `$ref`s. */
+	expanding = /* @__PURE__ */ new Set();
+	/**
+	* The per-action alias names actually emitted, keyed `type -> actionName -> { input?; output? }`.
+	* Populated by {@link actionTypeAliases}; consumed by {@link actionTypesMap} so the action
+	* type-map only references aliases that exist (a `none` input/output contributes neither).
+	*/
+	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;
+		this.descriptor = descriptor;
+		this.atomic = atomic;
+		this.schemas = doc.components?.schemas ?? {};
+		this.baseByType = this.indexBases();
+		this.provenance = deriveProvenance(doc);
+	}
+	/** Map each declared wire type back to the `Base` of its resource schema. */
+	indexBases() {
+		const out = /* @__PURE__ */ new Map();
+		for (const [name, schema] of Object.entries(this.schemas)) {
+			if (!name.endsWith("Resource") || name.endsWith("ResourceIdentifier")) continue;
+			const typeProp = schema.properties?.["type"];
+			if (isSchema(typeProp) && typeof typeProp.const === "string") out.set(typeProp.const, name.slice(0, -8));
+		}
+		return out;
+	}
+	emit() {
+		const interfaces = Object.keys(this.descriptor).map((type) => this.attributeInterface(type));
+		const writeInterfaces = Object.keys(this.descriptor).flatMap((type) => this.writeAttributeInterfaces(type));
+		const actionAliases = this.actionTypeAliases();
+		const enums = this.enumAliases();
+		return `${[
+			this.header(),
+			this.imports(),
+			...enums ? [enums] : [],
+			...interfaces,
+			...writeInterfaces,
+			...actionAliases,
+			this.attributesMap(),
+			this.writeAttributesMap(),
+			this.actionTypesMap(),
+			this.resourceMap(),
+			"export type ResourceMap = typeof resourceMap",
+			this.atomicConst(),
+			this.boundFactory()
+		].join("\n\n")}\n`;
+	}
+	header() {
+		return [
+			"/**",
+			" * AUTO-GENERATED by @haddowg/json-api-codegen — do not edit by hand.",
+			" * Regenerate from the source OpenAPI document instead.",
+			" *",
+			...provenanceLines(this.provenance),
+			" */"
+		].join("\n");
+	}
+	imports() {
+		return [
+			"import {",
+			"  type ApiDescriptor,",
+			"  type ClientOptions,",
+			"  createClient as createClientRuntime,",
+			"} from '@haddowg/json-api-client'"
+		].join("\n");
+	}
+	/** Per-type attribute interface, e.g. `export interface AlbumsAttributes { ... }`. */
+	attributeInterface(type) {
+		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);
+	}
+	/**
+	* The per-type WRITE attribute interfaces — `<Pascal>CreateAttributes` and
+	* `<Pascal>UpdateAttributes` — from the `<Base>CreateAttributes`/`<Base>UpdateAttributes`
+	* components (readOnly fields are already excluded vs the read attributes by the bundle).
+	* Create marks a field required iff it sits in the component's `required`; Update makes
+	* every field optional. A read-only type (no create/update component) contributes nothing.
+	*/
+	writeAttributeInterfaces(type) {
+		const base = this.baseByType.get(type);
+		if (base === void 0) return [];
+		const pascal = pascalCase(type);
+		const out = [];
+		const create = this.schemas[`${base}CreateAttributes`];
+		if (create !== void 0) {
+			const required = new Set(create.required ?? []);
+			const fields = Object.keys(create.properties ?? {}).sort();
+			out.push(this.renderInterface(`${pascal}CreateAttributes`, create.properties, fields, (field) => required.has(field)));
+		}
+		const update = this.schemas[`${base}UpdateAttributes`];
+		if (update !== void 0) {
+			const fields = Object.keys(update.properties ?? {}).sort();
+			out.push(this.renderInterface(`${pascal}UpdateAttributes`, update.properties, fields, () => false));
+		}
+		return out;
+	}
+	/**
+	* Per-action input/output type aliases for every type that declares custom actions. An
+	* action whose `input`/`output` resolves to a component schema gets a named alias
+	* (`<Pascal><Action>Input` / `<Pascal><Action>Output`) expanding that component via the
+	* shared {@link tsType} machinery — a `none` input/output (no body / a `204`) contributes
+	* no alias. Deterministic order: types, then action names (the descriptor is sorted).
+	*/
+	actionTypeAliases() {
+		const out = [];
+		for (const type of Object.keys(this.descriptor)) {
+			const actions = this.descriptor[type]?.actions;
+			if (actions === void 0) continue;
+			const pascal = pascalCase(type);
+			for (const [actionName, action] of Object.entries(actions)) {
+				const member = `${pascal}${pascalCase(actionName)}`;
+				const names = {};
+				const inputType = this.actionBodyType(action, "input");
+				if (inputType !== void 0) {
+					out.push(`export type ${member}Input = ${inputType}`);
+					names.input = `${member}Input`;
+				}
+				const outputType = this.actionBodyType(action, "output");
+				if (outputType !== void 0) {
+					out.push(`export type ${member}Output = ${outputType}`);
+					names.output = `${member}Output`;
+				}
+				if (names.input !== void 0 || names.output !== void 0) {
+					let byAction = this.actionAliasNames.get(type);
+					if (byAction === void 0) {
+						byAction = /* @__PURE__ */ new Map();
+						this.actionAliasNames.set(type, byAction);
+					}
+					byAction.set(actionName, names);
+				}
+			}
+		}
+		return out;
+	}
+	/**
+	* Emit the `ActionTypes` interface wiring the emitted per-action aliases onto the typed
+	* action surface — `type -> actionName -> { input?; output? }`, the client's fourth type
+	* argument. So `client.albums.id(id).actions.reissue(body)` takes `AlbumsReissueInput` and
+	* resolves `AlbumsReissueOutput` rather than a loose `Record<string,unknown>` / `unknown`.
+	* Only actions whose alias was emitted appear (a `none`-input/output action contributes the
+	* absent side, which the runtime types fall back to loosely). Emits `{}` when none exist.
+	*/
+	actionTypesMap() {
+		const typeLines = [];
+		for (const type of Object.keys(this.descriptor)) {
+			const byAction = this.actionAliasNames.get(type);
+			if (byAction === void 0 || byAction.size === 0) continue;
+			const actionLines = [];
+			for (const [actionName, names] of byAction) {
+				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("; ")} }`);
+			}
+			typeLines.push(`  ${objectKey(type)}: {\n${actionLines.join("\n")}\n  }`);
+		}
+		if (typeLines.length === 0) return "export interface ActionTypes {}";
+		return `export interface ActionTypes {\n${typeLines.join("\n")}\n}`;
+	}
+	/**
+	* The TS type alias (if any) for an action's request body.
+	*
+	* An action's RESULT and its FLAT input are derived at the type level from the descriptor
+	* (`outputType`/`outputCardinality` → the materialised resource view; `inputType` → the
+	* `CreateInput` of that type), so no `output` alias is emitted and a `document` input whose
+	* resource type resolves emits no `input` alias either. Only a bespoke command document (a
+	* `document` input with no resolvable `inputType`) keeps a raw-envelope alias as its typed body,
+	* expanded via {@link tsType} (falling back to a loose JSON:API document shape).
+	*/
+	actionBodyType(action, side) {
+		if (side === "output" || action.input !== "document" || action.inputType !== void 0) return;
+		const ref = (this.doc.paths?.[action.path]?.post)?.requestBody?.content?.[JSON_API_MEDIA_TYPE]?.schema?.$ref;
+		if (typeof ref !== "string") return LOOSE_DOCUMENT;
+		const target = refName(ref);
+		const resolved = target ? this.schemas[target] : void 0;
+		return resolved ? this.tsType(resolved) : LOOSE_DOCUMENT;
+	}
+	/** Emit the server-level atomic capability constant (`{ path }` or `null`). */
+	atomicConst() {
+		return `${[
+			"/**",
+			" * The server-level Atomic Operations endpoint (the atomic ext media type), or `null`",
+			" * when this server exposes none. The runtime `client.atomic` builder posts the batch here.",
+			" */"
+		].join("\n")}\nexport const atomic = ${this.atomic === null ? "null" : `${this.literal(this.atomic, 0)} as const`}`;
+	}
+	/**
+	* Render an attribute interface from a property map, a field order, and a `required`
+	* predicate (true => no `?`). Shared by the read and write attribute interfaces so the
+	* tsType/JSDoc logic stays in one place.
+	*/
+	renderInterface(name, props, fields, required) {
+		const lines = [];
+		for (const field of fields) {
+			const schema = props?.[field];
+			const tsType = isSchema(schema) ? this.tsType(schema) : "unknown";
+			const doc = isSchema(schema) ? jsDoc(schema.description, "  ") : void 0;
+			if (doc) lines.push(doc);
+			const optional = required(field) ? "" : "?";
+			lines.push(`  ${objectKey(field)}${optional}: ${tsType}`);
+		}
+		this.emittedInterfaces.add(name);
+		if (lines.length === 0) return `export interface ${name} {}`;
+		return `export interface ${name} {\n${lines.join("\n")}\n}`;
+	}
+	/** Map a JSON Schema attribute node to a precise TypeScript type. */
+	tsType(schema) {
+		if (typeof schema.$ref === "string") {
+			const target = refName(schema.$ref);
+			const resolved = target ? this.schemas[target] : void 0;
+			if (target && resolved && Array.isArray(resolved.enum)) {
+				this.usedEnums.set(target, resolved);
+				return target;
+			}
+			if (target && this.emittedInterfaces.has(target)) return target;
+			if (resolved === void 0 || target === void 0 || this.expanding.has(target)) return "unknown";
+			this.expanding.add(target);
+			const expanded = this.tsType(resolved);
+			this.expanding.delete(target);
+			return expanded;
+		}
+		const types = Array.isArray(schema.type) ? schema.type : schema.type ? [schema.type] : [];
+		const nullable = types.includes("null");
+		const base = this.baseTsType(schema, types.filter((t) => t !== "null"));
+		return nullable ? `${base} | null` : base;
+	}
+	/** 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 (types.length === 0) return "unknown";
+		const mapped = types.map((t) => this.scalarOrComposite(schema, t));
+		return [...new Set(mapped)].join(" | ");
+	}
+	scalarOrComposite(schema, type) {
+		switch (type) {
+			case "string": return "string";
+			case "number":
+			case "integer": return "number";
+			case "boolean": return "boolean";
+			case "object": return this.objectType(schema);
+			case "array": return this.arrayType(schema);
+			default: return "unknown";
+		}
+	}
+	/** A nested object type from its `properties` (falls back to an index signature). */
+	objectType(schema) {
+		const props = schema.properties;
+		if (props === void 0) return "Record<string, unknown>";
+		const required = new Set(schema.required ?? []);
+		const members = [];
+		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)}`);
+		}
+		if (members.length === 0) return "Record<string, unknown>";
+		return `{ ${members.join("; ")} }`;
+	}
+	arrayType(schema) {
+		const items = schema.items;
+		const element = isSchema(items) ? this.tsType(items) : "unknown";
+		return /[|&]/.test(element) ? `(${element})[]` : `${element}[]`;
+	}
+	/** Union aliases for every enum component an attribute referenced, sorted by name. */
+	enumAliases() {
+		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 doc = jsDoc(this.enumDoc(schema), "");
+			return doc ? `${doc}\n${alias}` : alias;
+		}).join("\n\n");
+	}
+	/**
+	* Documentation for an enum alias: a per-value list built from `x-enum-descriptions`
+	* (the richest hover DX, since a union alias can't carry per-member JSDoc), falling
+	* back to the component's own `description`.
+	*/
+	enumDoc(schema) {
+		const values = schema.enum ?? [];
+		const descriptions = schema["x-enum-descriptions"];
+		if (Array.isArray(descriptions) && descriptions.length === values.length && values.length > 0) return values.map((value, i) => `- \`${String(value)}\` — ${String(descriptions[i])}`).join("\n");
+		return schema.description;
+	}
+	/**
+	* Emit the `Attributes` interface mapping each wire type to its per-type attribute
+	* interface. The runtime descriptor only carries coarse format hints; this is how the
+	* precise per-type attribute types reach the bound client (passed as the second type
+	* 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}`;
+	}
+	/**
+	* Emit the `WriteAttributes` interface mapping each writable wire type to its
+	* `{ create; update }` attribute pair. A read-only type (no create/update component)
+	* contributes no entry, so the bound client only exposes writes where the API allows
+	* them. Passed as the third type argument to the runtime factory.
+	*/
+	writeAttributesMap() {
+		const lines = [];
+		for (const type of Object.keys(this.descriptor)) {
+			const base = this.baseByType.get(type);
+			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 members = [];
+			if (hasCreate) members.push(`create: ${pascal}CreateAttributes`);
+			if (hasUpdate) members.push(`update: ${pascal}UpdateAttributes`);
+			lines.push(`  ${objectKey(type)}: { ${members.join("; ")} }`);
+		}
+		if (lines.length === 0) return "export interface WriteAttributes {}";
+		return `export interface WriteAttributes {\n${lines.join("\n")}\n}`;
+	}
+	/** Emit the descriptor as a literal `as const satisfies ApiDescriptor`. */
+	resourceMap() {
+		return `export const resourceMap = ${this.literal(this.descriptor, 0)} as const satisfies ApiDescriptor`;
+	}
+	/** Render a JSON-serialisable descriptor value as deterministic TS object-literal source. */
+	literal(value, depth) {
+		const indent = "  ".repeat(depth);
+		const inner = "  ".repeat(depth + 1);
+		if (Array.isArray(value)) {
+			if (value.length === 0) return "[]";
+			return `[\n${value.map((item) => `${inner}${this.literal(item, depth + 1)}`).join(",\n")}\n${indent}]`;
+		}
+		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 JSON.stringify(value);
+	}
+	boundFactory() {
+		return [
+			"/**",
+			" * Descriptor-bound client factory; wraps the generic runtime with this API’s `resourceMap`.",
+			" * The server-level `atomic` capability is threaded in by default so `client.atomic` is wired",
+			" * (a caller may still override it via `options.atomic`).",
+			" */",
+			"export const createClient = (options: ClientOptions) =>",
+			"  createClientRuntime<typeof resourceMap, Attributes, WriteAttributes, ActionTypes>(",
+			"    resourceMap,",
+			"    {",
+			"      atomic,",
+			"      ...options,",
+			"    },",
+			"  )"
+		].join("\n");
+	}
+};
+/**
+* Generate the full source of the client module for a document + its built descriptor.
+* The server-level atomic capability is derived from the document (override via `atomic`).
+*/
+function emit(doc, descriptor, atomic = buildAtomic(doc)) {
+	return new Emitter(doc, descriptor, atomic).emit();
+}
+//#endregion
+//#region src/emit-schemas.ts
+/**
+* Emit the per-type JSON Schema map as a standalone generated artifact:
+*
+* ```ts
+* export const schemas = { <type>: { …json schema… }, … } as const
+* ```
+*
+* The values are the raw, self-contained resource-object JSON Schema documents the bundle
+* serves at `GET /schemas.json` — suitable to hand straight to a validation engine via the
+* opt-in `validate?` seam (ADR 0004). This is a separate file from the client so the main
+* descriptor/client output is unaffected when `--schemas` is absent.
+*
+* The schemas are emitted as JSON (deterministic, key order preserved) so the artifact is
+* stable to diff; `as const` keeps the literal shapes narrow.
+*/
+function emitSchemas(bundle) {
+	return `${[header(bundle), body(bundle)].join("\n\n")}\n`;
+}
+function header(bundle) {
+	return [
+		"/**",
+		" * AUTO-GENERATED by @haddowg/json-api-codegen — do not edit by hand.",
+		" * Per-type JSON Schemas for the opt-in validation seam; regenerate from the source bundle.",
+		" *",
+		` * Schema hash: ${hashJson(bundle)}`,
+		" */"
+	].join("\n");
+}
+function body(bundle) {
+	return `export const schemas = ${JSON.stringify(bundle, null, 2)} as const`;
+}
+//#endregion
+//#region src/reader.ts
+/** True when the input looks like an http(s) URL rather than a local path. */
+function isHttpUrl(input) {
+	return /^https?:\/\//i.test(input);
+}
+/** Decide YAML vs JSON by extension first, then by a cheap content sniff. */
+function looksLikeYaml(source, text) {
+	if (/\.ya?ml$/i.test(source)) return true;
+	if (/\.json$/i.test(source)) return false;
+	return !/^\s*[{[]/.test(text);
+}
+function parse$1(source, text, label) {
+	const doc = looksLikeYaml(source, text) ? parse(text) : JSON.parse(text);
+	if (doc === null || typeof doc !== "object") throw new Error(`${label} at ${source} did not parse to an object`);
+	return doc;
+}
+/**
+* Fetch (URL) or read (file) `input`, then parse it as JSON or YAML (decided by extension,
+* falling back to a content sniff). Shared by the OpenAPI and JSON Schema readers.
+*/
+async function readSource(input, label) {
+	if (isHttpUrl(input)) {
+		const res = await fetch(input);
+		if (!res.ok) throw new Error(`Failed to fetch ${label} from ${input}: ${res.status}`);
+		return parse$1(input, await res.text(), label);
+	}
+	return parse$1(input, await readFile(input, "utf8"), label);
+}
+/**
+* Read an OpenAPI document from an http(s) URL or a local file path. Supports both JSON
+* and YAML (decided by extension, falling back to a content sniff).
+*/
+async function readDocument(input) {
+	return readSource(input, "OpenAPI document");
+}
+/**
+* Read the bundle's JSON Schema bundle (`GET /schemas.json`) from an http(s) URL or a
+* local file path — a map keyed by JSON:API type, each value a self-contained JSON Schema
+* 2020-12 resource-object document. Supports both JSON and YAML, like {@link readDocument}.
+*/
+async function readSchemas(input) {
+	return readSource(input, "JSON Schema bundle");
+}
+//#endregion
+//#region src/index.ts
+/**
+* @haddowg/json-api-codegen — reads the bundle's OpenAPI 3.1 document (from a URL or
+* a local file) and emits the runtime descriptor + derived types + a bound
+* `createClient` (ADR 0001). Optionally reads the bundle's JSON Schemas to wire the
+* opt-in validation seam.
+*
+* The spec is fully self-describing for our needs (see CONTEXT.md): type identity is
+* `properties.type.const`; relationships, cardinality and related types come from the
+* relationship components' `data`; allowed `?include` paths are a bounded, pre-expanded
+* enum per endpoint; the create client-id policy is encoded in the create request
+* schema (`id: false` / required / optional).
+*/
+/**
+* The schema-artifact path beside a client output path: `client.gen.ts` -> `client.schemas.gen.ts`
+* (any `.gen.ts`/`.ts` suffix is preserved; a suffix-less path just gains `.schemas`).
+*/
+function schemasOutputPath(output) {
+	if (output.endsWith(".gen.ts")) return `${output.slice(0, -7)}.schemas.gen.ts`;
+	if (output.endsWith(".ts")) return `${output.slice(0, -3)}.schemas.ts`;
+	return `${output}.schemas`;
+}
+/**
+* Read the source spec(s), build the descriptor and render every generated artifact in
+* memory (the client source first, then the schema artifact when `config.schemas` is set)
+* — the shared core of {@link generate} (which writes them) and {@link check} (which
+* compares them). Verb-collision warnings are emitted here so both paths surface them.
+*/
+async function render(config) {
+	const doc = await readDocument(config.input);
+	const descriptor = buildDescriptor(doc);
+	for (const { type, relation } of detectVerbCollisions(descriptor)) console.warn(`[json-api-codegen] "${type}" has a relation named "${relation}" which collides with a reserved verb on the resource handle; it will be reachable via .rel("${relation}") in the fluent client.`);
+	const artifacts = [{
+		path: config.output,
+		content: emit(doc, descriptor)
+	}];
+	if (config.schemas !== void 0) {
+		const bundle = await readSchemas(config.schemas);
+		artifacts.push({
+			path: schemasOutputPath(config.output),
+			content: emitSchemas(bundle)
+		});
+	}
+	return artifacts;
+}
+/**
+* Read the OpenAPI document, build the runtime descriptor, emit the generated client
+* module and write it to `config.output` (creating parent directories as needed).
+*
+* When `config.schemas` is set, also read the bundle's JSON Schema bundle and write a
+* separate per-type schema artifact (`<output>.schemas.gen.ts`) beside the client, wiring
+* the opt-in validation seam (ADR 0004). The main client output is unchanged either way.
+*
+* `config.server` is metadata-only for now: the served document is already per-server,
+* so the caller selects the server by pointing `input` at the right document.
+*
+* Returns the generated client source. When `config.check` is set nothing is written;
+* call {@link check} instead for the drift-gate result.
+*/
+async function generate(config) {
+	const artifacts = await render(config);
+	await mkdir(dirname(config.output), { recursive: true });
+	for (const { path, content } of artifacts) await writeFile(path, content, "utf8");
+	return artifacts[0].content;
+}
+/**
+* Drift gate: regenerate every artifact in memory and compare it byte-for-byte against the
+* committed file on disk, WITHOUT writing anything. A missing committed file counts as drift
+* (not up to date). Returns per-artifact status plus an aggregate `ok` (true iff all match) —
+* the CI drift check reads `ok` and exits non-zero when it is false.
+*/
+async function check(config) {
+	const artifacts = await render(config);
+	const results = [];
+	for (const { path, content } of artifacts) {
+		let committed;
+		try {
+			committed = await readFile(path, "utf8");
+		} catch {
+			committed = void 0;
+		}
+		results.push({
+			path,
+			upToDate: committed === content
+		});
+	}
+	return {
+		ok: results.every((r) => r.upToDate),
+		artifacts: results
+	};
+}
+//#endregion
+export { readSchemas as a, detectVerbCollisions as c, hashJson as d, provenanceLines as f, buildDescriptor as h, readDocument as i, emit as l, buildAtomic as m, generate as n, emitSchemas as o, DescriptorBuilder as p, schemasOutputPath as r, Emitter as s, check as t, deriveProvenance as u };
+
+//# sourceMappingURL=src-B24cYyjM.mjs.map