@haddowg/json-api-codegen 1.9.0 → 1.11.0

package/dist/cli.d.mts

@@ -1,4 +1,4 @@
-import { r as CodegenConfig } from "./index-k_oATv7Q.mjs";
+import { r as CodegenConfig } from "./index-BLBSnK8y.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-py1RBWZr.mjs";
+import { i as generateFiles, t as check } from "./src-D29xU79S.mjs";
 import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 //#region src/cli.ts

package/dist/{index-k_oATv7Q.d.mts → index-BLBSnK8y.d.mts}

@@ -56,6 +56,20 @@ interface OperationObject {
   parameters?: readonly ParameterObject[];
   requestBody?: RequestBodyObject;
   responses?: Record<string, ResponseObject>;
+  /** What a custom action declares about its effects (generator contract 15). */
+  'x-safety'?: {
+    readOnly?: unknown;
+    destructive?: unknown;
+    idempotent?: unknown;
+  };
+  /** The credentials the operation takes: scheme name to the scopes it needs, per alternative. */
+  security?: readonly SecurityRequirement[];
+}
+/** One security alternative: each scheme it names, with the scopes it needs under that scheme. */
+type SecurityRequirement = Readonly<Record<string, readonly string[]>>;
+/** A security scheme; the codegen reads only its `type`, to find the `oauth2` ones. */
+interface SecuritySchemeObject {
+  type?: string;
 }
 type HttpMethod = 'get' | 'post' | 'patch' | 'put' | 'delete';
 type PathItemObject = Partial<Record<HttpMethod, OperationObject>>;
@@ -74,8 +88,11 @@ interface OpenApiDocument {
     url?: string;
   }[];
   paths?: Record<string, PathItemObject>;
+  /** The default security of every operation that declares none of its own. */
+  security?: readonly SecurityRequirement[];
   components?: {
     schemas?: Record<string, SchemaObject>;
+    securitySchemes?: Record<string, SecuritySchemeObject>;
   };
 }
 //#endregion
