@hey-api/shared 0.4.5 → 0.4.6

package/dist/index.mjs

@@ -293,6 +293,227 @@ function checkNodeVersion() {
 	}
 }
 //#endregion
+//#region src/normalize/coerce.ts
+const COERCER = Symbol("coercer");
+/**
+* Wraps a function as a coercer — a field-level resolver that receives the
+* raw user value and optional context, and returns the resolved field value.
+*
+* Unlike plain defaults, coercers run unconditionally on every resolution,
+* giving full control over the output regardless of what the user provides.
+*
+* Use when a field's resolved value requires computation, context access,
+* or delegation to another config normalizer.
+*
+* @param fn - Receives the raw input value and resolution context, returns
+* the resolved field value.
+*
+* @example
+* ```ts
+* // Delegate watch resolution to a nested config normalizer
+* watch: coerce((value) => watchConfig(value)),
+*
+* // Resolve a field from context
+* output: coerce((value, ctx) => value ?? ctx.defaultOutput),
+* ```
+*/
+function coerce(fn) {
+	return { [COERCER]: fn };
+}
+function isCoercer(value) {
+	return (typeof value === "object" || typeof value === "function") && value !== null && COERCER in value;
+}
+//#endregion
+//#region src/utils/object.ts
+function isPlainObject(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+}
+//#endregion
+//#region src/normalize/opaque.ts
+const OPAQUE = Symbol("opaque");
+/**
+* Marks a field as opaque — its value is assigned as-is without being
+* recursed into or merged as config fields.
+*
+* Use when a field accepts an arbitrary object that should not be treated
+* as a nested config table.
+*
+* @param defaultValue - The value to use when no input is provided.
+* @param fallback - Optional. Called with the full table input when the field
+* is absent from the input object. Return `undefined` to fall back to
+* `defaultValue`.
+*
+* @example
+* ```ts
+* path: opaque<string | object>('', (input) =>
+*   input && typeof input === 'object' && !('path' in input)
+*     ? input
+*     : undefined
+* ),
+* ```
+*/
+function opaque(defaultValue, fallback) {
+	return fallback ? {
+		[OPAQUE]: defaultValue,
+		fallback
+	} : { [OPAQUE]: defaultValue };
+}
+function isOpaque(value) {
+	return typeof value === "object" && value !== null && OPAQUE in value;
+}
+//#endregion
+//#region src/normalize/value.ts
+function resolveTable(input, table, { ancestor = {}, context = {}, resolvedCascade = {}, specAncestor = {} } = {}) {
+	const { $cascade: cascadeKeys = [], $coerce, $coerceAny, $finalize, ...entries } = table;
+	const result = {};
+	for (const [key, defaultVal] of Object.entries(entries)) if (!isCoercer(defaultVal) && !isPlainObject(defaultVal) && !isOpaque(defaultVal)) result[key] = defaultVal;
+	if (input !== void 0 && input !== null) {
+		if ($coerceAny) Object.assign(result, $coerceAny({
+			type: typeof input,
+			value: input
+		}));
+		if (isPlainObject(input)) for (const [key, val] of Object.entries(input)) {
+			const defaultVal = entries[key];
+			if (!isCoercer(defaultVal) && !isPlainObject(defaultVal) && !isOpaque(defaultVal)) result[key] = val;
+		}
+		else {
+			const handler = $coerce?.[typeof input];
+			if (handler) Object.assign(result, handler(input));
+		}
+	}
+	const localContext = { ...context };
+	const cascadeEntryKeys = cascadeKeys.filter((k) => k in entries);
+	const localResolvedCascade = { ...resolvedCascade };
+	for (const key of cascadeKeys) if (!cascadeEntryKeys.includes(key)) localContext[key] = result[key];
+	for (const key of cascadeEntryKeys) {
+		const userVal = isPlainObject(input) ? input[key] : void 0;
+		result[key] = resolveField(entries[key], result[key] ?? userVal, key, {
+			ancestor,
+			context: localContext,
+			resolvedCascade: localResolvedCascade,
+			specAncestor
+		});
+		localContext[key] = result[key];
+		if (isPlainObject(result[key])) localResolvedCascade[key] = result[key];
+	}
+	for (const [key, defaultVal] of Object.entries(entries)) {
+		if (cascadeEntryKeys.includes(key)) continue;
+		const userVal = isPlainObject(input) ? input[key] : void 0;
+		if (isOpaque(defaultVal)) {
+			if (result[key] !== void 0) {} else if (userVal !== void 0) result[key] = userVal;
+			else if (defaultVal.fallback) {
+				const fallbackResult = defaultVal.fallback(input);
+				result[key] = fallbackResult !== void 0 ? fallbackResult : defaultVal[OPAQUE];
+			} else result[key] = defaultVal[OPAQUE];
+			continue;
+		}
+		result[key] = resolveField(defaultVal, isCoercer(defaultVal) ? result[key] ?? userVal : userVal ?? result[key], key, {
+			ancestor,
+			context: localContext,
+			resolvedCascade: localResolvedCascade,
+			specAncestor
+		});
+	}
+	$finalize?.(result, input);
+	return result;
+}
+function collectDeps(spec, resolved, deps) {
+	const { $dependencies } = spec;
+	if ($dependencies) for (const key of $dependencies) {
+		const value = resolved[key];
+		if (value && typeof value === "string") deps.add(value);
+	}
+	for (const [key, specVal] of Object.entries(spec)) {
+		if (key.startsWith("$")) continue;
+		if (isPlainObject(specVal) && isPlainObject(resolved[key])) collectDeps(specVal, resolved[key], deps);
+	}
+}
+function resolveField(defaultVal, currentVal, key, { ancestor, context, resolvedCascade, specAncestor }) {
+	if (isCoercer(defaultVal)) return defaultVal[COERCER](currentVal, context);
+	if (isPlainObject(defaultVal)) {
+		const cascadeSpec = specAncestor[key];
+		const effectiveTable = cascadeSpec ? mergeSpecs(cascadeSpec, defaultVal) : mergeAncestorScalars(ancestor, defaultVal);
+		return resolveTable(currentVal !== void 0 ? currentVal : resolvedCascade[key], effectiveTable, {
+			ancestor,
+			context,
+			resolvedCascade,
+			specAncestor
+		});
+	}
+	return currentVal !== void 0 ? currentVal : defaultVal;
+}
+function mergeSpecs(cascadeSpec, localSpec) {
+	const result = { ...localSpec };
+	for (const [key, cascadeVal] of Object.entries(cascadeSpec)) {
+		if (key === "$coerceAny" || key === "$coerce" || key === "$cascade" || key === "$finalize") {
+			if (result[key] === void 0) result[key] = cascadeVal;
+			continue;
+		}
+		const localVal = result[key];
+		if (isPlainObject(cascadeVal) && isPlainObject(localVal)) result[key] = mergeSpecs(cascadeVal, localVal);
+	}
+	return result;
+}
+function mergeAncestorScalars(ancestor, target) {
+	const result = { ...target };
+	for (const [key, ancestorVal] of Object.entries(ancestor)) {
+		if (isPlainObject(ancestorVal)) continue;
+		if (result[key] === void 0) result[key] = ancestorVal;
+	}
+	return result;
+}
+//#endregion
+//#region src/normalize/config.ts
+/**
+* Creates a typed config normalizer from a resolution table.
+*
+* @example
+* ```ts
+* const normalizePlugin = defineConfig<PluginInput, PluginResolved>({
+*   $coerce: {
+*     boolean: (enabled) => ({ enabled }),
+*     function: (name) => ({ name, enabled: true }),
+*     string: (name) => ({ name, enabled: true }),
+*   },
+*   enabled: false,
+*   name: '',
+*   output: coerce((val, ctx) => val ?? ctx.defaultOutput),
+* });
+* ```
+*/
+function defineConfig(table) {
+	function normalize(config, externalContext) {
+		const resolvedTable = typeof table === "function" ? table(config) : table;
+		const { $cascade: cascadeKeys = [], ...entries } = resolvedTable;
+		const ancestor = {};
+		const specAncestor = {};
+		for (const key of cascadeKeys) {
+			const entrySpec = entries[key];
+			if (!(key in entries)) {
+				if (isPopulated(config, key)) ancestor[key] = config[key];
+				continue;
+			}
+			if (isPlainObject(entrySpec)) specAncestor[key] = entrySpec;
+			else {
+				const partial = resolveTable(config, { [key]: entrySpec });
+				if (partial[key] !== void 0) ancestor[key] = partial[key];
+			}
+		}
+		return resolveTable(config, resolvedTable, {
+			ancestor,
+			context: externalContext ?? {},
+			specAncestor
+		});
+	}
+	normalize[COERCER] = (value) => normalize(value);
+	return normalize;
+}
+function isPopulated(config, key) {
+	return typeof config === "object" && config !== null && key in config && config[key] !== void 0;
+}
+//#endregion
 //#region src/utils/input/heyApi.ts
 const registryRegExp$2 = /^([\w-]+)\/([\w-]+)(?:\?([\w=&.-]*))?$/;
 const heyApiRegistryBaseUrl = "https://get.heyapi.dev";
