ng-openapi 0.3.3 → 0.4.0

package/cli.cjs

@@ -42,6 +42,28 @@ 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 extends Error {
   static {
     __name(this, "NgOpenApiError");
@@ -50,10 +72,73 @@ var NgOpenApiError = class extends Error {
   cause;
   constructor(message, cause) {
     super(message);
-    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 {
+      name: this.name,
+      message: this.message,
+      ...cause === void 0 ? {} : {
+        cause
+      },
+      // Own enumerable properties: the brand is deliberately not one.
+      ...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) {
+    if (typeof value !== "object" || value === null) {
+      return false;
+    }
+    try {
+      if (Object.prototype.isPrototypeOf.call(this.prototype, value)) {
+        return true;
+      }
+      const expected = ERROR_LINEAGE.get(this)?.[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 {
+      return false;
+    }
   }
 };
+registerError(NgOpenApiError, [
+  "NgOpenApiError"
+]);
 var SpecLoadError = class extends NgOpenApiError {
   static {
     __name(this, "SpecLoadError");
@@ -65,6 +150,10 @@ var SpecLoadError = class extends NgOpenApiError {
     this.source = source;
   }
 };
+registerError(SpecLoadError, [
+  "SpecLoadError",
+  "NgOpenApiError"
+]);
 var SpecParseError = class extends NgOpenApiError {
   static {
     __name(this, "SpecParseError");
@@ -76,6 +165,113 @@ var SpecParseError = class extends NgOpenApiError {
     this.source = source;
   }
 };
+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 extends NgOpenApiError {
+  static {
+    __name(this, "InvalidIdentifierError");
+  }
+  /** The rejected name, verbatim; absent when no name could be derived. */
+  identifier;
+  /** The operation whose name was being derived. */
+  operation;
+  constructor(message, operation, identifier) {
+    super(message);
+    this.operation = captureOperation(operation);
+    this.identifier = identifier;
+  }
+};
+registerError(InvalidIdentifierError, [
+  "InvalidIdentifierError",
+  "NgOpenApiError"
+]);
+var DuplicateGeneratedNameError = class extends NgOpenApiError {
+  static {
+    __name(this, "DuplicateGeneratedNameError");
+  }
+  /** The colliding generated names. */
+  names;
+  /** The operations that produced them, when known. */
+  operations;
+  constructor(message, names, operations = []) {
+    super(message);
+    this.names = Object.freeze([
+      ...names
+    ]);
+    this.operations = Object.freeze(operations.map(captureOperation));
+  }
+};
+registerError(DuplicateGeneratedNameError, [
+  "DuplicateGeneratedNameError",
+  "NgOpenApiError"
+]);
+var UnresolvedPathTemplateError = class extends NgOpenApiError {
+  static {
+    __name(this, "UnresolvedPathTemplateError");
+  }
+  /** The path as written in the spec. */
+  path;
+  /** Placeholder names with no declared parameter. */
+  placeholders;
+  constructor(message, path15, placeholders) {
+    super(message);
+    this.path = path15;
+    this.placeholders = Object.freeze([
+      ...placeholders
+    ]);
+  }
+};
+registerError(UnresolvedPathTemplateError, [
+  "UnresolvedPathTemplateError",
+  "NgOpenApiError"
+]);
+var ConfigValidationError = class extends NgOpenApiError {
+  static {
+    __name(this, "ConfigValidationError");
+  }
+  issues;
+  constructor(issues) {
+    super(`Invalid ng-openapi configuration:
+${issues.map((issue) => `  - ${issue}`).join("\n")}`);
+    this.issues = Object.freeze([
+      ...issues
+    ]);
+  }
+};
+registerError(ConfigValidationError, [
+  "ConfigValidationError",
+  "NgOpenApiError"
+]);
+var ConfigLoadError = class extends NgOpenApiError {
+  static {
+    __name(this, "ConfigLoadError");
+  }
+  /** Path of the config file that failed to load. */
+  source;
+  constructor(message, source, cause) {
+    super(message, cause);
+    this.source = source;
+  }
+};
+registerError(ConfigLoadError, [
+  "ConfigLoadError",
+  "NgOpenApiError"
+]);
 
 // ../shared/src/core/spec-loader.ts
 async function loadSpecContent(pathOrUrl) {
@@ -177,6 +373,430 @@ 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 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) {
+  if (Array.isArray(node)) {
+    let changed2 = false;
+    const items = node.map((item) => {
+      const next = transform(item, ctx, chain, false);
+      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(ref.split("/").pop() ?? "");
+      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 ||= 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) {
+  const key = site === void 0 ? `${cause}:${ref}` : `${cause}:${ref}|${[
+    ...site
+  ].sort().join(",")}`;
+  if (ctx.warned.has(key)) {
+    return;
+  }
+  ctx.warned.add(key);
+  const emitted = ctx.emittedPerCause.get(cause) ?? 0;
+  if (emitted >= MAX_WARNINGS_PER_CAUSE) {
+    const refs = ctx.deferred.get(cause) ?? /* @__PURE__ */ new Set();
+    refs.add(ref);
+    ctx.deferred.set(cause, refs);
+    return;
+  }
+  ctx.emittedPerCause.set(cause, emitted + 1);
+  ctx.onWarning?.(message);
+}
+__name(warnOnce, "warnOnce");
+function flushDeferredWarnings(ctx) {
+  for (const [cause, refs] of ctx.deferred) {
+    ctx.onWarning?.(`\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) {
+  if (value === null) {
+    return "null";
+  }
+  if (Array.isArray(value)) {
+    return "an array";
+  }
+  if (isPlainObject(value)) {
+    return "an object";
+  }
+  if (typeof value === "object") {
+    const className = Object.getPrototypeOf(value)?.constructor?.name;
+    return typeof className === "string" ? `a ${className}` : "a non-plain object";
+  }
+  return `a ${typeof value}`;
+}
+__name(describeKind, "describeKind");
+function safeStringify(value) {
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    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",
@@ -193,7 +813,7 @@ function extractPaths(swaggerPaths = {}, methods = [
   "delete",
   "options",
   "head"
-]) {
+], onWarning, resolveParameter) {
   const paths = [];
   Object.entries(swaggerPaths).forEach(([path15, pathItem]) => {
     methods.forEach((method) => {
@@ -202,11 +822,11 @@ function extractPaths(swaggerPaths = {}, methods = [
         paths.push({
           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 || {}
         });
@@ -216,13 +836,54 @@ 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) => {
+    const ref = param.$ref;
+    if (typeof ref !== "string") {
+      return [
+        param
+      ];
+    }
+    const resolution = resolveParameter?.(ref) ?? {
+      problem: "cannot be resolved here: no reusable parameters were provided"
+    };
+    if ("parameter" in resolution) {
+      return [
+        resolution.parameter
+      ];
+    }
+    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?.(`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,
@@ -233,23 +894,38 @@ 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 pascalCaseForEnums(str) {
-  return str.replace(/[^a-zA-Z0-9]/g, "_").replace(/(?:^|_)([a-z])/g, (_, char) => char.toUpperCase()).replace(/^([0-9])/, "_$1");
+__name(escapeTemplateLiteral, "escapeTemplateLiteral");
+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) {
@@ -293,7 +969,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";
@@ -329,10 +1005,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) {
@@ -480,7 +1152,7 @@ function getResponseType(response, config) {
 __name(getResponseType, "getResponseType");
 
 // ../shared/src/core/normalize.ts
-function normalizeSpec(spec) {
+function normalizeSpec(spec, onWarning) {
   const rawDefinitions = spec.definitions || spec.components?.schemas || {};
   const definitions = Object.fromEntries(Object.entries(rawDefinitions).map(([name, definition]) => [
     name,
@@ -490,6 +1162,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",
@@ -499,7 +1172,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
   };
 }
@@ -589,24 +1262,29 @@ function normalizeContentSchemas(content) {
   ]));
 }
 __name(normalizeContentSchemas, "normalizeContentSchemas");
-function normalizeOperation(operation, resolveRef) {
+function normalizeOperation(operation, resolveRef, onWarning) {
+  warnAboutUnboundParameters(operation, onWarning);
   const content = operation.requestBody?.content;
   const isMultipart = !!content?.[CONTENT_TYPES.MULTIPART];
   const isUrlEncoded = !!content?.[CONTENT_TYPES.FORM_URLENCODED] && !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 = operation.parameters?.filter((p) => p.in === "path") || [];
+  const queryParams = operation.parameters?.filter((p) => p.in === "query") || [];
+  const formDataFields = Object.keys(formDataSchema?.properties || {});
+  const urlEncodedFields = Object.keys(urlEncodedSchema?.properties || {});
   return {
     ...operation,
-    pathParams: operation.parameters?.filter((p) => p.in === "path") || [],
-    queryParams: operation.parameters?.filter((p) => p.in === "query") || [],
+    pathParams,
+    queryParams,
     hasBody: !!operation.requestBody,
     isMultipart,
     isUrlEncoded,
     formDataSchema,
-    formDataFields: Object.keys(formDataSchema?.properties || {}),
+    formDataFields,
     urlEncodedSchema,
-    urlEncodedFields: Object.keys(urlEncodedSchema?.properties || {}),
+    urlEncodedFields,
     responseType: responseInfo.responseType,
     acceptHeader: responseInfo.acceptHeader
   };
@@ -635,6 +1313,68 @@ function determineResponseInfo(operation) {
   };
 }
 __name(determineResponseInfo, "determineResponseInfo");
+function createParameterResolver(spec) {
+  const components = (spec.swagger ? spec.parameters : spec.components?.parameters) ?? {};
+  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) {
+  for (const param of operation.parameters ?? []) {
+    if (param.in === "path" || param.in === "query") {
+      continue;
+    }
+    if (param.in === "header" || param.in === "cookie") {
+      if (param.required) {
+        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?.(`${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 {
@@ -643,24 +1383,36 @@ var SwaggerParser = class _SwaggerParser {
   }
   spec;
   normalized;
-  constructor(spec, config) {
-    const isInputValid = config.validateInput?.(spec) ?? 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. */
+  onWarning;
+  constructor(spec, 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 async create(swaggerPathOrUrl, config) {
+  static async create(swaggerPathOrUrl, config, onWarning) {
     const swaggerContent = await loadSpecContent(swaggerPathOrUrl);
     const spec = parseSpecContent(swaggerContent, swaggerPathOrUrl);
-    return new _SwaggerParser(spec, config);
+    const isInputValid = config.validateInput?.(spec) ?? 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);
   }
   /**
    * The version-free model generators consume. Computed once and cached —
@@ -668,7 +1420,7 @@ var SwaggerParser = class _SwaggerParser {
    * can be used as Map keys across generators.
    */
   getNormalizedSpec() {
-    this.normalized ??= normalizeSpec(this.spec);
+    this.normalized ??= normalizeSpec(this.spec, this.onWarning);
     return this.normalized;
   }
   /** Definition map regardless of version: 2.0 `definitions` or 3.x `components.schemas`. */
@@ -698,25 +1450,29 @@ 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;
   }
 };
+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) {
@@ -737,7 +1493,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?.isMultipart) {
@@ -761,38 +1517,273 @@ if (!headers.has('Content-Type')) {
 }
 __name(emitHeaders, "emitHeaders");
 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?.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) => identifiers.get(wireName) ?? 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) {
+  if (!operation.requestBody || operation.isMultipart) {
+    return void 0;
+  }
+  if (!operation.requestBody.content?.[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;
 }
 __name(plainParamValue, "plainParamValue");
-function emitUrlExpression(path15, pathParams, paramValue = plainParamValue) {
-  let urlExpression = `\`\${this.basePath}${path15}\``;
+function emitUrlExpression(path15, pathParams, argumentNames, paramValue = plainParamValue) {
+  const declared = new Set(pathParams.map((param) => param.name));
+  const unresolved = (path15.match(/{([^{}]*)}/g) ?? []).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(path15, pathParams) {
-  return `const url = ${emitUrlExpression(path15, 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}`;
@@ -854,55 +1845,158 @@ 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) => {
+    const tag = operation.tags?.[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 = controllerByFold.get(fold) ?? candidate;
+    controllerByFold.set(fold, controllerName);
+    if (tag !== void 0 && isNameless) {
+      namelessTags.add(tag);
+    } else if (tag !== void 0) {
+      const spellings = tagSpellings.get(controllerName) ?? /* @__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?.(`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?.(`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?.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) {
+  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) {
+    byName.get(methodNameOf(operation))?.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/config/constants.ts
 var disableLinting = `// @ts-nocheck
@@ -938,7 +2032,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");
@@ -949,11 +2043,9 @@ var ZOD_PLUGIN_INDEX_GENERATOR_HEADER_COMMENT = defaultHeaderComment + `* Genera
 
 // src/lib/cli.ts
 var import_commander = require("commander");
-var fs3 = __toESM(require("fs"));
-var path14 = __toESM(require("path"));
 
 // package.json
-var version = "0.3.3";
+var version = "0.4.0";
 
 // src/lib/core/generator.ts
 var import_ts_morph10 = require("ts-morph");
@@ -962,17 +2054,8 @@ var import_ts_morph10 = require("ts-morph");
 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 {
   static {
     __name(this, "TypeResolver");
@@ -1043,7 +2126,7 @@ var TypeResolver = class {
       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>";
@@ -1147,9 +2230,7 @@ var EnumBuilder = class {
   }
   build(name, definition) {
     if (!definition.enum?.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 {
@@ -1190,7 +2271,7 @@ var EnumBuilder = class {
     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(" | ");
@@ -1250,9 +2331,7 @@ var InterfaceBuilder = class {
       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)
     };
@@ -1271,9 +2350,7 @@ var InterfaceBuilder = class {
         type: propertyType,
         isReadonly: isReadOnly,
         hasQuestionToken: !isRequired,
-        docs: property.description ? [
-          property.description
-        ] : void 0
+        docs: emitDocs(property.description)
       };
     });
   }
@@ -1443,24 +2520,46 @@ var TypeGenerator = class {
     this.interfaceBuilder = new InterfaceBuilder(this.resolver);
   }
   async generate() {
-    try {
-      const definitions = this.parser.getNormalizedSpec().definitions;
-      if (!definitions || Object.keys(definitions).length === 0) {
-        this.onWarning?.("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();
-      await 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) {
+      this.onWarning?.("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();
+    await 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) {
+    const rawByType = /* @__PURE__ */ new Map();
+    for (const rawName of Object.keys(definitions)) {
+      const typeName = this.resolver.pascalName(rawName);
+      rawByType.set(typeName, [
+        ...rawByType.get(typeName) ?? [],
+        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);
@@ -1484,9 +2583,7 @@ var TypeGenerator = class {
           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)
         }
       ];
@@ -1503,9 +2600,7 @@ var TypeGenerator = class {
       name,
       type: typeExpression,
       isExported: true,
-      docs: definition.description ? [
-        definition.description
-      ] : void 0
+      docs: emitDocs(definition.description)
     };
   }
   buildArrayTypeAlias(name, definition) {
@@ -1514,9 +2609,7 @@ var TypeGenerator = class {
       kind: import_ts_morph4.StructureKind.TypeAlias,
       name,
       isExported: true,
-      docs: definition.description ? [
-        definition.description
-      ] : void 0,
+      docs: emitDocs(definition.description),
       type: `Array<${itemType}>`
     };
   }
@@ -1524,10 +2617,9 @@ var TypeGenerator = class {
     this.addSdkImports(this.sourceFile);
     this.sourceFile.addStatements(this.statements);
   }
-  async finalize() {
+  finalize() {
     this.sourceFile.formatText();
     this.sourceFile.insertText(0, TYPE_GENERATOR_HEADER_COMMENT);
-    await this.sourceFile.save();
   }
   generatePerType(definitions) {
     const registry = new ModelFileRegistry(this.onWarning);
@@ -1616,7 +2708,6 @@ var TypeGenerator = class {
   finalizeModelSourceFile(sourceFile) {
     sourceFile.formatText();
     sourceFile.insertText(0, TYPE_GENERATOR_HEADER_COMMENT);
-    sourceFile.saveSync();
   }
 };
 
@@ -1629,9 +2720,9 @@ var TokenGenerator = class {
   }
   project;
   clientName;
-  constructor(project, clientName = "default") {
+  constructor(project, clientName) {
     this.project = project;
-    this.clientName = clientName;
+    this.clientName = effectiveClientName(clientName);
   }
   generate(outputDir) {
     const tokensDir = path2.join(outputDir, "tokens");
@@ -1654,9 +2745,9 @@ var TokenGenerator = class {
         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,
@@ -1670,7 +2761,7 @@ var TokenGenerator = class {
         }
       ],
       leadingTrivia: `/**
- * Injection token for the ${this.clientName} client base API path
+ * Injection token for the ${escapeJsDoc(this.clientName)} client base API path
  */
 `
     });
@@ -1687,7 +2778,7 @@ var TokenGenerator = class {
         }
       ],
       leadingTrivia: `/**
- * Injection token for the ${this.clientName} client HTTP interceptor instances
+ * Injection token for the ${escapeJsDoc(this.clientName)} client HTTP interceptor instances
  */
 `
     });
@@ -1697,11 +2788,11 @@ var TokenGenerator = class {
       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
  */
 `
     });
@@ -1736,19 +2827,6 @@ var TokenGenerator = class {
       });
     }
     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}`;
   }
 };
 
@@ -1888,7 +2966,6 @@ var FileDownloadGenerator = class {
     return fallbackFilename;`
     });
     sourceFile.formatText();
-    sourceFile.saveSync();
   }
 };
 
@@ -2042,7 +3119,6 @@ var DateTransformerGenerator = class {
       ]
     });
     sourceFile.formatText();
-    sourceFile.saveSync();
   }
 };
 
@@ -2105,7 +3181,6 @@ var MainIndexGenerator = class {
       });
     });
     sourceFile.formatText();
-    sourceFile.saveSync();
   }
 };
 
@@ -2121,7 +3196,7 @@ var ProviderGenerator = class {
   constructor(project, config) {
     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");
@@ -2130,7 +3205,7 @@ var ProviderGenerator = class {
     });
     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: [
@@ -2206,22 +3281,19 @@ var ProviderGenerator = class {
       });
     }
     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
@@ -2269,7 +3341,7 @@ return makeEnvironmentProviders(providers);`;
       name: functionName,
       isExported: true,
       docs: [
-        `Provides configuration for ${this.clientName} client`,
+        `Provides configuration for ${escapeJsDoc(this.clientName)} client`,
         "",
         "@example",
         "```typescript",
@@ -2315,9 +3387,6 @@ return makeEnvironmentProviders(providers);`;
       });
     }
   }
-  capitalizeFirst(str) {
-    return str.charAt(0).toUpperCase() + str.slice(1);
-  }
 };
 
 // src/lib/generators/utility/base-interceptor.generator.ts
@@ -2329,9 +3398,9 @@ var BaseInterceptorGenerator = class {
   }
   #project;
   #clientName;
-  constructor(project, clientName = "default") {
+  constructor(project, clientName) {
     this.#project = project;
-    this.#clientName = clientName;
+    this.#clientName = effectiveClientName(clientName);
   }
   generate(outputDir) {
     const utilsDir = path7.join(outputDir, "utils");
@@ -2374,7 +3443,7 @@ var BaseInterceptorGenerator = class {
       }
     ]);
     sourceFile.addClass({
-      name: `${this.capitalizeFirst(this.#clientName)}BaseInterceptor`,
+      name: `${clientNameIdentifier(this.#clientName)}BaseInterceptor`,
       isExported: true,
       decorators: [
         {
@@ -2438,10 +3507,6 @@ var BaseInterceptorGenerator = class {
     });
     sourceFile.insertText(0, BASE_INTERCEPTOR_HEADER_COMMENT(this.#clientName));
     sourceFile.formatText();
-    sourceFile.saveSync();
-  }
-  capitalizeFirst(str) {
-    return str.charAt(0).toUpperCase() + str.slice(1);
   }
 };
 
@@ -2474,7 +3539,6 @@ var HttpParamsBuilderGenerator = class {
     });
     this.addMethods(classDeclaration);
     sourceFile.formatText();
-    sourceFile.saveSync();
   }
   addMethods(classDeclaration) {
     const methods = [
@@ -2670,22 +3734,23 @@ var ServiceMethodBodyGenerator = class {
     this.config = config;
   }
   generateMethodBody(operation) {
+    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: this.config.options.emitAcceptHeader ?? 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) {
     if (!operation.isMultipart || operation.formDataFields.length === 0) {
       return "";
     }
@@ -2694,21 +3759,22 @@ var ServiceMethodBodyGenerator = class {
       const fieldSchema = properties[field];
       const isFile = fieldSchema?.type === "string" && fieldSchema?.format === "binary";
       const isArray = fieldSchema?.type === "array";
+      const arg = argumentNames.of(field);
       if (isArray) {
         const itemSchema = Array.isArray(fieldSchema.items) ? fieldSchema.items[0] : fieldSchema.items;
         const isFileArray = itemSchema?.type === "string" && 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");
@@ -2716,7 +3782,7 @@ var ServiceMethodBodyGenerator = class {
 const formData = new FormData();
 ${formDataAppends}`;
   }
-  generateUrlEncodedFormData(operation) {
+  generateUrlEncodedFormData(operation, argumentNames) {
     if (!operation.isUrlEncoded || operation.urlEncodedFields.length === 0) {
       return "";
     }
@@ -2724,17 +3790,18 @@ ${formDataAppends}`;
     const formBodyAppends = operation.urlEncodedFields.map((field) => {
       const fieldSchema = properties[field];
       const isArray = 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");
@@ -2742,7 +3809,7 @@ ${formDataAppends}`;
 const formBody = new URLSearchParams();
 ${formBodyAppends}`;
   }
-  generateHttpRequest(operation) {
+  generateHttpRequest(operation, argumentNames) {
     const httpMethod = operation.method.toLowerCase();
     let bodyParam = "";
     if (operation.hasBody) {
@@ -2751,9 +3818,7 @@ ${formBodyAppends}`;
       } else if (operation.isUrlEncoded) {
         bodyParam = "formBody.toString()";
       } else if (operation.requestBody?.content?.[CONTENT_TYPES.JSON]) {
-        const bodyType = getRequestBodyType(operation.requestBody, this.config);
-        const isInterface = isDataTypeInterface(bodyType);
-        bodyParam = isInterface ? camelCase(bodyType) : "requestBody";
+        bodyParam = argumentNames.body ?? "requestBody";
       }
     }
     const methodsWithBody = [
@@ -2868,9 +3933,10 @@ var ServiceMethodParamsGenerator = class {
   }
   generateApiParameters(operation) {
     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.
@@ -2884,24 +3950,22 @@ var ServiceMethodParamsGenerator = class {
     if (requestBody) {
       const jsonContent = requestBody.content?.[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 || {
           ...param
         }, this.config),
@@ -2944,11 +4008,11 @@ var ServiceMethodParamsGenerator = class {
     return "any";
   }
   /** `schema` arrives ref-resolved from the normalizer (formData/urlEncoded schema). */
-  convertObjectToSingleParams(schema) {
+  convertObjectToSingleParams(schema, argumentNames) {
     const params = [];
     Object.entries(schema?.properties ?? {}).forEach(([key, value]) => {
       params.push({
-        name: key,
+        name: argumentNames.of(key),
         type: getTypeScriptType(value, this.config, value.nullable),
         hasQuestionToken: !schema?.required?.includes(key)
       });
@@ -3085,9 +4149,7 @@ ${methodBody}`;
       returnType,
       statements: methodBody,
       overloads: methodOverLoads,
-      docs: operation.description ? [
-        operation.description
-      ] : void 0
+      docs: emitDocs(operation.description)
     });
   }
   generateSingleRequestParameters(requestObject) {
@@ -3097,29 +4159,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}`;
-  }
 };
 
 // src/lib/generators/service/request-params.generator.ts
@@ -3132,8 +4176,10 @@ var RequestParamsGenerator = class {
   paramsGenerator;
   registry = /* @__PURE__ */ new Map();
   usedInterfaceNames = /* @__PURE__ */ new Set();
-  constructor(project, config) {
+  onWarning;
+  constructor(project, config, onWarning) {
     this.project = project;
+    this.onWarning = onWarning;
     this.paramsGenerator = new ServiceMethodParamsGenerator(config);
   }
   buildRegistry(controllerGroups, getMethodName) {
@@ -3143,10 +4189,6 @@ var RequestParamsGenerator = class {
         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));
       });
@@ -3166,15 +4208,12 @@ var RequestParamsGenerator = class {
         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);
   }
   /**
@@ -3204,19 +4243,23 @@ var RequestParamsGenerator = class {
       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) => {
+      this.usedInterfaceNames.add(name);
+      this.onWarning?.(`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"));
@@ -3227,7 +4270,6 @@ var RequestParamsGenerator = class {
       moduleSpecifier: "./request-params"
     });
     modelsIndex.formatText();
-    modelsIndex.saveSync();
   }
 };
 
@@ -3256,34 +4298,14 @@ var ServiceGenerator = class {
       this.onWarning?.("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);
     }
     await Promise.all(Object.entries(controllerGroups).map(([controllerName, operations]) => this.generateServiceFile(controllerName, operations, outputDir)));
   }
-  groupPathsByController(paths) {
-    const groups = {};
-    paths.forEach((path15) => {
-      let controllerName = "Default";
-      if (path15.tags && path15.tags.length > 0) {
-        controllerName = path15.tags[0];
-      } else {
-        const pathParts = path15.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(path15);
-    });
-    return groups;
-  }
   async generateServiceFile(controllerName, operations, outputDir) {
     const fileName = `${camelCase(controllerName)}.service.ts`;
     const filePath = path10.join(outputDir, fileName);
@@ -3293,7 +4315,21 @@ var ServiceGenerator = class {
     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) {
+    const { renamed, merged } = resolveArgumentNames(operation, this.config, SERVICE_ARGUMENT_PROFILE);
+    for (const { source, identifier } of renamed) {
+      this.onWarning?.(`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) {
+      this.onWarning?.(`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) {
     const className = getServiceClassName(controllerName, this.config.options.naming?.services);
@@ -3380,13 +4416,24 @@ var ServiceGenerator = class {
       ],
       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) => {
+      this.warnAboutRenamedArguments(operation);
+      this.warnAboutReservedMethodName(operation);
       this.methodGenerator.addServiceMethod(serviceClass, operation, this.requestObjects?.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) {
+    const collision = reservedMemberCollision(operation, this.config);
+    if (collision) {
+      this.onWarning?.(`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.`);
     }
   }
 };
@@ -3423,7 +4470,6 @@ var ServiceIndexGenerator = class {
         moduleSpecifier: `./${serviceName}.service`
       });
     });
-    sourceFile.saveSync();
   }
 };
 
@@ -3441,18 +4487,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 extends Error {
-  static {
-    __name(this, "ConfigValidationError");
-  }
-  issues;
-  constructor(issues) {
-    super(`Invalid ng-openapi configuration:
-${issues.map((issue) => `  - ${issue}`).join("\n")}`);
-    this.name = "ConfigValidationError";
-    this.issues = issues;
-  }
-};
 function validateGeneratorConfig(config) {
   if (!config || typeof config !== "object") {
     throw new ConfigValidationError([
@@ -3611,7 +4645,12 @@ async function generateFromConfig(config, reporter = {}) {
   const outputPath = config.output;
   const generateServices = config.options.generateServices ?? true;
   const warnings = [];
+  const seenWarnings = /* @__PURE__ */ new Set();
   const onWarning = /* @__PURE__ */ __name((message) => {
+    if (seenWarnings.has(message)) {
+      return;
+    }
+    seenWarnings.add(message);
     warnings.push(message);
     reporter.onWarning?.(message);
   }, "onWarning");
@@ -3636,7 +4675,7 @@ async function generateFromConfig(config, reporter = {}) {
     }
   });
   reporter.onPhase?.("processing-spec");
-  const swaggerParser = await SwaggerParser.create(config.input, config);
+  const swaggerParser = await 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);
@@ -3645,7 +4684,7 @@ async function generateFromConfig(config, reporter = {}) {
   const typeGenerator = new TypeGenerator(swaggerParser, project, config, outputPath, onWarning);
   await typeGenerator.generate();
   reporter.onPhase?.("types-generated");
-  if (generateServices) {
+  if (generateServices || config.plugins?.length) {
     const tokenGenerator = new TokenGenerator(project, config.clientName);
     tokenGenerator.generate(outputPath);
     if (config.options.dateType === "Date") {
@@ -3660,6 +4699,8 @@ async function generateFromConfig(config, reporter = {}) {
     providerGenerator.generate(outputPath);
     const baseInterceptorGenerator = new BaseInterceptorGenerator(project, config.clientName);
     baseInterceptorGenerator.generate(outputPath);
+  }
+  if (generateServices) {
     const serviceGenerator = new ServiceGenerator(swaggerParser, project, config, onWarning);
     await serviceGenerator.generate(outputPath);
     const indexGenerator = new ServiceIndexGenerator(project, config.options.naming?.services);
@@ -3680,6 +4721,7 @@ async function generateFromConfig(config, reporter = {}) {
   }
   const mainIndexGenerator = new MainIndexGenerator(project, config);
   mainIndexGenerator.generateMainIndex(outputPath);
+  await project.save();
   return {
     client: config.clientName,
     filesWritten: project.getSourceFiles().map((sourceFile) => sourceFile.getFilePath()),
@@ -3689,6 +4731,43 @@ async function generateFromConfig(config, reporter = {}) {
 }
 __name(generateFromConfig, "generateFromConfig");
 
+// src/lib/core/config-loader.ts
+var fs3 = __toESM(require("fs"));
+var path14 = __toESM(require("path"));
+async function loadConfigFile(configPath) {
+  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");
+
 // src/lib/cli.ts
 var program = new import_commander.Command();
 function createConsoleReporter(config) {
@@ -3721,43 +4800,22 @@ async function runGeneration(config) {
   const inputType = isUrl(config.input) ? "URL" : "file";
   const sourceInfo = `from ${inputType}: ${config.input}`;
   const clientPrefix = result.client ? `${result.client} ` : "";
-  console.log(`\u{1F389} ${clientPrefix}Generation completed successfully ${sourceInfo} -> ${config.output}`);
+  const outcome = result.warnings.length === 0 ? "completed successfully" : `completed with ${countWarnings(result.warnings.length)}`;
+  console.log(`\u{1F389} ${clientPrefix}Generation ${outcome} ${sourceInfo} -> ${config.output}`);
+  return result.warnings.length;
 }
 __name(runGeneration, "runGeneration");
-async function loadConfigFile(configPath) {
-  const resolvedPath = path14.resolve(configPath);
-  if (!fs3.existsSync(resolvedPath)) {
-    throw new Error(`Configuration file not found: ${resolvedPath}`);
-  }
-  delete require.cache[require.resolve(resolvedPath)];
-  try {
-    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 Error('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) {
-    throw new Error(`Failed to load configuration file: ${error instanceof Error ? error.message : error}`);
-  }
+function countWarnings(count) {
+  return `${count} warning${count === 1 ? "" : "s"}`;
 }
-__name(loadConfigFile, "loadConfigFile");
+__name(countWarnings, "countWarnings");
 async function generateFromOptions(options) {
   const timestamp = (/* @__PURE__ */ new Date()).getTime();
+  let warningCount = 0;
   try {
     if (options.config) {
       const config = await loadConfigFile(options.config);
-      await runGeneration(config);
+      warningCount = await runGeneration(config);
     } else if (options.input) {
       const config = {
         input: options.input,
@@ -3771,16 +4829,30 @@ async function generateFromOptions(options) {
           generateServices: !options.typesOnly
         }
       };
-      await runGeneration(config);
+      warningCount = await runGeneration(config);
     } else {
       console.error("Error: Either --config or --input option is required");
       program.help({
         error: true
       });
     }
-    console.log("\u2728 Generation completed successfully!");
+    if (warningCount === 0) {
+      console.log("\u2728 Generation completed successfully!");
+    } else {
+      console.log(`\u2728 Generation completed with ${countWarnings(warningCount)} \u2014 see above; each describes spec content that was not generated as written.`);
+    }
   } catch (error) {
     console.error("\u274C Generation failed:", error instanceof Error ? error.message : error);
+    const MAX_CAUSES = 3;
+    let cause = error?.cause;
+    for (let depth = 0; cause !== void 0 && cause !== null; depth++) {
+      if (depth === MAX_CAUSES) {
+        console.error("   \u2026 further causes omitted");
+        break;
+      }
+      console.error("   caused by:", cause instanceof Error ? cause.message : cause);
+      cause = cause.cause;
+    }
     if (error instanceof SpecLoadError && isUrl(error.source)) {
       console.error("\u{1F4A1} Tip: Make sure the URL is accessible and returns a valid OpenAPI/Swagger specification");
       console.error("\u{1F4A1} Alternative: Download the specification file locally and use the file path instead");