@@ -85,7 +102,22 @@ declare class DescriptorBuilder {
   private readonly paths;
   /** Lazily-built wire-type -> collection-level paginator kind (for per-relation divergence, D6a). */
   private typePaginators?;
+  /** The names of the document's `oauth2` security schemes, under which operations list scopes. */
+  private readonly scopeSchemes;
+  /** The document's default security, which an operation without its own inherits. */
+  private readonly defaultSecurity;
   constructor(source: OpenApiDocument);
+  /**
+   * The OAuth scopes an operation needs (generator contract 16): those its `security` lists under
+   * an `oauth2` scheme, in order and without repeats. `undefined` when it lists none.
+   */
+  private scopes;
+  /**
+   * The scopes each of a type's CRUD, related and relationship operations needs, keyed by the
+   * operationId without the type (`fetchOne`, `fetchRelated.author`). Operations needing none are
+   * left out; actions carry their own.
+   */
+  private operationScopes;
   /**
    * 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
@@ -152,9 +184,12 @@ declare class DescriptorBuilder {
    * `{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`).
+   * `output` is `document` (a 2xx returns a JSON:API document) or `none` (only `204`). An action
+   * answering to several methods gives one entry per method (see {@link pickOperations}).
    */
   private actions;
+  /** The descriptor for one operation of a custom action. */
+  private action;
   /**
    * The non-JSON:API media types an action answers with under its 2xx responses, each once, in
    * the document's order, with how the client reads its body.
@@ -295,7 +330,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 = 14;
+declare const MAXIMUM_CONTRACT = 16;
 /**
  * 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
@@ -682,5 +717,5 @@ 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, ResponseObject as H, MediaTypeObject as I, 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-k_oATv7Q.d.mts.map
+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-BLBSnK8y.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index-BLBSnK8y.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, H as ResponseObject, I as MediaTypeObject, 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-k_oATv7Q.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, buildExamples, check, checkContract, deriveProvenance, detectVerbCollisions, emit, emitErrorCodes, emitExamples, emitSchemas, examplesOutputPath, generate, generateFiles, hashJson, operationExamples, provenanceLines, readDocument, readErrorCatalogue, readSchemas, schemasOutputPath };
+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-BLBSnK8y.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-py1RBWZr.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-D29xU79S.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-py1RBWZr.mjs → src-D29xU79S.mjs}

@@ -95,10 +95,49 @@ var DescriptorBuilder = class {
 	paths;
 	/** Lazily-built wire-type -> collection-level paginator kind (for per-relation divergence, D6a). */
 	typePaginators;
+	/** The names of the document's `oauth2` security schemes, under which operations list scopes. */
+	scopeSchemes;
+	/** The document's default security, which an operation without its own inherits. */
+	defaultSecurity;
 	constructor(source) {
 		const doc = unwrapRefs(source);
 		this.schemas = doc.components?.schemas ?? {};
 		this.paths = doc.paths ?? {};
+		this.scopeSchemes = new Set(Object.entries(doc.components?.securitySchemes ?? {}).filter(([, scheme]) => scheme?.type === "oauth2").map(([name]) => name));
+		this.defaultSecurity = doc.security ?? [];
+	}
+	/**
+	* The OAuth scopes an operation needs (generator contract 16): those its `security` lists under
+	* an `oauth2` scheme, in order and without repeats. `undefined` when it lists none.
+	*/
+	scopes(op) {
+		if (op === void 0 || this.scopeSchemes.size === 0) return;
+		const out = /* @__PURE__ */ new Set();
+		for (const requirement of op.security ?? this.defaultSecurity) for (const [scheme, scopes] of Object.entries(requirement)) if (this.scopeSchemes.has(scheme) && Array.isArray(scopes)) for (const scope of scopes) out.add(scope);
+		return out.size === 0 ? void 0 : [...out];
+	}
+	/**
+	* The scopes each of a type's CRUD, related and relationship operations needs, keyed by the
+	* operationId without the type (`fetchOne`, `fetchRelated.author`). Operations needing none are
+	* left out; actions carry their own.
+	*/
+	operationScopes(wireType) {
+		const out = {};
+		for (const item of Object.values(this.paths)) for (const op of Object.values(item)) {
+			const id = op?.operationId;
+			if (typeof id !== "string") continue;
+			const dot = id.indexOf(".");
+			const prefix = id.slice(0, dot);
+			const rest = id.slice(dot + 1);
+			if (dot < 0 || prefix === "action" || prefix === "atomic") continue;
+			let key;
+			if (rest === wireType) key = prefix;
+			else if (rest.startsWith(`${wireType}.`)) key = `${prefix}.${rest.slice(wireType.length + 1)}`;
+			else continue;
+			const scopes = this.scopes(op);
+			if (scopes !== void 0) out[key] = scopes;
+		}
+		return sortRecord(out);
 	}
 	/**
 	* The collection-level paginator kind for a WIRE type (`tracks`), memoised. Resolves each
@@ -139,6 +178,8 @@ var DescriptorBuilder = class {
 			const filterable = this.filterable(collection);
 			if (filterable !== void 0) descriptor.filterable = filterable;
 			if (Object.keys(actions).length > 0) descriptor.actions = actions;
+			const scopes = this.operationScopes(wireType);
+			if (Object.keys(scopes).length > 0) descriptor.scopes = scopes;
 			if (Object.keys(schema.properties ?? {}).every((prop) => prop === "type") && Object.keys(descriptor.paths).length === 0) continue;
 			out[wireType] = descriptor;
 		}
@@ -152,7 +193,13 @@ var DescriptorBuilder = class {
 	buildAtomic() {
 		for (const [path, item] of Object.entries(this.paths)) {
 			const content = item.post?.requestBody?.content ?? {};
-			if (Object.keys(content).some(isAtomicMediaType)) return { path };
+			if (Object.keys(content).some(isAtomicMediaType)) {
+				const scopes = this.scopes(item.post);
+				return scopes === void 0 ? { path } : {
+					path,
+					scopes
+				};
+			}
 		}
 		return null;
 	}
@@ -327,7 +374,8 @@ var DescriptorBuilder = class {
 	* `{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`).
+	* `output` is `document` (a 2xx returns a JSON:API document) or `none` (only `204`). An action
+	* answering to several methods gives one entry per method (see {@link pickOperations}).
 	*/
 	actions(collection) {
 		const out = {};
@@ -344,47 +392,68 @@ var DescriptorBuilder = class {
 				name = path.slice(collectionPrefix.length);
 			} else continue;
 			if (name.length === 0 || name.includes("/")) continue;
-			const picked = pickOperation(item);
-			if (picked === void 0) {
+			const picked = pickOperations(item);
+			if (picked.length === 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;
+			for (const [index, { method, op }] of picked.entries()) {
+				const key = index === 0 ? name : methodActionName(name, method);
+				if (key in out) {
+					console.warn(`json-api codegen: the ${method.toUpperCase()} operation of custom action path "${path}" would be named "${key}", which another action already uses; skipping.`);
+					continue;
 				}
+				out[key] = this.action(scope, path, method, op);
 			}
-			if (input === "raw") {
-				const contentType = rawContentType(op);
-				if (contentType !== void 0) action.contentType = contentType;
-			}
-			const rawOutput = this.rawOutput(op);
-			if (rawOutput.length > 0) action.rawOutput = rawOutput;
-			const requestContent = Object.entries(op.requestBody?.content ?? {});
-			if (requestContent.length > 1) action.inputMedia = requestContent.map(([mediaType, media]) => ({
-				mediaType,
-				kind: this.inputMediaKind(mediaType, media.schema)
-			}));
-			out[name] = action;
 		}
 		return sortRecord(out);
 	}
+	/** The descriptor for one operation of a custom action. */
+	action(scope, path, method, op) {
+		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;
+		}
+		const rawOutput = this.rawOutput(op);
+		if (rawOutput.length > 0) action.rawOutput = rawOutput;
+		const requestContent = Object.entries(op.requestBody?.content ?? {});
+		if (requestContent.length > 1) action.inputMedia = requestContent.map(([mediaType, media]) => ({
+			mediaType,
+			kind: this.inputMediaKind(mediaType, media.schema)
+		}));
+		const safety = op["x-safety"];
+		for (const flag of [
+			"readOnly",
+			"destructive",
+			"idempotent"
+		]) {
+			const value = safety?.[flag];
+			if (typeof value === "boolean") action[flag] = value;
+		}
+		const scopes = this.scopes(op);
+		if (scopes !== void 0) action.scopes = scopes;
+		return action;
+	}
 	/**
 	* The non-JSON:API media types an action answers with under its 2xx responses, each once, in
 	* the document's order, with how the client reads its body.
@@ -495,16 +564,21 @@ var DescriptorBuilder = class {
 				if (readPivot !== void 0) relation.readPivot = readPivot;
 				return relation;
 			}
-			if (Array.isArray(items.anyOf)) return {
-				cardinality: "many",
-				types: this.constsFromRefs(items.anyOf),
-				pivot: false
-			};
+			if (Array.isArray(items.anyOf)) {
+				const types = this.constsFromRefs(items.anyOf);
+				return types.length === 0 ? void 0 : {
+					cardinality: "many",
+					types,
+					polymorphic: true,
+					pivot: false
+				};
+			}
 			return;
 		}
 		if (Array.isArray(data.anyOf)) {
 			const types = [];
 			let pivot = false;
+			let polymorphic = false;
 			let readPivot;
 			for (const entry of data.anyOf) if (typeof entry.$ref === "string") {
 				const type = this.resolveConst(entry.$ref);
@@ -516,9 +590,17 @@ var DescriptorBuilder = class {
 					pivot = true;
 					readPivot = this.pivotDescriptor(pivotNodeFromAllOf(entry.allOf), "read");
 				}
-			} else if (Array.isArray(entry.anyOf)) types.push(...this.constsFromRefs(entry.anyOf));
+			} else if (Array.isArray(entry.anyOf)) {
+				types.push(...this.constsFromRefs(entry.anyOf));
+				polymorphic = true;
+			}
 			if (types.length === 0) return;
-			const relation = {
+			const relation = polymorphic ? {
+				cardinality: "one",
+				types,
+				polymorphic: true,
+				pivot
+			} : {
 				cardinality: "one",
 				types,
 				pivot
@@ -837,18 +919,39 @@ const ACTION_METHODS = [
 	"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.
+* The operations an action is invoked over, the preferred one first: POST when advertised (the
+* common default), else the first advertised method. The other methods follow only when their
+* `operationId` differs from the preferred one's, as contract 15 makes it for an action answering
+* to several methods. An older document gave every method one id, and its client exposed only the
+* preferred one. Empty when the path item carries no operation at all.
 */
-function pickOperation(item) {
+function pickOperations(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
-	};
+	const preferred = available.includes("post") ? "post" : available[0];
+	if (preferred === void 0) return [];
+	const first = item[preferred];
+	const out = [{
+		method: preferred,
+		op: first
+	}];
+	for (const method of available) {
+		const op = item[method];
+		if (method !== preferred && op.operationId !== first.operationId) out.push({
+			method,
+			op
+		});
+	}
+	return out;
+}
+/**
+* The name a multi-method action's other methods go under: the action's name and the method,
+* joined the way the name joins its words. So `export` gives `exportGet` and `bulk-import` gives
+* `bulk-import-get`. Core refuses action ids that differ only in case or punctuation, so the
+* name can't clash with another action's.
+*/
+function methodActionName(name, method) {
+	const separator = /[-_.]/.exec(name)?.[0];
+	return separator === void 0 ? `${name}${method[0].toUpperCase()}${method.slice(1)}` : `${name}${separator}${method}`;
 }
 /** The body shape a custom action accepts: a JSON:API document, none, or a raw payload. */
 function actionInput(op) {
@@ -1044,7 +1147,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 = 14;
+const MAXIMUM_CONTRACT = 16;
 /**
 * 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
@@ -1054,8 +1157,8 @@ const MAXIMUM_CONTRACT = 14;
 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 14). Use an older codegen release, or regenerate the document from a newer server.`);
-	if (contract > 14) return `the document declares contract ${contract} and this codegen reads up to 14. 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 16). Use an older codegen release, or regenerate the document from a newer server.`);
+	if (contract > 16) return `the document declares contract ${contract} and this codegen reads up to 16. It describes capabilities that were not generated; upgrade the codegen to pick them up.`;
 }
 //#endregion
 //#region src/declared-links.ts
@@ -1521,6 +1624,57 @@ function actionDoc(name, op) {
 	if (description && !generated.test(description)) parts.push(description);
 	return parts.length === 0 ? void 0 : parts.join("\n\n");
 }
+/**
+* What an action declares about its effects (generator contract 15), as one sentence, or
+* `undefined` when it declares nothing.
+*/
+function safetyDoc(action) {
+	const words = [
+		[action.readOnly, "read-only"],
+		[action.destructive, "destructive"],
+		[action.idempotent, "idempotent"]
+	].filter(([value]) => value !== void 0).map(([value, word]) => value === true ? word : `not ${word}`);
+	if (words.length === 0) return;
+	return `The server declares this action ${words.length === 1 ? words[0] : `${words.slice(0, -1).join(", ")} and ${words.at(-1)}`}.`;
+}
+/** A list of scopes as inline code joined into prose: `a`, `b` and `c`. */
+function scopeList(scopes) {
+	const quoted = scopes.map((scope) => `\`${scope}\``);
+	return quoted.length === 1 ? quoted[0] : `${quoted.slice(0, -1).join(", ")} and ${quoted.at(-1)}`;
+}
+/** The sentence naming the OAuth scopes an operation needs (generator contract 16). */
+function scopeDoc(scopes) {
+	if (scopes === void 0 || scopes.length === 0) return;
+	return `Needs the OAuth ${scopes.length === 1 ? "scope" : "scopes"} ${scopeList(scopes)}.`;
+}
+/** The descriptor's `paths` keys, by the operation whose scopes they carry. */
+const PATH_OPERATIONS = {
+	fetchMany: "fetchCollection",
+	create: "create",
+	fetchOne: "fetchOne",
+	update: "update",
+	delete: "delete"
+};
+/** A relation's operations, in the order its JSDoc lists their scopes. */
+const RELATION_OPERATIONS = [
+	"fetchRelated",
+	"fetchRelationship",
+	"updateRelationship",
+	"addRelationship",
+	"removeRelationship"
+];
+/** The OAuth scopes each of a relation's endpoints needs, one line per operation, or `undefined`. */
+function relationScopeDoc(scopes, relation) {
+	const lines = RELATION_OPERATIONS.flatMap((operation) => {
+		const needed = scopes?.[`${operation}.${relation}`];
+		return needed === void 0 || needed.length === 0 ? [] : [`- \`${operation}\` needs ${scopeList(needed)}`];
+	});
+	return lines.length === 0 ? void 0 : [
+		"OAuth scopes:",
+		"",
+		...lines
+	].join("\n");
+}
 /** Whether a media type carries JSON: JSON:API, `application/json` or a `+json` suffix. */
 function isJsonMedia(mediaType) {
 	const essence = mediaType.split(";")[0].trim().toLowerCase();
@@ -1630,10 +1784,24 @@ var Emitter = class {
 				const single = action.contentType;
 				if (single !== void 0 && (single.startsWith("multipart/") || single === "application/x-www-form-urlencoded")) this.takenNames.add(`${stem}${pascalCase(name)}${pascalCase(single)}Input`);
 				const op = actionOperation(this.doc, action);
-				const parts = [actionDoc(name, op), exampleDoc(op)].filter((part) => part !== void 0);
+				const parts = [
+					actionDoc(action.path.slice(action.path.lastIndexOf("/") + 1), op),
+					safetyDoc(action),
+					scopeDoc(action.scopes),
+					exampleDoc(op)
+				].filter((part) => part !== void 0);
 				const doc = parts.length === 0 ? void 0 : parts.join("\n\n");
 				if (doc !== void 0) this.literalDocs.set(`${type}/actions/${name}`, doc);
 			}
+			const scopes = descriptor[type]?.scopes;
+			for (const [key, operation] of Object.entries(PATH_OPERATIONS)) {
+				const doc = scopeDoc(scopes?.[operation]);
+				if (doc !== void 0 && descriptor[type]?.paths[key] !== void 0) this.literalDocs.set(`${type}/paths/${key}`, doc);
+			}
+			for (const relation of Object.keys(descriptor[type]?.relations ?? {})) {
+				const doc = relationScopeDoc(scopes, relation);
+				if (doc !== void 0) this.literalDocs.set(`${type}/relations/${relation}`, doc);
+			}
 		}
 	}
 	/**
@@ -1977,10 +2145,12 @@ var Emitter = class {
 	}
 	/** Emit the server-level atomic capability constant (`{ path }` or `null`). */
 	atomicConst() {
+		const atomicScopes = scopeDoc(this.atomic?.scopes);
 		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.",
+			...atomicScopes === void 0 ? [] : [" *", ` * ${atomicScopes}`],
 			" */"
 		].join("\n")}\nexport const atomic = ${this.atomic === null ? "null" : `${this.literal(this.atomic, 0)} as const`}`;
 	}
@@ -2460,4 +2630,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-py1RBWZr.mjs.map
+//# sourceMappingURL=src-D29xU79S.mjs.map