@haddowg/json-api-codegen 1.12.0 → 1.14.0

package/README.md

@@ -30,19 +30,23 @@ pnpm add -D @haddowg/json-api-codegen
 
 Two bin names are installed: `json-api-codegen` and the short alias `japi`.
 
+The codegen reads documents up to generator contract 18 (`info.x-generator.contract`). A newer
+document still generates, with a warning that the client may miss what the server added.
+
 ## CLI
 
 ```bash
-json-api-codegen --input <url|file> --output <file> [--server <name>] [--schemas <url|file>] [--check]
+json-api-codegen --input <url|file> --output <file> [--server <name>] [--schemas <url|file>] [--examples] [--check]
 ```
 
-| Flag        | Required | Description                                                                           |
-| ----------- | -------- | ------------------------------------------------------------------------------------- |
-| `--input`   | yes      | OpenAPI document source — an http(s) URL or a local file path (JSON or YAML).         |
-| `--output`  | yes      | Output file for the generated client (e.g. `src/api/music.gen.ts`).                   |
-| `--server`  | no       | Server name to target. Metadata-only — the served document is already per-server.     |
-| `--schemas` | no       | JSON Schema source (URL or path) for the validation seam. Omit to skip schema output. |
-| `--check`   | no       | Drift gate — regenerate in memory and exit non-zero if the committed output differs.  |
+| Flag         | Required | Description                                                                           |
+| ------------ | -------- | ------------------------------------------------------------------------------------- |
+| `--input`    | yes      | OpenAPI document source — an http(s) URL or a local file path (JSON or YAML).         |
+| `--output`   | yes      | Output file for the generated client (e.g. `src/api/music.gen.ts`).                   |
+| `--server`   | no       | Server name to target. Metadata-only — the served document is already per-server.     |
+| `--schemas`  | no       | JSON Schema source (URL or path) for the validation seam. Omit to skip schema output. |
+| `--examples` | no       | Also write the operations' worked examples to a sibling `.examples.gen.ts` module.    |
+| `--check`    | no       | Drift gate — regenerate in memory and exit non-zero if the committed output differs.  |
 
 Example — generate against a served API, with the validation schemas:
 
@@ -57,6 +61,8 @@ This writes:
 
 - `src/api/music.gen.ts` — the typed client (descriptor + types + bound `createClient`);
 - `src/api/music.schemas.gen.ts` — the per-type JSON Schema map (only with `--schemas`).
+- `src/api/music.examples.gen.ts` — each operation's worked examples (only with `--examples`, and
+  only when the document declares some).
 
 The schema artifact path is derived from `--output`: a `.gen.ts` suffix becomes `.schemas.gen.ts`,
 a plain `.ts` becomes `.schemas.ts`.
@@ -118,6 +124,10 @@ The output module exports:
 - `Attributes` / `WriteAttributes` — the per-type attribute maps (read vs create/update).
 - Per-type `…Attributes` / `…CreateAttributes` / `…UpdateAttributes` interfaces, enum types
   (e.g. `AlbumStatus`), and action input/output types.
+- `Links` — the typed declared links of each type that declares any.
+- `ErrorCodes` / `ErrorCode` / `ErrorCodeByStatus` / `hasErrorCode` — the server's documented
+  error codes and a type guard bound to them.
+- `pageLimits` — each collection's page defaults and page-size caps.
 
 With `--schemas`, the sibling module exports `schemas` — the per-type JSON Schema 2020-12 map.
 