@@ -462,50 +683,35 @@ function inputToApiRegistry(input) {
 }
 //#endregion
 //#region src/config/input/input.ts
-const defaultWatch = {
+const watchConfig = defineConfig({
+	$coerce: {
+		boolean: (v) => ({ enabled: v }),
+		number: (v) => ({
+			enabled: true,
+			interval: v
+		})
+	},
 	enabled: false,
 	interval: 1e3,
 	timeout: 6e4
-};
-function getWatch(input) {
-	let watch = { ...defaultWatch };
-	if (typeof input.path !== "string") return watch;
-	if (typeof input.watch === "boolean") watch.enabled = input.watch;
-	else if (typeof input.watch === "number") {
-		watch.enabled = true;
-		watch.interval = input.watch;
-	} else if (input.watch) watch = {
-		...watch,
-		...input.watch
-	};
-	return watch;
-}
+});
+const inputConfig = defineConfig({
+	$coerce: { string: (path) => ({ path }) },
+	$finalize(config, input) {
+		if (input && typeof input === "object" && "organization" in input && config.path === "") config.path = heyApiRegistryBaseUrl;
+	},
+	path: opaque("", (input) => input && typeof input === "object" && !("path" in input) && !("organization" in input) ? input : void 0),
+	watch: coerce((value) => watchConfig(value))
+});
 function getInput(userConfig) {
 	const userInputs = userConfig.input instanceof Array ? userConfig.input : [userConfig.input];
 	const inputs = [];
 	for (const userInput of userInputs) {
-		let input = {
-			path: "",
-			watch: defaultWatch
-		};
-		if (typeof userInput === "string") input.path = userInput;
-		else if (userInput && (userInput.path !== void 0 || userInput.organization !== void 0)) {
-			input = {
-				...input,
-				path: heyApiRegistryBaseUrl,
-				...userInput
-			};
-			if (input.watch !== void 0) input.watch = getWatch(input);
-		} else input = {
-			...input,
-			path: userInput
-		};
+		const input = inputConfig(userInput);
+		if (!input.path) continue;
 		if (typeof input.path === "string") inputToApiRegistry(input);
-		if (userConfig.watch !== void 0 && input.watch.enabled === defaultWatch.enabled && input.watch.interval === defaultWatch.interval && input.watch.timeout === defaultWatch.timeout) input.watch = getWatch({
-			path: input.path,
-			watch: userConfig.watch
-		});
-		if (input.path) inputs.push(input);
+		if (userConfig.watch !== void 0 && input.watch.enabled === false && input.watch.interval === 1e3 && input.watch.timeout === 6e4) input.watch = watchConfig(userConfig.watch);
+		inputs.push(input);
 	}
 	return inputs;
 }
@@ -612,18 +818,14 @@ function logInputPaths(inputPaths, jobIndex) {
 }
 //#endregion
 //#region src/config/logs.ts
