@haddowg/json-api-codegen 1.10.0 → 1.12.0

package/dist/cli.d.mts

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

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

@@ -62,6 +62,14 @@ interface OperationObject {
     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>>;
@@ -80,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
@@ -91,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
@@ -304,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 = 15;
+declare const MAXIMUM_CONTRACT = 17;
 /**
  * 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
@@ -691,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-DqeWPRAD.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-Ch2PJH9Y.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index-Ch2PJH9Y.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-DqeWPRAD.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-Ch2PJH9Y.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-C3noZURK.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-D4apiVHe.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-C3noZURK.mjs → src-D4apiVHe.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;
 	}
@@ -403,6 +450,11 @@ var DescriptorBuilder = class {
 			const value = safety?.[flag];
 			if (typeof value === "boolean") action[flag] = value;
 		}
+		const scopes = this.scopes(op);
+		if (scopes !== void 0) action.scopes = scopes;
+		const okSchema = okJsonApiSchema(op);
+		const mediaType = okSchema === void 0 ? void 0 : locationMediaType(okSchema);
+		if (mediaType !== void 0) action.location = { mediaType };
 		return action;
 	}
 	/**
@@ -484,7 +536,8 @@ var DescriptorBuilder = class {
 	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;
+			const schema = response.content?.[JSON_API_MEDIA_TYPE$1]?.schema;
+			const ref = schema === void 0 ? void 0 : documentArms(schema)[0]?.$ref;
 			if (typeof ref === "string") return ref;
 		}
 	}
@@ -515,16 +568,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);
@@ -536,9 +594,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
@@ -914,13 +980,47 @@ function rawContentType(op) {
 * (only a `204`).
 */
 function actionOutput(op) {
+	const schema = okJsonApiSchema(op);
+	if (schema === void 0) return "none";
+	const arm = documentArms(schema)[0];
+	if (arm === void 0) return locationMediaType(schema) === void 0 ? "document" : "location";
+	return typeof arm.$ref === "string" && refName$1(arm.$ref) === "MetaDocument" ? "meta" : "document";
+}
+/** The JSON:API schema of an operation's first success response that declares one. */
+function okJsonApiSchema(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";
+		if (schema !== void 0) return schema;
+	}
+}
+/** Whether a schema is a location document: a `$ref` to `LocationDocument`, or an `allOf` with one. */
+function isLocationSchema(schema) {
+	const isRef = (entry) => typeof entry.$ref === "string" && refName$1(entry.$ref) === "LocationDocument";
+	return isRef(schema) || (schema.allOf?.some(isRef) ?? false);
+}
+/**
+* The documents a success response's schema offers besides a location document (generator
+* contract 17): each `oneOf` member that isn't one, or the schema itself when it isn't one.
+*/
+function documentArms(schema) {
+	return (schema.oneOf ?? [schema]).filter((arm) => !isLocationSchema(arm));
+}
+/**
+* The media type a location document's `links.location.type` is fixed to (generator contract
+* 17), `application/octet-stream` when the schema fixes none, or `undefined` when the schema
+* offers no location document.
+*/
+function locationMediaType(schema) {
+	const location = (schema.oneOf ?? [schema]).find(isLocationSchema);
+	if (location === void 0) return;
+	for (const entry of location.allOf ?? []) {
+		const links = entry.properties?.["links"];
+		const link = isSchema$3(links) ? links.properties?.["location"] : void 0;
+		const type = isSchema$3(link) ? link.properties?.["type"] : void 0;
+		if (isSchema$3(type) && typeof type.const === "string") return type.const;
 	}
-	return "none";
+	return "application/octet-stream";
 }
 /** Build the {@link ApiDescriptor} from a parsed OpenAPI document. */
 function buildDescriptor(doc) {
@@ -1085,7 +1185,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 = 15;
+const MAXIMUM_CONTRACT = 17;
 /**
 * 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
@@ -1095,8 +1195,8 @@ const MAXIMUM_CONTRACT = 15;
 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 15). Use an older codegen release, or regenerate the document from a newer server.`);
-	if (contract > 15) return `the document declares contract ${contract} and this codegen reads up to 15. 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 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.`;
 }
 //#endregion
 //#region src/declared-links.ts
@@ -1575,6 +1675,53 @@ function safetyDoc(action) {
 	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)}`}.`;
 }
+/**
+* What an action that answers with a URL returns (generator contract 17), as JSDoc, or
+* `undefined` for any other action.
+*/
+function locationDoc(action) {
+	if (action.location === void 0) return;
+	const serving = `a URL serving \`${action.location.mediaType}\``;
+	return action.output === "location" ? `Returns ${serving} as an \`ActionLocation\`. The client doesn't follow it.` : `May return ${serving} instead, as an \`ActionLocation\`. The client doesn't follow it.`;
+}
+/** 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();
@@ -1686,12 +1833,23 @@ var Emitter = class {
 				const op = actionOperation(this.doc, action);
 				const parts = [
 					actionDoc(action.path.slice(action.path.lastIndexOf("/") + 1), op),
+					locationDoc(action),
 					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);
+			}
 		}
 	}
 	/**
@@ -2035,10 +2193,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`}`;
 	}
@@ -2518,4 +2678,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-C3noZURK.mjs.map
+//# sourceMappingURL=src-D4apiVHe.mjs.map