@@ -162,8 +172,10 @@ if (!result.ok) process.exit(1)
 ```
 
 Lower-level building blocks are also exported for advanced use: `readDocument` / `readSchemas`,
-`buildDescriptor`, `emit`, `emitSchemas`, `detectVerbCollisions`, `schemasOutputPath`, and the
-provenance helpers `deriveProvenance` / `provenanceLines` / `hashJson`.
+`buildDescriptor`, `buildExamples`, `emit`, `emitSchemas`, `emitExamples`, `readErrorCatalogue`,
+`emitErrorCodes`, `checkContract`, `detectVerbCollisions`, `schemasOutputPath`,
+`examplesOutputPath`, and the provenance helpers `deriveProvenance` / `provenanceLines` /
+`hashJson`. `generateFiles(config)` generates like `generate` and returns the paths it wrote.
 
 ## License
 

package/dist/cli.d.mts

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

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { i as generateFiles, t as check } from "./src-D4apiVHe.mjs";
+import { i as generateFiles, t as check } from "./src-7yVCQTGQ.mjs";
 import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 //#region src/cli.ts

package/dist/{index-Ch2PJH9Y.d.mts → index-DQ_twN9s.d.mts}

@@ -169,9 +169,9 @@ declare class DescriptorBuilder {
    */
   private relationMutations;
   /**
-   * Attach the per-relation endpoint-exposure signal to a relation descriptor (D24). The bundle
+   * Attach the per-relation endpoint-exposure signal to a relation descriptor. The bundle
    * can suppress a relation's related or relationship endpoint (`withoutRelatedEndpoint()` /
-   * `withoutRelationshipEndpoint()`, ADR 0027), which the OpenAPI reflects by simply omitting that
+   * `withoutRelationshipEndpoint()`), 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
@@ -213,6 +213,12 @@ declare class DescriptorBuilder {
   private documentPrimary;
   /** The wire type of a single `data` schema — a `$ref` to a resource, or an inline `type.const`. */
   private dataConst;
+  /**
+   * The wire types a read's compound document can carry in `included`: the members of its
+   * document's `included.items` union. `undefined` when the document has no `included`, or types
+   * its items only as a generic `{type, id}` object.
+   */
+  private includedTypes;
   /** The `$ref` of the first 2xx JSON:API response body on an operation (the output document). */
   private firstOkJsonApiRef;
   /** Resolve a relationship component's `data` into a {@link RelationDescriptor}. */
@@ -233,6 +239,12 @@ declare class DescriptorBuilder {
   private pivotDescriptor;
   /** Pull the related type from the `$ref` entry of an `allOf` (the pivot shape). */
   private constFromAllOf;
+  /**
+   * The wire types of a union of `$ref`s: a `oneOf` discriminated by `type`, or the `anyOf` an
+   * older document writes. A member whose component carries no `type` const falls back to the
+   * discriminator mapping's key for its `$ref`. `undefined` when the schema is no union.
+   */
+  private unionTypes;
   /** Resolve every `$ref` entry in a list to its wire type. */
   private constsFromRefs;
   private clientId;
@@ -330,7 +342,7 @@ declare function buildExamples(doc: OpenApiDocument, descriptor: ApiDescriptor):
 /** 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 = 17;
+declare const MAXIMUM_CONTRACT = 19;
 /**
  * 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
@@ -397,6 +409,11 @@ declare class Emitter {
   emit(): string;
   private header;
   private imports;
+  /**
+   * The typed `included` of each read: a resource union discriminated by `type` over the types
+   * the document's typed `included` lists, or over every type when the document doesn't type it.
+   */
+  private includedAliases;
   /**
    * The links interface of a type that declares links, e.g. `ImagesLinks`: each declared link an
    * optional member, since the server leaves a link out when its href resolves to `null`. It
@@ -612,7 +629,7 @@ declare function readSchemas(input: string): Promise<SchemaBundle>;
  *
  * 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
+ * opt-in `validate?` seam. 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
@@ -697,8 +714,8 @@ declare function examplesOutputPath(output: string): string;
  *
  * 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.examples` writes the operation examples the same way (ADR 0011).
+ * the opt-in validation seam. The main client output is unchanged either way.
+ * `config.examples` writes the operation examples the same 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.
@@ -718,4 +735,4 @@ declare function generateFiles(config: CodegenConfig): Promise<string[]>;
 declare function check(config: CodegenConfig): Promise<CheckResult>;
 //#endregion
 export { operationExamples as A, PathItemObject as B, VerbCollision as C, MINIMUM_CONTRACT as D, MAXIMUM_CONTRACT as E, InfoObject as F, SecurityRequirement as G, ResponseObject as H, MediaTypeObject as I, SecuritySchemeObject as K, OpenApiDocument as L, buildAtomic as M, buildDescriptor as N, checkContract as O, HttpMethod as P, OperationObject as R, Emitter as S, emit as T, SchemaObject as U, RequestBodyObject as V, SchemaOrBool as W, emitExamples as _, examplesOutputPath as a, emitErrorCodes as b, schemasOutputPath as c, hashJson as d, provenanceLines as f, readSchemas as g, readDocument as h, check as i, DescriptorBuilder as j, buildExamples as k, Provenance as l, SchemaBundle as m, CheckResult as n, generate as o, emitSchemas as p, CodegenConfig as r, generateFiles as s, ArtifactDrift as t, deriveProvenance as u, DocumentedErrorCode as v, detectVerbCollisions as w, readErrorCatalogue as x, ErrorCatalogue as y, ParameterObject as z };