-function getLogs(userLogs) {
-	let logs = {
-		file: true,
-		level: "info",
-		path: process.cwd()
-	};
-	if (typeof userLogs === "string") logs.path = userLogs;
-	else logs = {
-		...logs,
-		...userLogs
-	};
-	return logs;
+const logsConfig = defineConfig({
+	$coerce: { string: (path) => ({ path }) },
+	file: true,
+	level: "info",
+	path: process.cwd()
+});
+function getLogs(input) {
+	return logsConfig(input);
 }
 //#endregion
 //#region src/config/output/postprocess.ts
@@ -646,65 +848,19 @@ function postprocessOutput(config, postProcessors, jobPrefix) {
 	}
 }
 //#endregion
-//#region src/config/utils/config.ts
-const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value) && typeof value !== "function";
-const mergeResult = (result, mapped) => {
-	for (const [key, value] of Object.entries(mapped)) if (value !== void 0 && value !== "") result[key] = value;
-	return result;
-};
-const valueToObject = ({ defaultValue, mappers, value }) => {
-	let result = { ...defaultValue };
-	switch (typeof value) {
-		case "boolean":
-			if (mappers && "boolean" in mappers) {
-				const mapper = mappers.boolean;
-				result = mergeResult(result, mapper(value));
-			}
-			break;
-		case "function":
-			if (mappers && "function" in mappers) {
-				const mapper = mappers.function;
-				result = mergeResult(result, mapper(value));
-			}
-			break;
-		case "number":
-			if (mappers && "number" in mappers) {
-				const mapper = mappers.number;
-				result = mergeResult(result, mapper(value));
-			}
-			break;
-		case "string":
-			if (mappers && "string" in mappers) {
-				const mapper = mappers.string;
-				result = mergeResult(result, mapper(value));
-			}
-			break;
-		case "object":
-			if (isPlainObject(value)) if (mappers && "object" in mappers && typeof mappers.object === "function") {
-				const mapper = mappers.object;
-				result = mergeResult(result, mapper(value, defaultValue));
-			} else result = mergeResult(result, value);
-			break;
-	}
-	return result;
-};
-//#endregion
 //#region src/config/output/source/config.ts
