ng-openapi 0.3.3 → 0.4.0

package/index.js

@@ -53,7 +53,7 @@ var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read fr
 var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
 var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), setter ? setter.call(obj, value) : member.set(obj, value), value);
 var __async = (__this, __arguments, generator) => {
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve2, reject) => {
     var fulfilled = (value) => {
       try {
         step(generator.next(value));
@@ -68,7 +68,7 @@ var __async = (__this, __arguments, generator) => {
         reject(e);
       }
     };
-    var step = (x) => x.done ? resolve(x.value) : Promise.resolve(x.value).then(fulfilled, rejected);
+    var step = (x) => x.done ? resolve2(x.value) : Promise.resolve(x.value).then(fulfilled, rejected);
     step((generator = generator.apply(__this, __arguments)).next());
   });
 };
@@ -78,31 +78,50 @@ var index_exports = {};
 __export(index_exports, {
   BASE_INTERCEPTOR_HEADER_COMMENT: () => BASE_INTERCEPTOR_HEADER_COMMENT,
   CONTENT_TYPES: () => CONTENT_TYPES,
+  ConfigLoadError: () => ConfigLoadError,
   ConfigValidationError: () => ConfigValidationError,
+  DuplicateGeneratedNameError: () => DuplicateGeneratedNameError,
   HTTP_RESOURCE_GENERATOR_HEADER_COMMENT: () => HTTP_RESOURCE_GENERATOR_HEADER_COMMENT,
+  InvalidIdentifierError: () => InvalidIdentifierError,
   MAIN_INDEX_GENERATOR_HEADER_COMMENT: () => MAIN_INDEX_GENERATOR_HEADER_COMMENT,
   NgOpenApiError: () => NgOpenApiError,
   PROVIDER_GENERATOR_HEADER_COMMENT: () => PROVIDER_GENERATOR_HEADER_COMMENT,
   REQUEST_PARAMS_GENERATOR_HEADER_COMMENT: () => REQUEST_PARAMS_GENERATOR_HEADER_COMMENT,
+  RESERVED_MEMBER_NAMES: () => RESERVED_MEMBER_NAMES,
+  RESOURCE_ARGUMENT_PROFILE: () => RESOURCE_ARGUMENT_PROFILE,
+  SERVICE_ARGUMENT_PROFILE: () => SERVICE_ARGUMENT_PROFILE,
   SERVICE_GENERATOR_HEADER_COMMENT: () => SERVICE_GENERATOR_HEADER_COMMENT,
   SERVICE_INDEX_GENERATOR_HEADER_COMMENT: () => SERVICE_INDEX_GENERATOR_HEADER_COMMENT,
   SpecLoadError: () => SpecLoadError,
   SpecParseError: () => SpecParseError,
   SwaggerParser: () => SwaggerParser,
   TYPE_GENERATOR_HEADER_COMMENT: () => TYPE_GENERATOR_HEADER_COMMENT,
+  UnresolvedPathTemplateError: () => UnresolvedPathTemplateError,
   ZOD_PLUGIN_GENERATOR_HEADER_COMMENT: () => ZOD_PLUGIN_GENERATOR_HEADER_COMMENT,
   ZOD_PLUGIN_INDEX_GENERATOR_HEADER_COMMENT: () => ZOD_PLUGIN_INDEX_GENERATOR_HEADER_COMMENT,
+  assertDistinctMemberNames: () => assertDistinctMemberNames,
   camelCase: () => camelCase,
+  capitalizeFirst: () => capitalizeFirst,
+  clientNameIdentifier: () => clientNameIdentifier,
   defineConfig: () => defineConfig,
+  describeOperation: () => describeOperation,
+  effectiveClientName: () => effectiveClientName,
   emitDefaultHeadersMerge: () => emitDefaultHeadersMerge,
+  emitDocs: () => emitDocs,
   emitHeaders: () => emitHeaders,
+  emitObjectKey: () => emitObjectKey,
+  emitPropertyName: () => emitPropertyName,
   emitQueryParams: () => emitQueryParams,
   emitResponseTypeOption: () => emitResponseTypeOption,
   emitServiceDecorator: () => emitServiceDecorator,
   emitSignalAwareQueryParams: () => emitSignalAwareQueryParams,
   emitUrlConstruction: () => emitUrlConstruction,
   emitUrlExpression: () => emitUrlExpression,
-  escapeString: () => escapeString,
+  escapeDoubleQuoted: () => escapeDoubleQuoted,
+  escapeJsDoc: () => escapeJsDoc,
+  escapeSingleQuoted: () => escapeSingleQuoted,
+  escapeString: () => escapeSingleQuoted,
+  escapeTemplateLiteral: () => escapeTemplateLiteral,
   extractPaths: () => extractPaths,
   generateFromConfig: () => generateFromConfig,
   generateParseRequestTypeParams: () => generateParseRequestTypeParams,
@@ -110,6 +129,7 @@ __export(index_exports, {
   getClientContextTokenName: () => getClientContextTokenName,
   getInterceptorsTokenName: () => getInterceptorsTokenName,
   getModelTypeName: () => getModelTypeName,
+  getOperationMethodName: () => getOperationMethodName,
   getRequestBodyType: () => getRequestBodyType,
   getResourceClassName: () => getResourceClassName,
   getResponseInfoFromResponse: () => getResponseInfoFromResponse,
@@ -117,21 +137,27 @@ __export(index_exports, {
   getResponseTypeFromResponse: () => getResponseTypeFromResponse,
   getServiceClassName: () => getServiceClassName,
   getTypeScriptType: () => getTypeScriptType,
+  groupOperationsByController: () => groupOperationsByController,
   hasDuplicateFunctionNames: () => hasDuplicateFunctionNames,
   inferResponseTypeFromContentType: () => inferResponseTypeFromContentType,
   isDataTypeInterface: () => isDataTypeInterface,
   isPrimitiveType: () => isPrimitiveType,
   isUrl: () => isUrl,
+  isValidIdentifier: () => isValidIdentifier,
   joinRequestOptionEntries: () => joinRequestOptionEntries,
   kebabCase: () => kebabCase,
   listGeneratedBarrelDirs: () => listGeneratedBarrelDirs,
   listGeneratedFileNames: () => listGeneratedFileNames,
+  loadConfigFile: () => loadConfigFile,
   normalizeSchema: () => normalizeSchema,
   normalizeSpec: () => normalizeSpec,
   nullableType: () => nullableType,
   pascalCase: () => pascalCase,
   pascalCaseForEnums: () => pascalCaseForEnums,
   plainParamValue: () => plainParamValue,
+  quoteLiteral: () => quoteLiteral,
+  reservedMemberCollision: () => reservedMemberCollision,
+  resolveArgumentNames: () => resolveArgumentNames,
   screamingSnakeCase: () => screamingSnakeCase,
   signalAwareParamValue: () => signalAwareParamValue,
   validateGeneratorConfig: () => validateGeneratorConfig,
@@ -160,17 +186,100 @@ function isUrl(input) {
 __name(isUrl, "isUrl");
 
 // ../shared/src/errors.ts
+var NG_OPENAPI_ERROR_BRAND = "__ngOpenApiError";
+var ERROR_LINEAGE = /* @__PURE__ */ new WeakMap();
+var FALLBACK_LINEAGE = Object.freeze([
+  "NgOpenApiError"
+]);
+function registerError(cls, lineage) {
+  ERROR_LINEAGE.set(cls, Object.freeze([
+    ...lineage
+  ]));
+  return cls;
+}
+__name(registerError, "registerError");
+function inheritedLineage(cls) {
+  for (let current = cls; typeof current === "function"; current = Object.getPrototypeOf(current)) {
+    const lineage = ERROR_LINEAGE.get(current);
+    if (lineage) {
+      return lineage;
+    }
+  }
+  return FALLBACK_LINEAGE;
+}
+__name(inheritedLineage, "inheritedLineage");
 var _NgOpenApiError = class _NgOpenApiError extends Error {
   constructor(message, cause) {
     super(message);
     /** The underlying error that caused this one, when there is one. */
     __publicField(this, "cause");
-    this.name = new.target.name;
+    const lineage = inheritedLineage(new.target);
+    this.name = lineage[0];
     this.cause = cause;
+    Object.defineProperty(this, NG_OPENAPI_ERROR_BRAND, {
+      value: lineage,
+      enumerable: false,
+      writable: false,
+      configurable: false
+    });
+  }
+  /**
+   * `message` and `name` are non-enumerable on Error, so the default
+   * JSON.stringify dropped both — the least useful possible serialization for
+   * something that exists to be logged.
+   *
+   * The payload is spread rather than enumerated: `source`, `issues`,
+   * `operation`, `names` and `placeholders` are why these classes are typed
+   * in the first place, and listing fields by hand silently drops whichever
+   * ones a later subclass adds.
+   */
+  toJSON() {
+    const cause = this.cause instanceof Error ? this.cause.message : this.cause;
+    return __spreadValues(__spreadValues({
+      name: this.name,
+      message: this.message
+    }, cause === void 0 ? {} : {
+      cause
+    }), Object.fromEntries(Object.entries(this).filter(([key]) => key !== "cause")));
+  }
+  /**
+   * Recognizes branded errors from another bundled copy of this module, so
+   * `error instanceof SpecLoadError` works for a plugin-thrown error too.
+   * The prototype chain is checked first, so a caller's own subclass of these
+   * classes still matches even though it carries no lineage entry.
+   *
+   * Never throws and never runs foreign code: both reflective reads sit
+   * inside the try, because a Proxy traps `getPrototypeOf` just as readily as
+   * `getOwnPropertyDescriptor`.
+   */
+  static [Symbol.hasInstance](value) {
+    var _a;
+    if (typeof value !== "object" || value === null) {
+      return false;
+    }
+    try {
+      if (Object.prototype.isPrototypeOf.call(this.prototype, value)) {
+        return true;
+      }
+      const expected = (_a = ERROR_LINEAGE.get(this)) == null ? void 0 : _a[0];
+      if (expected === void 0) {
+        return false;
+      }
+      const descriptor = Object.getOwnPropertyDescriptor(value, NG_OPENAPI_ERROR_BRAND);
+      if (!descriptor || descriptor.enumerable || !("value" in descriptor)) {
+        return false;
+      }
+      return Array.isArray(descriptor.value) && descriptor.value.includes(expected);
+    } catch (e) {
+      return false;
+    }
   }
 };
 __name(_NgOpenApiError, "NgOpenApiError");
 var NgOpenApiError = _NgOpenApiError;
+registerError(NgOpenApiError, [
+  "NgOpenApiError"
+]);
 var _SpecLoadError = class _SpecLoadError extends NgOpenApiError {
   constructor(message, source, cause) {
     super(message, cause);
@@ -181,6 +290,10 @@ var _SpecLoadError = class _SpecLoadError extends NgOpenApiError {
 };
 __name(_SpecLoadError, "SpecLoadError");
 var SpecLoadError = _SpecLoadError;
+registerError(SpecLoadError, [
+  "SpecLoadError",
+  "NgOpenApiError"
+]);
 var _SpecParseError = class _SpecParseError extends NgOpenApiError {
   constructor(message, source, cause) {
     super(message, cause);
@@ -191,6 +304,108 @@ var _SpecParseError = class _SpecParseError extends NgOpenApiError {
 };
 __name(_SpecParseError, "SpecParseError");
 var SpecParseError = _SpecParseError;
+registerError(SpecParseError, [
+  "SpecParseError",
+  "NgOpenApiError"
+]);
+function describeOperation(operation) {
+  const location = `(${operation.method}) ${operation.path}`;
+  return operation.operationId ? `${operation.operationId} (${location})` : location;
+}
+__name(describeOperation, "describeOperation");
+function captureOperation(operation) {
+  return Object.freeze({
+    operationId: operation.operationId,
+    method: operation.method,
+    path: operation.path
+  });
+}
+__name(captureOperation, "captureOperation");
+var _InvalidIdentifierError = class _InvalidIdentifierError extends NgOpenApiError {
+  constructor(message, operation, identifier) {
+    super(message);
+    /** The rejected name, verbatim; absent when no name could be derived. */
+    __publicField(this, "identifier");
+    /** The operation whose name was being derived. */
+    __publicField(this, "operation");
+    this.operation = captureOperation(operation);
+    this.identifier = identifier;
+  }
+};
+__name(_InvalidIdentifierError, "InvalidIdentifierError");
+var InvalidIdentifierError = _InvalidIdentifierError;
+registerError(InvalidIdentifierError, [
+  "InvalidIdentifierError",
+  "NgOpenApiError"
+]);
+var _DuplicateGeneratedNameError = class _DuplicateGeneratedNameError extends NgOpenApiError {
+  constructor(message, names, operations = []) {
+    super(message);
+    /** The colliding generated names. */
+    __publicField(this, "names");
+    /** The operations that produced them, when known. */
+    __publicField(this, "operations");
+    this.names = Object.freeze([
+      ...names
+    ]);
+    this.operations = Object.freeze(operations.map(captureOperation));
+  }
+};
+__name(_DuplicateGeneratedNameError, "DuplicateGeneratedNameError");
+var DuplicateGeneratedNameError = _DuplicateGeneratedNameError;
+registerError(DuplicateGeneratedNameError, [
+  "DuplicateGeneratedNameError",
+  "NgOpenApiError"
+]);
+var _UnresolvedPathTemplateError = class _UnresolvedPathTemplateError extends NgOpenApiError {
+  constructor(message, path15, placeholders) {
+    super(message);
+    /** The path as written in the spec. */
+    __publicField(this, "path");
+    /** Placeholder names with no declared parameter. */
+    __publicField(this, "placeholders");
+    this.path = path15;
+    this.placeholders = Object.freeze([
+      ...placeholders
+    ]);
+  }
+};
+__name(_UnresolvedPathTemplateError, "UnresolvedPathTemplateError");
+var UnresolvedPathTemplateError = _UnresolvedPathTemplateError;
+registerError(UnresolvedPathTemplateError, [
+  "UnresolvedPathTemplateError",
+  "NgOpenApiError"
+]);
+var _ConfigValidationError = class _ConfigValidationError extends NgOpenApiError {
+  constructor(issues) {
+    super(`Invalid ng-openapi configuration:
+${issues.map((issue) => `  - ${issue}`).join("\n")}`);
+    __publicField(this, "issues");
+    this.issues = Object.freeze([
+      ...issues
+    ]);
+  }
+};
+__name(_ConfigValidationError, "ConfigValidationError");
+var ConfigValidationError = _ConfigValidationError;
+registerError(ConfigValidationError, [
+  "ConfigValidationError",
+  "NgOpenApiError"
+]);
+var _ConfigLoadError = class _ConfigLoadError extends NgOpenApiError {
+  constructor(message, source, cause) {
+    super(message, cause);
+    /** Path of the config file that failed to load. */
+    __publicField(this, "source");
+    this.source = source;
+  }
+};
+__name(_ConfigLoadError, "ConfigLoadError");
+var ConfigLoadError = _ConfigLoadError;
+registerError(ConfigLoadError, [
+  "ConfigLoadError",
+  "NgOpenApiError"
+]);
 
 // ../shared/src/core/spec-loader.ts
 function loadSpecContent(pathOrUrl) {
@@ -296,6 +511,439 @@ function detectFormat(content) {
 }
 __name(detectFormat, "detectFormat");
 
+// ../shared/src/utils/string.utils.ts
+var IDENTIFIER_SEPARATORS = /(?:_|[^\p{ID_Continue}$])+(.)?/gu;
+var INVALID_IDENTIFIER_START = /^[^\p{ID_Start}$_]/u;
+function toIdentifier(converted) {
+  if (converted === "") {
+    return "_";
+  }
+  return converted.replace(INVALID_IDENTIFIER_START, (char) => `_${char}`);
+}
+__name(toIdentifier, "toIdentifier");
+function isValidIdentifier(name) {
+  return /^[\p{ID_Start}$_][\p{ID_Continue}$]*$/u.test(name);
+}
+__name(isValidIdentifier, "isValidIdentifier");
+function camelCase(str) {
+  const converted = str.replace(IDENTIFIER_SEPARATORS, (_, char) => char ? char.toUpperCase() : "").replace(/^./u, (char) => char.toLowerCase());
+  return toIdentifier(converted);
+}
+__name(camelCase, "camelCase");
+function kebabCase(str) {
+  return str.replace(/([a-z])([A-Z])/g, "$1-$2").replace(/[-_\s]+/g, "-").toLowerCase();
+}
+__name(kebabCase, "kebabCase");
+function pascalCase(str) {
+  const converted = str.replace(IDENTIFIER_SEPARATORS, (_, char) => char ? char.toUpperCase() : "").replace(/^./u, (char) => char.toUpperCase());
+  return toIdentifier(converted);
+}
+__name(pascalCase, "pascalCase");
+function screamingSnakeCase(str) {
+  return str.replace(/([a-z])([A-Z])/g, "$1_$2").replace(/[-\s]+/g, "_").toUpperCase();
+}
+__name(screamingSnakeCase, "screamingSnakeCase");
+function pascalCaseForEnums(str) {
+  const converted = str.replace(/[^a-zA-Z0-9]/g, "_").replace(/(?:^|_)([a-z])/g, (_, char) => char.toUpperCase()).replace(/^([0-9])/, "_$1");
+  return converted === "" ? "_" : converted;
+}
+__name(pascalCaseForEnums, "pascalCaseForEnums");
+function capitalizeFirst(str) {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+__name(capitalizeFirst, "capitalizeFirst");
+
+// ../shared/src/core/inline-nested-refs.ts
+function inlineNestedRefs(spec, onWarning) {
+  const ctx = {
+    root: spec,
+    onWarning,
+    warned: /* @__PURE__ */ new Set(),
+    emittedPerCause: /* @__PURE__ */ new Map(),
+    deferred: /* @__PURE__ */ new Map(),
+    budget: MAX_INLINED_NODES,
+    budgetExhausted: false
+  };
+  const result = transform(spec, ctx, [], false);
+  flushDeferredWarnings(ctx);
+  return result;
+}
+__name(inlineNestedRefs, "inlineNestedRefs");
+var MAX_REF_DEPTH = 64;
+var MAX_INLINED_NODES = 1e5;
+var MAX_WARNINGS_PER_CAUSE = 10;
+var WARNING_CAUSE_LABELS = {
+  cyclic: "cyclic nested $ref(s) left in place",
+  unresolvable: "unresolvable nested $ref(s) left in place",
+  "not-a-schema": "nested $ref(s) resolving to a non-schema value",
+  "not-a-schema-position": "nested $ref(s) that do not address a schema position",
+  depth: "nested $ref(s) past the pointer-hop limit",
+  budget: "nested $ref(s) left uninlined after the expansion budget ran out",
+  "sibling-conflict": "nested $ref site(s) whose siblings overrode the target",
+  "sibling-on-boolean": "nested $ref site(s) whose siblings were dropped on a boolean target",
+  "malformed-ref": "non-string $ref value(s)",
+  "unsupported-pointer-root": "deep $ref(s) into a root this pass does not inline"
+};
+var REFUSED = /* @__PURE__ */ Symbol("refused");
+function transform(node, ctx, chain, keysAreNames) {
+  var _a;
+  if (Array.isArray(node)) {
+    let changed2 = false;
+    const items = node.map((item) => {
+      const next = transform(item, ctx, chain, false);
+      changed2 || (changed2 = next !== item);
+      return next;
+    });
+    return changed2 ? items : node;
+  }
+  if (!isPlainObject(node)) {
+    return node;
+  }
+  const ref = keysAreNames ? void 0 : node["$ref"];
+  if (typeof ref === "string") {
+    if (isDeepSchemaPointer(ref)) {
+      const inlined = inlineTarget(node, ref, ctx, chain);
+      if (inlined !== REFUSED) {
+        return inlined;
+      }
+    } else if (isDeepPointerIntoUnsupportedRoot(ref)) {
+      const emittedName = pascalCase((_a = ref.split("/").pop()) != null ? _a : "");
+      warnOnce(ctx, "unsupported-pointer-root", ref, `Nested $ref "${ref}" points into a part of the document this generator does not inline (only #/components/schemas/\u2026 and #/definitions/\u2026 are) \u2014 it will be emitted as the type "${emittedName}", which nothing defines. Promote the target to a named schema and reference that. ${WRONG_TYPE_SUFFIX}`);
+    }
+  } else if (ref !== void 0) {
+    warnOnce(ctx, "malformed-ref", safeStringify(ref), `Ignoring a "$ref" whose value is ${describeKind(ref)}, not a string (${safeStringify(ref)}) \u2014 a $ref must be a JSON pointer string.`);
+  }
+  let changed = false;
+  const entries = Object.entries(node).map(([key, value]) => {
+    const next = transformEntry(key, value, ctx, chain, keysAreNames);
+    changed || (changed = next !== value);
+    return [
+      key,
+      next
+    ];
+  });
+  return changed ? Object.fromEntries(entries) : node;
+}
+__name(transform, "transform");
+function transformEntry(key, value, ctx, chain, keysAreNames) {
+  if (!keysAreNames && PAYLOAD_KEYS.has(key)) {
+    return value;
+  }
+  return transform(value, ctx, chain, !keysAreNames && NAME_KEYED_CONTAINERS.has(key));
+}
+__name(transformEntry, "transformEntry");
+function inlineTarget(node, ref, ctx, chain) {
+  if (chain.includes(ref)) {
+    warnOnce(ctx, "cyclic", ref, `Nested $ref "${ref}" is cyclic and cannot be inlined finitely \u2014 restructure the target as a named definition. ${WRONG_TYPE_SUFFIX}`);
+    return REFUSED;
+  }
+  const target = resolvePointer(ctx.root, ref);
+  if (target === void 0) {
+    warnOnce(ctx, "unresolvable", ref, `Could not resolve nested $ref "${ref}". ${WRONG_TYPE_SUFFIX}`);
+    return REFUSED;
+  }
+  if (!isPlainObject(target) && typeof target !== "boolean") {
+    warnOnce(ctx, "not-a-schema", ref, `Nested $ref "${ref}" resolves to ${describeKind(target)}, not a schema \u2014 point it at a schema object. ${WRONG_TYPE_SUFFIX}`);
+    return REFUSED;
+  }
+  const nonSchemaSegment = firstNonSchemaSegment(ref);
+  if (nonSchemaSegment !== void 0) {
+    warnOnce(ctx, "not-a-schema-position", ref, `Nested $ref "${ref}" does not address a schema \u2014 its "${nonSchemaSegment}" segment is not a schema-valued position (expected one of properties/<name>, items, additionalProperties, allOf|anyOf|oneOf/<index>, not, $defs/<name>). ${WRONG_TYPE_SUFFIX}`);
+    return REFUSED;
+  }
+  if (chain.length >= MAX_REF_DEPTH) {
+    warnOnce(ctx, "depth", ref, `Nested $ref "${ref}" is more than ${MAX_REF_DEPTH} pointer hops deep and was left uninlined \u2014 restructure the target as a named definition. ${WRONG_TYPE_SUFFIX}`);
+    return REFUSED;
+  }
+  if (ctx.budgetExhausted) {
+    warnOnce(ctx, "budget", ref, `Nested $ref "${ref}" was left uninlined: the ${MAX_INLINED_NODES}-node expansion budget was already exhausted earlier in this spec. ${WRONG_TYPE_SUFFIX}`);
+    return REFUSED;
+  }
+  const cost = countNodes(target);
+  if (cost > ctx.budget) {
+    ctx.budgetExhausted = true;
+    warnOnce(ctx, "budget", ref, `Inlining nested $refs exceeded the ${MAX_INLINED_NODES}-node expansion budget at "${ref}" \u2014 it and every deep $ref after it were left uninlined. The spec expands combinatorially; restructure the repeated targets as named definitions. ${WRONG_TYPE_SUFFIX}`);
+    return REFUSED;
+  }
+  ctx.budget -= cost;
+  const inlined = transform(structuredClone(target), ctx, [
+    ...chain,
+    ref
+  ], false);
+  return mergeSiblings(node, inlined, ref, ctx, chain);
+}
+__name(inlineTarget, "inlineTarget");
+var WRONG_TYPE_SUFFIX = "The generated type will not match the spec (generated files ship @ts-nocheck, so this surfaces as a silently wrong type rather than a compile error).";
+var PAYLOAD_KEYS = /* @__PURE__ */ new Set([
+  "example",
+  "examples",
+  "default",
+  "enum",
+  "const"
+]);
+var NAME_KEYED_CONTAINERS = /* @__PURE__ */ new Set([
+  // Schema keyword maps
+  "properties",
+  "patternProperties",
+  "dependentSchemas",
+  "$defs",
+  "definitions",
+  // Document-level maps keyed by name, status code, path or media type
+  "schemas",
+  "responses",
+  "parameters",
+  "requestBodies",
+  "headers",
+  "securitySchemes",
+  "links",
+  "callbacks",
+  "encoding",
+  "variables",
+  "content",
+  "paths",
+  "webhooks",
+  "pathItems"
+]);
+function mergeSiblings(node, inlined, ref, ctx, chain) {
+  const siblings = Object.entries(node).filter(([key]) => key !== "$ref");
+  if (siblings.length === 0) {
+    return inlined;
+  }
+  if (!isPlainObject(inlined)) {
+    const dropped = siblings.map(([key]) => key);
+    warnOnce(ctx, "sibling-on-boolean", ref, `Nested $ref "${ref}" resolves to a boolean schema, so the keys next to it (${dropped.join(", ")}) were dropped.`, dropped);
+    return inlined;
+  }
+  const conflicts = siblings.filter(([key, value]) => !ANNOTATION_ONLY_KEYS.has(key) && Object.prototype.hasOwnProperty.call(inlined, key) && !sameValue(value, inlined[key])).map(([key]) => key);
+  if (conflicts.length > 0) {
+    warnOnce(ctx, "sibling-conflict", ref, `Nested $ref "${ref}" sits next to key(s) (${conflicts.join(", ")}) that its target also defines \u2014 the local value won and the target's was dropped, per JSON Schema 2020-12, where $ref composes with its siblings; OpenAPI 3.0 would have ignored the local one instead. The generated type follows the sibling, not the target \u2014 drop it if the target's value was meant to apply.`, conflicts);
+  }
+  return Object.fromEntries([
+    ...Object.entries(inlined),
+    // The ref node is a schema, so its keys are keywords: a payload sibling
+    // stays verbatim, exactly as it would one level up.
+    ...siblings.map(([key, value]) => [
+      key,
+      transformEntry(key, value, ctx, chain, false)
+    ])
+  ]);
+}
+__name(mergeSiblings, "mergeSiblings");
+var ANNOTATION_ONLY_KEYS = /* @__PURE__ */ new Set([
+  "description",
+  "title",
+  "summary",
+  "example",
+  "examples",
+  "externalDocs",
+  "deprecated",
+  "xml",
+  "$comment"
+]);
+function sameValue(a, b) {
+  if (a === b) {
+    return true;
+  }
+  if (Array.isArray(a) || Array.isArray(b)) {
+    return Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((item, index) => sameValue(item, b[index]));
+  }
+  if (isPlainObject(a) && isPlainObject(b)) {
+    const keys = Object.keys(a);
+    return keys.length === Object.keys(b).length && keys.every((key) => Object.prototype.hasOwnProperty.call(b, key) && sameValue(a[key], b[key]));
+  }
+  return typeof a === "object" && typeof b === "object" && safeStringify(a) === safeStringify(b);
+}
+__name(sameValue, "sameValue");
+function warnOnce(ctx, cause, ref, message, site) {
+  var _a, _b, _c;
+  const key = site === void 0 ? `${cause}:${ref}` : `${cause}:${ref}|${[
+    ...site
+  ].sort().join(",")}`;
+  if (ctx.warned.has(key)) {
+    return;
+  }
+  ctx.warned.add(key);
+  const emitted = (_a = ctx.emittedPerCause.get(cause)) != null ? _a : 0;
+  if (emitted >= MAX_WARNINGS_PER_CAUSE) {
+    const refs = (_b = ctx.deferred.get(cause)) != null ? _b : /* @__PURE__ */ new Set();
+    refs.add(ref);
+    ctx.deferred.set(cause, refs);
+    return;
+  }
+  ctx.emittedPerCause.set(cause, emitted + 1);
+  (_c = ctx.onWarning) == null ? void 0 : _c.call(ctx, message);
+}
+__name(warnOnce, "warnOnce");
+function flushDeferredWarnings(ctx) {
+  var _a;
+  for (const [cause, refs] of ctx.deferred) {
+    (_a = ctx.onWarning) == null ? void 0 : _a.call(ctx, `\u2026and ${refs.size} more ${WARNING_CAUSE_LABELS[cause]} (only the first ${MAX_WARNINGS_PER_CAUSE} are reported in full): ${[
+      ...refs
+    ].join(", ")}.`);
+  }
+}
+__name(flushDeferredWarnings, "flushDeferredWarnings");
+function describeKind(value) {
+  var _a, _b;
+  if (value === null) {
+    return "null";
+  }
+  if (Array.isArray(value)) {
+    return "an array";
+  }
+  if (isPlainObject(value)) {
+    return "an object";
+  }
+  if (typeof value === "object") {
+    const className = (_b = (_a = Object.getPrototypeOf(value)) == null ? void 0 : _a.constructor) == null ? void 0 : _b.name;
+    return typeof className === "string" ? `a ${className}` : "a non-plain object";
+  }
+  return `a ${typeof value}`;
+}
+__name(describeKind, "describeKind");
+function safeStringify(value) {
+  var _a;
+  try {
+    return (_a = JSON.stringify(value)) != null ? _a : String(value);
+  } catch (e) {
+    return String(value);
+  }
+}
+__name(safeStringify, "safeStringify");
+function countNodes(value) {
+  if (Array.isArray(value)) {
+    return value.reduce((total, item) => total + countNodes(item), 1);
+  }
+  if (!isPlainObject(value)) {
+    return 1;
+  }
+  return Object.values(value).reduce((total, item) => total + countNodes(item), 1);
+}
+__name(countNodes, "countNodes");
+function isDeepSchemaPointer(ref) {
+  if (!ref.startsWith("#/")) {
+    return false;
+  }
+  const segments = ref.slice(2).split("/");
+  if (segments[0] === "components" && segments[1] === "schemas") {
+    return segments.length > 3;
+  }
+  if (segments[0] === "definitions") {
+    return segments.length > 2;
+  }
+  return false;
+}
+__name(isDeepSchemaPointer, "isDeepSchemaPointer");
+function isDeepPointerIntoUnsupportedRoot(ref) {
+  if (!ref.startsWith("#/") || isDeepSchemaPointer(ref)) {
+    return false;
+  }
+  const segments = ref.slice(2).split("/");
+  const wholeEntryDepth = segments[0] === "components" ? 3 : 2;
+  return segments.length > wholeEntryDepth;
+}
+__name(isDeepPointerIntoUnsupportedRoot, "isDeepPointerIntoUnsupportedRoot");
+var SCHEMA_KEYWORDS = /* @__PURE__ */ new Set([
+  "not",
+  "additionalProperties",
+  "unevaluatedItems",
+  "unevaluatedProperties",
+  "contains",
+  "propertyNames",
+  "contentSchema",
+  "if",
+  "then",
+  "else"
+]);
+var SCHEMA_MAP_KEYWORDS = /* @__PURE__ */ new Set([
+  "properties",
+  "patternProperties",
+  "dependentSchemas",
+  "$defs",
+  "definitions"
+]);
+var SCHEMA_LIST_KEYWORDS = /* @__PURE__ */ new Set([
+  "allOf",
+  "anyOf",
+  "oneOf",
+  "prefixItems"
+]);
+var SCHEMA_OR_LIST_KEYWORDS = /* @__PURE__ */ new Set([
+  "items",
+  "additionalItems"
+]);
+function firstNonSchemaSegment(ref) {
+  const segments = pointerSegments(ref);
+  const rest = segments.slice(segments[0] === "definitions" ? 2 : 3);
+  let position = "schema";
+  for (const segment of rest) {
+    if (position === "schema-map") {
+      position = "schema";
+      continue;
+    }
+    if (position === "schema-list") {
+      if (toArrayIndex(segment) === void 0) {
+        return segment;
+      }
+      position = "schema";
+      continue;
+    }
+    if (position === "schema-or-list" && toArrayIndex(segment) !== void 0) {
+      position = "schema";
+      continue;
+    }
+    if (SCHEMA_KEYWORDS.has(segment)) {
+      position = "schema";
+    } else if (SCHEMA_MAP_KEYWORDS.has(segment)) {
+      position = "schema-map";
+    } else if (SCHEMA_LIST_KEYWORDS.has(segment)) {
+      position = "schema-list";
+    } else if (SCHEMA_OR_LIST_KEYWORDS.has(segment)) {
+      position = "schema-or-list";
+    } else {
+      return segment;
+    }
+  }
+  return position === "schema" || position === "schema-or-list" ? void 0 : rest[rest.length - 1];
+}
+__name(firstNonSchemaSegment, "firstNonSchemaSegment");
+function pointerSegments(ref) {
+  return ref.slice(2).split("/").map((segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~"));
+}
+__name(pointerSegments, "pointerSegments");
+function resolvePointer(root, ref) {
+  let current = root;
+  const segments = pointerSegments(ref);
+  for (const segment of segments) {
+    if (Array.isArray(current)) {
+      const index = toArrayIndex(segment);
+      if (index === void 0 || index >= current.length) {
+        return void 0;
+      }
+      current = current[index];
+      continue;
+    }
+    if (!isPlainObject(current) || !Object.prototype.hasOwnProperty.call(current, segment)) {
+      return void 0;
+    }
+    current = current[segment];
+  }
+  return current;
+}
+__name(resolvePointer, "resolvePointer");
+function toArrayIndex(segment) {
+  return /^(?:0|[1-9][0-9]*)$/.test(segment) ? Number(segment) : void 0;
+}
+__name(toArrayIndex, "toArrayIndex");
+function isPlainObject(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+__name(isPlainObject, "isPlainObject");
+
 // ../shared/src/utils/content-types.constants.ts
 var CONTENT_TYPES = {
   MULTIPART: "multipart/form-data",
@@ -312,20 +960,20 @@ function extractPaths(swaggerPaths = {}, methods = [
   "delete",
   "options",
   "head"
-]) {
+], onWarning, resolveParameter) {
   const paths = [];
-  Object.entries(swaggerPaths).forEach(([path14, pathItem]) => {
+  Object.entries(swaggerPaths).forEach(([path15, pathItem]) => {
     methods.forEach((method) => {
       const operation = pathItem[method];
       if (operation) {
         paths.push({
-          path: path14,
+          path: path15,
           method: method.toUpperCase(),
-          operationId: operation.operationId,
+          operationId: asName(operation.operationId),
           summary: operation.summary,
           description: operation.description,
-          tags: operation.tags || [],
-          parameters: parseParameters(operation.parameters || [], pathItem.parameters || []),
+          tags: Array.isArray(operation.tags) ? operation.tags.flatMap(nameOrNothing) : [],
+          parameters: parseParameters(operation.parameters || [], pathItem.parameters || [], `(${method.toUpperCase()}) ${path15}`, onWarning, resolveParameter),
           requestBody: operation.requestBody,
           responses: operation.responses || {}
         });
@@ -335,13 +983,55 @@ function extractPaths(swaggerPaths = {}, methods = [
   return paths;
 }
 __name(extractPaths, "extractPaths");
-function parseParameters(operationParams, pathParams) {
+function asName(value) {
+  if (typeof value === "string") {
+    return value;
+  }
+  return typeof value === "number" && Number.isFinite(value) ? String(value) : void 0;
+}
+__name(asName, "asName");
+function nameOrNothing(value) {
+  const name = asName(value);
+  return name === void 0 ? [] : [
+    name
+  ];
+}
+__name(nameOrNothing, "nameOrNothing");
+function parseParameters(operationParams, pathParams, location, onWarning, resolveParameter) {
   const allParams = [
     ...pathParams,
     ...operationParams
-  ];
-  return allParams.map((param) => ({
-    name: param.name,
+  ].flatMap((param) => {
+    var _a;
+    const ref = param.$ref;
+    if (typeof ref !== "string") {
+      return [
+        param
+      ];
+    }
+    const resolution = (_a = resolveParameter == null ? void 0 : resolveParameter(ref)) != null ? _a : {
+      problem: "cannot be resolved here: no reusable parameters were provided"
+    };
+    if ("parameter" in resolution) {
+      return [
+        resolution.parameter
+      ];
+    }
+    onWarning == null ? void 0 : onWarning(`A parameter of ${location} references "${ref}", which ${resolution.problem}. The parameter was skipped.`);
+    return [];
+  });
+  const named = allParams.filter((param) => {
+    const name = asName(param.name);
+    if (name !== void 0 && name !== "") {
+      return true;
+    }
+    const where = typeof param.in === "string" ? `${param.in} parameter` : "parameter";
+    const shown = param.name === void 0 ? "no name" : `name ${JSON.stringify(param.name)}`;
+    onWarning == null ? void 0 : onWarning(`A ${where} of ${location} has ${shown} and was skipped. Give it a name in the spec.`);
+    return false;
+  });
+  return named.map((param) => ({
+    name: asName(param.name),
     in: param.in,
     required: param.required || param.in === "path",
     schema: param.schema,
@@ -352,27 +1042,43 @@ function parseParameters(operationParams, pathParams) {
 }
 __name(parseParameters, "parseParameters");
 
-// ../shared/src/utils/string.utils.ts
-function camelCase(str) {
-  return str.replace(/[-_.\s]+(.)?/g, (_, char) => char ? char.toUpperCase() : "").replace(/^./, (char) => char.toLowerCase());
+// ../shared/src/emit/literal.emit.ts
+function quoteLiteral(value) {
+  return `'${escapeSingleQuoted(value)}'`;
 }
-__name(camelCase, "camelCase");
-function kebabCase(str) {
-  return str.replace(/([a-z])([A-Z])/g, "$1-$2").replace(/[-_\s]+/g, "-").toLowerCase();
+__name(quoteLiteral, "quoteLiteral");
+function escapeSingleQuoted(value) {
+  return value.replace(/[\\']/g, (char) => `\\${char}`).replace(/\r/g, "\\r").replace(/\n/g, "\\n");
 }
-__name(kebabCase, "kebabCase");
-function pascalCase(str) {
-  return str.replace(/[-_.\s]+(.)?/g, (_, char) => char ? char.toUpperCase() : "").replace(/^./, (char) => char.toUpperCase());
+__name(escapeSingleQuoted, "escapeSingleQuoted");
+function escapeTemplateLiteral(value) {
+  return value.replace(/[\\`]/g, (char) => `\\${char}`).replace(/\$\{/g, "\\${").replace(/\r/g, "\\r");
 }
-__name(pascalCase, "pascalCase");
-function screamingSnakeCase(str) {
-  return str.replace(/([a-z])([A-Z])/g, "$1_$2").replace(/[-\s]+/g, "_").toUpperCase();
+__name(escapeTemplateLiteral, "escapeTemplateLiteral");
+function emitObjectKey(name, quoteStyle = "double") {
+  const quoted = quoteStyle === "single" ? quoteLiteral(name) : `"${escapeDoubleQuoted(name)}"`;
+  return name === "__proto__" ? `[${quoted}]` : quoted;
 }
-__name(screamingSnakeCase, "screamingSnakeCase");
-function pascalCaseForEnums(str) {
-  return str.replace(/[^a-zA-Z0-9]/g, "_").replace(/(?:^|_)([a-z])/g, (_, char) => char.toUpperCase()).replace(/^([0-9])/, "_$1");
+__name(emitObjectKey, "emitObjectKey");
+function escapeDoubleQuoted(value) {
+  return value.replace(/[\\"]/g, (char) => `\\${char}`).replace(/\r/g, "\\r").replace(/\n/g, "\\n");
 }
-__name(pascalCaseForEnums, "pascalCaseForEnums");
+__name(escapeDoubleQuoted, "escapeDoubleQuoted");
+function emitPropertyName(name) {
+  return IDENTIFIER_NAME.test(name) ? name : `"${escapeDoubleQuoted(name)}"`;
+}
+__name(emitPropertyName, "emitPropertyName");
+var IDENTIFIER_NAME = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
+function escapeJsDoc(text) {
+  return text.replace(/\*\//g, "*\\/");
+}
+__name(escapeJsDoc, "escapeJsDoc");
+function emitDocs(description) {
+  return typeof description === "string" && description ? [
+    escapeJsDoc(description)
+  ] : void 0;
+}
+__name(emitDocs, "emitDocs");
 
 // ../shared/src/utils/functions/class-names.ts
 function decorate(base, defaultSuffix, naming) {
@@ -422,7 +1128,7 @@ function getTypeScriptType(schemaOrType, config, formatOrNullable, isNullable, c
   switch (schema.type) {
     case "string":
       if (schema.enum) {
-        return schema.enum.map((value) => typeof value === "string" ? `'${escapeString(value)}'` : String(value)).join(" | ");
+        return schema.enum.map((value) => typeof value === "string" ? `'${escapeSingleQuoted(value)}'` : String(value)).join(" | ");
       }
       if (schema.format === "date" || schema.format === "date-time") {
         const dateType = config.options.dateType === "Date" ? "Date" : "string";
@@ -458,10 +1164,6 @@ function nullableType(type, isNullable) {
   return type + (isNullable ? " | null" : "");
 }
 __name(nullableType, "nullableType");
-function escapeString(str) {
-  return str.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
-}
-__name(escapeString, "escapeString");
 
 // ../shared/src/utils/functions/extract-swagger-response-type.ts
 function getResponseTypeFromResponse(response, responseTypeMapping) {
@@ -610,7 +1312,7 @@ function getResponseType(response, config) {
 __name(getResponseType, "getResponseType");
 
 // ../shared/src/core/normalize.ts
-function normalizeSpec(spec) {
+function normalizeSpec(spec, onWarning) {
   var _a;
   const rawDefinitions = spec.definitions || ((_a = spec.components) == null ? void 0 : _a.schemas) || {};
   const definitions = Object.fromEntries(Object.entries(rawDefinitions).map(([name, definition]) => [
@@ -621,6 +1323,7 @@ function normalizeSpec(spec) {
     const parts = ref.split("/");
     return definitions[parts[parts.length - 1]];
   }, "resolveReference");
+  const resolveParameter = createParameterResolver(spec);
   return {
     version: spec.swagger ? {
       type: "swagger",
@@ -630,7 +1333,7 @@ function normalizeSpec(spec) {
       version: spec.openapi
     } : null,
     definitions,
-    operations: extractPaths(spec.paths).map((operation) => normalizeOperation(normalizeOperationSchemas(operation), resolveReference)),
+    operations: extractPaths(spec.paths, void 0, onWarning, resolveParameter).map((operation) => normalizeOperation(normalizeOperationSchemas(operation), resolveReference, onWarning)),
     resolveReference
   };
 }
@@ -714,24 +1417,29 @@ function normalizeContentSchemas(content) {
   ]));
 }
 __name(normalizeContentSchemas, "normalizeContentSchemas");
-function normalizeOperation(operation, resolveRef) {
+function normalizeOperation(operation, resolveRef, onWarning) {
   var _a, _b, _c;
+  warnAboutUnboundParameters(operation, onWarning);
   const content = (_a = operation.requestBody) == null ? void 0 : _a.content;
   const isMultipart = !!(content == null ? void 0 : content[CONTENT_TYPES.MULTIPART]);
   const isUrlEncoded = !!(content == null ? void 0 : content[CONTENT_TYPES.FORM_URLENCODED]) && !(content == null ? void 0 : content[CONTENT_TYPES.JSON]);
   const formDataSchema = isMultipart ? resolveBodySchema(operation.requestBody, CONTENT_TYPES.MULTIPART, resolveRef) : void 0;
   const urlEncodedSchema = isUrlEncoded ? resolveBodySchema(operation.requestBody, CONTENT_TYPES.FORM_URLENCODED, resolveRef) : void 0;
   const responseInfo = determineResponseInfo(operation);
+  const pathParams = ((_b = operation.parameters) == null ? void 0 : _b.filter((p) => p.in === "path")) || [];
+  const queryParams = ((_c = operation.parameters) == null ? void 0 : _c.filter((p) => p.in === "query")) || [];
+  const formDataFields = Object.keys((formDataSchema == null ? void 0 : formDataSchema.properties) || {});
+  const urlEncodedFields = Object.keys((urlEncodedSchema == null ? void 0 : urlEncodedSchema.properties) || {});
   return __spreadProps(__spreadValues({}, operation), {
-    pathParams: ((_b = operation.parameters) == null ? void 0 : _b.filter((p) => p.in === "path")) || [],
-    queryParams: ((_c = operation.parameters) == null ? void 0 : _c.filter((p) => p.in === "query")) || [],
+    pathParams,
+    queryParams,
     hasBody: !!operation.requestBody,
     isMultipart,
     isUrlEncoded,
     formDataSchema,
-    formDataFields: Object.keys((formDataSchema == null ? void 0 : formDataSchema.properties) || {}),
+    formDataFields,
     urlEncodedSchema,
-    urlEncodedFields: Object.keys((urlEncodedSchema == null ? void 0 : urlEncodedSchema.properties) || {}),
+    urlEncodedFields,
     responseType: responseInfo.responseType,
     acceptHeader: responseInfo.acceptHeader
   });
@@ -762,31 +1470,107 @@ function determineResponseInfo(operation) {
   };
 }
 __name(determineResponseInfo, "determineResponseInfo");
+function createParameterResolver(spec) {
+  var _a, _b;
+  const components = (_b = spec.swagger ? spec.parameters : (_a = spec.components) == null ? void 0 : _a.parameters) != null ? _b : {};
+  const prefix = spec.swagger ? "#/parameters/" : "#/components/parameters/";
+  return (ref) => {
+    const chain = [];
+    let current = ref;
+    for (; ; ) {
+      if (chain.includes(current)) {
+        return {
+          problem: `is part of a reference cycle (${[
+            ...chain,
+            current
+          ].map((r) => `"${r}"`).join(" -> ")})`
+        };
+      }
+      chain.push(current);
+      const hash = current.indexOf("#");
+      if (hash > 0) {
+        return {
+          problem: `points into another document ("${current.slice(0, hash)}"); references into other documents are not supported, so bundle the spec into one document first`
+        };
+      }
+      if (!current.startsWith(prefix)) {
+        return {
+          problem: `is not a parameter component pointer (expected "${prefix}<name>")`
+        };
+      }
+      const name = current.slice(prefix.length).replace(/~1/g, "/").replace(/~0/g, "~");
+      const candidate = Object.prototype.hasOwnProperty.call(components, name) ? components[name] : void 0;
+      if (!candidate || typeof candidate !== "object") {
+        return {
+          problem: `does not resolve: there is no parameter component named "${name}"`
+        };
+      }
+      const next = candidate.$ref;
+      if (typeof next === "string") {
+        current = next;
+        continue;
+      }
+      return {
+        parameter: candidate
+      };
+    }
+  };
+}
+__name(createParameterResolver, "createParameterResolver");
+function warnAboutUnboundParameters(operation, onWarning) {
+  var _a;
+  for (const param of (_a = operation.parameters) != null ? _a : []) {
+    if (param.in === "path" || param.in === "query") {
+      continue;
+    }
+    if (param.in === "header" || param.in === "cookie") {
+      if (param.required) {
+        onWarning == null ? void 0 : onWarning(`Required ${param.in} parameter "${param.name}" of ${describeOperation(operation)} is not bound by the generated clients \u2014 callers must pass it through the trailing options parameter.`);
+      }
+      continue;
+    }
+    const kind = param.in === "formData" || param.in === "body" ? `Swagger 2.0 \`in: ${param.in}\`` : `\`in: ${String(param.in)}\``;
+    onWarning == null ? void 0 : onWarning(`${kind} parameter "${param.name}" of ${describeOperation(operation)} is not supported and was dropped` + (param.required ? " (it is marked required)" : "") + ". Describe it as a requestBody, or as a path or query parameter, to have it generated.");
+  }
+}
+__name(warnAboutUnboundParameters, "warnAboutUnboundParameters");
 
 // ../shared/src/core/swagger-parser.ts
 var _SwaggerParser = class _SwaggerParser {
-  constructor(spec, config) {
+  constructor(spec, onWarning) {
     __publicField(this, "spec");
     __publicField(this, "normalized");
-    var _a, _b;
-    const isInputValid = (_b = (_a = config.validateInput) == null ? void 0 : _a.call(config, spec)) != null ? _b : true;
-    if (!isInputValid) {
-      throw new SpecParseError("Swagger spec is not valid. Check your `validateInput` condition.");
-    }
+    /** Non-fatal problems found while normalizing — a parameter with no usable name, for one. */
+    __publicField(this, "onWarning");
     this.spec = spec;
+    this.onWarning = onWarning;
   }
   /**
    * Loads, parses and wraps a spec.
    *
+   * @param onWarning receives non-fatal spec problems found while parsing or
+   *   normalizing — a deep-pointer `$ref` that cannot be inlined, a parameter
+   *   with no usable name.
    * @throws SpecLoadError when the file/URL cannot be read.
-   * @throws SpecParseError when the content cannot be parsed or the
-   *   config's `validateInput` hook rejects the spec.
+   * @throws SpecParseError when the content cannot be parsed, `$ref` inlining
+   *   fails, or the config's `validateInput` hook rejects the spec.
    */
-  static create(swaggerPathOrUrl, config) {
+  static create(swaggerPathOrUrl, config, onWarning) {
     return __async(this, null, function* () {
+      var _a, _b;
       const swaggerContent = yield loadSpecContent(swaggerPathOrUrl);
       const spec = parseSpecContent(swaggerContent, swaggerPathOrUrl);
-      return new _SwaggerParser(spec, config);
+      const isInputValid = (_b = (_a = config.validateInput) == null ? void 0 : _a.call(config, spec)) != null ? _b : true;
+      if (!isInputValid) {
+        throw new SpecParseError("Swagger spec is not valid. Check your `validateInput` condition.");
+      }
+      let inlinedSpec;
+      try {
+        inlinedSpec = inlineNestedRefs(spec, onWarning);
+      } catch (error) {
+        throw new SpecParseError(`Failed to inline nested $refs in the spec: ${error instanceof Error ? error.message : String(error)}`, swaggerPathOrUrl, error);
+      }
+      return new _SwaggerParser(inlinedSpec, onWarning);
     });
   }
   /**
@@ -796,7 +1580,7 @@ var _SwaggerParser = class _SwaggerParser {
    */
   getNormalizedSpec() {
     var _a;
-    (_a = this.normalized) != null ? _a : this.normalized = normalizeSpec(this.spec);
+    (_a = this.normalized) != null ? _a : this.normalized = normalizeSpec(this.spec, this.onWarning);
     return this.normalized;
   }
   /** Definition map regardless of version: 2.0 `definitions` or 3.x `components.schemas`. */
@@ -827,20 +1611,20 @@ var _SwaggerParser = class _SwaggerParser {
   }
   /** Whether the spec declares a supported version (Swagger 2.x or OpenAPI 3.x). */
   isValidSpec() {
-    return !!(this.spec.swagger && this.spec.swagger.startsWith("2.") || this.spec.openapi && this.spec.openapi.startsWith("3."));
+    return specVersionOf(this.spec.swagger, "2.") || specVersionOf(this.spec.openapi, "3.");
   }
   /** Detected flavor + literal version string, or null when neither field is present. */
   getSpecVersion() {
-    if (this.spec.swagger) {
+    if (this.spec.swagger !== void 0 && this.spec.swagger !== null) {
       return {
         type: "swagger",
-        version: this.spec.swagger
+        version: String(this.spec.swagger)
       };
     }
-    if (this.spec.openapi) {
+    if (this.spec.openapi !== void 0 && this.spec.openapi !== null) {
       return {
         type: "openapi",
-        version: this.spec.openapi
+        version: String(this.spec.openapi)
       };
     }
     return null;
@@ -848,6 +1632,10 @@ var _SwaggerParser = class _SwaggerParser {
 };
 __name(_SwaggerParser, "SwaggerParser");
 var SwaggerParser = _SwaggerParser;
+function specVersionOf(value, majorPrefix) {
+  return typeof value === "string" || typeof value === "number" ? String(value).startsWith(majorPrefix) : false;
+}
+__name(specVersionOf, "specVersionOf");
 
 // ../shared/src/emit/headers.emit.ts
 function emitHeaders(options) {
@@ -868,7 +1656,7 @@ ${emitDefaultHeaderGuards(customHeaders)}`;
     headerCode += `
 // Advertise the response content type declared in the spec
 if (!headers.has('Accept')) {
-  headers = headers.set('Accept', '${accept}');
+  headers = headers.set('Accept', ${quoteLiteral(accept)});
 }`;
   }
   if (contentType == null ? void 0 : contentType.isMultipart) {
@@ -892,7 +1680,7 @@ if (!headers.has('Content-Type')) {
 }
 __name(emitHeaders, "emitHeaders");
 function emitDefaultHeadersMerge(optionsExpression, customHeaders) {
-  const defaultsLiteral = Object.entries(customHeaders).map(([key, value]) => `'${key}': '${value}'`).join(", ");
+  const defaultsLiteral = Object.entries(customHeaders).map(([key, value]) => `${emitObjectKey(key, "single")}: ${quoteLiteral(value)}`).join(", ");
   return `
 // Add default headers if not already present
 let headers = ${optionsExpression}?.headers;
@@ -904,12 +1692,242 @@ ${emitDefaultHeaderGuards(customHeaders)}
 }
 __name(emitDefaultHeadersMerge, "emitDefaultHeadersMerge");
 function emitDefaultHeaderGuards(customHeaders) {
-  return Object.entries(customHeaders).map(([key, value]) => `if (!headers.has('${key}')) {
-  headers = headers.set('${key}', '${value}');
-}`).join("\n");
+  return Object.entries(customHeaders).map(([key, value]) => {
+    const name = quoteLiteral(key);
+    return `if (!headers.has(${name})) {
+  headers = headers.set(${name}, ${quoteLiteral(value)});
+}`;
+  }).join("\n");
 }
 __name(emitDefaultHeaderGuards, "emitDefaultHeaderGuards");
 
+// ../shared/src/utils/functions/get-request-body-type.ts
+function getRequestBodyType(requestBody, config) {
+  const content = requestBody.content || {};
+  const jsonContent = content[CONTENT_TYPES.JSON];
+  if (jsonContent == null ? void 0 : jsonContent.schema) {
+    return getTypeScriptType(jsonContent.schema, config, jsonContent.schema.nullable);
+  }
+  return "any";
+}
+__name(getRequestBodyType, "getRequestBodyType");
+
+// ../shared/src/utils/functions/is-data-type-interface.ts
+function isDataTypeInterface(type) {
+  const invalidTypes = [
+    "any",
+    "File",
+    "string",
+    "number",
+    "boolean",
+    "object",
+    "unknown",
+    "[]",
+    "Array"
+  ];
+  return !invalidTypes.some((invalidType) => type.includes(invalidType));
+}
+__name(isDataTypeInterface, "isDataTypeInterface");
+
+// ../shared/src/utils/functions/argument-names.ts
+var RESERVED_WORDS = [
+  "arguments",
+  "await",
+  "break",
+  "case",
+  "catch",
+  "class",
+  "const",
+  "continue",
+  "debugger",
+  "default",
+  "delete",
+  "do",
+  "else",
+  "enum",
+  "eval",
+  "export",
+  "extends",
+  "false",
+  "finally",
+  "for",
+  "function",
+  "if",
+  "implements",
+  "import",
+  "in",
+  "instanceof",
+  "interface",
+  "let",
+  "new",
+  "null",
+  "package",
+  "private",
+  "protected",
+  "public",
+  "return",
+  "static",
+  "super",
+  "switch",
+  "this",
+  "throw",
+  "true",
+  "try",
+  "typeof",
+  "var",
+  "void",
+  "while",
+  "with",
+  "yield"
+];
+var SERVICE_ARGUMENT_PROFILE = Object.freeze({
+  reserved: Object.freeze([
+    "observe",
+    "options",
+    "url",
+    "params",
+    "headers",
+    "formData",
+    "formBody"
+  ]),
+  bindsRequestBody: true
+});
+var RESOURCE_ARGUMENT_PROFILE = Object.freeze({
+  reserved: Object.freeze([
+    "resourceOptions",
+    "requestOptions",
+    "params",
+    "headers"
+  ]),
+  bindsRequestBody: false
+});
+var REQUEST_BODY_KEY = /* @__PURE__ */ Symbol("requestBody");
+function resolveArgumentNames(operation, config, profile) {
+  let byConfig = RESOLVED.get(operation);
+  if (!byConfig) {
+    byConfig = /* @__PURE__ */ new WeakMap();
+    RESOLVED.set(operation, byConfig);
+  }
+  let byProfile = byConfig.get(config);
+  if (!byProfile) {
+    byProfile = /* @__PURE__ */ new WeakMap();
+    byConfig.set(config, byProfile);
+  }
+  const cached = byProfile.get(profile);
+  if (cached) {
+    return cached;
+  }
+  const resolved = computeArgumentNames(operation, config, profile);
+  byProfile.set(profile, resolved);
+  return resolved;
+}
+__name(resolveArgumentNames, "resolveArgumentNames");
+var RESOLVED = /* @__PURE__ */ new WeakMap();
+function computeArgumentNames(operation, config, profile) {
+  const entries = [
+    ...operation.pathParams.map((param) => ({
+      key: param.name,
+      base: camelCase(param.name)
+    })),
+    ...operation.formDataFields.map((field) => ({
+      key: field,
+      base: camelCase(field)
+    })),
+    ...operation.urlEncodedFields.map((field) => ({
+      key: field,
+      base: camelCase(field)
+    }))
+  ];
+  const bodyBase = profile.bindsRequestBody ? jsonBodyIdentifier(operation, config) : void 0;
+  if (bodyBase !== void 0) {
+    entries.push({
+      key: REQUEST_BODY_KEY,
+      base: bodyBase
+    });
+  }
+  entries.push(...operation.queryParams.map((param) => ({
+    key: param.name,
+    base: camelCase(param.name)
+  })));
+  const identifiers = /* @__PURE__ */ new Map();
+  const used = /* @__PURE__ */ new Set([
+    ...profile.reserved,
+    ...RESERVED_WORDS
+  ]);
+  const renamed = [];
+  const merged = /* @__PURE__ */ new Set();
+  for (const { key, base } of entries) {
+    if (identifiers.has(key)) {
+      if (typeof key === "string") {
+        merged.add(key);
+      }
+      continue;
+    }
+    let identifier = base;
+    let suffix = 2;
+    while (used.has(identifier)) {
+      identifier = `${base}${suffix}`;
+      suffix++;
+    }
+    if (identifier !== base) {
+      renamed.push(Object.freeze({
+        source: typeof key === "string" ? key : base,
+        identifier
+      }));
+    }
+    used.add(identifier);
+    identifiers.set(key, identifier);
+  }
+  return {
+    // The fallback runs the *same* rules the resolver would have, rather
+    // than a bare camelCase: an unregistered wire name otherwise came back
+    // as `class` or `options`, names the resolver never assigns.
+    // Uniquified against everything already assigned, not just the reserved
+    // words: an unregistered wire name that camelCases onto an identifier
+    // this operation already bound would otherwise alias it — compiling
+    // fine and sending the wrong value. Only reachable for operations built
+    // outside the normalizer, but the resolver is public API.
+    of: /* @__PURE__ */ __name((wireName) => {
+      var _a;
+      return (_a = identifiers.get(wireName)) != null ? _a : deriveLocalName(camelCase(wireName), [
+        ...used
+      ]);
+    }, "of"),
+    body: identifiers.get(REQUEST_BODY_KEY),
+    all: Object.freeze([
+      ...identifiers.values()
+    ]),
+    renamed: Object.freeze(renamed),
+    merged: Object.freeze([
+      ...merged
+    ])
+  };
+}
+__name(computeArgumentNames, "computeArgumentNames");
+function jsonBodyIdentifier(operation, config) {
+  var _a;
+  if (!operation.requestBody || operation.isMultipart) {
+    return void 0;
+  }
+  if (!((_a = operation.requestBody.content) == null ? void 0 : _a[CONTENT_TYPES.JSON])) {
+    return void 0;
+  }
+  const bodyType = getRequestBodyType(operation.requestBody, config);
+  return isDataTypeInterface(bodyType) ? camelCase(bodyType) : "requestBody";
+}
+__name(jsonBodyIdentifier, "jsonBodyIdentifier");
+function deriveLocalName(base, taken) {
+  const used = new Set(taken);
+  let name = base;
+  let suffix = 2;
+  while (used.has(name)) {
+    name = `${base}${suffix}`;
+    suffix++;
+  }
+  return name;
+}
+__name(deriveLocalName, "deriveLocalName");
+
 // ../shared/src/emit/url.emit.ts
 function plainParamValue(identifier) {
   return identifier;
@@ -919,40 +1937,54 @@ function signalAwareParamValue(identifier) {
   return `typeof ${identifier} === 'function' ? ${identifier}() : ${identifier}`;
 }
 __name(signalAwareParamValue, "signalAwareParamValue");
-function emitUrlExpression(path14, pathParams, paramValue = plainParamValue) {
-  let urlExpression = `\`\${this.basePath}${path14}\``;
+function emitUrlExpression(path15, pathParams, argumentNames, paramValue = plainParamValue) {
+  var _a;
+  const declared = new Set(pathParams.map((param) => param.name));
+  const unresolved = ((_a = path15.match(/{([^{}]*)}/g)) != null ? _a : []).map((placeholder) => placeholder.slice(1, -1)).filter((name) => !declared.has(name));
+  if (unresolved.length > 0) {
+    throw new UnresolvedPathTemplateError(`Path "${path15}" declares no parameter for ${unresolved.map((name) => `{${name}}`).join(", ")}. Declare each placeholder as a path parameter, or remove it from the path.`, path15, unresolved);
+  }
+  let urlExpression = "`${this.basePath}" + escapeTemplateLiteral(path15) + "`";
   pathParams.forEach((param) => {
-    urlExpression = urlExpression.replace(`{${param.name}}`, `\${${paramValue(camelCase(param.name))}}`);
+    const replacement = "${" + paramValue(argumentNames.of(param.name)) + "}";
+    urlExpression = urlExpression.split(`{${escapeTemplateLiteral(param.name)}}`).join(replacement);
   });
   return urlExpression;
 }
 __name(emitUrlExpression, "emitUrlExpression");
-function emitUrlConstruction(path14, pathParams) {
-  return `const url = ${emitUrlExpression(path14, pathParams)};`;
+function emitUrlConstruction(path15, pathParams, argumentNames) {
+  return `const url = ${emitUrlExpression(path15, pathParams, argumentNames)};`;
 }
 __name(emitUrlConstruction, "emitUrlConstruction");
 
 // ../shared/src/emit/query-params.emit.ts
-function emitQueryParams(queryParams) {
+function emitQueryParams(queryParams, argumentNames) {
   if (queryParams.length === 0) {
     return "";
   }
-  const paramMappings = queryParams.map((param) => `if (${camelCase(param.name)} != null) {
-  params = HttpParamsBuilder.addToHttpParams(params, ${camelCase(param.name)}, '${param.name}');
-}`).join("\n");
+  const paramMappings = queryParams.map((param) => {
+    const identifier = argumentNames.of(param.name);
+    return `if (${identifier} != null) {
+  params = HttpParamsBuilder.addToHttpParams(params, ${identifier}, ${quoteLiteral(param.name)});
+}`;
+  }).join("\n");
   return `
 let params = new HttpParams();
 ${paramMappings}`;
 }
 __name(emitQueryParams, "emitQueryParams");
-function emitSignalAwareQueryParams(queryParams) {
+function emitSignalAwareQueryParams(queryParams, argumentNames) {
   if (queryParams.length === 0) {
     return "";
   }
-  const paramMappings = queryParams.map((param) => `const ${camelCase(param.name)}Value = ${signalAwareParamValue(camelCase(param.name))};
-                if (${camelCase(param.name)}Value != null) {
-                    params = HttpParamsBuilder.addToHttpParams(params, ${camelCase(param.name)}Value, '${param.name}');
-                }`).join("\n");
+  const paramMappings = queryParams.map((param) => {
+    const identifier = argumentNames.of(param.name);
+    const local = deriveLocalName(`${identifier}Value`, argumentNames.all);
+    return `const ${local} = ${signalAwareParamValue(identifier)};
+                if (${local} != null) {
+                    params = HttpParamsBuilder.addToHttpParams(params, ${local}, ${quoteLiteral(param.name)});
+                }`;
+  }).join("\n");
   return `
 let params = new HttpParams();
 ${paramMappings}`;
@@ -1014,55 +2046,166 @@ function listGeneratedBarrelDirs(project, rootPath) {
 __name(listGeneratedBarrelDirs, "listGeneratedBarrelDirs");
 
 // ../shared/src/utils/functions/token-names.ts
-function getClientContextTokenName(clientName = "default") {
-  const clientSuffix = clientName.toUpperCase().replace(/[^A-Z0-9]/g, "_");
+function effectiveClientName(clientName) {
+  return clientName ? clientName : "default";
+}
+__name(effectiveClientName, "effectiveClientName");
+function clientNameIdentifier(clientName) {
+  return isValidIdentifier(clientName) ? capitalizeFirst(clientName) : pascalCase(clientName);
+}
+__name(clientNameIdentifier, "clientNameIdentifier");
+function tokenSuffix(clientName) {
+  return effectiveClientName(clientName).toUpperCase().replace(/[^A-Z0-9]/g, "_");
+}
+__name(tokenSuffix, "tokenSuffix");
+function getClientContextTokenName(clientName) {
+  const clientSuffix = tokenSuffix(clientName);
   return `CLIENT_CONTEXT_TOKEN_${clientSuffix}`;
 }
 __name(getClientContextTokenName, "getClientContextTokenName");
-function getBasePathTokenName(clientName = "default") {
-  const clientSuffix = clientName.toUpperCase().replace(/[^A-Z0-9]/g, "_");
+function getBasePathTokenName(clientName) {
+  const clientSuffix = tokenSuffix(clientName);
   return `BASE_PATH_${clientSuffix}`;
 }
 __name(getBasePathTokenName, "getBasePathTokenName");
-function getInterceptorsTokenName(clientName = "default") {
-  const clientSuffix = clientName.toUpperCase().replace(/[^A-Z0-9]/g, "_");
+function getInterceptorsTokenName(clientName) {
+  const clientSuffix = tokenSuffix(clientName);
   return `HTTP_INTERCEPTORS_${clientSuffix}`;
 }
 __name(getInterceptorsTokenName, "getInterceptorsTokenName");
 
-// ../shared/src/utils/functions/duplicate-function-name.ts
-function hasDuplicateFunctionNames(arr) {
-  return new Set(arr.map((fn) => fn.getName())).size !== arr.length;
+// ../shared/src/utils/functions/controller-groups.ts
+function groupOperationsByController(operations, onWarning) {
+  const groups = {};
+  const controllerByFold = /* @__PURE__ */ new Map();
+  const tagSpellings = /* @__PURE__ */ new Map();
+  const namelessTags = /* @__PURE__ */ new Set();
+  operations.forEach((operation) => {
+    var _a, _b, _c;
+    const tag = (_a = operation.tags) == null ? void 0 : _a[0];
+    let rawName = "Default";
+    if (tag !== void 0) {
+      rawName = tag;
+    } else {
+      const pathParts = operation.path.split("/").filter((part) => part && !part.startsWith("{"));
+      if (pathParts.length > 1) {
+        rawName = pathParts[1];
+      }
+    }
+    const sanitized = pascalCase(rawName);
+    const isNameless = !new RegExp("\\p{L}", "u").test(sanitized);
+    const candidate = isNameless ? "Default" : sanitized;
+    const fold = candidate.toLowerCase();
+    const controllerName = (_b = controllerByFold.get(fold)) != null ? _b : candidate;
+    controllerByFold.set(fold, controllerName);
+    if (tag !== void 0 && isNameless) {
+      namelessTags.add(tag);
+    } else if (tag !== void 0) {
+      const spellings = (_c = tagSpellings.get(controllerName)) != null ? _c : /* @__PURE__ */ new Set();
+      spellings.add(tag);
+      tagSpellings.set(controllerName, spellings);
+    }
+    if (!groups[controllerName]) {
+      groups[controllerName] = [];
+    }
+    groups[controllerName].push(operation);
+  });
+  for (const tag of namelessTags) {
+    onWarning == null ? void 0 : onWarning(`Tag "${tag}" contains no characters usable in a name \u2014 its operations are generated into the "Default" controller. Rename the tag to give them a file of their own.`);
+  }
+  for (const [controllerName, spellings] of tagSpellings) {
+    if (spellings.size > 1) {
+      onWarning == null ? void 0 : onWarning(`Tags ${[
+        ...spellings
+      ].map((name) => `"${name}"`).join(" and ")} all map to the controller "${controllerName}" \u2014 their operations are generated into one file. Rename one tag to keep them apart.`);
+    }
+  }
+  return groups;
 }
-__name(hasDuplicateFunctionNames, "hasDuplicateFunctionNames");
+__name(groupOperationsByController, "groupOperationsByController");
 
-// ../shared/src/utils/functions/get-request-body-type.ts
-function getRequestBodyType(requestBody, config) {
-  const content = requestBody.content || {};
-  const jsonContent = content[CONTENT_TYPES.JSON];
-  if (jsonContent == null ? void 0 : jsonContent.schema) {
-    return getTypeScriptType(jsonContent.schema, config, jsonContent.schema.nullable);
+// ../shared/src/utils/functions/method-names.ts
+var RESERVED_MEMBER_NAMES = Object.freeze([
+  "constructor",
+  "httpClient",
+  "basePath",
+  "clientContextToken",
+  "createContextWithClientId"
+]);
+var RESERVED_MEMBER_SET = new Set(RESERVED_MEMBER_NAMES);
+function reservedMemberCollision(operation, config) {
+  if (config.options.customizeMethodName || !operation.operationId) {
+    return void 0;
   }
-  return "any";
+  const natural = camelCase(operation.operationId);
+  return RESERVED_MEMBER_SET.has(natural) ? {
+    from: natural,
+    to: `_${natural}`
+  } : void 0;
 }
-__name(getRequestBodyType, "getRequestBodyType");
+__name(reservedMemberCollision, "reservedMemberCollision");
+function getOperationMethodName(operation, config) {
+  const customize = config.options.customizeMethodName;
+  if (!customize) {
+    return defaultOperationMethodName(operation);
+  }
+  if (operation.operationId == null) {
+    throw new InvalidIdentifierError(`customizeMethodName needs an operationId, and ${describeOperation(operation)} has none. Add one to the spec, or drop customizeMethodName to use the derived name.`, operation);
+  }
+  const customName = customize(operation.operationId);
+  if (!isValidIdentifier(customName) || RESERVED_MEMBER_SET.has(customName)) {
+    throw new InvalidIdentifierError(`customizeMethodName returned "${customName}" for ${describeOperation(operation)}, which is not a usable TypeScript method name. Return an identifier \u2014 letters, digits, "_" and "$", not starting with a digit \u2014 and not one of ${RESERVED_MEMBER_NAMES.map((name) => `"${name}"`).join(", ")}.`, operation, customName);
+  }
+  return customName;
+}
+__name(getOperationMethodName, "getOperationMethodName");
+function defaultOperationMethodName(operation) {
+  if (operation.operationId) {
+    const name = camelCase(operation.operationId);
+    return RESERVED_MEMBER_SET.has(name) ? `_${name}` : name;
+  }
+  const method = pascalCase(operation.method.toLowerCase());
+  const pathParts = operation.path.split("/").filter((segment) => segment !== "").map((segment) => pascalCase(segment));
+  const resource = pathParts.join("") || "resource";
+  return `${camelCase(resource)}${method}`;
+}
+__name(defaultOperationMethodName, "defaultOperationMethodName");
 
-// ../shared/src/utils/functions/is-data-type-interface.ts
-function isDataTypeInterface(type) {
-  const invalidTypes = [
-    "any",
-    "File",
-    "string",
-    "number",
-    "boolean",
-    "object",
-    "unknown",
-    "[]",
-    "Array"
+// ../shared/src/utils/functions/distinct-member-names.ts
+function assertDistinctMemberNames(serviceClass, className, operations, methodNameOf) {
+  var _a;
+  const methodNames = serviceClass.getMethods().map((method) => method.getName());
+  const propertyNames = new Set(serviceClass.getProperties().map((property) => property.getName()));
+  const duplicates = [
+    ...new Set(methodNames.filter((name, index) => methodNames.indexOf(name) !== index || propertyNames.has(name)))
   ];
-  return !invalidTypes.some((invalidType) => type.includes(invalidType));
+  if (duplicates.length === 0) {
+    return;
+  }
+  const byName = new Map(duplicates.map((name) => [
+    name,
+    []
+  ]));
+  for (const operation of operations) {
+    (_a = byName.get(methodNameOf(operation))) == null ? void 0 : _a.push(operation);
+  }
+  const detail = [
+    ...byName
+  ].map(([name, ops]) => {
+    const from = ops.map(describeOperation).join(" and ");
+    return propertyNames.has(name) ? `"${name}" from ${from} (a property of ${className})` : `"${name}" from ${from}`;
+  }).join("; ");
+  throw new DuplicateGeneratedNameError(`Operations map to the same member name in ${className}: ${detail}. Ensure each operationId maps to a unique name.`, duplicates, [
+    ...byName.values()
+  ].flat());
 }
-__name(isDataTypeInterface, "isDataTypeInterface");
+__name(assertDistinctMemberNames, "assertDistinctMemberNames");
+
+// ../shared/src/utils/functions/duplicate-function-name.ts
+function hasDuplicateFunctionNames(arr) {
+  return new Set(arr.map((fn) => fn.getName())).size !== arr.length;
+}
+__name(hasDuplicateFunctionNames, "hasDuplicateFunctionNames");
 
 // ../shared/src/utils/functions/generate-parse-request-type-params.ts
 function generateParseRequestTypeParams(params) {
@@ -1117,7 +2260,7 @@ var PROVIDER_GENERATOR_HEADER_COMMENT = defaultHeaderComment + `* Generated prov
 * Do not edit this file manually
 */
 `;
-var BASE_INTERCEPTOR_HEADER_COMMENT = /* @__PURE__ */ __name((clientName) => defaultHeaderComment + `* Generated Base Interceptor for client ${clientName}
+var BASE_INTERCEPTOR_HEADER_COMMENT = /* @__PURE__ */ __name((clientName) => defaultHeaderComment + `* Generated Base Interceptor for client ${escapeJsDoc(clientName)}
 * Do not edit this file manually
 */
 `, "BASE_INTERCEPTOR_HEADER_COMMENT");
@@ -1138,17 +2281,8 @@ var ZOD_PLUGIN_INDEX_GENERATOR_HEADER_COMMENT = defaultHeaderComment + `* Genera
 var import_ts_morph = require("ts-morph");
 
 // src/lib/generators/type/type-resolver.ts
-function escapeString2(str) {
-  return str.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
-}
-__name(escapeString2, "escapeString");
-function sanitizePropertyName(name) {
-  if (!/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name)) {
-    return `"${name}"`;
-  }
-  return name;
-}
-__name(sanitizePropertyName, "sanitizePropertyName");
+var escapeString = escapeSingleQuoted;
+var sanitizePropertyName = emitPropertyName;
 var _TypeResolver = class _TypeResolver {
   constructor(config, onWarning) {
     __publicField(this, "config");
@@ -1217,7 +2351,7 @@ var _TypeResolver = class _TypeResolver {
       return this.resolveReference(schema.$ref);
     }
     if (schema.enum) {
-      return schema.enum.map((value) => typeof value === "string" ? `'${escapeString2(value)}'` : String(value)).join(" | ");
+      return schema.enum.map((value) => typeof value === "string" ? `'${escapeString(value)}'` : String(value)).join(" | ");
     }
     if (schema.allOf) {
       return schema.allOf.map((def) => this.resolve(def)).filter((type) => type !== "any" && type !== "unknown").join(" & ") || "Record<string, unknown>";
@@ -1323,9 +2457,7 @@ var _EnumBuilder = class _EnumBuilder {
   build(name, definition) {
     var _a;
     if (!((_a = definition.enum) == null ? void 0 : _a.length)) return [];
-    const docs = !this.config.options.generateEnumBasedOnDescription && definition.description ? [
-      definition.description
-    ] : void 0;
+    const docs = this.config.options.generateEnumBasedOnDescription ? void 0 : emitDocs(definition.description);
     if (this.config.options.enumStyle === "enum") {
       return this.buildEnumAsEnum(name, definition, docs);
     } else {
@@ -1368,7 +2500,7 @@ var _EnumBuilder = class _EnumBuilder {
     const objectProperties = [];
     const unionType = definition.enum.map((value) => {
       const key = toEnumKey(value);
-      const val = typeof value === "string" ? `'${escapeString2(value)}'` : isNaN(value) ? `'${value}'` : `${value}`;
+      const val = typeof value === "string" ? `'${escapeString(value)}'` : isNaN(value) ? `'${value}'` : `${value}`;
       objectProperties.push(`${key}: ${val} as ${name}`);
       return val;
     }).join(" | ");
@@ -1428,9 +2560,7 @@ var _InterfaceBuilder = class _InterfaceBuilder {
       kind: import_ts_morph2.StructureKind.Interface,
       name,
       isExported: true,
-      docs: definition.description ? [
-        definition.description
-      ] : void 0,
+      docs: emitDocs(definition.description),
       properties: this.buildProperties(definition),
       indexSignatures: this.buildIndexSignatures(definition)
     };
@@ -1450,9 +2580,7 @@ var _InterfaceBuilder = class _InterfaceBuilder {
         type: propertyType,
         isReadonly: isReadOnly,
         hasQuestionToken: !isRequired,
-        docs: property.description ? [
-          property.description
-        ] : void 0
+        docs: emitDocs(property.description)
       };
     });
   }
@@ -1624,26 +2752,49 @@ var _TypeGenerator = class _TypeGenerator {
   generate() {
     return __async(this, null, function* () {
       var _a;
-      try {
-        const definitions = this.parser.getNormalizedSpec().definitions;
-        if (!definitions || Object.keys(definitions).length === 0) {
-          (_a = this.onWarning) == null ? void 0 : _a.call(this, "No definitions found in swagger file");
-        }
-        if (this.config.options.modelFileStructure === "per-type") {
-          this.generatePerType(definitions);
-          return;
-        }
-        Object.entries(definitions).forEach(([name, definition]) => {
-          this.statements.push(...this.collectTypeStructure(name, definition));
-        });
-        this.statements.push(...buildSdkTypes(this.config));
-        this.applyBatchUpdates();
-        yield this.finalize();
-      } catch (error) {
-        throw new Error(`Failed to generate types: ${error instanceof Error ? error.message : "Unknown error"}`);
+      const definitions = this.parser.getNormalizedSpec().definitions;
+      if (!definitions || Object.keys(definitions).length === 0) {
+        (_a = this.onWarning) == null ? void 0 : _a.call(this, "No definitions found in swagger file");
       }
+      this.assertDistinctTypeNames(definitions);
+      if (this.config.options.modelFileStructure === "per-type") {
+        this.generatePerType(definitions);
+        return;
+      }
+      Object.entries(definitions).forEach(([name, definition]) => {
+        this.statements.push(...this.collectTypeStructure(name, definition));
+      });
+      this.statements.push(...buildSdkTypes(this.config));
+      this.applyBatchUpdates();
+      yield this.finalize();
     });
   }
+  /**
+   * Two schemas whose names sanitize onto one type name (`Pet-Store` and
+   * `Pet.Store` both become `Pet_Store`) would emit two declarations of one
+   * interface — and TypeScript declaration-merges those, so the compile
+   * check cannot see it and one model silently acquires the other's
+   * properties. Worse than a hard error, hence a hard error.
+   */
+  assertDistinctTypeNames(definitions) {
+    var _a;
+    const rawByType = /* @__PURE__ */ new Map();
+    for (const rawName of Object.keys(definitions)) {
+      const typeName = this.resolver.pascalName(rawName);
+      rawByType.set(typeName, [
+        ...(_a = rawByType.get(typeName)) != null ? _a : [],
+        rawName
+      ]);
+    }
+    const collisions = [
+      ...rawByType
+    ].filter(([, raws]) => raws.length > 1);
+    if (collisions.length === 0) {
+      return;
+    }
+    const detail = collisions.map(([typeName, raws]) => `"${typeName}" from schemas ${raws.map((raw) => `"${raw}"`).join(" and ")}`).join("; ");
+    throw new DuplicateGeneratedNameError(`Schemas map to the same type name: ${detail}. Rename one schema to keep them apart.`, collisions.map(([typeName]) => typeName));
+  }
   collectTypeStructure(name, definition) {
     const typeName = this.resolver.pascalName(name);
     if (definition.enum) {
@@ -1666,9 +2817,7 @@ var _TypeGenerator = class _TypeGenerator {
           kind: import_ts_morph4.StructureKind.TypeAlias,
           name: typeName,
           isExported: true,
-          docs: definition.description ? [
-            definition.description
-          ] : void 0,
+          docs: emitDocs(definition.description),
           type: this.resolver.resolve(definition)
         }
       ];
@@ -1685,9 +2834,7 @@ var _TypeGenerator = class _TypeGenerator {
       name,
       type: typeExpression,
       isExported: true,
-      docs: definition.description ? [
-        definition.description
-      ] : void 0
+      docs: emitDocs(definition.description)
     };
   }
   buildArrayTypeAlias(name, definition) {
@@ -1696,9 +2843,7 @@ var _TypeGenerator = class _TypeGenerator {
       kind: import_ts_morph4.StructureKind.TypeAlias,
       name,
       isExported: true,
-      docs: definition.description ? [
-        definition.description
-      ] : void 0,
+      docs: emitDocs(definition.description),
       type: `Array<${itemType}>`
     };
   }
@@ -1707,11 +2852,8 @@ var _TypeGenerator = class _TypeGenerator {
     this.sourceFile.addStatements(this.statements);
   }
   finalize() {
-    return __async(this, null, function* () {
-      this.sourceFile.formatText();
-      this.sourceFile.insertText(0, TYPE_GENERATOR_HEADER_COMMENT);
-      yield this.sourceFile.save();
-    });
+    this.sourceFile.formatText();
+    this.sourceFile.insertText(0, TYPE_GENERATOR_HEADER_COMMENT);
   }
   generatePerType(definitions) {
     const registry = new ModelFileRegistry(this.onWarning);
@@ -1801,7 +2943,6 @@ var _TypeGenerator = class _TypeGenerator {
   finalizeModelSourceFile(sourceFile) {
     sourceFile.formatText();
     sourceFile.insertText(0, TYPE_GENERATOR_HEADER_COMMENT);
-    sourceFile.saveSync();
   }
 };
 __name(_TypeGenerator, "TypeGenerator");
@@ -1811,11 +2952,11 @@ var TypeGenerator = _TypeGenerator;
 var import_ts_morph5 = require("ts-morph");
 var path2 = __toESM(require("path"));
 var _TokenGenerator = class _TokenGenerator {
-  constructor(project, clientName = "default") {
+  constructor(project, clientName) {
     __publicField(this, "project");
     __publicField(this, "clientName");
     this.project = project;
-    this.clientName = clientName;
+    this.clientName = effectiveClientName(clientName);
   }
   generate(outputDir) {
     const tokensDir = path2.join(outputDir, "tokens");
@@ -1838,9 +2979,9 @@ var _TokenGenerator = class _TokenGenerator {
         moduleSpecifier: "@angular/common/http"
       }
     ]);
-    const basePathTokenName = this.getBasePathTokenName();
-    const interceptorsTokenName = this.getInterceptorsTokenName();
-    const clientContextTokenName = this.getClientContextTokenName();
+    const basePathTokenName = getBasePathTokenName(this.clientName);
+    const interceptorsTokenName = getInterceptorsTokenName(this.clientName);
+    const clientContextTokenName = getClientContextTokenName(this.clientName);
     sourceFile.addVariableStatement({
       isExported: true,
       declarationKind: import_ts_morph5.VariableDeclarationKind.Const,
@@ -1854,7 +2995,7 @@ var _TokenGenerator = class _TokenGenerator {
         }
       ],
       leadingTrivia: `/**
- * Injection token for the ${this.clientName} client base API path
+ * Injection token for the ${escapeJsDoc(this.clientName)} client base API path
  */
 `
     });
@@ -1871,7 +3012,7 @@ var _TokenGenerator = class _TokenGenerator {
         }
       ],
       leadingTrivia: `/**
- * Injection token for the ${this.clientName} client HTTP interceptor instances
+ * Injection token for the ${escapeJsDoc(this.clientName)} client HTTP interceptor instances
  */
 `
     });
@@ -1881,11 +3022,11 @@ var _TokenGenerator = class _TokenGenerator {
       declarations: [
         {
           name: clientContextTokenName,
-          initializer: `new HttpContextToken<string>(() => '${this.clientName}')`
+          initializer: `new HttpContextToken<string>(() => ${quoteLiteral(this.clientName)})`
         }
       ],
       leadingTrivia: `/**
- * HttpContext token to identify requests belonging to the ${this.clientName} client
+ * HttpContext token to identify requests belonging to the ${escapeJsDoc(this.clientName)} client
  */
 `
     });
@@ -1920,19 +3061,6 @@ var _TokenGenerator = class _TokenGenerator {
       });
     }
     sourceFile.formatText();
-    sourceFile.saveSync();
-  }
-  getBasePathTokenName() {
-    const clientSuffix = this.clientName.toUpperCase().replace(/[^A-Z0-9]/g, "_");
-    return `BASE_PATH_${clientSuffix}`;
-  }
-  getInterceptorsTokenName() {
-    const clientSuffix = this.clientName.toUpperCase().replace(/[^A-Z0-9]/g, "_");
-    return `HTTP_INTERCEPTORS_${clientSuffix}`;
-  }
-  getClientContextTokenName() {
-    const clientSuffix = this.clientName.toUpperCase().replace(/[^A-Z0-9]/g, "_");
-    return `CLIENT_CONTEXT_TOKEN_${clientSuffix}`;
   }
 };
 __name(_TokenGenerator, "TokenGenerator");
@@ -2071,7 +3199,6 @@ var _FileDownloadGenerator = class _FileDownloadGenerator {
     return fallbackFilename;`
     });
     sourceFile.formatText();
-    sourceFile.saveSync();
   }
 };
 __name(_FileDownloadGenerator, "FileDownloadGenerator");
@@ -2224,7 +3351,6 @@ var _DateTransformerGenerator = class _DateTransformerGenerator {
       ]
     });
     sourceFile.formatText();
-    sourceFile.saveSync();
   }
 };
 __name(_DateTransformerGenerator, "DateTransformerGenerator");
@@ -2286,7 +3412,6 @@ var _MainIndexGenerator = class _MainIndexGenerator {
       });
     });
     sourceFile.formatText();
-    sourceFile.saveSync();
   }
 };
 __name(_MainIndexGenerator, "MainIndexGenerator");
@@ -2301,7 +3426,7 @@ var _ProviderGenerator = class _ProviderGenerator {
     __publicField(this, "clientName");
     this.project = project;
     this.config = config;
-    this.clientName = config.clientName || "default";
+    this.clientName = effectiveClientName(config.clientName);
   }
   generate(outputDir) {
     const filePath = path6.join(outputDir, "providers.ts");
@@ -2310,7 +3435,7 @@ var _ProviderGenerator = class _ProviderGenerator {
     });
     const basePathTokenName = getBasePathTokenName(this.clientName);
     const interceptorsTokenName = getInterceptorsTokenName(this.clientName);
-    const baseInterceptorClassName = `${this.capitalizeFirst(this.clientName)}BaseInterceptor`;
+    const baseInterceptorClassName = `${clientNameIdentifier(this.clientName)}BaseInterceptor`;
     sourceFile.addImportDeclarations([
       {
         namedImports: [
@@ -2386,22 +3511,19 @@ var _ProviderGenerator = class _ProviderGenerator {
       });
     }
     sourceFile.addInterface({
-      name: `${this.capitalizeFirst(this.clientName)}Config`,
+      name: `${clientNameIdentifier(this.clientName)}Config`,
       isExported: true,
-      docs: [
-        `Configuration options for ${this.clientName} client`
-      ],
+      docs: emitDocs(`Configuration options for ${this.clientName} client`),
       properties: configProperties
     });
     this.addMainProviderFunction(sourceFile, basePathTokenName, interceptorsTokenName, baseInterceptorClassName);
     sourceFile.insertText(0, PROVIDER_GENERATOR_HEADER_COMMENT);
     sourceFile.formatText();
-    sourceFile.saveSync();
   }
   addMainProviderFunction(sourceFile, basePathTokenName, interceptorsTokenName, baseInterceptorClassName) {
     const hasDateInterceptor = this.config.options.dateType === "Date";
-    const functionName = `provide${this.capitalizeFirst(this.clientName)}Client`;
-    const configTypeName = `${this.capitalizeFirst(this.clientName)}Config`;
+    const functionName = `provide${clientNameIdentifier(this.clientName)}Client`;
+    const configTypeName = `${clientNameIdentifier(this.clientName)}Config`;
     const functionBody = `
 const providers: Provider[] = [
     // Base path token for this client
@@ -2449,7 +3571,7 @@ return makeEnvironmentProviders(providers);`;
       name: functionName,
       isExported: true,
       docs: [
-        `Provides configuration for ${this.clientName} client`,
+        `Provides configuration for ${escapeJsDoc(this.clientName)} client`,
         "",
         "@example",
         "```typescript",
@@ -2495,9 +3617,6 @@ return makeEnvironmentProviders(providers);`;
       });
     }
   }
-  capitalizeFirst(str) {
-    return str.charAt(0).toUpperCase() + str.slice(1);
-  }
 };
 __name(_ProviderGenerator, "ProviderGenerator");
 var ProviderGenerator = _ProviderGenerator;
@@ -2507,11 +3626,11 @@ var import_ts_morph7 = require("ts-morph");
 var path7 = __toESM(require("path"));
 var _project, _clientName;
 var _BaseInterceptorGenerator = class _BaseInterceptorGenerator {
-  constructor(project, clientName = "default") {
+  constructor(project, clientName) {
     __privateAdd(this, _project);
     __privateAdd(this, _clientName);
     __privateSet(this, _project, project);
-    __privateSet(this, _clientName, clientName);
+    __privateSet(this, _clientName, effectiveClientName(clientName));
   }
   generate(outputDir) {
     const utilsDir = path7.join(outputDir, "utils");
@@ -2554,7 +3673,7 @@ var _BaseInterceptorGenerator = class _BaseInterceptorGenerator {
       }
     ]);
     sourceFile.addClass({
-      name: `${this.capitalizeFirst(__privateGet(this, _clientName))}BaseInterceptor`,
+      name: `${clientNameIdentifier(__privateGet(this, _clientName))}BaseInterceptor`,
       isExported: true,
       decorators: [
         {
@@ -2618,10 +3737,6 @@ var _BaseInterceptorGenerator = class _BaseInterceptorGenerator {
     });
     sourceFile.insertText(0, BASE_INTERCEPTOR_HEADER_COMMENT(__privateGet(this, _clientName)));
     sourceFile.formatText();
-    sourceFile.saveSync();
-  }
-  capitalizeFirst(str) {
-    return str.charAt(0).toUpperCase() + str.slice(1);
   }
 };
 _project = new WeakMap();
@@ -2655,7 +3770,6 @@ var _HttpParamsBuilderGenerator = class _HttpParamsBuilderGenerator {
     });
     this.addMethods(classDeclaration);
     sourceFile.formatText();
-    sourceFile.saveSync();
   }
   addMethods(classDeclaration) {
     const methods = [
@@ -2851,22 +3965,23 @@ var _ServiceMethodBodyGenerator = class _ServiceMethodBodyGenerator {
   }
   generateMethodBody(operation) {
     var _a;
+    const argumentNames = resolveArgumentNames(operation, this.config, SERVICE_ARGUMENT_PROFILE);
     const bodyParts = [
-      emitUrlConstruction(operation.path, operation.pathParams),
-      emitQueryParams(operation.queryParams),
+      emitUrlConstruction(operation.path, operation.pathParams, argumentNames),
+      emitQueryParams(operation.queryParams, argumentNames),
       emitHeaders({
         optionsExpression: "options",
         customHeaders: this.config.options.customHeaders,
         accept: ((_a = this.config.options.emitAcceptHeader) != null ? _a : true) ? operation.acceptHeader : void 0,
         contentType: operation
       }),
-      this.generateMultipartFormData(operation),
-      this.generateUrlEncodedFormData(operation),
-      this.generateHttpRequest(operation)
+      this.generateMultipartFormData(operation, argumentNames),
+      this.generateUrlEncodedFormData(operation, argumentNames),
+      this.generateHttpRequest(operation, argumentNames)
     ];
     return bodyParts.filter(Boolean).join("\n");
   }
-  generateMultipartFormData(operation) {
+  generateMultipartFormData(operation, argumentNames) {
     var _a;
     if (!operation.isMultipart || operation.formDataFields.length === 0) {
       return "";
@@ -2876,21 +3991,22 @@ var _ServiceMethodBodyGenerator = class _ServiceMethodBodyGenerator {
       const fieldSchema = properties[field];
       const isFile = (fieldSchema == null ? void 0 : fieldSchema.type) === "string" && (fieldSchema == null ? void 0 : fieldSchema.format) === "binary";
       const isArray = (fieldSchema == null ? void 0 : fieldSchema.type) === "array";
+      const arg = argumentNames.of(field);
       if (isArray) {
         const itemSchema = Array.isArray(fieldSchema.items) ? fieldSchema.items[0] : fieldSchema.items;
         const isFileArray = (itemSchema == null ? void 0 : itemSchema.type) === "string" && (itemSchema == null ? void 0 : itemSchema.format) === "binary";
         const valueExpression = isFileArray ? "item" : "String(item)";
-        return `if (${field} !== undefined && Array.isArray(${field})) {
-                  ${field}.forEach((item) => {
+        return `if (${arg} !== undefined && Array.isArray(${arg})) {
+                  ${arg}.forEach((item) => {
                     if (item !== undefined && item !== null) {
-                      formData.append('${field}', ${valueExpression});
+                      formData.append(${quoteLiteral(field)}, ${valueExpression});
                     }
                   });
                 }`;
       } else {
-        const valueExpression = isFile ? field : `String(${field})`;
-        return `if (${field} !== undefined) {
-                  formData.append('${field}', ${valueExpression});
+        const valueExpression = isFile ? arg : `String(${arg})`;
+        return `if (${arg} !== undefined) {
+                  formData.append(${quoteLiteral(field)}, ${valueExpression});
                 }`;
       }
     }).join("\n");
@@ -2898,7 +4014,7 @@ var _ServiceMethodBodyGenerator = class _ServiceMethodBodyGenerator {
 const formData = new FormData();
 ${formDataAppends}`;
   }
-  generateUrlEncodedFormData(operation) {
+  generateUrlEncodedFormData(operation, argumentNames) {
     var _a;
     if (!operation.isUrlEncoded || operation.urlEncodedFields.length === 0) {
       return "";
@@ -2907,17 +4023,18 @@ ${formDataAppends}`;
     const formBodyAppends = operation.urlEncodedFields.map((field) => {
       const fieldSchema = properties[field];
       const isArray = (fieldSchema == null ? void 0 : fieldSchema.type) === "array";
+      const arg = argumentNames.of(field);
       if (isArray) {
-        return `if (${field} !== undefined && Array.isArray(${field})) {
-                  ${field}.forEach((item) => {
+        return `if (${arg} !== undefined && Array.isArray(${arg})) {
+                  ${arg}.forEach((item) => {
                     if (item !== undefined && item !== null) {
-                      formBody.append('${field}', String(item));
+                      formBody.append(${quoteLiteral(field)}, String(item));
                     }
                   });
                 }`;
       } else {
-        return `if (${field} !== undefined && ${field} !== null) {
-                  formBody.append('${field}', String(${field}));
+        return `if (${arg} !== undefined && ${arg} !== null) {
+                  formBody.append(${quoteLiteral(field)}, String(${arg}));
                 }`;
       }
     }).join("\n");
@@ -2925,8 +4042,8 @@ ${formDataAppends}`;
 const formBody = new URLSearchParams();
 ${formBodyAppends}`;
   }
-  generateHttpRequest(operation) {
-    var _a, _b, _c;
+  generateHttpRequest(operation, argumentNames) {
+    var _a, _b, _c, _d;
     const httpMethod = operation.method.toLowerCase();
     let bodyParam = "";
     if (operation.hasBody) {
@@ -2935,9 +4052,7 @@ ${formBodyAppends}`;
       } else if (operation.isUrlEncoded) {
         bodyParam = "formBody.toString()";
       } else if ((_b = (_a = operation.requestBody) == null ? void 0 : _a.content) == null ? void 0 : _b[CONTENT_TYPES.JSON]) {
-        const bodyType = getRequestBodyType(operation.requestBody, this.config);
-        const isInterface = isDataTypeInterface(bodyType);
-        bodyParam = isInterface ? camelCase(bodyType) : "requestBody";
+        bodyParam = (_c = argumentNames.body) != null ? _c : "requestBody";
       }
     }
     const methodsWithBody = [
@@ -2945,7 +4060,7 @@ ${formBodyAppends}`;
       "put",
       "patch"
     ];
-    const parseResponse = ((_c = this.config.options.validation) == null ? void 0 : _c.response) ? `.pipe(map(response => options?.parse?.(response) ?? response))` : "";
+    const parseResponse = ((_d = this.config.options.validation) == null ? void 0 : _d.response) ? `.pipe(map(response => options?.parse?.(response) ?? response))` : "";
     const entries = [];
     if (methodsWithBody.includes(httpMethod)) {
       entries.push(`body: ${bodyParam || "null"}`);
@@ -3051,9 +4166,10 @@ var _ServiceMethodParamsGenerator = class _ServiceMethodParamsGenerator {
   generateApiParameters(operation) {
     var _a;
     const params = [];
+    const argumentNames = resolveArgumentNames(operation, this.config, SERVICE_ARGUMENT_PROFILE);
     operation.pathParams.forEach((param) => {
       params.push({
-        name: camelCase(param.name),
+        name: argumentNames.of(param.name),
         // Swagger 2.0 puts type/format/enum on the parameter itself; the
         // spread (vs passing param directly) is needed because Parameter
         // lacks TypeSchema's index signature — a fresh literal satisfies it.
@@ -3065,24 +4181,22 @@ var _ServiceMethodParamsGenerator = class _ServiceMethodParamsGenerator {
     if (requestBody) {
       const jsonContent = (_a = requestBody.content) == null ? void 0 : _a[CONTENT_TYPES.JSON];
       if (operation.isMultipart) {
-        params.push(...this.convertObjectToSingleParams(operation.formDataSchema));
+        params.push(...this.convertObjectToSingleParams(operation.formDataSchema, argumentNames));
       }
       if (operation.isUrlEncoded) {
-        params.push(...this.convertObjectToSingleParams(operation.urlEncodedSchema));
+        params.push(...this.convertObjectToSingleParams(operation.urlEncodedSchema, argumentNames));
       }
-      if (jsonContent && !operation.isMultipart) {
-        const bodyType = this.getRequestBodyType(requestBody);
-        const isInterface = isDataTypeInterface(bodyType);
+      if (jsonContent && !operation.isMultipart && argumentNames.body) {
         params.push({
-          name: isInterface ? camelCase(bodyType) : "requestBody",
-          type: bodyType,
+          name: argumentNames.body,
+          type: this.getRequestBodyType(requestBody),
           hasQuestionToken: !requestBody.required
         });
       }
     }
     operation.queryParams.forEach((param) => {
       params.push({
-        name: camelCase(param.name),
+        name: argumentNames.of(param.name),
         type: getTypeScriptType(param.schema || __spreadValues({}, param), this.config),
         hasQuestionToken: !param.required
       });
@@ -3124,13 +4238,13 @@ var _ServiceMethodParamsGenerator = class _ServiceMethodParamsGenerator {
     return "any";
   }
   /** `schema` arrives ref-resolved from the normalizer (formData/urlEncoded schema). */
-  convertObjectToSingleParams(schema) {
+  convertObjectToSingleParams(schema, argumentNames) {
     var _a;
     const params = [];
     Object.entries((_a = schema == null ? void 0 : schema.properties) != null ? _a : {}).forEach(([key, value]) => {
       var _a2;
       params.push({
-        name: key,
+        name: argumentNames.of(key),
         type: getTypeScriptType(value, this.config, value.nullable),
         hasQuestionToken: !((_a2 = schema == null ? void 0 : schema.required) == null ? void 0 : _a2.includes(key))
       });
@@ -3267,9 +4381,7 @@ ${methodBody}`;
       returnType,
       statements: methodBody,
       overloads: methodOverLoads,
-      docs: operation.description ? [
-        operation.description
-      ] : void 0
+      docs: emitDocs(operation.description)
     });
   }
   generateSingleRequestParameters(requestObject) {
@@ -3279,29 +4391,11 @@ ${methodBody}`;
     ];
   }
   generateMethodName(operation) {
-    if (this.config.options.customizeMethodName) {
-      if (operation.operationId == null) {
-        throw new Error(`Operation ID is required for method name customization of operation: (${operation.method}) ${operation.path}`);
-      }
-      return this.config.options.customizeMethodName(operation.operationId);
-    } else {
-      return this.defaultNameGenerator(operation);
-    }
+    return getOperationMethodName(operation, this.config);
   }
   generateReturnType() {
     return "Observable<any>";
   }
-  defaultNameGenerator(operation) {
-    if (operation.operationId) {
-      return camelCase(operation.operationId);
-    }
-    const method = pascalCase(operation.method.toLowerCase());
-    const pathParts = operation.path.split("/").map((str) => {
-      return pascalCase(pascalCase(str).replace(/[^a-zA-Z0-9]/g, ""));
-    });
-    const resource = pathParts.join("") || "resource";
-    return `${camelCase(resource)}${method}`;
-  }
 };
 __name(_ServiceMethodGenerator, "ServiceMethodGenerator");
 var ServiceMethodGenerator = _ServiceMethodGenerator;
@@ -3309,12 +4403,14 @@ var ServiceMethodGenerator = _ServiceMethodGenerator;
 // src/lib/generators/service/request-params.generator.ts
 var path9 = __toESM(require("path"));
 var _RequestParamsGenerator = class _RequestParamsGenerator {
-  constructor(project, config) {
+  constructor(project, config, onWarning) {
     __publicField(this, "project");
     __publicField(this, "paramsGenerator");
     __publicField(this, "registry", /* @__PURE__ */ new Map());
     __publicField(this, "usedInterfaceNames", /* @__PURE__ */ new Set());
+    __publicField(this, "onWarning");
     this.project = project;
+    this.onWarning = onWarning;
     this.paramsGenerator = new ServiceMethodParamsGenerator(config);
   }
   buildRegistry(controllerGroups, getMethodName) {
@@ -3324,10 +4420,6 @@ var _RequestParamsGenerator = class _RequestParamsGenerator {
         if (parameters.length === 0) {
           return;
         }
-        const reserved = parameters.find((param) => param.name === "observe" || param.name === "options");
-        if (reserved) {
-          throw new Error(`Parameter name '${reserved.name}' conflicts with the reserved '${reserved.name}' method parameter when useSingleRequestParameter is enabled: (${operation.method}) ${operation.path}`);
-        }
         const interfaceName = this.reserveInterfaceName(controllerName, getMethodName(operation));
         this.registry.set(operation, ServiceMethodRequestObjectGenerator.createEntry(interfaceName, parameters));
       });
@@ -3347,15 +4439,12 @@ var _RequestParamsGenerator = class _RequestParamsGenerator {
         name: entry.interfaceName,
         isExported: true,
         properties: ServiceMethodRequestObjectGenerator.toInterfaceProperties(entry),
-        docs: operation.description ? [
-          operation.description
-        ] : void 0
+        docs: emitDocs(operation.description)
       });
     });
     this.addMissingImports(sourceFile);
     sourceFile.formatText();
     sourceFile.insertText(0, REQUEST_PARAMS_GENERATOR_HEADER_COMMENT);
-    sourceFile.saveSync();
     this.addModelsBarrelExport(outputRoot);
   }
   /**
@@ -3385,19 +4474,24 @@ var _RequestParamsGenerator = class _RequestParamsGenerator {
       base,
       `${pascalCase(controllerName)}${base}`
     ];
-    for (const candidate of candidates) {
-      if (!this.usedInterfaceNames.has(candidate)) {
-        this.usedInterfaceNames.add(candidate);
-        return candidate;
-      }
+    if (!this.usedInterfaceNames.has(base)) {
+      this.usedInterfaceNames.add(base);
+      return base;
+    }
+    const warnRenamed = /* @__PURE__ */ __name((name) => {
+      var _a;
+      this.usedInterfaceNames.add(name);
+      (_a = this.onWarning) == null ? void 0 : _a.call(this, `Request-parameter interface "${base}" is already taken; the parameters of "${methodName}" in ${controllerName} are exposed as "${name}". Renaming the operationId keeps the type name stable.`);
+      return name;
+    }, "warnRenamed");
+    if (!this.usedInterfaceNames.has(candidates[1])) {
+      return warnRenamed(candidates[1]);
     }
     let suffix = 2;
     while (this.usedInterfaceNames.has(`${candidates[1]}${suffix}`)) {
       suffix++;
     }
-    const name = `${candidates[1]}${suffix}`;
-    this.usedInterfaceNames.add(name);
-    return name;
+    return warnRenamed(`${candidates[1]}${suffix}`);
   }
   addModelsBarrelExport(outputRoot) {
     const modelsIndex = this.project.getSourceFile(path9.join(outputRoot, "models", "index.ts"));
@@ -3408,7 +4502,6 @@ var _RequestParamsGenerator = class _RequestParamsGenerator {
       moduleSpecifier: "./request-params"
     });
     modelsIndex.formatText();
-    modelsIndex.saveSync();
   }
 };
 __name(_RequestParamsGenerator, "RequestParamsGenerator");
@@ -3438,35 +4531,15 @@ var _ServiceGenerator = class _ServiceGenerator {
         (_a = this.onWarning) == null ? void 0 : _a.call(this, "No API paths found in the specification");
         return;
       }
-      const controllerGroups = this.groupPathsByController(paths);
+      const controllerGroups = groupOperationsByController(paths, this.onWarning);
       if (this.config.options.useSingleRequestParameter) {
-        const requestParamsGenerator = new RequestParamsGenerator(this.project, this.config);
+        const requestParamsGenerator = new RequestParamsGenerator(this.project, this.config, this.onWarning);
         this.requestObjects = requestParamsGenerator.buildRegistry(controllerGroups, (operation) => this.methodGenerator.generateMethodName(operation));
         requestParamsGenerator.generate(outputRoot);
       }
       yield Promise.all(Object.entries(controllerGroups).map(([controllerName, operations]) => this.generateServiceFile(controllerName, operations, outputDir)));
     });
   }
-  groupPathsByController(paths) {
-    const groups = {};
-    paths.forEach((path14) => {
-      let controllerName = "Default";
-      if (path14.tags && path14.tags.length > 0) {
-        controllerName = path14.tags[0];
-      } else {
-        const pathParts = path14.path.split("/").filter((p) => p && !p.startsWith("{"));
-        if (pathParts.length > 1) {
-          controllerName = pascalCase(pathParts[1]);
-        }
-      }
-      controllerName = pascalCase(controllerName);
-      if (!groups[controllerName]) {
-        groups[controllerName] = [];
-      }
-      groups[controllerName].push(path14);
-    });
-    return groups;
-  }
   generateServiceFile(controllerName, operations, outputDir) {
     return __async(this, null, function* () {
       const fileName = `${camelCase(controllerName)}.service.ts`;
@@ -3477,9 +4550,24 @@ var _ServiceGenerator = class _ServiceGenerator {
       this.addServiceClass(sourceFile, controllerName, operations);
       sourceFile.fixMissingImports().formatText();
       sourceFile.insertText(0, SERVICE_GENERATOR_HEADER_COMMENT(controllerName));
-      sourceFile.saveSync();
     });
   }
+  /**
+   * A renamed argument is part of the method's public signature, and the
+   * suffix depends on which other arguments the operation has — so adding or
+   * removing one renumbers the survivor and breaks call sites. Silent is the
+   * one thing that must not happen.
+   */
+  warnAboutRenamedArguments(operation) {
+    var _a, _b;
+    const { renamed, merged } = resolveArgumentNames(operation, this.config, SERVICE_ARGUMENT_PROFILE);
+    for (const { source, identifier } of renamed) {
+      (_a = this.onWarning) == null ? void 0 : _a.call(this, `Parameter "${source}" of ${describeOperation(operation)} is exposed as "${identifier}" \u2014 its natural name is already taken by another parameter or by the method itself. Renaming it in the spec keeps the generated signature stable.`);
+    }
+    for (const wireName of merged) {
+      (_b = this.onWarning) == null ? void 0 : _b.call(this, `Parameter "${wireName}" of ${describeOperation(operation)} is declared in more than one location; they collapse into one argument, so the first declaration's type wins and the same value is sent for both.`);
+    }
+  }
   addServiceClass(sourceFile, controllerName, operations) {
     var _a;
     const className = getServiceClassName(controllerName, (_a = this.config.options.naming) == null ? void 0 : _a.services);
@@ -3566,14 +4654,26 @@ var _ServiceGenerator = class _ServiceGenerator {
       ],
       returnType: "HttpContext",
       statements: `const context = existingContext || new HttpContext();
-return context.set(this.clientContextToken, '${this.config.clientName || "default"}');`
+return context.set(this.clientContextToken, ${quoteLiteral(effectiveClientName(this.config.clientName))});`
     });
     operations.forEach((operation) => {
       var _a2;
+      this.warnAboutRenamedArguments(operation);
+      this.warnAboutReservedMethodName(operation);
       this.methodGenerator.addServiceMethod(serviceClass, operation, (_a2 = this.requestObjects) == null ? void 0 : _a2.get(operation));
     });
-    if (hasDuplicateFunctionNames(serviceClass.getMethods())) {
-      throw new Error(`Duplicate method names found in service class ${className}. Please ensure unique method names for each operation.`);
+    assertDistinctMemberNames(serviceClass, className, operations, (op) => this.methodGenerator.generateMethodName(op));
+  }
+  /**
+   * A derived method name that landed on a member the class binds itself is
+   * prefixed rather than rejected — the spec is valid — but the rename is
+   * public signature and must be said out loud.
+   */
+  warnAboutReservedMethodName(operation) {
+    var _a;
+    const collision = reservedMemberCollision(operation, this.config);
+    if (collision) {
+      (_a = this.onWarning) == null ? void 0 : _a.call(this, `Operation ${describeOperation(operation)} would be named "${collision.from}", which the generated class already binds \u2014 it is emitted as "${collision.to}". Rename the operationId to choose the name.`);
     }
   }
 };
@@ -3609,7 +4709,6 @@ var _ServiceIndexGenerator = class _ServiceIndexGenerator {
         moduleSpecifier: `./${serviceName}.service`
       });
     });
-    sourceFile.saveSync();
   }
 };
 __name(_ServiceIndexGenerator, "ServiceIndexGenerator");
@@ -3629,17 +4728,6 @@ var NAMING_KEYS = [
 ];
 var NAME_PREFIX_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 var NAME_SUFFIX_PATTERN = /^[A-Za-z0-9_]*$/;
-var _ConfigValidationError = class _ConfigValidationError extends Error {
-  constructor(issues) {
-    super(`Invalid ng-openapi configuration:
-${issues.map((issue) => `  - ${issue}`).join("\n")}`);
-    __publicField(this, "issues");
-    this.name = "ConfigValidationError";
-    this.issues = issues;
-  }
-};
-__name(_ConfigValidationError, "ConfigValidationError");
-var ConfigValidationError = _ConfigValidationError;
 function validateGeneratorConfig(config) {
   if (!config || typeof config !== "object") {
     throw new ConfigValidationError([
@@ -3793,15 +4881,20 @@ function validateInput(inputPath) {
 __name(validateInput, "validateInput");
 function generateFromConfig(_0) {
   return __async(this, arguments, function* (config, reporter = {}) {
-    var _a, _b, _c, _d, _e, _f, _g;
+    var _a, _b, _c, _d, _e, _f, _g, _h;
     const startedAt = Date.now();
     validateGeneratorConfig(config);
     validateInput(config.input);
     const outputPath = config.output;
     const generateServices = (_a = config.options.generateServices) != null ? _a : true;
     const warnings = [];
+    const seenWarnings = /* @__PURE__ */ new Set();
     const onWarning = /* @__PURE__ */ __name((message) => {
       var _a2;
+      if (seenWarnings.has(message)) {
+        return;
+      }
+      seenWarnings.add(message);
       warnings.push(message);
       (_a2 = reporter.onWarning) == null ? void 0 : _a2.call(reporter, message);
     }, "onWarning");
@@ -3825,7 +4918,7 @@ function generateFromConfig(_0) {
       }, config.compilerOptions)
     });
     (_b = reporter.onPhase) == null ? void 0 : _b.call(reporter, "processing-spec");
-    const swaggerParser = yield SwaggerParser.create(config.input, config);
+    const swaggerParser = yield SwaggerParser.create(config.input, config, onWarning);
     if (!swaggerParser.isValidSpec()) {
       const versionInfo = swaggerParser.getSpecVersion();
       throw new SpecParseError(`Invalid or unsupported specification format. Expected OpenAPI 3.x or Swagger 2.x. ${versionInfo ? `Found: ${versionInfo.type} ${versionInfo.version}` : "No version info found"}`, config.input);
@@ -3834,7 +4927,7 @@ function generateFromConfig(_0) {
     const typeGenerator = new TypeGenerator(swaggerParser, project, config, outputPath, onWarning);
     yield typeGenerator.generate();
     (_c = reporter.onPhase) == null ? void 0 : _c.call(reporter, "types-generated");
-    if (generateServices) {
+    if (generateServices || ((_d = config.plugins) == null ? void 0 : _d.length)) {
       const tokenGenerator = new TokenGenerator(project, config.clientName);
       tokenGenerator.generate(outputPath);
       if (config.options.dateType === "Date") {
@@ -3849,13 +4942,15 @@ function generateFromConfig(_0) {
       providerGenerator.generate(outputPath);
       const baseInterceptorGenerator = new BaseInterceptorGenerator(project, config.clientName);
       baseInterceptorGenerator.generate(outputPath);
+    }
+    if (generateServices) {
       const serviceGenerator = new ServiceGenerator(swaggerParser, project, config, onWarning);
       yield serviceGenerator.generate(outputPath);
-      const indexGenerator = new ServiceIndexGenerator(project, (_d = config.options.naming) == null ? void 0 : _d.services);
+      const indexGenerator = new ServiceIndexGenerator(project, (_e = config.options.naming) == null ? void 0 : _e.services);
       indexGenerator.generateIndex(outputPath);
-      (_e = reporter.onPhase) == null ? void 0 : _e.call(reporter, "services-generated");
+      (_f = reporter.onPhase) == null ? void 0 : _f.call(reporter, "services-generated");
     }
-    if ((_f = config.plugins) == null ? void 0 : _f.length) {
+    if ((_g = config.plugins) == null ? void 0 : _g.length) {
       for (const plugin of config.plugins) {
         const pluginGenerator = new plugin({
           spec: normalizedSpec,
@@ -3865,10 +4960,11 @@ function generateFromConfig(_0) {
         });
         yield pluginGenerator.generate(outputPath);
       }
-      (_g = reporter.onPhase) == null ? void 0 : _g.call(reporter, "plugins-generated");
+      (_h = reporter.onPhase) == null ? void 0 : _h.call(reporter, "plugins-generated");
     }
     const mainIndexGenerator = new MainIndexGenerator(project, config);
     mainIndexGenerator.generateMainIndex(outputPath);
+    yield project.save();
     return {
       client: config.clientName,
       filesWritten: project.getSourceFiles().map((sourceFile) => sourceFile.getFilePath()),
@@ -3878,35 +4974,93 @@ function generateFromConfig(_0) {
   });
 }
 __name(generateFromConfig, "generateFromConfig");
+
+// src/lib/core/config-loader.ts
+var fs3 = __toESM(require("fs"));
+var path14 = __toESM(require("path"));
+function loadConfigFile(configPath) {
+  return __async(this, null, function* () {
+    const resolvedPath = path14.resolve(configPath);
+    if (!fs3.existsSync(resolvedPath)) {
+      throw new ConfigLoadError(`Configuration file not found: ${resolvedPath}`, resolvedPath);
+    }
+    try {
+      delete require.cache[require.resolve(resolvedPath)];
+      if (resolvedPath.endsWith(".ts")) {
+        require("ts-node/register");
+      }
+      const configModule = require(resolvedPath);
+      const config = configModule.default || configModule.config || configModule;
+      if (!config.input || !config.output) {
+        throw new ConfigValidationError([
+          'Configuration must include "input" and "output" properties'
+        ]);
+      }
+      const configDir = path14.dirname(resolvedPath);
+      if (!isUrl(config.input) && !path14.isAbsolute(config.input)) {
+        config.input = path14.resolve(configDir, config.input);
+      }
+      if (!path14.isAbsolute(config.output)) {
+        config.output = path14.resolve(configDir, config.output);
+      }
+      return config;
+    } catch (error) {
+      if (error instanceof NgOpenApiError) {
+        throw error;
+      }
+      throw new ConfigLoadError(`Failed to load configuration file: ${resolvedPath}`, resolvedPath, error);
+    }
+  });
+}
+__name(loadConfigFile, "loadConfigFile");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BASE_INTERCEPTOR_HEADER_COMMENT,
   CONTENT_TYPES,
+  ConfigLoadError,
   ConfigValidationError,
+  DuplicateGeneratedNameError,
   HTTP_RESOURCE_GENERATOR_HEADER_COMMENT,
+  InvalidIdentifierError,
   MAIN_INDEX_GENERATOR_HEADER_COMMENT,
   NgOpenApiError,
   PROVIDER_GENERATOR_HEADER_COMMENT,
   REQUEST_PARAMS_GENERATOR_HEADER_COMMENT,
+  RESERVED_MEMBER_NAMES,
+  RESOURCE_ARGUMENT_PROFILE,
+  SERVICE_ARGUMENT_PROFILE,
   SERVICE_GENERATOR_HEADER_COMMENT,
   SERVICE_INDEX_GENERATOR_HEADER_COMMENT,
   SpecLoadError,
   SpecParseError,
   SwaggerParser,
   TYPE_GENERATOR_HEADER_COMMENT,
+  UnresolvedPathTemplateError,
   ZOD_PLUGIN_GENERATOR_HEADER_COMMENT,
   ZOD_PLUGIN_INDEX_GENERATOR_HEADER_COMMENT,
+  assertDistinctMemberNames,
   camelCase,
+  capitalizeFirst,
+  clientNameIdentifier,
   defineConfig,
+  describeOperation,
+  effectiveClientName,
   emitDefaultHeadersMerge,
+  emitDocs,
   emitHeaders,
+  emitObjectKey,
+  emitPropertyName,
   emitQueryParams,
   emitResponseTypeOption,
   emitServiceDecorator,
   emitSignalAwareQueryParams,
   emitUrlConstruction,
   emitUrlExpression,
+  escapeDoubleQuoted,
+  escapeJsDoc,
+  escapeSingleQuoted,
   escapeString,
+  escapeTemplateLiteral,
   extractPaths,
   generateFromConfig,
   generateParseRequestTypeParams,
@@ -3914,6 +5068,7 @@ __name(generateFromConfig, "generateFromConfig");
   getClientContextTokenName,
   getInterceptorsTokenName,
   getModelTypeName,
+  getOperationMethodName,
   getRequestBodyType,
   getResourceClassName,
   getResponseInfoFromResponse,
@@ -3921,21 +5076,27 @@ __name(generateFromConfig, "generateFromConfig");
   getResponseTypeFromResponse,
   getServiceClassName,
   getTypeScriptType,
+  groupOperationsByController,
   hasDuplicateFunctionNames,
   inferResponseTypeFromContentType,
   isDataTypeInterface,
   isPrimitiveType,
   isUrl,
+  isValidIdentifier,
   joinRequestOptionEntries,
   kebabCase,
   listGeneratedBarrelDirs,
   listGeneratedFileNames,
+  loadConfigFile,
   normalizeSchema,
   normalizeSpec,
   nullableType,
   pascalCase,
   pascalCaseForEnums,
   plainParamValue,
+  quoteLiteral,
+  reservedMemberCollision,
+  resolveArgumentNames,
   screamingSnakeCase,
   signalAwareParamValue,
   validateGeneratorConfig,