-//# sourceMappingURL=index-Ch2PJH9Y.d.mts.map
+//# sourceMappingURL=index-DQ_twN9s.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index-DQ_twN9s.d.mts","names":[],"sources":["../src/openapi.ts","../src/build-descriptor.ts","../src/build-examples.ts","../src/contract.ts","../src/emit.ts","../src/error-codes.ts","../src/emit-examples.ts","../src/reader.ts","../src/emit-schemas.ts","../src/provenance.ts","../src/index.ts"],"mappings":"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"}

package/dist/index.d.mts

@@ -1,2 +1,2 @@
-import { A as operationExamples, B as PathItemObject, C as VerbCollision, D as MINIMUM_CONTRACT, E as MAXIMUM_CONTRACT, F as InfoObject, G as SecurityRequirement, H as ResponseObject, I as MediaTypeObject, K as SecuritySchemeObject, L as OpenApiDocument, M as buildAtomic, N as buildDescriptor, O as checkContract, P as HttpMethod, R as OperationObject, S as Emitter, T as emit, U as SchemaObject, V as RequestBodyObject, W as SchemaOrBool, _ as emitExamples, a as examplesOutputPath, b as emitErrorCodes, c as schemasOutputPath, d as hashJson, f as provenanceLines, g as readSchemas, h as readDocument, i as check, j as DescriptorBuilder, k as buildExamples, l as Provenance, m as SchemaBundle, n as CheckResult, o as generate, p as emitSchemas, r as CodegenConfig, s as generateFiles, t as ArtifactDrift, u as deriveProvenance, v as DocumentedErrorCode, w as detectVerbCollisions, x as readErrorCatalogue, y as ErrorCatalogue, z as ParameterObject } from "./index-Ch2PJH9Y.mjs";
+import { A as operationExamples, B as PathItemObject, C as VerbCollision, D as MINIMUM_CONTRACT, E as MAXIMUM_CONTRACT, F as InfoObject, G as SecurityRequirement, H as ResponseObject, I as MediaTypeObject, K as SecuritySchemeObject, L as OpenApiDocument, M as buildAtomic, N as buildDescriptor, O as checkContract, P as HttpMethod, R as OperationObject, S as Emitter, T as emit, U as SchemaObject, V as RequestBodyObject, W as SchemaOrBool, _ as emitExamples, a as examplesOutputPath, b as emitErrorCodes, c as schemasOutputPath, d as hashJson, f as provenanceLines, g as readSchemas, h as readDocument, i as check, j as DescriptorBuilder, k as buildExamples, l as Provenance, m as SchemaBundle, n as CheckResult, o as generate, p as emitSchemas, r as CodegenConfig, s as generateFiles, t as ArtifactDrift, u as deriveProvenance, v as DocumentedErrorCode, w as detectVerbCollisions, x as readErrorCatalogue, y as ErrorCatalogue, z as ParameterObject } from "./index-DQ_twN9s.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 SecurityRequirement, type SecuritySchemeObject, type VerbCollision, buildAtomic, buildDescriptor, buildExamples, check, checkContract, deriveProvenance, detectVerbCollisions, emit, emitErrorCodes, emitExamples, emitSchemas, examplesOutputPath, generate, generateFiles, hashJson, operationExamples, provenanceLines, readDocument, readErrorCatalogue, readSchemas, schemasOutputPath };

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { C as DescriptorBuilder, S as operationExamples, T as buildDescriptor, _ as readErrorCatalogue, a as schemasOutputPath, b as checkContract, c as emitSchemas, d as detectVerbCollisions, f as emit, g as emitErrorCodes, h as provenanceLines, i as generateFiles, l as emitExamples, m as hashJson, n as examplesOutputPath, o as readDocument, p as deriveProvenance, r as generate, s as readSchemas, t as check, u as Emitter, v as MAXIMUM_CONTRACT, w as buildAtomic, x as buildExamples, y as MINIMUM_CONTRACT } from "./src-D4apiVHe.mjs";
+import { C as DescriptorBuilder, S as operationExamples, T as buildDescriptor, _ as readErrorCatalogue, a as schemasOutputPath, b as checkContract, c as emitSchemas, d as detectVerbCollisions, f as emit, g as emitErrorCodes, h as provenanceLines, i as generateFiles, l as emitExamples, m as hashJson, n as examplesOutputPath, o as readDocument, p as deriveProvenance, r as generate, s as readSchemas, t as check, u as Emitter, v as MAXIMUM_CONTRACT, w as buildAtomic, x as buildExamples, y as MINIMUM_CONTRACT } from "./src-7yVCQTGQ.mjs";
 export { DescriptorBuilder, Emitter, MAXIMUM_CONTRACT, MINIMUM_CONTRACT, buildAtomic, buildDescriptor, buildExamples, check, checkContract, deriveProvenance, detectVerbCollisions, emit, emitErrorCodes, emitExamples, emitSchemas, examplesOutputPath, generate, generateFiles, hashJson, operationExamples, provenanceLines, readDocument, readErrorCatalogue, readSchemas, schemasOutputPath };