-function resolveSource(config) {
-	const source = valueToObject({
-		defaultValue: {
-			enabled: Boolean(config.source),
-			extension: "json",
-			fileName: "source",
-			serialize: (input) => JSON.stringify(input, null, 2)
-		},
-		mappers: { boolean: (enabled) => ({ enabled }) },
-		value: config.source
-	});
-	if (source.path === void 0 || source.path === true) source.path = "";
-	else if (source.path === false) source.path = null;
-	return source;
-}
+const sourceConfig = defineConfig({
+	$coerceAny: ({ value }) => ({ enabled: Boolean(value) }),
+	enabled: false,
+	extension: "json",
+	fileName: "source",
+	path: coerce((value) => {
+		if (value === true || value === void 0 || value === "") return "";
+		if (value === false || value === null) return null;
+		return value;
+	}),
+	serialize: coerce((value) => typeof value === "function" ? value : (input) => JSON.stringify(input, null, 2))
+});
 //#endregion
 //#region src/config/parser/config.ts
 const defaultPaginationKeywords = [
@@ -715,93 +871,44 @@ const defaultPaginationKeywords = [
 	"page",
 	"start"
 ];
-function getParser(userConfig) {
-	return valueToObject({
-		defaultValue: {
-			hooks: {},
-			pagination: { keywords: defaultPaginationKeywords },
-			transforms: {
-				enums: {
-					case: "PascalCase",
-					enabled: false,
-					mode: "root",
-					name: "{{name}}Enum"
-				},
-				propertiesRequiredByDefault: false,
-				readWrite: {
-					enabled: true,
-					requests: {
-						case: "preserve",
-						name: "{{name}}Writable"
-					},
-					responses: {
-						case: "preserve",
-						name: "{{name}}"
-					}
+const parserConfig = defineConfig({
+	hooks: {},
+	pagination: { keywords: defaultPaginationKeywords },
+	transforms: {
+		enums: {
+			$coerce: { string: (mode) => ({ mode }) },
+			$coerceAny: ({ value }) => ({ enabled: Boolean(value) }),
+			case: "PascalCase",
+			enabled: false,
+			mode: "root",
+			name: "{{name}}Enum"
+		},
+		propertiesRequiredByDefault: false,
+		readWrite: {
+			$coerceAny: ({ value }) => ({ enabled: Boolean(value) }),
+			enabled: true,
+			requests: {
+				$coerce: {
+					function: (name) => ({ name }),
+					string: (name) => ({ name })
 				},
-				schemaName: void 0
+				case: "preserve",
+				name: "{{name}}Writable"
 			},
-			validate_EXPERIMENTAL: false
-		},
-		mappers: { object: (fields, defaultValue) => ({
-			...fields,
-			pagination: valueToObject({
-				defaultValue: { ...defaultValue.pagination },
-				value: fields.pagination
-			}),
-			transforms: valueToObject({
-				defaultValue: { ...defaultValue.transforms },
-				mappers: { object: (fields, defaultValue) => ({
-					...fields,
-					enums: valueToObject({
-						defaultValue: {
-							...defaultValue.enums,
-							enabled: fields.enums !== void 0 ? Boolean(fields.enums) : defaultValue.enums.enabled
-						},
-						mappers: {
-							boolean: (enabled) => ({ enabled }),
-							string: (mode) => ({ mode })
-						},
-						value: fields.enums
-					}),
-					propertiesRequiredByDefault: fields.propertiesRequiredByDefault !== void 0 ? fields.propertiesRequiredByDefault : defaultValue.propertiesRequiredByDefault,
-					readWrite: valueToObject({
-						defaultValue: {
-							...defaultValue.readWrite,
-							enabled: fields.readWrite !== void 0 ? Boolean(fields.readWrite) : defaultValue.readWrite.enabled
-						},
-						mappers: {
-							boolean: (enabled) => ({ enabled }),
-							object: (fields, defaultValue) => ({
-								...fields,
-								requests: valueToObject({
-									defaultValue: { ...defaultValue.requests },
-									mappers: {
-										function: (name) => ({ name }),
-										string: (name) => ({ name })
-									},
-									value: fields.requests
-								}),
-								responses: valueToObject({
-									defaultValue: { ...defaultValue.responses },
-									mappers: {
-										function: (name) => ({ name }),
-										string: (name) => ({ name })
-									},
-									value: fields.responses
-								})
-							})
-						},
-						value: fields.readWrite
-					}),
-					schemaName: fields.schemaName !== void 0 ? fields.schemaName : defaultValue.schemaName
-				}) },
-				value: fields.transforms
-			}),
-			validate_EXPERIMENTAL: fields.validate_EXPERIMENTAL === true ? "warn" : fields.validate_EXPERIMENTAL
-		}) },
-		value: userConfig.parser
-	});
+			responses: {
+				$coerce: {
+					function: (name) => ({ name }),
+					string: (name) => ({ name })
+				},
+				case: "preserve",
+				name: "{{name}}"
+			}
+		}
+	},
+	validate_EXPERIMENTAL: coerce((value) => value === true ? "warn" : value || false)
+});
+function getParser(input) {
+	return parserConfig(input.parser ?? {});
 }
 //#endregion
 //#region src/config/utils/dependencies.ts
@@ -1475,6 +1582,7 @@ async function getSpec({ fetchOptions, inputPath, timeout, watch }) {
 //#endregion
 //#region src/utils/minHeap.ts
 var MinHeap = class {
+	declIndex;
 	heap = [];
 	constructor(declIndex) {
 		this.declIndex = declIndex;
@@ -1872,7 +1980,7 @@ var PluginInstance = class {
 	api;
 	config;
 	context;
-	dependencies = [];
+	dependencies = /* @__PURE__ */ new Set();
 	eventHooks;
 	gen;
 	handler;
@@ -1884,6 +1992,8 @@ var PluginInstance = class {
 	* code generation.
 	*/
 	package;
+	/** Symbols declared in the plugin config. */
+	symbols;
 	constructor(props) {
 		this.api = props.api ?? {};
 		this.config = props.config;
@@ -1894,6 +2004,7 @@ var PluginInstance = class {
 		this.handler = props.handler;
 		this.name = props.name;
 		this.package = props.context.package;
+		this.symbols = this.buildSymbols(props.symbols);
 	}
 	external(resource, meta = {}) {
 		return this.gen.symbols.reference({
@@ -2093,7 +2204,7 @@ var PluginInstance = class {
 		const symbolIn = {
 			...symbol,
 			meta: {
-				pluginName: path.isAbsolute(this.name) ? "custom" : this.name,
+				...symbol.external ? {} : { pluginName: path.isAbsolute(this.name) ? "custom" : this.name },
 				...meta
 			},
 			name
@@ -2140,6 +2251,9 @@ var PluginInstance = class {
 		}
 		return result;
 	}
+	buildSymbols(fn) {
+		return fn ? fn(this) : {};
+	}
 	forEachError(error, event) {
 		const originalError = error instanceof Error ? error : new Error(String(error));
 		throw new HeyApiError({
@@ -2264,10 +2378,11 @@ var Context = class {
 			api: plugin.api,
 			config: plugin.config,
 			context: this,
-			dependencies: plugin.dependencies ?? [],
+			dependencies: plugin.dependencies ?? /* @__PURE__ */ new Set(),
 			gen: this.gen,
 			handler: plugin.handler,
-			name: plugin.name
+			name: plugin.name,
+			symbols: plugin.symbols
 		});
 		this.plugins[instance.name] = instance;
 		return instance;
@@ -2601,8 +2716,9 @@ function hasFilters(config) {
 function collectOperations({ filters, parameters, requestBodies, resourceMetadata, responses, schemas }) {
 	const finalSet = /* @__PURE__ */ new Set();
 	const stack = [...filters.operations.include.size ? filters.operations.include : new Set(resourceMetadata.operations.keys())];
-	while (stack.length) {
-		const key = stack.pop();
+	let index = 0;
+	while (index < stack.length) {
+		const key = stack[index++];
 		if (filters.operations.exclude.has(key) || finalSet.has(key)) continue;
 		const node = resourceMetadata.operations.get(key);
 		if (!node) continue;
@@ -2633,8 +2749,9 @@ function collectOperations({ filters, parameters, requestBodies, resourceMetadat
 function collectParameters({ filters, resourceMetadata, schemas }) {
 	const finalSet = /* @__PURE__ */ new Set();
 	const stack = [...filters.parameters.include.size ? filters.parameters.include : new Set(resourceMetadata.parameters.keys())];
-	while (stack.length) {
-		const key = stack.pop();
+	let index = 0;
+	while (index < stack.length) {
+		const key = stack[index++];
 		if (filters.parameters.exclude.has(key) || finalSet.has(key)) continue;
 		const node = resourceMetadata.parameters.get(key);
 		if (!node) continue;
@@ -2663,8 +2780,9 @@ function collectParameters({ filters, resourceMetadata, schemas }) {
 function collectRequestBodies({ filters, resourceMetadata, schemas }) {
 	const finalSet = /* @__PURE__ */ new Set();
 	const stack = [...filters.requestBodies.include.size ? filters.requestBodies.include : new Set(resourceMetadata.requestBodies.keys())];
-	while (stack.length) {
-		const key = stack.pop();
+	let index = 0;
+	while (index < stack.length) {
+		const key = stack[index++];
 		if (filters.requestBodies.exclude.has(key) || finalSet.has(key)) continue;
 		const node = resourceMetadata.requestBodies.get(key);
 		if (!node) continue;
@@ -2693,8 +2811,9 @@ function collectRequestBodies({ filters, resourceMetadata, schemas }) {
 function collectResponses({ filters, resourceMetadata, schemas }) {
 	const finalSet = /* @__PURE__ */ new Set();
 	const stack = [...filters.responses.include.size ? filters.responses.include : new Set(resourceMetadata.responses.keys())];
-	while (stack.length) {
-		const key = stack.pop();
+	let index = 0;
+	while (index < stack.length) {
+		const key = stack[index++];
 		if (filters.responses.exclude.has(key) || finalSet.has(key)) continue;
 		const node = resourceMetadata.responses.get(key);
 		if (!node) continue;
@@ -2723,8 +2842,9 @@ function collectResponses({ filters, resourceMetadata, schemas }) {
 function collectSchemas({ filters, resourceMetadata }) {
 	const finalSet = /* @__PURE__ */ new Set();
 	const stack = [...filters.schemas.include.size ? filters.schemas.include : new Set(resourceMetadata.schemas.keys())];
-	while (stack.length) {
-		const key = stack.pop();
+	let index = 0;
+	while (index < stack.length) {
+		const key = stack[index++];
 		if (filters.schemas.exclude.has(key) || finalSet.has(key)) continue;
 		const node = resourceMetadata.schemas.get(key);
 		if (!node) continue;
@@ -2836,8 +2956,9 @@ function collectExplicitDependencies({ filters, resourceMetadata }) {
 function collectOperationDependencies({ operations, resourceMetadata }) {
 	const finalSet = /* @__PURE__ */ new Set();
 	const stack = [...new Set([...operations].flatMap((key) => [...resourceMetadata.operations.get(key)?.dependencies ?? []]))];
-	while (stack.length) {
-		const key = stack.pop();
+	let index = 0;
+	while (index < stack.length) {
+		const key = stack[index++];
 		if (finalSet.has(key)) continue;
 		finalSet.add(key);
 		const dependencies = getResourceDependencies(key, resourceMetadata);
@@ -4170,6 +4291,47 @@ const mergeParametersObjects = ({ source, target }) => {
 	return result;
 };
 //#endregion
+//#region src/openApi/shared/utils/security.ts
+function securitySchemeSignature(scheme) {
+	switch (scheme.type) {
+		case "apiKey":
+			if (!scheme.in || !scheme.name) return;
+			if (scheme.in !== "header" && scheme.in !== "query" && scheme.in !== "cookie") return;
+			return `apiKey:${scheme.in}:${scheme.name}`;
+		case "basic": return "http:basic";
+		case "http": {
+			const httpScheme = (scheme.scheme ?? "").toLowerCase();
+			if (httpScheme !== "bearer" && httpScheme !== "basic") return;
+			return `http:${httpScheme}`;
+		}
+		case "oauth2":
+		case "openIdConnect": return "http:bearer";
+		default: return;
+	}
+}
+/**
+* Build the set of security keys whose canonical signature collides
+* with another scheme. Only these keys should have their name preserved
+* on the IR `key` field — schemes with unique signatures don't need
+* disambiguation at runtime.
+*/
+function computeAmbiguousSecurityKeys(schemes) {
+	const buckets = /* @__PURE__ */ new Map();
+	for (const [name, scheme] of schemes) {
+		const signature = securitySchemeSignature(scheme);
+		if (!signature) continue;
+		const bucket = buckets.get(signature) ?? [];
+		bucket.push(name);
+		buckets.set(signature, bucket);
+	}
+	const ambiguous = /* @__PURE__ */ new Set();
+	for (const bucket of buckets.values()) {
+		if (bucket.length < 2) continue;
+		for (const name of bucket) ambiguous.add(name);
+	}
+	return ambiguous;
+}
+//#endregion
 //#region src/openApi/shared/utils/validator.ts
 const isSimpleKey = (key) => /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key);
 const formatPath = (path) => path.map((segment, i) => {
@@ -4805,13 +4967,13 @@ const paginationField$2 = ({ context, name, schema }) => {
 };
 //#endregion
 //#region src/openApi/2.0.x/parser/operation.ts
-const parseOperationJsDoc$2 = ({ irOperation, operation }) => {
+function parseOperationJsDoc$2({ irOperation, operation }) {
 	if (operation.deprecated !== void 0) irOperation.deprecated = operation.deprecated;
 	if (operation.description) irOperation.description = operation.description;
 	if (operation.summary) irOperation.summary = operation.summary;
 	if (operation.tags?.length) irOperation.tags = operation.tags;
-};
-const initIrOperation$2 = ({ context, method, operation, path, state }) => {
+}
+function initIrOperation$2({ context, method, operation, path, state }) {
 	const irOperation = {
 		id: operationToId({
 			context,
@@ -4833,8 +4995,8 @@ const initIrOperation$2 = ({ context, method, operation, path, state }) => {
 		target: irOperation
 	});
 	return irOperation;
-};
-const operationToIrOperation$2 = ({ context, method, operation, path, securitySchemesMap, state }) => {
+}
+function operationToIrOperation$2({ ambiguousSecurityKeys, context, method, operation, path, securitySchemesMap, state }) {
 	const irOperation = initIrOperation$2({
 		context,
 		method,
@@ -4990,16 +5152,18 @@ const operationToIrOperation$2 = ({ context, method, operation, path, securitySc
 				}
 			}
 			if (!irSecuritySchemeObject) continue;
+			if (ambiguousSecurityKeys.has(name)) irSecuritySchemeObject.key = name;
 			securitySchemeObjects.set(name, irSecuritySchemeObject);
 		}
 		if (securitySchemeObjects.size) irOperation.security = Array.from(securitySchemeObjects.values());
 	}
 	return irOperation;
-};
-const parsePathOperation$2 = ({ context, method, operation, path, securitySchemesMap, state }) => {
+}
+function parsePathOperation$2({ ambiguousSecurityKeys, context, method, operation, path, securitySchemesMap, state }) {
 	if (!context.ir.paths) context.ir.paths = {};
 	if (!context.ir.paths[path]) context.ir.paths[path] = {};
 	context.ir.paths[path][method] = operationToIrOperation$2({
+		ambiguousSecurityKeys,
 		context,
 		method,
 		operation,
@@ -5007,7 +5171,7 @@ const parsePathOperation$2 = ({ context, method, operation, path, securityScheme
 		securitySchemesMap,
 		state
 	});
-};
+}
 //#endregion
 //#region src/openApi/2.0.x/parser/parameter.ts
 /**
@@ -5206,6 +5370,7 @@ const parseV2_0_X = (context) => {
 		const securitySchemeObject = context.spec.securityDefinitions[name];
 		securitySchemesMap.set(name, securitySchemeObject);
 	}
+	const ambiguousSecurityKeys = computeAmbiguousSecurityKeys(securitySchemesMap);
 	if (context.spec.definitions) for (const name in context.spec.definitions) {
 		const $ref = pathToJsonPointer(["definitions", name]);
 		const schema = context.spec.definitions[name];
@@ -5230,6 +5395,7 @@ const parseV2_0_X = (context) => {
 			security: context.spec.security
 		};
 		const operationArgs = {
+			ambiguousSecurityKeys,
 			context,
 			operation: {
 				...commonOperation,
@@ -6182,13 +6348,13 @@ const paginationField$1 = ({ context, name, schema }) => {
 };
 //#endregion
 //#region src/openApi/3.0.x/parser/operation.ts
-const parseOperationJsDoc$1 = ({ irOperation, operation }) => {
+function parseOperationJsDoc$1({ irOperation, operation }) {
 	if (operation.deprecated !== void 0) irOperation.deprecated = operation.deprecated;
 	if (operation.description) irOperation.description = operation.description;
 	if (operation.summary) irOperation.summary = operation.summary;
 	if (operation.tags?.length) irOperation.tags = operation.tags;
-};
-const initIrOperation$1 = ({ context, method, operation, path, state }) => {
+}
+function initIrOperation$1({ context, method, operation, path, state }) {
 	const irOperation = {
 		id: operationToId({
 			context,
@@ -6210,8 +6376,8 @@ const initIrOperation$1 = ({ context, method, operation, path, state }) => {
 		target: irOperation
 	});
 	return irOperation;
-};
-const operationToIrOperation$1 = ({ context, method, operation, path, securitySchemesMap, state }) => {
+}
+function operationToIrOperation$1({ ambiguousSecurityKeys, context, method, operation, path, securitySchemesMap, state }) {
 	const irOperation = initIrOperation$1({
 		context,
 		method,
@@ -6286,17 +6452,19 @@ const operationToIrOperation$1 = ({ context, method, operation, path, securitySc
 		for (const securityRequirementObject of operation.security) for (const name in securityRequirementObject) {
 			const securitySchemeObject = securitySchemesMap.get(name);
 			if (!securitySchemeObject) continue;
+			if (ambiguousSecurityKeys.has(name)) securitySchemeObject.key = name;
 			securitySchemeObjects.set(name, securitySchemeObject);
 		}
 		if (securitySchemeObjects.size) irOperation.security = Array.from(securitySchemeObjects.values());
 	}
 	return irOperation;
-};
-const parsePathOperation$1 = ({ context, method, operation, path, securitySchemesMap, state }) => {
+}
+function parsePathOperation$1({ ambiguousSecurityKeys, context, method, operation, path, securitySchemesMap, state }) {
 	if (!context.ir.paths) context.ir.paths = {};
 	if (!context.ir.paths[path]) context.ir.paths[path] = {};
 	if (operation.servers) context.ir.servers = [...context.ir.servers ?? [], ...operation.servers];
 	context.ir.paths[path][method] = operationToIrOperation$1({
+		ambiguousSecurityKeys,
 		context,
 		method,
 		operation,
@@ -6304,7 +6472,7 @@ const parsePathOperation$1 = ({ context, method, operation, path, securityScheme
 		securitySchemesMap,
 		state
 	});
-};
+}
 //#endregion
 //#region src/openApi/3.0.x/parser/parameter.ts
 /**
@@ -6590,6 +6758,7 @@ const parseV3_0_X = (context) => {
 			});
 		}
 	}
+	const ambiguousSecurityKeys = computeAmbiguousSecurityKeys(securitySchemesMap);
 	parseServers$1({ context });
 	for (const path in context.spec.paths) {
 		if (path.startsWith("x-")) continue;
@@ -6599,6 +6768,7 @@ const parseV3_0_X = (context) => {
 			...pathItem
 		} : pathItem;
 		const operationArgs = {
+			ambiguousSecurityKeys,
 			context,
 			operation: {
 				description: finalPathItem.description,
@@ -7637,13 +7807,13 @@ const paginationField = ({ context, name, schema }) => {
 };
 //#endregion
 //#region src/openApi/3.1.x/parser/operation.ts
-const parseOperationJsDoc = ({ irOperation, operation }) => {
+function parseOperationJsDoc({ irOperation, operation }) {
 	if (operation.deprecated !== void 0) irOperation.deprecated = operation.deprecated;
 	if (operation.description) irOperation.description = operation.description;
 	if (operation.summary) irOperation.summary = operation.summary;
 	if (operation.tags?.length) irOperation.tags = operation.tags;
-};
-const initIrOperation = ({ context, method, operation, path, state }) => {
+}
+function initIrOperation({ context, method, operation, path, state }) {
 	const irOperation = {
 		id: operationToId({
 			context,
@@ -7665,8 +7835,8 @@ const initIrOperation = ({ context, method, operation, path, state }) => {
 		target: irOperation
 	});
 	return irOperation;
-};
-const operationToIrOperation = ({ context, method, operation, path, securitySchemesMap, state }) => {
+}
+function operationToIrOperation({ ambiguousSecurityKeys, context, method, operation, path, securitySchemesMap, state }) {
 	const irOperation = initIrOperation({
 		context,
 		method,
@@ -7732,15 +7902,17 @@ const operationToIrOperation = ({ context, method, operation, path, securitySche
 		for (const securityRequirementObject of operation.security) for (const name in securityRequirementObject) {
 			const securitySchemeObject = securitySchemesMap.get(name);
 			if (!securitySchemeObject) continue;
+			if (ambiguousSecurityKeys.has(name)) securitySchemeObject.key = name;
 			securitySchemeObjects.set(name, securitySchemeObject);
 		}
 		if (securitySchemeObjects.size) irOperation.security = Array.from(securitySchemeObjects.values());
 	}
 	return irOperation;
-};
-const parseOperationObject = ({ context, method, operation, path, securitySchemesMap, state }) => {
+}
+function parseOperationObject({ ambiguousSecurityKeys, context, method, operation, path, securitySchemesMap, state }) {
 	if (operation.servers) context.ir.servers = [...context.ir.servers ?? [], ...operation.servers];
 	return { parsed: operationToIrOperation({
+		ambiguousSecurityKeys,
 		context,
 		method,
 		operation,
@@ -7748,8 +7920,8 @@ const parseOperationObject = ({ context, method, operation, path, securityScheme
 		securitySchemesMap,
 		state
 	}) };
-};
-const parsePathOperation = ({ context, method, path, ...options }) => {
+}
+function parsePathOperation({ context, method, path, ...options }) {
 	if (!context.ir.paths) context.ir.paths = {};
 	if (!context.ir.paths[path]) context.ir.paths[path] = {};
 	const { parsed } = parseOperationObject({
@@ -7759,8 +7931,8 @@ const parsePathOperation = ({ context, method, path, ...options }) => {
 		...options
 	});
 	context.ir.paths[path][method] = parsed;
-};
-const parseWebhookOperation = ({ context, key, method, ...options }) => {
+}
+function parseWebhookOperation({ context, key, method, ...options }) {
 	if (!context.ir.webhooks) context.ir.webhooks = {};
 	if (!context.ir.webhooks[key]) context.ir.webhooks[key] = {};
 	const { parsed } = parseOperationObject({
@@ -7770,7 +7942,7 @@ const parseWebhookOperation = ({ context, key, method, ...options }) => {
 		...options
 	});
 	context.ir.webhooks[key][method] = parsed;
-};
+}
 //#endregion
 //#region src/openApi/3.1.x/parser/parameter.ts
 /**
@@ -7983,7 +8155,7 @@ const validateOpenApiSpec = (spec, logger) => {
 };
 //#endregion
 //#region src/openApi/3.1.x/parser/webhook.ts
-const parseWebhooks = ({ context, securitySchemesMap }) => {
+function parseWebhooks({ ambiguousSecurityKeys, context, securitySchemesMap }) {
 	const state = { ids: /* @__PURE__ */ new Map() };
 	for (const key in context.spec.webhooks) {
 		const webhook = context.spec.webhooks[key];
@@ -7992,6 +8164,7 @@ const parseWebhooks = ({ context, securitySchemesMap }) => {
 			...webhook
 		} : webhook;
 		const operationArgs = {
+			ambiguousSecurityKeys,
 			context,
 			key,
 			operation: {
@@ -8128,7 +8301,7 @@ const parseWebhooks = ({ context, securitySchemesMap }) => {
 			}
 		});
 	}
-};
+}
 //#endregion
 //#region src/openApi/3.1.x/parser/index.ts
 const parseV3_1_X = (context) => {
@@ -8200,6 +8373,7 @@ const parseV3_1_X = (context) => {
 			});
 		}
 	}
+	const ambiguousSecurityKeys = computeAmbiguousSecurityKeys(securitySchemesMap);
 	parseServers({ context });
 	for (const path in context.spec.paths) {
 		if (path.startsWith("x-")) continue;
@@ -8209,6 +8383,7 @@ const parseV3_1_X = (context) => {
 			...pathItem
 		} : pathItem;
 		const operationArgs = {
+			ambiguousSecurityKeys,
 			context,
 			operation: {
 				description: finalPathItem.description,
@@ -8346,6 +8521,7 @@ const parseV3_1_X = (context) => {
 		});
 	}
 	parseWebhooks({
+		ambiguousSecurityKeys,
 		context,
 		securitySchemesMap
 	});
@@ -8378,15 +8554,43 @@ function parseOpenApiSpec(context) {
 * Built-in strategies for operations.
 */
 const OperationStrategy = {
+	/**
+	* Creates one root container per operation tag.
+	*
+	* Operations with multiple tags appear in multiple root containers.
+	* Operations without tags use the fallback root container.
+	*
+	* @example
+	* // Operation with tags: ['users', 'admin']
+	* // Path function returns: ['list']
+	* // Result: [{ path: ['users', 'list'], shell }, { path: ['admin', 'list'], shell }]
+	*/
 	byTags: (config) => (operation) => {
 		const tags = operation.tags && operation.tags.length ? operation.tags : [config.fallback];
 		const pathSegments = (config.path ?? OperationPath.id())(operation);
 		return tags.map((tag) => [tag, ...pathSegments]);
 	},
+	/**
+	* Creates flat functions without any container.
+	*
+	* Each operation becomes a standalone function at the root level.
+	* No shell is applied.
+	*
+	* @example
+	* // Operation id: 'getUsers'
+	* // Result: [{ path: ['getUsers'] }]
+	*/
 	flat: (config) => (operation) => {
 		const pathSegments = (config?.path ?? OperationPath.id())(operation);
 		return [[pathSegments[pathSegments.length - 1]]];
 	},
+	/**
+	* Places all operations under a single root container.
+	*
+	* @example
+	* // Root: 'Sdk', path function returns: ['users', 'list']
+	* // Result: [{ path: ['Sdk', 'users', 'list'], shell }]
+	*/
 	single: (config) => (operation) => {
 		const pathSegments = (config.path ?? OperationPath.id())(operation);
 		return [[config.root, ...pathSegments]];
@@ -8396,6 +8600,17 @@ const OperationStrategy = {
 * Built-in path derivation helpers for operations.
 */
 const OperationPath = {
+	/**
+	* Splits operationId by delimiters to create nested paths.
+	*
+	* @example
+	* // operationId: 'users.accounts.list'
+	* // Result: ['users', 'accounts', 'list']
+	*
+	* @example
+	* // operationId: 'users/accounts/getAll'
+	* // Result: ['users', 'accounts', 'getAll']
+	*/
 	fromOperationId: (config) => (operation) => {
 		const fallback = config?.fallback ?? OperationPath.id();
 		if (!operation.operationId) return fallback(operation);
@@ -8403,6 +8618,23 @@ const OperationPath = {
 		const segments = operation.operationId.split(delimiters).filter(Boolean);
 		return !segments.length ? fallback(operation) : segments;
 	},
+	/**
+	* Splits path by delimiters to create nested paths.
+	*
+	* Can include the method as a prefix or suffix segment.
+	*
+	* @example
+	* // path: '/users/{id}/accounts', method: 'get', delimiters: /[\/{}]+/, methodPosition: 'none'
+	* // Result: ['users', 'id', 'accounts']
+	*
+	* @example
+	* // path: '/users/{id}/accounts', method: 'get', delimiters: /[\/{}]+/, methodPosition: 'prefix'
+	* // Result: ['get', 'users', 'id', 'accounts']
+	*
+	* @example
+	* // path: '/users/{id}/accounts', method: 'get', delimiters: /[\/{}]+/, methodPosition: 'suffix'
+	* // Result: ['users', 'id', 'accounts', 'get']
+	*/
 	fromPath: (config) => (operation) => {
 		const delimiters = config?.delimiters ?? /[./]/;
 		const segments = operation.path.split(delimiters).filter(Boolean);
@@ -8417,6 +8649,13 @@ const OperationPath = {
 		}
 		return segments;
 	},
+	/**
+	* Uses operation.id as a single path segment.
+	*
+	* @example
+	* // operation.id: 'getUserById'
+	* // Result: ['getUserById']
+	*/
 	id: () => (operation) => [operation.id]
 };
 //#endregion
@@ -8559,31 +8798,22 @@ function warnOnConflictingDuplicatePlugins(plugins) {
 }
 //#endregion
 //#region src/plugins/shared/utils/config.ts
-const definePluginConfig = (defaultConfig) => (userConfig) => ({
-	...defaultConfig,
-	config: {
-		...defaultConfig.config,
-		...userConfig
-	}
-});
-/**
-* Reusable mappers for `enabled` and `name` fields.
-*/
-const mappers = {
-	boolean: (enabled) => ({ enabled }),
-	function: (name) => ({
-		enabled: true,
-		name
-	}),
-	object: (fields) => ({
-		enabled: true,
-		...fields
-	}),
-	string: (name) => ({
-		enabled: true,
-		name
-	})
-};
+function definePluginConfig(pluginConfig) {
+	return (userConfig) => ({
+		...pluginConfig,
+		config: {
+			...pluginConfig.config,
+			...userConfig ?? {}
+		},
+		/**
+		* Cast name to `any` so it doesn't throw type error in `plugins` array.
+		* We could allow any `string` as plugin `name` in the object syntax, but
+		* that TypeScript trick would cause all string methods to appear as
+		* suggested auto completions, which is undesirable.
+		*/
+		name: pluginConfig.name
+	});
+}
 //#endregion
 //#region src/plugins/symbol.ts
 /**
@@ -8647,9 +8877,15 @@ function escapeComment(value) {
 * Utilities shared across the package.
 */
 const utils = {
+	/**
+	* @deprecated use `toCase` instead
+	*/
 	stringCase({ case: casing, stripLeadingSeparators, value }) {
 		return toCase(value, casing, { stripLeadingSeparators });
 	},
+	/**
+	* Converts the given string to the specified casing.
+	*/
 	toCase
 };
 //#endregion
@@ -8773,6 +9009,6 @@ function pathToName(path, options) {
 	return names.join("-");
 }
 //#endregion
-export { ConfigError, ConfigValidationError, Context, HeyApiError, InputError, IntentContext, JobError, MinHeap, OperationPath, OperationStrategy, PluginInstance, addItemsToSchema, applyNaming, buildGraph, buildSymbolIn, checkNodeVersion, childContext, compileInputPath, createOperationKey, createSchemaProcessor, createSchemaWalker, debugTools, deduplicateSchema, defaultPaginationKeywords, definePluginConfig, dependencyFactory, encodeJsonPointerSegment, ensureDirSync, escapeComment, findPackageJson, findTsConfigPath, getInput, getInputError, getLogs, getParser, getSpec, hasOperationDataRequired, hasParameterGroupObjectRequired, hasParametersObjectRequired, heyApiRegistryBaseUrl, inputToApiRegistry, isEnvironment, isTopLevelComponent, jsonPointerToPath, loadPackageJson, logCrashReport, logInputPaths, mappers, normalizeJsonPointer, openGitHubIssueWithCrashReport, operationPagination, operationResponsesMap, outputHeaderToPrefix, parameterWithPagination, parseOpenApiSpec, parseUrl, parseV2_0_X, parseV3_0_X, parseV3_1_X, patchOpenApiSpec, pathToJsonPointer, pathToName, postprocessOutput, printCliIntro, printCrashReport, refToName, requestValidatorLayers, resolveNaming, resolveRef, resolveSource, resolveValidatorLayer, satisfies, shouldReportCrash, statusCodeToGroup, toCase, utils, valueToObject, warnOnConflictingDuplicatePlugins };
+export { COERCER, ConfigError, ConfigValidationError, Context, HeyApiError, InputError, IntentContext, JobError, MinHeap, OperationPath, OperationStrategy, PluginInstance, addItemsToSchema, applyNaming, buildGraph, buildSymbolIn, checkNodeVersion, childContext, coerce, collectDeps, compileInputPath, createOperationKey, createSchemaProcessor, createSchemaWalker, debugTools, deduplicateSchema, defaultPaginationKeywords, defineConfig, definePluginConfig, dependencyFactory, encodeJsonPointerSegment, ensureDirSync, escapeComment, findPackageJson, findTsConfigPath, getInput, getInputError, getLogs, getParser, getSpec, hasOperationDataRequired, hasParameterGroupObjectRequired, hasParametersObjectRequired, heyApiRegistryBaseUrl, inputToApiRegistry, isCoercer, isEnvironment, isPlainObject, isTopLevelComponent, jsonPointerToPath, loadPackageJson, logCrashReport, logInputPaths, normalizeJsonPointer, openGitHubIssueWithCrashReport, operationPagination, operationResponsesMap, outputHeaderToPrefix, parameterWithPagination, parseOpenApiSpec, parseUrl, parseV2_0_X, parseV3_0_X, parseV3_1_X, patchOpenApiSpec, pathToJsonPointer, pathToName, postprocessOutput, printCliIntro, printCrashReport, refToName, requestValidatorLayers, resolveNaming, resolveRef, resolveValidatorLayer, satisfies, shouldReportCrash, sourceConfig, statusCodeToGroup, toCase, utils, warnOnConflictingDuplicatePlugins };
 
 //# sourceMappingURL=index.mjs.map