swagger-digest 0.1.1 → 0.1.2

package/dist/{chunk-UZQM2SHL.js → chunk-CBSDTIKN.js}

@@ -1,6 +1,504 @@
+// src/version.ts
+import { createRequire } from "module";
+function readPackageVersion(moduleUrl) {
+  try {
+    const require2 = createRequire(moduleUrl);
+    const pkg = require2("../package.json");
+    if (typeof pkg?.version === "string" && pkg.version) return pkg.version;
+    return "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+var VERSION = readPackageVersion(import.meta.url);
+var USER_AGENT = `swagger-digest/${VERSION}`;
+
+// src/transformer/utils.ts
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function entries(value) {
+  return isObject(value) ? Object.entries(value) : [];
+}
+function cleanText(value) {
+  return typeof value === "string" ? value.trim().replace(/\s+/g, " ") : "";
+}
+function markdownCell(value) {
+  return cleanText(value).replace(/\|/g, "\\|").replace(/`/g, "\\`") || "\u2014";
+}
+function safeSourceUrl(value) {
+  try {
+    const url = new URL(value);
+    url.username = "";
+    url.password = "";
+    for (const key of [...url.searchParams.keys()]) {
+      if (/(token|secret|password|signature|credential|api[-_]?key|authorization|auth)/i.test(key)) {
+        url.searchParams.set(key, "[redacted]");
+      }
+    }
+    return url.toString();
+  } catch {
+    return value;
+  }
+}
+function safeComment(value) {
+  return cleanText(value).replace(/\*\//g, "* /").replace(/[\r\n]+/g, " ");
+}
+function propertyKey(value) {
+  return /^[$A-Z_a-z][$\w]*$/.test(value) ? value : JSON.stringify(value);
+}
+function toTypeScriptIdentifier(value) {
+  let identifier = value.replace(/[^\p{L}\p{N}_$]+/gu, "_").replace(/^([^\p{L}_$])/u, "_$1");
+  if (!identifier) identifier = "Unnamed";
+  const reserved = /* @__PURE__ */ new Set([
+    "abstract",
+    "any",
+    "as",
+    "asserts",
+    "async",
+    "await",
+    "boolean",
+    "break",
+    "case",
+    "catch",
+    "class",
+    "const",
+    "constructor",
+    "continue",
+    "debugger",
+    "declare",
+    "default",
+    "delete",
+    "do",
+    "else",
+    "enum",
+    "export",
+    "extends",
+    "false",
+    "finally",
+    "for",
+    "from",
+    "function",
+    "get",
+    "if",
+    "implements",
+    "import",
+    "in",
+    "infer",
+    "instanceof",
+    "interface",
+    "is",
+    "keyof",
+    "let",
+    "module",
+    "namespace",
+    "never",
+    "new",
+    "null",
+    "number",
+    "object",
+    "of",
+    "package",
+    "private",
+    "protected",
+    "public",
+    "readonly",
+    "require",
+    "return",
+    "set",
+    "static",
+    "string",
+    "super",
+    "switch",
+    "symbol",
+    "this",
+    "throw",
+    "true",
+    "try",
+    "type",
+    "typeof",
+    "undefined",
+    "unique",
+    "unknown",
+    "var",
+    "void",
+    "while",
+    "with",
+    "yield"
+  ]);
+  if (reserved.has(identifier)) identifier = `${identifier}Model`;
+  return identifier;
+}
+
 // src/fetcher.ts
 import { load } from "cheerio";
+import { parse as parseYaml2 } from "yaml";
+
+// src/errors.ts
+var FetchError = class extends Error {
+  kind;
+  constructor(kind, message) {
+    super(message);
+    this.name = "FetchError";
+    this.kind = kind;
+  }
+};
+var FetchSizeError = class extends FetchError {
+  constructor(message) {
+    super("size", message);
+    this.name = "FetchSizeError";
+  }
+};
+var BlockedNetworkError = class extends FetchError {
+  constructor(message) {
+    super("blocked", message);
+    this.name = "BlockedNetworkError";
+  }
+};
+var FetchNetworkError = class extends FetchError {
+  constructor(message) {
+    super("network", message);
+    this.name = "FetchNetworkError";
+  }
+};
+var FetchHttpError = class extends FetchError {
+  status;
+  constructor(message, status) {
+    super("http", message);
+    this.name = "FetchHttpError";
+    this.status = status;
+  }
+};
+function isFailFastFetchError(error) {
+  return error instanceof FetchError && (error.kind === "size" || error.kind === "blocked" || error.kind === "network");
+}
+
+// src/hardened-fetch.ts
+import { lookup } from "dns/promises";
+import { isIP } from "net";
+var DEFAULT_MAX_BYTES = 10 * 1024 * 1024;
+var DEFAULT_MAX_REDIRECTS = 5;
+var REDIRECT_STATUSES = /* @__PURE__ */ new Set([301, 302, 303, 307, 308]);
+function isPrivateAddress(address) {
+  const family = isIP(address);
+  if (family === 4) return isPrivateIPv4(address);
+  if (family === 6) {
+    const normalized = address.toLowerCase();
+    const mapped = normalized.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+    if (mapped?.[1]) return isPrivateIPv4(mapped[1]);
+    if (normalized === "::1" || normalized === "::") return true;
+    if (/^f[cd][0-9a-f]{2}(?::|$)/.test(normalized)) return true;
+    if (/^fe[89ab][0-9a-f](?::|$)/.test(normalized)) return true;
+    return false;
+  }
+  return true;
+}
+function isPrivateIPv4(address) {
+  const parts = address.split(".").map(Number);
+  if (parts.length !== 4 || parts.some((part) => Number.isNaN(part))) return true;
+  const [a, b] = parts;
+  if (a === 0) return true;
+  if (a === 10) return true;
+  if (a === 127) return true;
+  if (a === 169 && b === 254) return true;
+  if (a === 172 && b >= 16 && b <= 31) return true;
+  if (a === 192 && b === 168) return true;
+  return false;
+}
+async function assertPublicHost(hostname) {
+  if (isIP(hostname) !== 0) {
+    if (isPrivateAddress(hostname)) {
+      throw new BlockedNetworkError(
+        `Blocked request to private network address (host resolved to a loopback/private/metadata address). Enable this only for hosts you trust; use it against internal corporate APIs without this option.`
+      );
+    }
+    return;
+  }
+  let addresses;
+  try {
+    addresses = await lookup(hostname, { all: true, verbatim: true });
+  } catch (error) {
+    throw new FetchNetworkError(
+      `DNS resolution failed for ${hostname}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  if (!addresses.length) {
+    throw new FetchNetworkError(`DNS resolution returned no addresses for ${hostname}`);
+  }
+  for (const { address } of addresses) {
+    if (isPrivateAddress(address)) {
+      throw new BlockedNetworkError(
+        `Blocked request to ${hostname}: it resolves to a private/loopback/metadata address while blockPrivateNetworks is enabled.`
+      );
+    }
+  }
+}
+function normalizeHeaders(headers) {
+  return Object.fromEntries(Object.entries(headers ?? {}).map(([name, value]) => [name.toLowerCase(), value]));
+}
+async function fetchWithLimits(url, options) {
+  const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+  const maxRedirects = options.maxRedirects ?? DEFAULT_MAX_REDIRECTS;
+  const defaultHeaders = normalizeHeaders({
+    accept: "application/json, application/yaml, text/yaml, text/plain, text/html;q=0.8, */*;q=0.5",
+    "user-agent": USER_AGENT
+  });
+  const userHeaders = normalizeHeaders(options.headers ?? {});
+  return await follow(url, defaultHeaders, userHeaders, options, maxBytes, maxRedirects);
+}
+async function follow(url, defaultHeaders, userHeaders, options, maxBytes, redirectsLeft) {
+  let target;
+  try {
+    target = new URL(url);
+  } catch {
+    throw new FetchNetworkError(`Invalid URL: ${url}`);
+  }
+  if (target.protocol !== "http:" && target.protocol !== "https:") {
+    throw new FetchNetworkError(`Only HTTP and HTTPS URLs are supported: ${url}`);
+  }
+  if (options.blockPrivateNetworks) {
+    await assertPublicHost(target.hostname);
+  }
+  const sameOrigin = !options.allowedHeaderOrigin || !options.headers || target.origin === options.allowedHeaderOrigin;
+  if (!sameOrigin && options.allowedHeaderOrigin && options.headers && Object.keys(options.headers).length > 0) {
+    options.onCrossOriginHeadersDropped?.(target.origin);
+  }
+  const requestHeaders = sameOrigin ? { ...defaultHeaders, ...userHeaders } : defaultHeaders;
+  const controller = new AbortController();
+  const timeout = AbortSignal.timeout(options.timeoutMs);
+  timeout.addEventListener("abort", () => controller.abort(), { once: true });
+  let response;
+  try {
+    response = await fetch(target, {
+      headers: requestHeaders,
+      redirect: "manual",
+      signal: controller.signal
+    });
+  } catch (error) {
+    if (error instanceof FetchError) throw error;
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new FetchNetworkError(`Request to ${target} failed: ${describeNetworkError(reason)}`);
+  }
+  if (REDIRECT_STATUSES.has(response.status)) {
+    const location = response.headers.get("location");
+    if (!location) {
+      throw new FetchNetworkError(`Redirect response without a Location header from ${target}`);
+    }
+    if (redirectsLeft <= 0) {
+      throw new FetchNetworkError(`Too many redirects (limit ${options.maxRedirects ?? 5}) while fetching ${url}`);
+    }
+    try {
+      await response.arrayBuffer();
+    } catch {
+    }
+    const next = new URL(response.headers.get("location") ?? "", target);
+    return follow(next.toString(), defaultHeaders, userHeaders, options, maxBytes, redirectsLeft - 1);
+  }
+  if (!response.ok) {
+    await discardBodySafely(response);
+    throw new FetchHttpError(`HTTP ${response.status} ${response.statusText} for ${url}`, response.status);
+  }
+  const contentLength = response.headers.get("content-length");
+  if (contentLength !== null) {
+    const declared = Number(contentLength);
+    if (Number.isFinite(declared) && declared > maxBytes) {
+      await discardBodySafely(response);
+      throw new FetchSizeError(
+        `Response from ${target} is ${declared} bytes, exceeding the ${maxBytes} byte limit (content-length). Increase --max-bytes if the spec is genuinely large.`
+      );
+    }
+  }
+  const text = await readBodyWithCap(response, target.toString(), maxBytes);
+  return {
+    text,
+    contentType: response.headers.get("content-type") ?? "",
+    status: response.status,
+    url: target.toString()
+  };
+}
+function describeNetworkError(reason) {
+  if (/timeouterror|timed out|aborted/i.test(reason)) return "request timed out";
+  if (/enotfound|getaddrinfo/i.test(reason)) return "host not found (DNS)";
+  if (/econnrefused/i.test(reason)) return "connection refused";
+  return reason;
+}
+async function readBodyWithCap(response, url, maxBytes) {
+  const body = response.body;
+  if (!body) return "";
+  const chunks = [];
+  let total = 0;
+  try {
+    for await (const chunk of body) {
+      chunks.push(chunk);
+      total += chunk.byteLength;
+      if (total > maxBytes) {
+        try {
+          await body.cancel();
+        } catch {
+        }
+        throw new FetchSizeError(
+          `Response body from ${url} exceeded the ${maxBytes} byte limit while streaming (content-length was ${response.headers.get("content-length") ?? "not declared"}). Use --max-bytes to raise the cap if the spec is genuinely large.`
+        );
+      }
+    }
+  } catch (error) {
+    if (error instanceof FetchSizeError) throw error;
+    throw new FetchNetworkError(`Failed to read response body from ${url}: ${describeNetworkError(String(error))}`);
+  }
+  const decoder = new TextDecoder("utf-8");
+  const parts = [];
+  for (const chunk of chunks) parts.push(decoder.decode(chunk, { stream: true }));
+  parts.push(decoder.decode());
+  return parts.join("");
+}
+async function discardBodySafely(response) {
+  try {
+    await response.arrayBuffer();
+  } catch {
+  }
+}
+
+// src/bundler.ts
 import { parse as parseYaml } from "yaml";
+var MAX_EXTERNAL_DOCUMENTS = 5;
+async function bundleExternalRefs(spec, sourceUrl, fetchDocument) {
+  if (!sourceUrl) return spec;
+  const externalRefs = collectExternalRefs(spec);
+  if (externalRefs.size === 0) return spec;
+  const schemaBucket = openSchemaBucket(spec);
+  const usedNames = new Set(Object.keys(schemaBucket));
+  const mapping = /* @__PURE__ */ new Map();
+  let fetched = 0;
+  for (const ref of externalRefs) {
+    if (fetched >= MAX_EXTERNAL_DOCUMENTS) break;
+    const { docUrl, pointer } = splitExternalRef(ref, sourceUrl);
+    if (!docUrl) continue;
+    try {
+      const text = await fetchDocument(docUrl);
+      const parsed = parseDocumentText(text);
+      if (parsed === void 0) continue;
+      fetched += 1;
+      const target = resolvePointer(parsed, pointer);
+      if (target === void 0) continue;
+      const localName = uniqueNameFor(localNameFor(docUrl, pointer), usedNames);
+      schemaBucket[localName] = target;
+      mapping.set(ref, localName);
+    } catch {
+    }
+  }
+  if (mapping.size === 0) return spec;
+  const rewritten = rewriteRefs(spec, mapping);
+  return isObject(rewritten) ? rewritten : spec;
+}
+function collectExternalRefs(node) {
+  const found = /* @__PURE__ */ new Set();
+  const walk = (value) => {
+    if (Array.isArray(value)) {
+      for (const item of value) walk(item);
+      return;
+    }
+    if (!isObject(value)) return;
+    for (const [key, refValue] of Object.entries(value)) {
+      if (key === "$ref" && typeof refValue === "string" && !refValue.startsWith("#")) {
+        found.add(refValue);
+        continue;
+      }
+      if (key === "example" || key === "examples" || key === "externalDocs") continue;
+      walk(refValue);
+    }
+  };
+  walk(node);
+  return found;
+}
+function rewriteRefs(node, mapping) {
+  if (Array.isArray(node)) return node.map((item) => rewriteRefs(item, mapping));
+  if (!isObject(node)) return node;
+  const result = {};
+  for (const [key, value] of Object.entries(node)) {
+    if (key === "$ref" && typeof value === "string") {
+      const localName = mapping.get(value);
+      if (localName === void 0) {
+        result[key] = value;
+        continue;
+      }
+      result[key] = `#/${bucketPath(bucketStyle(value))}/${localName}`;
+      continue;
+    }
+    result[key] = rewriteRefs(value, mapping);
+  }
+  return result;
+}
+function bucketStyle(ref) {
+  return ref.includes("/components/") ? "openapi" : "swagger";
+}
+function bucketPath(style) {
+  return style === "openapi" ? "components/schemas" : "definitions";
+}
+function openSchemaBucket(spec) {
+  if (isObject(spec.components)) {
+    if (!isObject(spec.components.schemas)) spec.components.schemas = {};
+    return spec.components.schemas;
+  }
+  if (!isObject(spec.definitions)) spec.definitions = {};
+  return spec.definitions;
+}
+function splitExternalRef(ref, baseUrl) {
+  const hashIndex = ref.indexOf("#");
+  if (hashIndex < 0) return { docUrl: void 0, pointer: "" };
+  const docPart = ref.slice(0, hashIndex);
+  const pointer = ref.slice(hashIndex + 1);
+  try {
+    return { docUrl: new URL(docPart, baseUrl).toString(), pointer };
+  } catch {
+    return { docUrl: void 0, pointer };
+  }
+}
+function parseDocumentText(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    try {
+      return parseYaml(text);
+    } catch {
+      return void 0;
+    }
+  }
+}
+function resolvePointer(root, pointer) {
+  if (!pointer.startsWith("/")) return void 0;
+  let current = root;
+  for (const rawPart of pointer.slice(1).split("/")) {
+    const part = rawPart.replace(/~1/g, "/").replace(/~0/g, "~");
+    if (!isObject(current)) return void 0;
+    current = current[part];
+  }
+  return current;
+}
+function localNameFor(docUrl, pointer) {
+  try {
+    const url = new URL(docUrl);
+    const file = url.pathname.split("/").pop() ?? "external";
+    const stem = file.replace(/\.(json|ya?ml)$/i, "").replace(/[^A-Za-z0-9_$]+/g, "_") || "external";
+    const segments = pointer.split("/").filter(Boolean);
+    const pointerName = segments.length > 0 ? segments[segments.length - 1] : void 0;
+    const cleanedPointer = pointerName?.replace(/[^A-Za-z0-9_$]+/g, "_");
+    return [stem, cleanedPointer].filter(Boolean).join("_") || "external";
+  } catch {
+    return "external";
+  }
+}
+function uniqueNameFor(base, used) {
+  let candidate = base;
+  let suffix = 2;
+  while (used.has(candidate)) {
+    candidate = `${candidate}${suffix}`;
+    suffix += 1;
+  }
+  used.add(candidate);
+  return candidate;
+}
+
+// src/fetcher.ts
 var SPEC_FILE_EXTENSION = /\.(?:json|ya?ml)$/i;
 var FALLBACK_PATHS = ["/v3/api-docs", "/swagger/v1/swagger.json", "/swagger.json", "/openapi.json", "/api-docs"];
 function isRecord(value) {
@@ -14,7 +512,7 @@ function isOpenApiSpec(value) {
   return hasVersion && hasInfo && hasPaths;
 }
 function parseSpecText(text, source = "response") {
-  const parsers = [() => JSON.parse(text), () => parseYaml(text)];
+  const parsers = [() => JSON.parse(text), () => parseYaml2(text)];
   const errors = [];
   for (const parser of parsers) {
     try {
@@ -30,62 +528,164 @@ function parseSpecText(text, source = "response") {
 function isDirectSpecUrl(url) {
   return SPEC_FILE_EXTENSION.test(url.pathname);
 }
-async function fetchText(url, timeoutMs) {
-  const response = await fetch(url, {
-    headers: {
-      accept: "application/json, application/yaml, text/yaml, text/plain, text/html;q=0.8, */*;q=0.5",
-      "user-agent": "swagger-digest/0.1.0"
-    },
-    signal: AbortSignal.timeout(timeoutMs),
-    redirect: "follow"
+async function fetchText(url, ctx) {
+  const response = await fetchWithLimits(url, {
+    timeoutMs: ctx.timeoutMs,
+    maxBytes: ctx.maxBytes,
+    maxRedirects: ctx.maxRedirects,
+    blockPrivateNetworks: ctx.blockPrivateNetworks,
+    headers: ctx.headers,
+    allowedHeaderOrigin: ctx.allowedHeaderOrigin,
+    onCrossOriginHeadersDropped: ctx.onCrossOriginHeadersDropped
   });
-  if (!response.ok) {
-    throw new Error(`HTTP ${response.status} ${response.statusText} for ${url}`);
-  }
   return {
-    text: await response.text(),
-    contentType: response.headers.get("content-type") ?? ""
+    text: response.text,
+    contentType: response.contentType
   };
 }
 function extractScripts(html) {
   const $ = load(html);
   const inline = [];
   const external = [];
-  $("script").each((_index, element) => {
+  for (const element of $("script").toArray()) {
     const body = $(element).html();
     if (body?.trim()) inline.push(body);
     const src = $(element).attr("src");
     if (src?.trim()) external.push(src.trim());
-  });
+  }
   return { inline, external };
 }
 function extractSpecUrlFromScripts(scripts, pageUrl) {
-  const urlPattern = /\burl\s*:\s*(["'])(.*?)\1/s;
-  for (const script of scripts) {
-    const match = urlPattern.exec(script);
-    if (!match?.[2]) continue;
-    const candidate = match[2].trim();
-    if (!candidate || candidate.startsWith("data:")) continue;
+  return extractSpecUrlsFromScripts(scripts, pageUrl)[0];
+}
+function extractSpecUrlsFromScripts(scripts, pageUrl) {
+  const found = [];
+  const pushCandidate = (candidate) => {
+    const trimmed = candidate.trim();
+    if (!trimmed || trimmed.startsWith("data:")) return;
     try {
-      return new URL(candidate, pageUrl).toString();
+      const resolved = new URL(trimmed, pageUrl).toString();
+      if (!found.includes(resolved)) found.push(resolved);
     } catch {
     }
+  };
+  for (const script of scripts) {
+    const urlsArray = findObjectLiteralArrayAfterKey(script, "urls");
+    if (urlsArray) {
+      const entryPattern = /\burl\s*:\s*(["'])(.*?)\1/gs;
+      for (const match of urlsArray.matchAll(entryPattern)) {
+        pushCandidate(match[2] ?? "");
+      }
+    }
+    if (!urlsArray) {
+      const urlPattern = /\burl\s*:\s*(["'])(.*?)\1/s;
+      const match = urlPattern.exec(script);
+      if (match?.[2]) pushCandidate(match[2]);
+    }
+  }
+  return found;
+}
+function findObjectLiteralArrayAfterKey(source, key) {
+  const keyPattern = new RegExp(`\\b${key}\\s*:`);
+  const match = keyPattern.exec(source);
+  if (!match) return void 0;
+  let index = match.index + match[0].length;
+  while (/\s/.test(source[index] ?? "")) index += 1;
+  if (source[index] !== "[") return void 0;
+  const start = index;
+  let depth = 0;
+  let quote;
+  let escaped = false;
+  let lineComment = false;
+  let blockComment = false;
+  for (; index < source.length; index += 1) {
+    const char = source[index] ?? "";
+    const next = source[index + 1] ?? "";
+    if (lineComment) {
+      if (char === "\n") lineComment = false;
+      continue;
+    }
+    if (blockComment) {
+      if (char === "*" && next === "/") {
+        blockComment = false;
+        index += 1;
+      }
+      continue;
+    }
+    if (quote) {
+      if (escaped) {
+        escaped = false;
+      } else if (char === "\\") {
+        escaped = true;
+      } else if (char === quote) {
+        quote = void 0;
+      }
+      continue;
+    }
+    if (char === "/" && next === "/") {
+      lineComment = true;
+      index += 1;
+      continue;
+    }
+    if (char === "/" && next === "*") {
+      blockComment = true;
+      index += 1;
+      continue;
+    }
+    if (char === '"' || char === "'" || char === "`") {
+      quote = char;
+      continue;
+    }
+    if (char === "[") depth += 1;
+    if (char === "]") {
+      depth -= 1;
+      if (depth === 0) return source.slice(start, index + 1);
+    }
   }
   return void 0;
 }
-function extractSpecUrl(scripts, pageUrl) {
-  const fromScript = extractSpecUrlFromScripts(scripts, pageUrl);
-  if (fromScript) return fromScript;
+function extractSpecUrls(scripts, pageUrl) {
+  const fromScripts = extractSpecUrlsFromScripts(scripts, pageUrl);
   const queryUrl = pageUrl.searchParams.get("url");
   if (queryUrl) {
     try {
-      return new URL(queryUrl, pageUrl).toString();
+      const resolved = new URL(queryUrl, pageUrl).toString();
+      if (!fromScripts.includes(resolved)) fromScripts.push(resolved);
     } catch {
     }
   }
+  return fromScripts;
+}
+async function probeSpecUrls(candidates, ctx, recordFailure, onMultiple) {
+  if (candidates.length === 0) return void 0;
+  if (candidates.length > 1) {
+    onMultiple?.(candidates[0] ?? "", candidates);
+  }
+  const batchSize = 4;
+  for (let start = 0; start < candidates.length; start += batchSize) {
+    const batch = candidates.slice(start, start + batchSize);
+    const attempts = await Promise.all(
+      batch.map(async (candidate) => {
+        try {
+          return { candidate, spec: await tryFetchSpec(candidate, ctx) };
+        } catch (error) {
+          return { candidate, error };
+        }
+      })
+    );
+    const winner = attempts.find(
+      (attempt) => attempt.spec !== void 0
+    );
+    if (winner) {
+      return { spec: winner.spec, sourceUrl: winner.candidate, retrievalMethod: "html-config" };
+    }
+    for (const attempt of attempts) {
+      recordFailure("Configured spec", attempt.error, attempt.candidate);
+    }
+  }
   return void 0;
 }
-async function fetchExternalConfigScripts(srcs, pageUrl, timeoutMs, errors) {
+async function fetchExternalConfigScripts(srcs, pageUrl, ctx, errors) {
   const candidates = srcs.map((src) => {
     try {
       return new URL(src, pageUrl);
@@ -100,7 +700,7 @@ async function fetchExternalConfigScripts(srcs, pageUrl, timeoutMs, errors) {
   const scripts = [];
   for (const candidate of candidates.slice(0, 10)) {
     try {
-      const response = await fetchText(candidate.toString(), timeoutMs);
+      const response = await fetchText(candidate.toString(), ctx);
       scripts.push(response.text);
       if (extractSpecUrlFromScripts(scripts, pageUrl) || scripts.some((script) => findObjectLiteralAfterKey(script, "spec"))) {
         break;
@@ -195,7 +795,7 @@ function findObjectLiteralAfterKey(source, key) {
 function parseInlineObjectLiteral(literal) {
   const candidates = [
     () => JSON.parse(literal),
-    () => parseYaml(literal),
+    () => parseYaml2(literal),
     // Swagger config often uses JS object syntax with trailing commas.
     () => JSON.parse(literal.replace(/,\s*([}\]])/g, "$1"))
   ];
@@ -217,11 +817,26 @@ function extractInlineSpec(scripts) {
   }
   return void 0;
 }
-async function tryFetchSpec(url, timeoutMs) {
-  const response = await fetchText(url, timeoutMs);
-  return parseSpecText(response.text, url);
+async function tryFetchSpec(url, ctx) {
+  const response = await fetchText(url, ctx);
+  const parsed = parseSpecText(response.text, url);
+  try {
+    return await bundleExternalRefs(parsed, url, async (docUrl) => (await fetchText(docUrl, ctx)).text);
+  } catch {
+    return parsed;
+  }
+}
+function headersForBrowserRequest(requestUrl, headers, allowedOrigin) {
+  if (!headers || Object.keys(headers).length === 0) return void 0;
+  let requestOrigin;
+  try {
+    requestOrigin = new URL(requestUrl).origin;
+  } catch {
+    return void 0;
+  }
+  return requestOrigin === allowedOrigin ? headers : void 0;
 }
-async function tryBrowserFallback(pageUrl) {
+async function tryBrowserFallback(pageUrl, headers) {
   let playwright;
   try {
     const optionalModuleName = "playwright";
@@ -234,6 +849,20 @@ async function tryBrowserFallback(pageUrl) {
   const browser = await playwright.chromium.launch({ headless: true });
   try {
     const page = await browser.newPage();
+    const allowedOrigin = new URL(pageUrl).origin;
+    if (headers && Object.keys(headers).length > 0) {
+      const browserHeaders = Object.fromEntries(
+        Object.entries(headers).map(([name, value]) => [name.toLowerCase(), value])
+      );
+      await page.route("**/*", async (route) => {
+        const extra = headersForBrowserRequest(route.request().url(), browserHeaders, allowedOrigin);
+        if (!extra) {
+          await route.continue();
+          return;
+        }
+        await route.continue({ headers: { ...route.request().headers(), ...extra } });
+      });
+    }
     await page.goto(pageUrl, { waitUntil: "domcontentloaded", timeout: 3e4 });
     await page.waitForFunction(
       () => {
@@ -241,7 +870,8 @@ async function tryBrowserFallback(pageUrl) {
         try {
           const candidate = w.ui?.spec?.();
           const document = candidate && typeof candidate.toJSON === "function" ? candidate.toJSON() : candidate;
-          return Boolean(document?.openapi || document?.swagger || w.swaggerDoc?.openapi || w.swaggerDoc?.swagger);
+          const doc = document;
+          return Boolean(doc?.openapi || doc?.swagger || w.swaggerDoc?.openapi || w.swaggerDoc?.swagger);
         } catch {
           return Boolean(w.swaggerDoc?.openapi || w.swaggerDoc?.swagger);
         }
@@ -286,18 +916,42 @@ async function fetchOpenApiSpec(input, options = {}) {
     throw new Error("Only HTTP and HTTPS URLs are supported.");
   }
   const timeoutMs = options.timeoutMs ?? 15e3;
+  const ctx = {
+    timeoutMs,
+    maxBytes: options.maxBytes,
+    maxRedirects: options.maxRedirects,
+    blockPrivateNetworks: options.blockPrivateNetworks,
+    allowedHeaderOrigin: pageUrl.origin,
+    headers: options.headers,
+    onCrossOriginHeadersDropped: (origin) => options.warn?.(
+      `Custom headers were withheld: ${origin} is a different origin from the URL you supplied. Only tool defaults were sent.`
+    )
+  };
   const errors = [];
+  const recordFailure = (label, error, subject) => {
+    if (isFailFastFetchError(error)) throw error;
+    const prefix = subject ? `${label} (${subject}):` : `${label}:`;
+    errors.push(`${prefix} ${error instanceof Error ? error.message : String(error)}`);
+  };
   if (isDirectSpecUrl(pageUrl)) {
     try {
-      const spec = await tryFetchSpec(pageUrl.toString(), timeoutMs);
+      const spec = await tryFetchSpec(pageUrl.toString(), ctx);
       return { spec, sourceUrl: pageUrl.toString(), retrievalMethod: "direct-spec" };
     } catch (error) {
-      errors.push(`Direct spec: ${error instanceof Error ? error.message : String(error)}`);
+      recordFailure("Direct spec", error);
+    }
+  }
+  if (options.specUrl) {
+    try {
+      const spec = await tryFetchSpec(options.specUrl, ctx);
+      return { spec, sourceUrl: options.specUrl, retrievalMethod: "direct-spec" };
+    } catch (error) {
+      recordFailure("Specified spec (--spec)", error, options.specUrl);
     }
   }
   let html;
   try {
-    const response = await fetchText(pageUrl.toString(), timeoutMs);
+    const response = await fetchText(pageUrl.toString(), ctx);
     try {
       const spec = parseSpecText(response.text, pageUrl.toString());
       return { spec, sourceUrl: pageUrl.toString(), retrievalMethod: "direct-spec" };
@@ -305,35 +959,29 @@ async function fetchOpenApiSpec(input, options = {}) {
       html = response.text;
     }
   } catch (error) {
-    errors.push(`Swagger UI page: ${error instanceof Error ? error.message : String(error)}`);
+    recordFailure("Swagger UI page", error);
   }
   if (html !== void 0) {
     const pageScripts = extractScripts(html);
-    let scripts = pageScripts.inline;
-    let specUrl = extractSpecUrl(scripts, pageUrl);
+    const scripts = pageScripts.inline;
     const inlineSpec = extractInlineSpec(scripts);
     if (inlineSpec) {
       return { spec: inlineSpec, sourceUrl: pageUrl.toString(), retrievalMethod: "inline-spec" };
     }
-    if (specUrl) {
-      try {
-        const spec = await tryFetchSpec(specUrl, timeoutMs);
-        return { spec, sourceUrl: specUrl, retrievalMethod: "html-config" };
-      } catch (error) {
-        errors.push(`Configured spec (${specUrl}): ${error instanceof Error ? error.message : String(error)}`);
-      }
-    }
-    const externalScripts = await fetchExternalConfigScripts(pageScripts.external, pageUrl, timeoutMs, errors);
-    scripts = [...scripts, ...externalScripts];
-    specUrl = extractSpecUrl(scripts, pageUrl);
-    if (specUrl && specUrl !== pageUrl.searchParams.get("url")) {
-      try {
-        const spec = await tryFetchSpec(specUrl, timeoutMs);
-        return { spec, sourceUrl: specUrl, retrievalMethod: "html-config" };
-      } catch (error) {
-        errors.push(`Configured spec (${specUrl}): ${error instanceof Error ? error.message : String(error)}`);
+    const noteMultiple = (picked, all) => {
+      if (all.length > 1) {
+        options.warn?.(
+          `Multiple spec definitions found (${String(all.length)}); using ${picked}. Others: ${all.filter((url) => url !== picked).join(", ")}.`
+        );
       }
-    }
+    };
+    const fromInline = await probeSpecUrls(extractSpecUrls(scripts, pageUrl), ctx, recordFailure, noteMultiple);
+    if (fromInline) return fromInline;
+    const externalScripts = await fetchExternalConfigScripts(pageScripts.external, pageUrl, ctx, errors);
+    const inlineUrls = extractSpecUrls(scripts, pageUrl);
+    const externalUrls = extractSpecUrls(externalScripts, pageUrl).filter((url) => !inlineUrls.includes(url));
+    const fromExternal = await probeSpecUrls([...inlineUrls, ...externalUrls], ctx, recordFailure, noteMultiple);
+    if (fromExternal) return fromExternal;
     for (const script of scripts) {
       const literal = findObjectLiteralAfterKey(script, "spec");
       if (!literal) continue;
@@ -341,17 +989,33 @@ async function fetchOpenApiSpec(input, options = {}) {
       if (spec) return { spec, sourceUrl: pageUrl.toString(), retrievalMethod: "inline-spec" };
     }
   }
-  for (const candidate of getFallbackUrls(pageUrl)) {
-    try {
-      const spec = await tryFetchSpec(candidate, timeoutMs);
-      return { spec, sourceUrl: candidate, retrievalMethod: "fallback-path" };
-    } catch (error) {
-      errors.push(`${candidate}: ${error instanceof Error ? error.message : String(error)}`);
+  const probeCtx = { ...ctx, timeoutMs: options.probeTimeoutMs ?? 5e3 };
+  const candidates = getFallbackUrls(pageUrl);
+  const probeBatchSize = 4;
+  for (let start = 0; start < candidates.length; start += probeBatchSize) {
+    const batch = candidates.slice(start, start + probeBatchSize);
+    const attempts = await Promise.all(
+      batch.map(async (candidate) => {
+        try {
+          return { candidate, spec: await tryFetchSpec(candidate, probeCtx) };
+        } catch (error) {
+          return { candidate, error };
+        }
+      })
+    );
+    const winner = attempts.find(
+      (attempt) => attempt.spec !== void 0
+    );
+    if (winner) {
+      return { spec: winner.spec, sourceUrl: winner.candidate, retrievalMethod: "fallback-path" };
+    }
+    for (const attempt of attempts) {
+      recordFailure(attempt.candidate, attempt.error);
     }
   }
   if (options.useBrowserFallback !== false) {
     try {
-      const spec = await tryBrowserFallback(pageUrl.toString());
+      const spec = await tryBrowserFallback(pageUrl.toString(), ctx.headers);
       return { spec, sourceUrl: pageUrl.toString(), retrievalMethod: "headless-browser" };
     } catch (error) {
       errors.push(`Headless browser: ${error instanceof Error ? error.message : String(error)}`);
@@ -366,171 +1030,147 @@ Check that the URL is reachable from this terminal and points to a Swagger UI pa
   );
 }
 
-// src/transformer.ts
-var HTTP_METHODS = ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
-var COMMON_ERROR_CODES = /* @__PURE__ */ new Set([
-  "400",
-  "401",
-  "403",
-  "404",
-  "405",
-  "409",
-  "415",
-  "422",
-  "429",
-  "500",
-  "501",
-  "502",
-  "503",
-  "default"
-]);
-function isObject(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-function entries(value) {
-  return isObject(value) ? Object.entries(value) : [];
-}
-function cleanText(value) {
-  return typeof value === "string" ? value.trim().replace(/\s+/g, " ") : "";
-}
-function markdownCell(value) {
-  return cleanText(value).replace(/\|/g, "\\|").replace(/`/g, "\\`") || "\u2014";
-}
-function safeSourceUrl(value) {
-  try {
-    const url = new URL(value);
-    url.username = "";
-    url.password = "";
-    for (const key of [...url.searchParams.keys()]) {
-      if (/(token|secret|password|signature|credential|api[-_]?key|authorization|auth)/i.test(key)) {
-        url.searchParams.set(key, "[redacted]");
+// src/tokens.ts
+var MODEL_CONFIGS = {
+  claude: { name: "Claude (Sonnet / Opus)", contextWindow: 2e5, ratio: 1.08 },
+  openai: { name: "OpenAI (GPT-4o / o-series)", contextWindow: 128e3, ratio: 0.95 },
+  gemini: { name: "Google Gemini (Pro / Flash)", contextWindow: 1e6, ratio: 0.9 },
+  deepseek: { name: "DeepSeek (V3 / R1)", contextWindow: 128e3, ratio: 0.97 },
+  llama: { name: "Meta Llama (3.3 / 4)", contextWindow: 128e3, ratio: 0.98 }
+};
+function estimateTokens(text) {
+  const characters = text.length;
+  if (characters === 0) {
+    const zeroModel = ({ name, contextWindow }) => ({
+      name,
+      tokens: 0,
+      contextWindow,
+      contextPercent: 0
+    });
+    return {
+      characters: 0,
+      models: {
+        claude: zeroModel(MODEL_CONFIGS.claude),
+        openai: zeroModel(MODEL_CONFIGS.openai),
+        gemini: zeroModel(MODEL_CONFIGS.gemini),
+        deepseek: zeroModel(MODEL_CONFIGS.deepseek),
+        llama: zeroModel(MODEL_CONFIGS.llama)
       }
-    }
-    return url.toString();
-  } catch {
-    return value;
+    };
   }
+  const wordCount = (text.match(/\b[\w$]+\b/gu) || []).length;
+  const syntaxSymbols = (text.match(/[{}[\]()<>=:;,."`|/-]/g) || []).length;
+  const whitespaces = (text.match(/\s+/g) || []).length;
+  const baseTokens = wordCount * 1.18 + syntaxSymbols * 0.42 + whitespaces * 0.05;
+  const calculate = (name, ratio, contextWindow) => {
+    const tokens = Math.max(1, Math.round(baseTokens * ratio));
+    const contextPercent = Number((tokens / contextWindow * 100).toFixed(1));
+    return { name, tokens, contextWindow, contextPercent };
+  };
+  return {
+    characters,
+    models: {
+      claude: calculate(MODEL_CONFIGS.claude.name, MODEL_CONFIGS.claude.ratio, MODEL_CONFIGS.claude.contextWindow),
+      openai: calculate(MODEL_CONFIGS.openai.name, MODEL_CONFIGS.openai.ratio, MODEL_CONFIGS.openai.contextWindow),
+      gemini: calculate(MODEL_CONFIGS.gemini.name, MODEL_CONFIGS.gemini.ratio, MODEL_CONFIGS.gemini.contextWindow),
+      deepseek: calculate(
+        MODEL_CONFIGS.deepseek.name,
+        MODEL_CONFIGS.deepseek.ratio,
+        MODEL_CONFIGS.deepseek.contextWindow
+      ),
+      llama: calculate(MODEL_CONFIGS.llama.name, MODEL_CONFIGS.llama.ratio, MODEL_CONFIGS.llama.contextWindow)
+    }
+  };
 }
-function safeComment(value) {
-  return cleanText(value).replace(/\*\//g, "* /").replace(/[\r\n]+/g, " ");
+
+// src/transformer/security.ts
+function describeSecurityScheme(name, scheme) {
+  const type = cleanText(scheme.type).toLowerCase();
+  const label = cleanText(scheme.description);
+  let details = name;
+  if (type === "http" && cleanText(scheme.scheme).toLowerCase() === "bearer")
+    details += " (Bearer token via Authorization header)";
+  else if (type === "http" && cleanText(scheme.scheme).toLowerCase() === "basic")
+    details += " (HTTP Basic via Authorization header)";
+  else if (type === "apikey" || type === "apiKey")
+    details += ` (API key in ${cleanText(scheme.in) || "header"}: ${cleanText(scheme.name) || "key"})`;
+  else if (type === "oauth2") {
+    const flows = entries(scheme.flows).map(([flowName]) => flowName).join(", ") || cleanText(scheme.flow);
+    details += ` (OAuth2${flows ? `; ${flows}` : ""})`;
+  } else if (type === "openidconnect" || type === "openIdConnect") details += " (OpenID Connect)";
+  else if (type === "basic") details += " (HTTP Basic)";
+  else if (type) details += ` (${type})`;
+  if (label) details += ` \u2014 ${label}`;
+  return details;
 }
-function schemaMetadata(schemaValue) {
-  if (!isObject(schemaValue)) return [];
-  const schema = schemaValue;
-  const metadata = [];
-  if (cleanText(schema.description)) metadata.push(cleanText(schema.description));
-  if (cleanText(schema.format)) metadata.push(`format: ${cleanText(schema.format)}`);
-  const constraints = [
-    ["default", "default"],
-    ["pattern", "pattern"],
-    ["minLength", "minLength"],
-    ["maxLength", "maxLength"],
-    ["minimum", "minimum"],
-    ["maximum", "maximum"],
-    ["exclusiveMinimum", "exclusiveMinimum"],
-    ["exclusiveMaximum", "exclusiveMaximum"],
-    ["minItems", "minItems"],
-    ["maxItems", "maxItems"],
-    ["uniqueItems", "uniqueItems"],
-    ["multipleOf", "multipleOf"]
-  ];
-  for (const [property, label] of constraints) {
-    const value = schema[property];
-    if (value === void 0) continue;
-    if (property === "default" && (value === null || value === "")) continue;
-    metadata.push(
-      `${label}: ${property === "default" ? JSON.stringify(value) : typeof value === "string" ? value : JSON.stringify(value)}`
-    );
-  }
-  if (schema.readOnly === true) metadata.push("read-only");
-  if (schema.writeOnly === true) metadata.push("write-only");
-  if (schema.deprecated === true) metadata.push("deprecated");
-  return [...new Set(metadata)];
+function getSecuritySchemes(spec) {
+  const dictionary = spec.components?.securitySchemes ?? spec.securityDefinitions ?? {};
+  return entries(dictionary).filter((entry) => isObject(entry[1]));
 }
-function toTypeScriptIdentifier(value) {
-  let identifier = value.replace(/[^\p{L}\p{N}_$]+/gu, "_").replace(/^([^\p{L}_$])/u, "_$1");
-  if (!identifier) identifier = "Unnamed";
-  const reserved = /* @__PURE__ */ new Set([
-    "abstract",
-    "any",
-    "as",
-    "asserts",
-    "async",
-    "await",
-    "boolean",
-    "break",
-    "case",
-    "catch",
-    "class",
-    "const",
-    "constructor",
-    "continue",
-    "debugger",
-    "declare",
-    "default",
-    "delete",
-    "do",
-    "else",
-    "enum",
-    "export",
-    "extends",
-    "false",
-    "finally",
-    "for",
-    "from",
-    "function",
-    "get",
-    "if",
-    "implements",
-    "import",
-    "in",
-    "infer",
-    "instanceof",
-    "interface",
-    "is",
-    "keyof",
-    "let",
-    "module",
-    "namespace",
-    "never",
-    "new",
-    "null",
-    "number",
-    "object",
-    "of",
-    "package",
-    "private",
-    "protected",
-    "public",
-    "readonly",
-    "require",
-    "return",
-    "set",
-    "static",
-    "string",
-    "super",
-    "switch",
-    "symbol",
-    "this",
-    "throw",
-    "true",
-    "try",
-    "type",
-    "typeof",
-    "undefined",
-    "unique",
-    "unknown",
-    "var",
-    "void",
-    "while",
-    "with",
-    "yield"
-  ]);
-  if (reserved.has(identifier)) identifier = `${identifier}Model`;
-  return identifier;
+function securityRequirement(spec, operation) {
+  const security = operation.security !== void 0 ? operation.security : spec.security;
+  if (!Array.isArray(security) || security.length === 0) return "None explicitly required";
+  const allSchemes = new Map(getSecuritySchemes(spec));
+  return security.map((requirement) => {
+    if (!isObject(requirement)) return "";
+    const names = Object.entries(requirement).map(([name, scopes]) => {
+      const label = allSchemes.has(name) ? name : `${name} (scheme not defined)`;
+      return Array.isArray(scopes) && scopes.length ? `${label} [scopes: ${scopes.join(", ")}]` : label;
+    });
+    return names.length ? names.join(" + ") : "No auth";
+  }).filter(Boolean).join(" OR ");
+}
+function authOverview(spec) {
+  const schemes = getSecuritySchemes(spec);
+  if (!schemes.length) return ["- **Authentication:** No security schemes declared."];
+  const globalSecurity = securityRequirement(spec, {});
+  return [
+    `- **Authentication required globally:** ${globalSecurity}`,
+    "- **Available schemes:**",
+    ...schemes.map(([name, scheme]) => `  - ${describeSecurityScheme(name, scheme)}`)
+  ];
 }
-function propertyKey(value) {
-  return /^[$A-Z_a-z][$\w]*$/.test(value) ? value : JSON.stringify(value);
+
+// src/transformer/render-style.ts
+var FULL_STYLE = { includeExamples: true, collapsed: false };
+function shortenDescription(text, limit) {
+  if (limit === void 0 || text.length <= limit) return text;
+  return `${text.slice(0, limit).trimEnd()}\u2026`;
+}
+
+// src/transformer/schema-type.ts
+function schemaMetadata(schemaValue) {
+  if (!isObject(schemaValue)) return [];
+  const schema = schemaValue;
+  const metadata = [];
+  if (cleanText(schema.description)) metadata.push(cleanText(schema.description));
+  if (cleanText(schema.format)) metadata.push(`format: ${cleanText(schema.format)}`);
+  const constraints = [
+    ["default", "default"],
+    ["pattern", "pattern"],
+    ["minLength", "minLength"],
+    ["maxLength", "maxLength"],
+    ["minimum", "minimum"],
+    ["maximum", "maximum"],
+    ["exclusiveMinimum", "exclusiveMinimum"],
+    ["exclusiveMaximum", "exclusiveMaximum"],
+    ["minItems", "minItems"],
+    ["maxItems", "maxItems"],
+    ["uniqueItems", "uniqueItems"],
+    ["multipleOf", "multipleOf"]
+  ];
+  for (const [property, label] of constraints) {
+    const value = schema[property];
+    if (value === void 0) continue;
+    if (property === "default" && (value === null || value === "")) continue;
+    metadata.push(
+      `${label}: ${property === "default" ? JSON.stringify(value) : typeof value === "string" ? value : JSON.stringify(value)}`
+    );
+  }
+  if (schema.readOnly === true) metadata.push("read-only");
+  if (schema.writeOnly === true) metadata.push("write-only");
+  if (schema.deprecated === true) metadata.push("deprecated");
+  return [...new Set(metadata)];
 }
 function refName(ref) {
   const parts = ref.split("/");
@@ -635,80 +1275,7 @@ function getSchemaDictionary(spec) {
   const schemas = spec.components?.schemas ?? spec.definitions ?? {};
   return isObject(schemas) ? schemas : {};
 }
-function collectSchemaRefs(value, output, root, seen = /* @__PURE__ */ new Set(), followedRefs = /* @__PURE__ */ new Set()) {
-  if (!value || typeof value !== "object" || seen.has(value)) return;
-  seen.add(value);
-  if (Array.isArray(value)) {
-    for (const item of value) collectSchemaRefs(item, output, root, seen, followedRefs);
-    return;
-  }
-  const object = value;
-  if (typeof object.$ref === "string") {
-    if (isSchemaRef(object.$ref)) {
-      const name = refName(object.$ref);
-      if (name) output.add(name);
-    } else if (root && object.$ref.startsWith("#/") && !followedRefs.has(object.$ref)) {
-      followedRefs.add(object.$ref);
-      const target = resolvePointer(root, object.$ref);
-      if (target !== void 0) collectSchemaRefs(target, output, root, seen, followedRefs);
-    }
-  }
-  for (const [key, child] of Object.entries(object)) {
-    if (key !== "example" && key !== "examples" && key !== "externalDocs")
-      collectSchemaRefs(child, output, root, seen, followedRefs);
-  }
-}
-function referencedSchemas(spec) {
-  const dictionary = getSchemaDictionary(spec);
-  const knownByName = /* @__PURE__ */ new Map();
-  for (const [name, schema] of Object.entries(dictionary)) {
-    knownByName.set(toTypeScriptIdentifier(name), [name, schema]);
-  }
-  const refs = /* @__PURE__ */ new Set();
-  collectSchemaRefs(spec.paths ?? {}, refs, spec);
-  const selected = /* @__PURE__ */ new Set();
-  const queue = [...refs];
-  while (queue.length) {
-    const name = queue.shift();
-    if (!name || selected.has(name)) continue;
-    selected.add(name);
-    const model = knownByName.get(name);
-    if (!model) continue;
-    const childRefs = /* @__PURE__ */ new Set();
-    collectSchemaRefs(model[1], childRefs, spec);
-    for (const child of childRefs) if (!selected.has(child)) queue.push(child);
-  }
-  return [...selected].map((name) => knownByName.get(name)).filter((entry) => Boolean(entry));
-}
-function modelDeclaration(name, schema) {
-  const identifier = toTypeScriptIdentifier(name);
-  const description = safeComment(schema.description);
-  const comment = description ? `/** ${description} */
-` : "";
-  if (schema.$ref) return `${comment}export type ${identifier} = ${typeExpression(schema)};`;
-  if (Array.isArray(schema.enum) || schema.const !== void 0 || schema.oneOf || schema.anyOf || schema.allOf) {
-    return `${comment}export type ${identifier} = ${typeExpression(schema)};`;
-  }
-  const kind = Array.isArray(schema.type) ? schema.type.find((item) => item !== "null") : schema.type;
-  if (kind === "object" || schema.properties || schema.additionalProperties !== void 0) {
-    const properties = entries(schema.properties);
-    const required = new Set(Array.isArray(schema.required) ? schema.required : []);
-    const fields = properties.map(([field, value]) => {
-      const metadata = schemaMetadata(value).map(safeComment).filter(Boolean).join("; ");
-      const doc = metadata ? `    /** ${metadata} */
-` : "";
-      return `${doc}    ${propertyKey(field)}${required.has(field) ? "" : "?"}: ${typeExpression(value)};`;
-    });
-    if (schema.additionalProperties === true) fields.push("    [key: string]: unknown;");
-    else if (isObject(schema.additionalProperties))
-      fields.push(`    [key: string]: ${typeExpression(schema.additionalProperties)};`);
-    return `${comment}export interface ${identifier} {
-${fields.join("\n")}
-}`;
-  }
-  return `${comment}export type ${identifier} = ${typeExpression(schema)};`;
-}
-function resolvePointer(root, ref) {
+function resolvePointer2(root, ref) {
   if (!ref.startsWith("#/")) return void 0;
   let current = root;
   for (const rawPart of ref.slice(2).split("/")) {
@@ -723,7 +1290,7 @@ function resolveReferenceObject(spec, value, seen = /* @__PURE__ */ new Set()) {
   if (typeof value.$ref !== "string") return value;
   const ref = value.$ref;
   if (seen.has(ref)) return {};
-  const target = resolvePointer(spec, ref);
+  const target = resolvePointer2(spec, ref);
   if (!isObject(target)) return value;
   const nextSeen = new Set(seen).add(ref);
   return {
@@ -731,112 +1298,8 @@ function resolveReferenceObject(spec, value, seen = /* @__PURE__ */ new Set()) {
     ...Object.fromEntries(Object.entries(value).filter(([key]) => key !== "$ref"))
   };
 }
-function getEndpoints(spec) {
-  const result = [];
-  const paths = isObject(spec.paths) ? spec.paths : {};
-  for (const [path2, pathItemValue] of Object.entries(paths)) {
-    if (!isObject(pathItemValue)) continue;
-    const pathParameters = Array.isArray(pathItemValue.parameters) ? pathItemValue.parameters.map((parameter) => resolveReferenceObject(spec, parameter)) : [];
-    for (const method of HTTP_METHODS) {
-      const operationValue = pathItemValue[method];
-      if (!isObject(operationValue)) continue;
-      const firstTag = Array.isArray(operationValue.tags) && operationValue.tags.length ? String(operationValue.tags[0]) : "General";
-      result.push({ method, path: path2, operation: operationValue, pathParameters, tag: firstTag });
-    }
-  }
-  return result;
-}
-function getServers(spec) {
-  if (Array.isArray(spec.servers) && spec.servers.length) {
-    return spec.servers.map((server) => cleanText(server?.url)).filter(Boolean);
-  }
-  if (isObject(spec)) {
-    const host = cleanText(spec.host);
-    if (host) {
-      const schemes = Array.isArray(spec.schemes) && spec.schemes.length ? spec.schemes : ["https"];
-      const basePath = cleanText(spec.basePath) || "/";
-      return schemes.map(
-        (scheme) => `${scheme}://${host}${basePath.startsWith("/") ? basePath : `/${basePath}`}`
-      );
-    }
-  }
-  return [];
-}
-function describeSecurityScheme(name, scheme) {
-  const type = cleanText(scheme.type).toLowerCase();
-  const label = cleanText(scheme.description);
-  let details = name;
-  if (type === "http" && cleanText(scheme.scheme).toLowerCase() === "bearer")
-    details += " (Bearer token via Authorization header)";
-  else if (type === "http" && cleanText(scheme.scheme).toLowerCase() === "basic")
-    details += " (HTTP Basic via Authorization header)";
-  else if (type === "apikey" || type === "apiKey")
-    details += ` (API key in ${cleanText(scheme.in) || "header"}: ${cleanText(scheme.name) || "key"})`;
-  else if (type === "oauth2") {
-    const flows = entries(scheme.flows).map(([flowName]) => flowName).join(", ") || cleanText(scheme.flow);
-    details += ` (OAuth2${flows ? `; ${flows}` : ""})`;
-  } else if (type === "openidconnect" || type === "openIdConnect") details += " (OpenID Connect)";
-  else if (type === "basic") details += " (HTTP Basic)";
-  else if (type) details += ` (${type})`;
-  if (label) details += ` \u2014 ${label}`;
-  return details;
-}
-function getSecuritySchemes(spec) {
-  const dictionary = spec.components?.securitySchemes ?? spec.securityDefinitions ?? {};
-  return entries(dictionary).filter((entry) => isObject(entry[1]));
-}
-function securityRequirement(spec, operation) {
-  const security = operation.security !== void 0 ? operation.security : spec.security;
-  if (!Array.isArray(security) || security.length === 0) return "None explicitly required";
-  const allSchemes = new Map(getSecuritySchemes(spec));
-  return security.map((requirement) => {
-    if (!isObject(requirement)) return "";
-    const names = Object.entries(requirement).map(([name, scopes]) => {
-      const label = allSchemes.has(name) ? name : `${name} (scheme not defined)`;
-      return Array.isArray(scopes) && scopes.length ? `${label} [scopes: ${scopes.join(", ")}]` : label;
-    });
-    return names.length ? names.join(" + ") : "No auth";
-  }).filter(Boolean).join(" OR ");
-}
-function mergedParameters(spec, endpoint) {
-  const operationParameters = Array.isArray(endpoint.operation.parameters) ? endpoint.operation.parameters.map((parameter) => resolveReferenceObject(spec, parameter)) : [];
-  const byIdentity = /* @__PURE__ */ new Map();
-  for (const parameter of [...endpoint.pathParameters, ...operationParameters]) {
-    if (parameter.in === "body") continue;
-    const key = `${cleanText(parameter.in)}:${cleanText(parameter.name)}`;
-    if (key !== ":") byIdentity.set(key, parameter);
-  }
-  return [...byIdentity.values()];
-}
-function parameterType(parameter) {
-  if (isObject(parameter.schema)) return typeExpression(parameter.schema);
-  if (parameter.type === "array") return `${typeExpression(parameter.items)}[]`;
-  if (parameter.type) return typeExpression({ type: parameter.type, format: parameter.format, enum: parameter.enum });
-  return "unknown";
-}
-function parameterDisplayType(parameter) {
-  return parameterType(parameter).replace(/\/\*\s*([^*]+?)\s*\*\//g, "($1)");
-}
-function parameterDefault(parameter) {
-  if (parameter.default !== void 0) return parameter.default;
-  if (isObject(parameter.schema)) return parameter.schema.default;
-  return void 0;
-}
-function isMeaningfulDefault(value) {
-  return value !== void 0 && value !== null && value !== "";
-}
-function parameterList(parameters) {
-  if (!parameters.length) return "_None._";
-  return parameters.map((parameter) => {
-    const required = parameter.required === true || parameter.in === "path";
-    const type = parameterDisplayType(parameter);
-    const defaultValue = parameterDefault(parameter);
-    const defaultSuffix = isMeaningfulDefault(defaultValue) ? ` (default: ${typeof defaultValue === "string" ? JSON.stringify(defaultValue) : String(defaultValue)})` : "";
-    const description = cleanText(parameter.description);
-    const details = description ? ` \u2014 ${description}` : "";
-    return `- \`${cleanText(parameter.name)}\` (\`${cleanText(parameter.in)}\`${required ? ", required" : ""}) \xB7 \`${type}\`${defaultSuffix}${details}`;
-  }).join("\n");
-}
+
+// src/transformer/examples.ts
 function chooseMediaType(content) {
   const mediaTypes = Object.keys(content);
   return mediaTypes.find((type) => type.toLowerCase() === "application/json") ?? mediaTypes.find((type) => type.toLowerCase().includes("+json")) ?? mediaTypes[0];
@@ -849,7 +1312,7 @@ function firstDeclaredExample(spec, schemaValue, seen = /* @__PURE__ */ new Set(
   let schema = schemaValue;
   if (typeof schema.$ref === "string") {
     if (seen.has(schema.$ref)) return void 0;
-    const target = resolvePointer(spec, schema.$ref);
+    const target = resolvePointer2(spec, schema.$ref);
     if (!isObject(target)) return void 0;
     const nextSeen = new Set(seen).add(schema.$ref);
     schema = { ...target, ...Object.fromEntries(Object.entries(schema).filter(([key]) => key !== "$ref")) };
@@ -866,7 +1329,7 @@ function generateSchemaExample(spec, schemaValue, depth = 0, seenRefs = /* @__PU
   let nextSeen = seenRefs;
   if (typeof schema.$ref === "string") {
     if (seenRefs.has(schema.$ref)) return null;
-    const target = resolvePointer(spec, schema.$ref);
+    const target = resolvePointer2(spec, schema.$ref);
     if (!isObject(target)) return void 0;
     nextSeen = new Set(seenRefs).add(schema.$ref);
     schema = { ...target, ...Object.fromEntries(Object.entries(schema).filter(([key]) => key !== "$ref")) };
@@ -946,25 +1409,76 @@ function generateSchemaExample(spec, schemaValue, depth = 0, seenRefs = /* @__PU
   if (schema.properties || schema.additionalProperties !== void 0) return {};
   return void 0;
 }
-function payloadExample(spec, mediaValue, schemaValue, legacyExamples) {
-  const media = isObject(mediaValue) ? mediaValue : {};
-  if (hasOwn(media, "example")) return { value: media.example, origin: "declared" };
-  for (const [name, exampleValue] of entries(media.examples)) {
-    const example = resolveReferenceObject(spec, exampleValue);
-    if (hasOwn(example, "value")) return { value: example.value, origin: "declared", name };
-  }
-  if (isObject(legacyExamples)) {
-    const mediaType = Object.keys(legacyExamples).find((key) => key.toLowerCase() === "application/json") ?? Object.keys(legacyExamples)[0];
-    if (mediaType && hasOwn(legacyExamples, mediaType)) {
-      return { value: legacyExamples[mediaType], origin: "declared" };
-    }
+function payloadExample(spec, mediaValue, schemaValue, legacyExamples) {
+  const media = isObject(mediaValue) ? mediaValue : {};
+  if (hasOwn(media, "example")) return { value: media.example, origin: "declared" };
+  for (const [name, exampleValue] of entries(media.examples)) {
+    const example = resolveReferenceObject(spec, exampleValue);
+    if (hasOwn(example, "value")) return { value: example.value, origin: "declared", name };
+  }
+  if (isObject(legacyExamples)) {
+    const mediaType = Object.keys(legacyExamples).find((key) => key.toLowerCase() === "application/json") ?? Object.keys(legacyExamples)[0];
+    if (mediaType && hasOwn(legacyExamples, mediaType)) {
+      return { value: legacyExamples[mediaType], origin: "declared" };
+    }
+  }
+  const declaredSchemaExample = firstDeclaredExample(spec, schemaValue);
+  if (declaredSchemaExample !== void 0) return { value: declaredSchemaExample, origin: "declared" };
+  const generated = generateSchemaExample(spec, schemaValue);
+  return generated === void 0 ? void 0 : { value: generated, origin: "schema-derived" };
+}
+function formattedExample(value) {
+  try {
+    return JSON.stringify(value, null, 2) ?? "null";
+  } catch {
+    return "null";
+  }
+}
+
+// src/transformer/parameters.ts
+function mergedParameters(spec, endpoint) {
+  const operationParameters = Array.isArray(endpoint.operation.parameters) ? endpoint.operation.parameters.map((parameter) => resolveReferenceObject(spec, parameter)) : [];
+  const byIdentity = /* @__PURE__ */ new Map();
+  for (const parameter of [...endpoint.pathParameters, ...operationParameters]) {
+    if (parameter.in === "body") continue;
+    const key = `${cleanText(parameter.in)}:${cleanText(parameter.name)}`;
+    if (key !== ":") byIdentity.set(key, parameter);
+  }
+  return [...byIdentity.values()];
+}
+function parameterType(parameter) {
+  if (isObject(parameter.schema)) return typeExpression(parameter.schema);
+  if (parameter.type === "array") return `${typeExpression(parameter.items)}[]`;
+  if (parameter.type) return typeExpression({ type: parameter.type, format: parameter.format, enum: parameter.enum });
+  return "unknown";
+}
+function parameterDisplayType(parameter) {
+  return parameterType(parameter).replace(/\/\*\s*([^*]+?)\s*\*\//g, "($1)");
+}
+function parameterDefault(parameter) {
+  if (parameter.default !== void 0) return parameter.default;
+  if (isObject(parameter.schema)) return parameter.schema.default;
+  return void 0;
+}
+function isMeaningfulDefault(value) {
+  return value !== void 0 && value !== null && value !== "";
+}
+function parameterList(parameters, style = FULL_STYLE) {
+  if (!parameters.length) return "_None._";
+  if (style.collapsed) {
+    return `- _${parameters.length} parameter${parameters.length === 1 ? "" : "s"} (detail collapsed for token budget)._`;
   }
-  const declaredSchemaExample = firstDeclaredExample(spec, schemaValue);
-  if (declaredSchemaExample !== void 0) return { value: declaredSchemaExample, origin: "declared" };
-  const generated = generateSchemaExample(spec, schemaValue);
-  return generated === void 0 ? void 0 : { value: generated, origin: "schema-derived" };
+  return parameters.map((parameter) => {
+    const required = parameter.required === true || parameter.in === "path";
+    const type = parameterDisplayType(parameter);
+    const defaultValue = parameterDefault(parameter);
+    const defaultSuffix = isMeaningfulDefault(defaultValue) ? ` (default: ${typeof defaultValue === "string" ? JSON.stringify(defaultValue) : String(defaultValue)})` : "";
+    const description = shortenDescription(cleanText(parameter.description), style.descriptionLimit);
+    const details = description ? ` \u2014 ${description}` : "";
+    return `- \`${cleanText(parameter.name)}\` (\`${cleanText(parameter.in)}\`${required ? ", required" : ""}) \xB7 \`${type}\`${defaultSuffix}${details}`;
+  }).join("\n");
 }
-function requestPayloadDescription(spec, operation) {
+function requestPayloadDescription(spec, operation, style = FULL_STYLE) {
   if (isObject(operation.requestBody) || operation.requestBody?.$ref) {
     const body = resolveReferenceObject(spec, operation.requestBody);
     const content = isObject(body.content) ? body.content : {};
@@ -974,7 +1488,7 @@ function requestPayloadDescription(spec, operation) {
     return {
       type: schema ? typeExpression(schema) : "unknown",
       mediaType: mediaType || "unknown media type",
-      example: media || schema ? payloadExample(spec, media, schema) : void 0,
+      example: style.includeExamples && (media || schema) ? payloadExample(spec, media, schema) : void 0,
       required: body.required === true
     };
   }
@@ -985,13 +1499,31 @@ function requestPayloadDescription(spec, operation) {
     return {
       type: typeExpression(bodyParameter.schema),
       mediaType: consumes[0] ?? "application/json",
-      example: payloadExample(spec, void 0, bodyParameter.schema),
+      example: style.includeExamples ? payloadExample(spec, void 0, bodyParameter.schema) : void 0,
       required: bodyParameter.required === true
     };
   }
   return void 0;
 }
-function responseSchema(spec, responseValue) {
+
+// src/transformer/responses.ts
+var COMMON_ERROR_CODES = /* @__PURE__ */ new Set([
+  "400",
+  "401",
+  "403",
+  "404",
+  "405",
+  "409",
+  "415",
+  "422",
+  "429",
+  "500",
+  "501",
+  "502",
+  "503",
+  "default"
+]);
+function responseSchema(spec, responseValue, style = FULL_STYLE) {
   const response = resolveReferenceObject(spec, responseValue);
   if (isObject(response.content)) {
     const mediaType = chooseMediaType(response.content);
@@ -1000,30 +1532,26 @@ function responseSchema(spec, responseValue) {
     return {
       type: schema ? typeExpression(schema) : void 0,
       mediaType,
-      example: schema || media ? payloadExample(spec, media, schema, response.examples) : void 0
+      example: style.includeExamples && (schema || media) ? payloadExample(spec, media, schema, response.examples) : void 0
     };
   }
   if (isObject(response.schema)) {
     return {
       type: typeExpression(response.schema),
       mediaType: "application/json",
-      example: payloadExample(spec, void 0, response.schema, response.examples)
+      example: style.includeExamples ? payloadExample(spec, void 0, response.schema, response.examples) : void 0
     };
   }
   return {};
 }
-function formattedExample(value) {
-  try {
-    return JSON.stringify(value, null, 2) ?? "null";
-  } catch {
-    return "null";
-  }
-}
-function responseBlock(spec, code, responseValue) {
+function responseBlock(spec, code, responseValue, style = FULL_STYLE) {
   const response = resolveReferenceObject(spec, responseValue);
-  const description = cleanText(response.description);
-  const payload = responseSchema(spec, responseValue);
+  const description = style.collapsed ? "" : shortenDescription(cleanText(response.description), style.descriptionLimit);
+  const payload = responseSchema(spec, responseValue, style);
   const suffix = payload.type ? ` \u2014 \`${payload.type}\`${payload.mediaType ? ` (${payload.mediaType})` : ""}` : " \u2014 no body schema declared";
+  if (style.collapsed) {
+    return [`- **${markdownCell(code)}**${suffix}`].join("\n");
+  }
   const lines = [`- **${markdownCell(code)}${description ? ` ${description}` : ""}**${suffix}`];
   if (payload.example?.origin === "declared") {
     const label = payload.example.name ? ` \xB7 ${payload.example.name}` : "";
@@ -1088,7 +1616,7 @@ function collapsibleErrorEntry(spec, code, responseValue) {
   if (schemaValue === void 0) return `\`${code}\``;
   return `\`${code}\` (\`${typeExpression(schemaValue)}\`)`;
 }
-function responseSection(spec, operation) {
+function responseSection(spec, operation, style = FULL_STYLE) {
   const responses = entries(operation.responses).filter(([, value]) => isObject(value));
   if (!responses.length) return "_No responses declared._";
   const success = responses.filter(([code]) => /^2\d\d$/.test(code));
@@ -1096,42 +1624,96 @@ function responseSection(spec, operation) {
   const errors = responses.filter(
     ([code]) => (COMMON_ERROR_CODES.has(code) || /^([45])\d\d$/.test(code)) && !success.some(([successCode]) => successCode === code)
   );
+  if (style.collapsed) {
+    const collapsedLines = success.map(([code, response]) => responseBlock(spec, code, response, style));
+    collapsedLines.push(...errors.map(([code, responseValue]) => responseBlock(spec, code, responseValue, style)));
+    return collapsedLines.join("\n");
+  }
   const detailedErrors = [];
   const collapsedErrors = [];
   for (const [code, responseValue] of errors) {
     const entry = collapsibleErrorEntry(spec, code, responseValue);
-    if (entry === void 0) detailedErrors.push(responseBlock(spec, code, responseValue));
+    if (entry === void 0) detailedErrors.push(responseBlock(spec, code, responseValue, style));
     else collapsedErrors.push(entry);
   }
   const primarySuccess = success[0];
-  const lines = primarySuccess ? [responseBlock(spec, primarySuccess[0], primarySuccess[1])] : [];
+  const lines = primarySuccess ? [responseBlock(spec, primarySuccess[0], primarySuccess[1], style)] : [];
   lines.push(...detailedErrors);
   if (collapsedErrors.length) lines.push(`- **Errors:** ${collapsedErrors.join(", ")}`);
   if (success.length > 1) {
-    const others = success.slice(1).map(([code, response]) => responseBlock(spec, code, response));
+    const others = success.slice(1).map(([code, response]) => responseBlock(spec, code, response, style));
     lines.push("", "<details><summary>Other successful responses</summary>", "", ...others, "", "</details>");
   }
   if (!lines.length) {
-    return responses.map(([code, response]) => responseBlock(spec, code, response)).join("\n\n");
+    return responses.map(([code, response]) => responseBlock(spec, code, response, style)).join("\n\n");
   }
   return lines.join("\n");
 }
+
+// src/transformer/endpoints.ts
+var HTTP_METHODS = ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
+function getEndpoints(spec) {
+  const result = [];
+  const paths = isObject(spec.paths) ? spec.paths : {};
+  for (const [path2, pathItemValue] of Object.entries(paths)) {
+    if (!isObject(pathItemValue)) continue;
+    const pathParameters = Array.isArray(pathItemValue.parameters) ? pathItemValue.parameters.map((parameter) => resolveReferenceObject(spec, parameter)) : [];
+    for (const method of HTTP_METHODS) {
+      const operationValue = pathItemValue[method];
+      if (!isObject(operationValue)) continue;
+      const firstTag = Array.isArray(operationValue.tags) && operationValue.tags.length ? String(operationValue.tags[0]) : "General";
+      result.push({ method, path: path2, operation: operationValue, pathParameters, tag: firstTag });
+    }
+  }
+  return result;
+}
+function getServers(spec) {
+  if (Array.isArray(spec.servers) && spec.servers.length) {
+    return spec.servers.map((server) => cleanText(isObject(server) ? server.url : void 0)).filter(Boolean);
+  }
+  if (isObject(spec)) {
+    const host = cleanText(spec.host);
+    if (host) {
+      const schemes = Array.isArray(spec.schemes) && spec.schemes.length ? spec.schemes : ["https"];
+      const basePath = cleanText(spec.basePath) || "/";
+      return schemes.map(
+        (scheme) => `${scheme}://${host}${basePath.startsWith("/") ? basePath : `/${basePath}`}`
+      );
+    }
+  }
+  return [];
+}
+function collectTags(spec, endpoints) {
+  const declared = Array.isArray(spec.tags) ? spec.tags.map((tag) => cleanText(isObject(tag) ? tag.name : void 0)).filter(Boolean) : [];
+  const encountered = [...new Set(endpoints.map((endpoint) => endpoint.tag))];
+  return [
+    ...declared.filter((tag) => encountered.includes(tag)),
+    ...encountered.filter((tag) => !declared.includes(tag))
+  ];
+}
+function endpointTypeBase(method, path2, operation) {
+  if (cleanText(operation.operationId)) return toTypeScriptIdentifier(cleanText(operation.operationId));
+  const pathName = path2.replace(/[{}]/g, "").split(/[^a-zA-Z0-9]+/).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
+  return toTypeScriptIdentifier(`${method.charAt(0).toUpperCase()}${method.slice(1)}${pathName}`);
+}
 function shortOperationDescription(operation) {
   return markdownCell(operation.summary || operation.operationId || operation.description || "\u2014");
 }
-function endpointMarkdown(spec, endpoint) {
+function endpointMarkdown(spec, endpoint, style = FULL_STYLE) {
   const { operation, method, path: path2 } = endpoint;
   const heading = `#### \`${method.toUpperCase()} ${path2}\``;
   const summary = cleanText(operation.summary);
   const description = cleanText(operation.description);
   const lines = [heading];
-  if (summary) lines.push("", summary);
-  if (description && description !== summary) lines.push("", description);
+  if (summary) lines.push("", shortenDescription(summary, style.descriptionLimit));
+  if (description && description !== summary) {
+    lines.push("", shortenDescription(description, style.descriptionLimit));
+  }
   lines.push("", `**Authentication:** ${securityRequirement(spec, operation)}`);
   const parameters = mergedParameters(spec, endpoint);
-  const request = requestPayloadDescription(spec, operation);
+  const request = requestPayloadDescription(spec, operation, style);
   lines.push("", "**Parameters**");
-  lines.push(parameterList(parameters));
+  lines.push(parameterList(parameters, style));
   if (request) {
     lines.push(
       "",
@@ -1149,31 +1731,83 @@ function endpointMarkdown(spec, endpoint) {
       );
     }
   }
-  lines.push("", "**Responses**", responseSection(spec, operation));
+  lines.push("", "**Responses**", responseSection(spec, operation, style));
   return lines.join("\n");
 }
-function authOverview(spec) {
-  const schemes = getSecuritySchemes(spec);
-  if (!schemes.length) return ["- **Authentication:** No security schemes declared."];
-  const globalSecurity = securityRequirement(spec, {});
-  return [
-    `- **Authentication required globally:** ${globalSecurity}`,
-    "- **Available schemes:**",
-    ...schemes.map(([name, scheme]) => `  - ${describeSecurityScheme(name, scheme)}`)
-  ];
+
+// src/transformer/models.ts
+function collectSchemaRefs(value, output, root, seen = /* @__PURE__ */ new Set(), followedRefs = /* @__PURE__ */ new Set()) {
+  if (!value || typeof value !== "object" || seen.has(value)) return;
+  seen.add(value);
+  if (Array.isArray(value)) {
+    for (const item of value) collectSchemaRefs(item, output, root, seen, followedRefs);
+    return;
+  }
+  const object = value;
+  if (typeof object.$ref === "string") {
+    if (isSchemaRef(object.$ref)) {
+      const name = refName(object.$ref);
+      if (name) output.add(name);
+    } else if (root && object.$ref.startsWith("#/") && !followedRefs.has(object.$ref)) {
+      followedRefs.add(object.$ref);
+      const target = resolvePointer2(root, object.$ref);
+      if (target !== void 0) collectSchemaRefs(target, output, root, seen, followedRefs);
+    }
+  }
+  for (const [key, child] of Object.entries(object)) {
+    if (key !== "example" && key !== "examples" && key !== "externalDocs")
+      collectSchemaRefs(child, output, root, seen, followedRefs);
+  }
 }
-function collectTags(spec, endpoints) {
-  const declared = Array.isArray(spec.tags) ? spec.tags.map((tag) => cleanText(tag?.name)).filter(Boolean) : [];
-  const encountered = [...new Set(endpoints.map((endpoint) => endpoint.tag))];
-  return [
-    ...declared.filter((tag) => encountered.includes(tag)),
-    ...encountered.filter((tag) => !declared.includes(tag))
-  ];
+function referencedSchemas(spec) {
+  const dictionary = getSchemaDictionary(spec);
+  const knownByName = /* @__PURE__ */ new Map();
+  for (const [name, schema] of Object.entries(dictionary)) {
+    knownByName.set(toTypeScriptIdentifier(name), [name, schema]);
+  }
+  const refs = /* @__PURE__ */ new Set();
+  collectSchemaRefs(spec.paths ?? {}, refs, spec);
+  const selected = /* @__PURE__ */ new Set();
+  const queue = [...refs];
+  while (queue.length) {
+    const name = queue.shift();
+    if (!name || selected.has(name)) continue;
+    selected.add(name);
+    const model = knownByName.get(name);
+    if (!model) continue;
+    const childRefs = /* @__PURE__ */ new Set();
+    collectSchemaRefs(model[1], childRefs, spec);
+    for (const child of childRefs) if (!selected.has(child)) queue.push(child);
+  }
+  return [...selected].map((name) => knownByName.get(name)).filter((entry) => Boolean(entry));
 }
-function endpointTypeBase(method, path2, operation) {
-  if (cleanText(operation.operationId)) return toTypeScriptIdentifier(cleanText(operation.operationId));
-  const pathName = path2.replace(/[{}]/g, "").split(/[^a-zA-Z0-9]+/).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
-  return toTypeScriptIdentifier(`${method.charAt(0).toUpperCase()}${method.slice(1)}${pathName}`);
+function modelDeclaration(name, schema) {
+  const identifier = toTypeScriptIdentifier(name);
+  const description = safeComment(schema.description);
+  const comment = description ? `/** ${description} */
+` : "";
+  if (schema.$ref) return `${comment}export type ${identifier} = ${typeExpression(schema)};`;
+  if (Array.isArray(schema.enum) || schema.const !== void 0 || schema.oneOf || schema.anyOf || schema.allOf) {
+    return `${comment}export type ${identifier} = ${typeExpression(schema)};`;
+  }
+  const kind = Array.isArray(schema.type) ? schema.type.find((item) => item !== "null") : schema.type;
+  if (kind === "object" || schema.properties || schema.additionalProperties !== void 0) {
+    const properties = entries(schema.properties);
+    const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+    const fields = properties.map(([field, value]) => {
+      const metadata = schemaMetadata(value).map(safeComment).filter(Boolean).join("; ");
+      const doc = metadata ? `    /** ${metadata} */
+` : "";
+      return `${doc}    ${propertyKey(field)}${required.has(field) ? "" : "?"}: ${typeExpression(value)};`;
+    });
+    if (schema.additionalProperties === true) fields.push("    [key: string]: unknown;");
+    else if (isObject(schema.additionalProperties))
+      fields.push(`    [key: string]: ${typeExpression(schema.additionalProperties)};`);
+    return `${comment}export interface ${identifier} {
+${fields.join("\n")}
+}`;
+  }
+  return `${comment}export type ${identifier} = ${typeExpression(schema)};`;
 }
 function normalizeInlinePayloadSchemas(spec) {
   const document = structuredClone(spec);
@@ -1267,26 +1901,123 @@ function normalizeInlinePayloadSchemas(spec) {
   }
   return document;
 }
-function transformOpenApiToMarkdown(spec, sourceUrl) {
-  const normalizedSpec = normalizeInlinePayloadSchemas(spec);
-  spec = normalizedSpec;
+
+// src/transformer/index.ts
+var HTTP_METHODS2 = ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
+function tagsOfEndpoint(endpoint) {
+  const tags = endpoint.operation.tags;
+  return Array.isArray(tags) && tags.length ? tags.map(String) : ["General"];
+}
+function filterSpec(spec, endpoints, options, warnings) {
+  const includeTags = options.includeTags ?? [];
+  const excludeTags = options.excludeTags ?? [];
+  const hasFilter = includeTags.length > 0 || excludeTags.length > 0 || options.pathPrefix !== void 0;
+  if (!hasFilter) return spec;
+  const declared = Array.isArray(spec.tags) ? spec.tags.map((tag) => isObject(tag) && typeof tag.name === "string" ? tag.name : "").filter(Boolean) : [];
+  const available = [.../* @__PURE__ */ new Set([...declared, ...endpoints.map((endpoint) => endpoint.tag)])];
+  const unknownTags = [
+    ...includeTags.filter((tag) => !available.includes(tag)),
+    ...excludeTags.filter((tag) => !available.includes(tag))
+  ];
+  if (unknownTags.length > 0) {
+    warnings.push(
+      `Unknown tag(s): ${[...new Set(unknownTags)].join(", ")}. Available tags: ${available.join(", ") || "none"}.`
+    );
+  }
+  const keep = (endpoint) => {
+    if (options.pathPrefix && !endpoint.path.startsWith(options.pathPrefix)) return false;
+    const tags = tagsOfEndpoint(endpoint);
+    if (includeTags.length > 0 && !tags.some((tag) => includeTags.includes(tag))) return false;
+    if (excludeTags.length > 0 && tags.some((tag) => excludeTags.includes(tag))) return false;
+    return true;
+  };
+  const paths = {};
+  for (const endpoint of endpoints.filter(keep)) {
+    const source = isObject(spec.paths?.[endpoint.path]) ? spec.paths[endpoint.path] : {};
+    const item = paths[endpoint.path] ?? { ...source };
+    for (const method of HTTP_METHODS2) delete item[method];
+    item[endpoint.method] = source[endpoint.method];
+    paths[endpoint.path] = item;
+  }
+  return { ...spec, paths };
+}
+function buildTrimStages(_endpoints, tags) {
+  const stages = [];
+  const emptyTags = /* @__PURE__ */ new Set();
+  stages.push({
+    includeExamples: true,
+    collapsedTags: emptyTags,
+    indexOnly: false
+  });
+  stages.push({
+    includeExamples: false,
+    collapsedTags: emptyTags,
+    indexOnly: false,
+    action: "removed declared example payloads"
+  });
+  stages.push({
+    includeExamples: false,
+    descriptionLimit: 200,
+    collapsedTags: emptyTags,
+    indexOnly: false,
+    action: "shortened long descriptions"
+  });
+  const collapsedSoFar = /* @__PURE__ */ new Set();
+  for (const tag of [...tags].reverse()) {
+    collapsedSoFar.add(tag);
+    stages.push({
+      includeExamples: false,
+      descriptionLimit: 200,
+      collapsedTags: new Set(collapsedSoFar),
+      indexOnly: false,
+      action: `collapsed parameter and response detail for tag "${tag}"`
+    });
+  }
+  stages.push({
+    includeExamples: false,
+    descriptionLimit: 200,
+    collapsedTags: new Set(tags),
+    indexOnly: true,
+    action: "kept only the Quick index entries for the remaining tags"
+  });
+  return stages;
+}
+function renderDigest(spec, sourceUrl, endpoints, tags, stage) {
   const info = isObject(spec.info) ? spec.info : {};
   const title = cleanText(info.title) || "API";
   const version = cleanText(info.version) || "unspecified";
   const openApiVersion = cleanText(spec.openapi) || (spec.swagger ? `Swagger ${spec.swagger}` : "OpenAPI");
   const servers = getServers(spec);
-  const endpoints = getEndpoints(spec);
-  const tags = collectTags(spec, endpoints);
   const indexRows = endpoints.map(
     (endpoint) => `| **${endpoint.method.toUpperCase()}** | \`${markdownCell(endpoint.path)}\` | ${shortOperationDescription(endpoint.operation)} | ${markdownCell(Array.isArray(endpoint.operation.tags) ? endpoint.operation.tags.join(", ") : endpoint.tag)} |`
   );
+  const detailEndpoints = stage.indexOnly ? [] : endpoints.filter((endpoint) => !stage.collapsedTags.has(endpoint.tag));
   const groupedEndpoints = tags.map((tag) => {
     const members = endpoints.filter((endpoint) => endpoint.tag === tag);
     if (!members.length) return "";
-    return [`### ${tag}`, ...members.map((endpoint) => endpointMarkdown(spec, endpoint))].join("\n\n");
+    const rendered = members.map(
+      (endpoint) => endpointMarkdown(spec, endpoint, {
+        includeExamples: stage.includeExamples,
+        descriptionLimit: stage.descriptionLimit,
+        collapsed: stage.collapsedTags.has(endpoint.tag)
+      })
+    );
+    return [`### ${tag}`, ...rendered].join("\n\n");
   }).filter(Boolean);
-  const models = referencedSchemas(spec);
-  const modelSection = models.length ? [
+  let modelSpec = spec;
+  if (detailEndpoints.length !== endpoints.length) {
+    const scopedPaths = {};
+    for (const endpoint of detailEndpoints) {
+      const source = isObject(spec.paths?.[endpoint.path]) ? spec.paths[endpoint.path] : {};
+      const item = scopedPaths[endpoint.path] ?? { ...source };
+      for (const method of HTTP_METHODS2) delete item[method];
+      item[endpoint.method] = source[endpoint.method];
+      scopedPaths[endpoint.path] = item;
+    }
+    modelSpec = { ...spec, paths: scopedPaths };
+  }
+  const models = referencedSchemas(modelSpec);
+  const modelSection = !stage.indexOnly && models.length ? [
     "## Data types",
     "",
     "```typescript",
@@ -1309,62 +2040,67 @@ function transformOpenApiToMarkdown(spec, sourceUrl) {
     "",
     "| Method | Path | Summary | Tags |",
     "|---|---|---|---|",
-    ...indexRows.length ? indexRows : ["| \u2014 | \u2014 | No operations declared | \u2014 |"],
-    "",
-    "## Endpoints",
-    "",
-    ...groupedEndpoints.length ? groupedEndpoints : ["_No endpoints declared._"],
-    ...modelSection ? ["", modelSection] : []
+    ...indexRows.length ? indexRows : ["| \u2014 | \u2014 | No operations declared | \u2014 |"]
   ];
+  if (!stage.indexOnly) {
+    sections.push(
+      "",
+      "## Endpoints",
+      "",
+      ...groupedEndpoints.length ? groupedEndpoints : ["_No endpoints declared._"]
+    );
+  }
+  if (modelSection) {
+    sections.push("", modelSection);
+  }
   return `${sections.join("\n").replace(/\n{3,}/g, "\n\n").trim()}
 `;
 }
+function appendTrimNote(markdown, actions, budget) {
+  return `${markdown}
+## Trimmed
 
-// src/tokens.ts
-function estimateTokens(text) {
-  const characters = text.length;
-  if (characters === 0) {
-    const zeroModel = (name, window2) => ({
-      name,
-      tokens: 0,
-      contextWindow: window2,
-      contextPercent: 0
-    });
-    return {
-      characters: 0,
-      models: {
-        claude: zeroModel("Claude (Sonnet / Opus)", 2e5),
-        openai: zeroModel("OpenAI (GPT-4o / o-series)", 128e3),
-        gemini: zeroModel("Google Gemini (Pro / Flash)", 1e6),
-        deepseek: zeroModel("DeepSeek (V3 / R1)", 128e3),
-        llama: zeroModel("Meta Llama (3.3 / 4)", 128e3)
-      }
-    };
+> _Trimmed to fit the ~${budget.toLocaleString()}-token budget: ${actions.join("; ")}._
+`;
+}
+function transformOpenApiToMarkdown(spec, sourceUrl, options = {}) {
+  const warnings = [];
+  const filteredSpec = filterSpec(spec, getEndpoints(spec), options, warnings);
+  for (const message of warnings) options.onWarning?.(message);
+  const normalizedSpec = normalizeInlinePayloadSchemas(filteredSpec);
+  const endpoints = getEndpoints(normalizedSpec);
+  const tags = collectTags(normalizedSpec, endpoints);
+  const fullStage = {
+    includeExamples: true,
+    collapsedTags: /* @__PURE__ */ new Set(),
+    indexOnly: false
+  };
+  if (options.maxTokens === void 0) {
+    return renderDigest(normalizedSpec, sourceUrl, endpoints, tags, fullStage);
   }
-  const wordCount = (text.match(/\b[\w$]+\b/gu) || []).length;
-  const syntaxSymbols = (text.match(/[{}[\]()<>=:;,."`|/-]/g) || []).length;
-  const whitespaces = (text.match(/\s+/g) || []).length;
-  const baseTokens = wordCount * 1.18 + syntaxSymbols * 0.42 + whitespaces * 0.05;
-  const calculate = (name, ratio, contextWindow) => {
-    const tokens = Math.max(1, Math.round(baseTokens * ratio));
-    const contextPercent = Number((tokens / contextWindow * 100).toFixed(1));
-    return { name, tokens, contextWindow, contextPercent };
+  const worst = (markdown2) => {
+    const report = estimateTokens(markdown2);
+    return Math.max(...Object.values(report.models).map((model) => model.tokens));
   };
-  return {
-    characters,
-    models: {
-      // Claude BPE splits subwords and code tokens slightly finer
-      claude: calculate("Claude (Sonnet / Opus)", 1.08, 2e5),
-      // OpenAI o200k_base has efficient compression on whitespace and symbols
-      openai: calculate("OpenAI (GPT-4o / o-series)", 0.95, 128e3),
-      // Gemini 256k vocab is the most compressed on markdown & code
-      gemini: calculate("Google Gemini (Pro / Flash)", 0.9, 1e6),
-      // DeepSeek 128k tokenizer
-      deepseek: calculate("DeepSeek (V3 / R1)", 0.97, 128e3),
-      // Llama 3/4 128k tokenizer
-      llama: calculate("Meta Llama (3.3 / 4)", 0.98, 128e3)
+  const fits = (markdown2) => worst(markdown2) <= options.maxTokens;
+  const full = renderDigest(normalizedSpec, sourceUrl, endpoints, tags, fullStage);
+  if (fits(full)) return full;
+  const stages = buildTrimStages(endpoints, tags);
+  for (let i = 1; i < stages.length; i += 1) {
+    const stage = stages[i];
+    const markdown2 = renderDigest(normalizedSpec, sourceUrl, endpoints, tags, stage);
+    if (fits(markdown2)) {
+      return appendTrimNote(
+        markdown2,
+        stages.slice(1, i + 1).map((entry) => entry.action).filter((action) => Boolean(action)),
+        options.maxTokens
+      );
     }
-  };
+  }
+  const last = stages[stages.length - 1];
+  const markdown = renderDigest(normalizedSpec, sourceUrl, endpoints, tags, last);
+  const allActions = stages.slice(1).map((stage) => stage.action).filter((action) => Boolean(action));
+  return appendTrimNote(markdown, allActions, options.maxTokens);
 }
 
 // src/writer.ts
@@ -1398,12 +2134,13 @@ async function writeDigest(options) {
 }
 
 export {
+  VERSION,
+  toTypeScriptIdentifier,
   isOpenApiSpec,
   parseSpecText,
   fetchOpenApiSpec,
-  toTypeScriptIdentifier,
-  transformOpenApiToMarkdown,
   estimateTokens,
+  transformOpenApiToMarkdown,
   defaultOutputDirectory,
   defaultFilename,
   resolveOutputDirectory,