package/dist/{src-D4apiVHe.mjs → src-7yVCQTGQ.mjs}

@@ -173,6 +173,8 @@ var DescriptorBuilder = class {
 			if (countable !== void 0) descriptor.countable = countable;
 			const includable = this.includable(collection);
 			if (includable !== void 0) descriptor.includable = includable;
+			const included = this.includedTypes(collection === void 0 ? void 0 : this.operation(collection, "get"));
+			if (included !== void 0) descriptor.included = included;
 			const sortable = this.sortable(collection);
 			if (sortable !== void 0) descriptor.sortable = sortable;
 			const filterable = this.filterable(collection);
@@ -337,9 +339,9 @@ var DescriptorBuilder = class {
 		return mutations;
 	}
 	/**
-	* Attach the per-relation endpoint-exposure signal to a relation descriptor (D24). The bundle
+	* Attach the per-relation endpoint-exposure signal to a relation descriptor. The bundle
 	* can suppress a relation's related or relationship endpoint (`withoutRelatedEndpoint()` /
-	* `withoutRelationshipEndpoint()`, ADR 0027), which the OpenAPI reflects by simply omitting that
+	* `withoutRelationshipEndpoint()`), 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
@@ -359,6 +361,8 @@ var DescriptorBuilder = class {
 			out.relationship = false;
 			out.mutations = {};
 		} else out.mutations = mutations;
+		const included = this.includedTypes(relatedGet);
+		if (included !== void 0) out.included = included;
 		const countable = withCountParam(relatedGet) ?? withCountParam(this.operation(relationshipPath, "get"));
 		if (countable !== void 0) out.countable = countable;
 		if (descriptor.cardinality === "many") {
@@ -532,6 +536,18 @@ var DescriptorBuilder = class {
 		const typeProp = data.properties?.["type"];
 		return isSchema$3(typeProp) && typeof typeProp.const === "string" ? typeProp.const : void 0;
 	}
+	/**
+	* The wire types a read's compound document can carry in `included`: the members of its
+	* document's `included.items` union. `undefined` when the document has no `included`, or types
+	* its items only as a generic `{type, id}` object.
+	*/
+	includedTypes(op) {
+		const ref = op === void 0 ? void 0 : this.firstOkJsonApiRef(op);
+		const included = (ref === void 0 ? void 0 : this.schemas[refName$1(ref) ?? ""])?.properties?.["included"];
+		const items = isSchema$3(included) ? included.items : void 0;
+		const types = items === void 0 || !Array.isArray(items.oneOf) ? void 0 : this.unionTypes(items);
+		return types !== void 0 && types.length > 0 ? types : 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 ?? {})) {
@@ -568,15 +584,13 @@ var DescriptorBuilder = class {
 				if (readPivot !== void 0) relation.readPivot = readPivot;
 				return relation;
 			}
-			if (Array.isArray(items.anyOf)) {
-				const types = this.constsFromRefs(items.anyOf);
-				return types.length === 0 ? void 0 : {
-					cardinality: "many",
-					types,
-					polymorphic: true,
-					pivot: false
-				};
-			}
+			const types = this.unionTypes(items);
+			if (types !== void 0) return types.length === 0 ? void 0 : {
+				cardinality: "many",
+				types,
+				polymorphic: true,
+				pivot: false
+			};
 			return;
 		}
 		if (Array.isArray(data.anyOf)) {
@@ -594,9 +608,12 @@ var DescriptorBuilder = class {
 					pivot = true;
 					readPivot = this.pivotDescriptor(pivotNodeFromAllOf(entry.allOf), "read");
 				}
-			} else if (Array.isArray(entry.anyOf)) {
-				types.push(...this.constsFromRefs(entry.anyOf));
-				polymorphic = true;
+			} else {
+				const union = this.unionTypes(entry);
+				if (union !== void 0) {
+					types.push(...union);
+					polymorphic = true;
+				}
 			}
 			if (types.length === 0) return;
 			const relation = polymorphic ? {
@@ -655,6 +672,24 @@ var DescriptorBuilder = class {
 			if (type !== void 0) return type;
 		}
 	}
+	/**
+	* The wire types of a union of `$ref`s: a `oneOf` discriminated by `type`, or the `anyOf` an
+	* older document writes. A member whose component carries no `type` const falls back to the
+	* discriminator mapping's key for its `$ref`. `undefined` when the schema is no union.
+	*/
+	unionTypes(schema) {
+		if (Array.isArray(schema.oneOf)) {
+			const byRef = discriminatorTypesByRef(schema);
+			const types = [];
+			for (const entry of schema.oneOf) {
+				if (typeof entry.$ref !== "string") continue;
+				const type = this.resolveConst(entry.$ref) ?? byRef.get(entry.$ref);
+				if (type !== void 0) types.push(type);
+			}
+			return types;
+		}
+		return Array.isArray(schema.anyOf) ? this.constsFromRefs(schema.anyOf) : void 0;
+	}
 	/** Resolve every `$ref` entry in a list to its wire type. */
 	constsFromRefs(entries) {
 		const types = [];
@@ -846,6 +881,16 @@ function pivotNodeOf(component) {
 	if (Array.isArray(data.items?.allOf)) return pivotNodeFromAllOf(data.items.allOf);
 	for (const entry of data.anyOf ?? []) if (Array.isArray(entry.allOf)) return pivotNodeFromAllOf(entry.allOf);
 }
+/** A `type` discriminator's mapping, inverted to the wire type each `$ref` stands for. */
+function discriminatorTypesByRef(schema) {
+	const byRef = /* @__PURE__ */ new Map();
+	const discriminator = schema["discriminator"];
+	if (typeof discriminator !== "object" || discriminator === null) return byRef;
+	const { propertyName, mapping } = discriminator;
+	if (propertyName !== "type" || typeof mapping !== "object" || mapping === null) return byRef;
+	for (const [type, ref] of Object.entries(mapping)) if (typeof ref === "string") byRef.set(ref, type);
+	return byRef;
+}
 /** Whether a schema admits `null`: a `null` type, or a `null` branch in `anyOf`/`oneOf`. */
 function isNullable(schema) {
 	const type = schema.type;
@@ -1032,7 +1077,7 @@ function buildAtomic(doc) {
 }
 /**
 * Classify a page member set: `number`+`size` = `page`; `offset`+`limit` = `offset`; either
-* cursor bound (`after`/`before`) = `cursor` (link-driven, D44); `number` alone = `fixed` (the
+* cursor bound (`after`/`before`) = `cursor` (link-driven); `number` alone = `fixed` (the
 * server fixes the size); no members = `none`; anything else = `undefined` (unrecognised).
 */
 function kindOfMembers(members) {
@@ -1185,7 +1230,7 @@ function buildExamples(doc, descriptor) {
 /** 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 = 17;
+const MAXIMUM_CONTRACT = 19;
 /**
 * 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
@@ -1195,8 +1240,8 @@ const MAXIMUM_CONTRACT = 17;
 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 17). Use an older codegen release, or regenerate the document from a newer server.`);
-	if (contract > 17) return `the document declares contract ${contract} and this codegen reads up to 17. 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 19). Use an older codegen release, or regenerate the document from a newer server.`);
+	if (contract > 19) return `the document declares contract ${contract} and this codegen reads up to 19. It describes capabilities that were not generated; upgrade the codegen to pick them up.`;
 }
 //#endregion
 //#region src/declared-links.ts
@@ -1205,6 +1250,16 @@ function isSchema$2(value) {
 	return typeof value === "object" && value !== null;
 }
 /**
+* The named links of a `<Type>ResourceLinks` component. From generator contract 18 the component
+* is an `allOf` of the shared `ResourceLinks` and an object listing them; before, it listed them
+* beside `self`.
+*/
+function namedLinks(component) {
+	const own = Object.entries(component?.properties ?? {});
+	const extended = (component?.allOf ?? []).filter((member) => member.$ref === void 0).flatMap((member) => Object.entries(member.properties ?? {}));
+	return [...own, ...extended];
+}
+/**
 * The declared links on a `<Type>ResourceLinks` component, in document order. `self` is never
 * declared, and a link the server builds itself, such as an action's link, points at
 * `RenderedLink`, so neither is read. A server that renders its links as strings points those at
@@ -1213,7 +1268,7 @@ function isSchema$2(value) {
 */
 function readDeclaredLinks(component) {
 	const out = [];
-	for (const [name, schema] of Object.entries(component?.properties ?? {})) {
+	for (const [name, schema] of namedLinks(component)) {
 		if (name === "self" || !isSchema$2(schema)) continue;
 		if (schema.$ref === LINK_OBJECT_REF) out.push({
 			name,
@@ -1902,6 +1957,7 @@ var Emitter = class {
 			this.actionTypesMap(),
 			this.resourceMap(),
 			"export type ResourceMap = typeof resourceMap",
+			this.includedAliases(),
 			this.atomicConst(),
 			this.pageLimitsConst(),
 			emitErrorCodes(readErrorCatalogue(this.doc)),
@@ -1926,11 +1982,42 @@ var Emitter = class {
 			"  createClient as createClientRuntime,",
 			"  type ErrorCodeGuard,",
 			"  hasErrorCode as hasErrorCodeRuntime,",
+			"  type IncludedResource,",
+			"  type RelatedIncludedResource,",
+			"  type RelationName,",
 			...this.declaredLinks.size > 0 ? ["  type ResourceLinks,"] : [],
+			"  type TypeName,",
+			"  type WithLinks,",
 			"} from '@haddowg/json-api-client'"
 		].join("\n");
 	}
 	/**
+	* The typed `included` of each read: a resource union discriminated by `type` over the types
+	* the document's typed `included` lists, or over every type when the document doesn't type it.
+	*/
+	includedAliases() {
+		return [
+			"/**",
+			" * One resource of a compound document's `included` for a read of type `T`, discriminated by",
+			" * `type` over the types its `include` paths reach.",
+			" */",
+			"export type Included<T extends TypeName<ResourceMap>> = IncludedResource<",
+			"  ResourceMap,",
+			"  WithLinks<Attributes, Links>,",
+			"  T",
+			">",
+			"",
+			"/**",
+			" * One resource of the `included` of relation `R`'s related read on type `T`, discriminated by",
+			" * `type` over the types its `include` paths reach.",
+			" */",
+			"export type RelatedIncluded<",
+			"  T extends TypeName<ResourceMap>,",
+			"  R extends RelationName<ResourceMap, T>,",
+			"> = RelatedIncludedResource<ResourceMap, WithLinks<Attributes, Links>, T, R>"
+		].join("\n");
+	}
+	/**
 	* The links interface of a type that declares links, e.g. `ImagesLinks`: each declared link an
 	* optional member, since the server leaves a link out when its href resolves to `null`. It
 	* extends the loose `ResourceLinks`, so `self` and any link the type doesn't declare stay
@@ -2491,7 +2578,7 @@ function emitExamples(doc, examples) {
 *
 * 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
+* opt-in `validate?` seam. 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
@@ -2562,10 +2649,10 @@ async function readSchemas(input) {
 /**
 * @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
+* `createClient`. 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
+* The spec is fully self-describing for our needs (see docs/concepts.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
@@ -2627,8 +2714,8 @@ async function render(config) {
 *
 * 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.examples` writes the operation examples the same way (ADR 0011).
+* the opt-in validation seam. The main client output is unchanged either way.
+* `config.examples` writes the operation examples the same 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.
@@ -2678,4 +2765,4 @@ async function check(config) {
 //#endregion
 export { DescriptorBuilder as C, operationExamples as S, buildDescriptor as T, readErrorCatalogue as _, schemasOutputPath as a, checkContract as b, emitSchemas as c, detectVerbCollisions as d, emit as f, emitErrorCodes as g, provenanceLines as h, generateFiles as i, emitExamples as l, hashJson as m, examplesOutputPath as n, readDocument as o, deriveProvenance as p, generate as r, readSchemas as s, check as t, Emitter as u, MAXIMUM_CONTRACT as v, buildAtomic as w, buildExamples as x, MINIMUM_CONTRACT as y };
 
-//# sourceMappingURL=src-D4apiVHe.mjs.map
+//# sourceMappingURL=src-7yVCQTGQ.mjs.map