@thallylabs/migrate 0.2.12 → 0.2.14

package/dist/index.js

@@ -3235,7 +3235,7 @@ function projectedHref(value) {
   return href;
 }
 function labelFor(value, fallback) {
-  for (const key of ["tab", "group", "anchor", "product", "dropdown", "version", "menu", "label", "name", "title"]) {
+  for (const key of ["tab", "group", "anchor", "product", "dropdown", "version", "menu", "item", "label", "name", "title"]) {
     if (typeof value[key] === "string" && value[key]) return String(value[key]);
   }
   return fallback;
@@ -3307,29 +3307,40 @@ function readMintlifyConfig(repositoryRoot) {
   const raw = readMintlifyJson(configPath, repositoryRoot);
   return resolveJsonReferences(raw, configPath, repositoryRoot, /* @__PURE__ */ new Set());
 }
+function specSource(value) {
+  const source = typeof value === "string" ? value : objectValue(value)?.source;
+  return typeof source === "string" && source.trim() ? source.trim() : void 0;
+}
+var hasNavigationChildren = (node) => ["groups", "pages"].some((key) => Array.isArray(node[key]) && node[key].length > 0);
 function mintlifyNavigationApiReferences(config) {
   const navigation = objectValue(config.navigation) ?? config;
   const references = [];
   const containerKeys = ["tabs", "anchors", "products", "dropdowns", "versions", "menus", "languages"];
   const nestedKeys = ["groups", "pages"];
-  function visit(rawNode, tabLabel) {
-    const node = withFlattenedProductGroups(rawNode);
+  function collect(node, tabLabel, sibling) {
     for (const kind of ["openapi", "asyncapi"]) {
-      const value = node[kind];
-      if (typeof value === "string" && value.trim()) {
-        references.push({ value: value.trim(), kind, tabLabel });
-        continue;
-      }
-      const object = objectValue(value);
-      if (object && typeof object.source === "string" && object.source.trim()) {
+      const value = specSource(node[kind]);
+      const directory = objectValue(node[kind])?.directory;
+      if (value) {
         references.push({
-          value: object.source.trim(),
+          value,
           kind,
           tabLabel,
-          ...typeof object.directory === "string" && object.directory.trim() ? { directory: object.directory.trim() } : {}
+          ...sibling,
+          ...typeof directory === "string" && directory.trim() ? { directory: directory.trim() } : {}
         });
       }
     }
+  }
+  const siblingSources = /* @__PURE__ */ new Map();
+  function uniqueSiblingLabel(label, source) {
+    let candidate = label;
+    for (let n = 2; siblingSources.has(candidate) && siblingSources.get(candidate) !== source; n++) candidate = `${label} (${n})`;
+    siblingSources.set(candidate, source);
+    return candidate;
+  }
+  function visitChildren(rawNode, tabLabel) {
+    const node = withFlattenedProductGroups(rawNode);
     for (const key of containerKeys) {
       const entries = node[key];
       if (!Array.isArray(entries)) continue;
@@ -3348,10 +3359,45 @@ function mintlifyNavigationApiReferences(config) {
         if (object) visit(object, tabLabel);
       }
     }
+    if (Array.isArray(node.menu)) {
+      const tab = tabLabel ?? "Documentation";
+      const items = node.menu.flatMap((entry) => {
+        const object = objectValue(entry);
+        return object ? [object] : [];
+      });
+      const apiItems = items.filter((item) => specSource(item.openapi) || specSource(item.asyncapi));
+      const soleContent = apiItems.length === 1 && !hasNavigationChildren(node) && !items.some(hasNavigationChildren);
+      items.forEach((item, index) => {
+        if (soleContent && apiItems[0] === item) collect(item, tab);
+        else if (apiItems.includes(item)) {
+          const label = uniqueSiblingLabel(
+            `${tab}: ${labelFor(item, `Menu item ${index + 1}`)}`,
+            `${specSource(item.openapi) ?? ""}|${specSource(item.asyncapi) ?? ""}`
+          );
+          const icon = iconName(item.icon);
+          collect(item, label, { parentTab: tab, ...icon ? { icon } : {}, ...item.hidden === true ? { hidden: true } : {} });
+        }
+        visitChildren(item, tabLabel);
+      });
+    }
+  }
+  function visit(node, tabLabel) {
+    collect(node, tabLabel);
+    visitChildren(node, tabLabel);
   }
   visit(navigation, void 0);
   return references;
 }
+function insertApiTab(tabs, tab, parentTab) {
+  let index = -1;
+  if (parentTab) {
+    tabs.forEach((candidate, position) => {
+      if (candidate.tab === parentTab || candidate.tab.startsWith(`${parentTab}: `)) index = position;
+    });
+  }
+  tabs.splice(index === -1 ? tabs.length : index + 1, 0, tab);
+  return tabs;
+}
 function normalizePageRef(value, pathPrefix = "") {
   if (/^(?:https?:)?\/\//i.test(value) || value.startsWith("#")) return null;
   let ref = localReference(value).split("?", 1)[0].replace(/^\/+/, "");
@@ -3437,6 +3483,65 @@ function convertPage(value, context) {
   }
   return null;
 }
+var KNOWN_NAVIGATION_KEYS = /* @__PURE__ */ new Set([
+  "tabs",
+  "anchors",
+  "products",
+  "dropdowns",
+  "versions",
+  "menus",
+  "languages",
+  "productGroups",
+  "groups",
+  "pages",
+  "menu",
+  "global"
+]);
+function convertMenuItems(items, context) {
+  return items.flatMap((value, index) => {
+    const item = objectValue(value);
+    if (!item) return [];
+    const label = labelFor(item, `Menu item ${index + 1}`);
+    if (typeof item.description === "string" && item.description.trim()) {
+      warnOnce(
+        context,
+        `menu-item-description:${label}`,
+        `Mintlify menu item "${label}" has a description, which Thally groups cannot display; it was omitted.`
+      );
+    }
+    const hasUnsourcedSpec = Boolean(item.openapi || item.asyncapi) && !specSource(item.openapi) && !specSource(item.asyncapi);
+    if (hasUnsourcedSpec) {
+      warnOnce(
+        context,
+        `menu-item-spec:${label}`,
+        `Mintlify menu item "${label}" has an openapi/asyncapi value without a "source", so its API reference was not migrated.`
+      );
+    }
+    const children = convertNavigationValues([
+      ...Array.isArray(item.groups) ? item.groups : [],
+      ...Array.isArray(item.pages) ? item.pages : []
+    ], context);
+    if (typeof item.href === "string" && item.href) {
+      warnOnce(
+        context,
+        `menu-item-href:${label}`,
+        `Mintlify menu item "${label}" links to ${item.href}, which cannot be represented as a Thally group; the link was omitted.`
+      );
+    }
+    if (children.length === 0) {
+      if (!specSource(item.openapi) && !specSource(item.asyncapi) && !hasUnsourcedSpec) {
+        warnOnce(context, `menu-item-empty:${label}`, `Mintlify menu item "${label}" has no projectable pages and was omitted.`);
+      }
+      return [];
+    }
+    return [{
+      group: label,
+      ...iconName(item.icon) ? { icon: iconName(item.icon) } : {},
+      ...item.hidden === true ? { hidden: true } : {},
+      pages: children
+    }];
+  });
+}
 function convertNavigationValues(values, context) {
   return values.flatMap((value) => {
     const page = convertPage(value, context);
@@ -3448,6 +3553,13 @@ function convertContainerToTabs(containerValue, context, fallbackTab, trace, dep
   if (!rawContainer) return [];
   const container = withFlattenedProductGroups(rawContainer);
   const containerKeys = ["tabs", "anchors", "products", "dropdowns", "versions", "menus"];
+  for (const key of Object.keys(container)) {
+    if (KNOWN_NAVIGATION_KEYS.has(key)) continue;
+    const entries = container[key];
+    if (Array.isArray(entries) && entries.some((entry) => objectValue(entry))) {
+      warnOnce(context, `unknown-container:${key}`, `Mintlify navigation key "${key}" is not supported and its contents were not projected.`);
+    }
+  }
   for (const key of containerKeys) {
     if (!Array.isArray(container[key])) continue;
     const entries = [...container[key]];
@@ -3459,7 +3571,7 @@ function convertContainerToTabs(containerValue, context, fallbackTab, trace, dep
       if (!object) return [];
       const tab = labelFor(object, `${fallbackTab} ${index + 1}`);
       const href = projectedHref(object.href);
-      const hasNestedContainers = containerKeys.some((containerKey) => Array.isArray(object[containerKey]));
+      const hasNestedContainers = [...containerKeys, "menu"].some((containerKey) => Array.isArray(object[containerKey]));
       if (href && !object.pages && !object.groups && !hasNestedContainers) {
         return [{
           tab,
@@ -3491,6 +3603,11 @@ function convertContainerToTabs(containerValue, context, fallbackTab, trace, dep
       return [];
     });
     if (tabs.length > 0) {
+      for (const sibling of ["groups", "pages", "menu"]) {
+        if (Array.isArray(container[sibling]) && container[sibling].length > 0) {
+          warnOnce(context, `container-sibling:${key}:${sibling}`, `Mintlify "${sibling}" next to "${key}" was not projected; only the "${key}" containers were kept.`);
+        }
+      }
       if (depth === 0 && trace) trace.rootContainerKind = key;
       return tabs;
     }
@@ -3503,7 +3620,10 @@ function convertContainerToTabs(containerValue, context, fallbackTab, trace, dep
     ...rawGroups,
     ...rawPages
   ];
-  const children = convertNavigationValues(values, context);
+  const children = [
+    ...convertNavigationValues(values, context),
+    ...Array.isArray(container.menu) ? convertMenuItems(container.menu, context) : []
+  ];
   return children.length > 0 ? [{
     tab: fallbackTab,
     ...hasRootNodes ? { pages: children } : { groups: children },
@@ -3553,7 +3673,7 @@ function projectedGlobalNavigationLinks(value) {
       const label = labelFor(item, "");
       if (label) links.push({ label, href });
     }
-    for (const key of ["tabs", "anchors", "dropdowns", "products", "versions", "languages", "menus"]) {
+    for (const key of ["tabs", "anchors", "dropdowns", "products", "versions", "languages", "menus", "menu"]) {
       if (Array.isArray(item[key])) visit(item[key]);
     }
   };
@@ -5387,6 +5507,10 @@ var MAX_PAGE_BYTES = 2e6;
 var MAX_ASSET_BYTES = 25e6;
 var MAX_TOTAL_ASSET_BYTES = 5e8;
 var GIT_LFS_POINTER_PREFIX = "version https://git-lfs.github.com/spec/v1";
+function listAssetPaths(paths) {
+  const shown = paths.slice(0, 5).join(", ");
+  return paths.length > 5 ? `${shown}, and ${paths.length - 5} more` : shown;
+}
 function isGitLfsPointer(content) {
   return content.length < 1024 && content.toString("utf8", 0, GIT_LFS_POINTER_PREFIX.length) === GIT_LFS_POINTER_PREFIX;
 }
@@ -5810,17 +5934,23 @@ function parseGitHubRepositoryUrl(rawUrl) {
 }
 var CLONE_RETRY_ATTEMPTS = 3;
 var CLONE_RETRY_DELAY_MS = 1e3;
-var DEFAULT_CLONE_TIMEOUT_MS = 10 * 6e4;
+var DEFAULT_CLONE_IDLE_TIMEOUT_MS = 2 * 6e4;
+var MAX_GIT_PROCESS_MS = 60 * 6e4;
+var HARD_TIMEOUT_REASON = `still running after ${MAX_GIT_PROCESS_MS / 6e4} minutes`;
+var GIT_EXIT_DRAIN_MS = 2e3;
 var RETRYABLE_CLONE_ERROR = /RPC failed|Recv failure|early EOF|curl \d+|Could not resolve host|Connection (?:reset|refused|timed out)|The remote end hung up|SSL[_ ]?(?:read|connect|write) error|timed out|network is unreachable/i;
 function delay(ms) {
   return new Promise((resolve3) => {
     setTimeout(resolve3, ms);
   });
 }
-function gitProcessTimeoutMs() {
+function gitIdleTimeoutMs() {
   const raw = process.env.THALLY_MIGRATE_CLONE_TIMEOUT_MS;
   const parsed = raw ? Number(raw) : NaN;
-  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_CLONE_TIMEOUT_MS;
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_CLONE_IDLE_TIMEOUT_MS;
+}
+function gitErrorTail(stderr) {
+  return stderr.split(/[\r\n]+/).map((line) => line.trim()).filter((line) => line && !/^(?:remote: )?[A-Za-z][A-Za-z ]*:\s+\d+%/.test(line)).slice(-5).join("\n");
 }
 function runGit(args, options) {
   return new Promise((resolve3, reject) => {
@@ -5830,24 +5960,66 @@ function runGit(args, options) {
       env: { ...process.env, ...options.env }
     });
     let stderr = "";
-    let timedOut = false;
-    const timer = setTimeout(() => {
-      timedOut = true;
+    let timeoutReason = "";
+    let settled = false;
+    let exitCode;
+    let drainTimer;
+    const idleMs = gitIdleTimeoutMs();
+    const idleMessage = `no progress for ${idleMs < 1e3 ? `${idleMs}ms` : `${Math.round(idleMs / 1e3)}s`}`;
+    const clearTimers = () => {
+      clearTimeout(idleTimer);
+      clearTimeout(hardTimer);
+      clearTimeout(drainTimer);
+    };
+    const finish = (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimers();
+      child.stderr.destroy();
+      if (code === 0) resolve3();
+      else if (timeoutReason) {
+        const hint = timeoutReason === HARD_TIMEOUT_REASON ? "" : "; on a very slow link, raise THALLY_MIGRATE_CLONE_TIMEOUT_MS (milliseconds of allowed silence)";
+        reject(new Error(`${options.label}: timed out (${timeoutReason}) and was killed. Check your network connection and try again${hint}.`));
+      } else reject(new Error(`${options.label}: ${gitErrorTail(stderr) || `git exited ${code}`}`));
+    };
+    const kill = (reason) => {
+      if (exitCode !== void 0) {
+        finish(exitCode);
+        return;
+      }
+      timeoutReason = reason;
       child.kill("SIGKILL");
-    }, gitProcessTimeoutMs());
+    };
+    let idleTimer = setTimeout(() => {
+      kill(idleMessage);
+    }, idleMs);
+    const hardTimer = setTimeout(() => {
+      kill(HARD_TIMEOUT_REASON);
+    }, MAX_GIT_PROCESS_MS);
     child.stderr.setEncoding("utf8");
     child.stderr.on("data", (chunk) => {
-      if (stderr.length < 16e3) stderr += chunk;
+      stderr = (stderr + chunk).slice(-16e3);
+      if (exitCode !== void 0 || settled) return;
+      clearTimeout(idleTimer);
+      idleTimer = setTimeout(() => {
+        kill(idleMessage);
+      }, idleMs);
     });
     child.on("error", (error) => {
-      clearTimeout(timer);
+      if (settled) return;
+      settled = true;
+      clearTimers();
       reject(error);
     });
-    child.on("close", (code) => {
-      clearTimeout(timer);
-      if (code === 0) resolve3();
-      else if (timedOut) reject(new Error(`${options.label} timed out after ${gitProcessTimeoutMs()}ms and was killed.`));
-      else reject(new Error(`${options.label}: ${stderr.trim() || `git exited ${code}`}`));
+    child.on("close", finish);
+    child.on("exit", (code) => {
+      exitCode = code;
+      clearTimeout(idleTimer);
+      clearTimeout(hardTimer);
+      if (timeoutReason) finish(code);
+      else drainTimer = setTimeout(() => {
+        finish(code);
+      }, GIT_EXIT_DRAIN_MS);
     });
   });
 }
@@ -5863,7 +6035,7 @@ var LFS_FILTER_OVERRIDE_ENV = {
   GIT_CONFIG_VALUE_3: "false"
 };
 function cloneOnce(source, targetDir) {
-  const args = ["clone", "--depth", "1", "--single-branch"];
+  const args = ["clone", "--progress", "--depth", "1", "--single-branch"];
   if (source.branch !== "HEAD") args.push("--branch", source.branch);
   args.push("--", source.cloneUrl, targetDir);
   return runGit(args, {
@@ -5912,6 +6084,7 @@ async function initSubmodules(targetDir, warnings) {
         "submodule",
         "update",
         "--init",
+        "--progress",
         "--depth",
         "1",
         "--",
@@ -6149,6 +6322,13 @@ function classifyApiSpec(path) {
   if (!topLevel) return "unknown";
   return /asyncapi/i.test(topLevel) ? "asyncapi" : "openapi";
 }
+var SPEC_DIRECTORY = "openapi";
+function specAssetPath(filename) {
+  return `${SPEC_DIRECTORY}/${filename}`;
+}
+function specAsset(filename, content) {
+  return { path: specAssetPath(filename), content, projectRelative: true };
+}
 function mintlifyTopLevelApiReferences(config) {
   const api = config?.api && typeof config.api === "object" && !Array.isArray(config.api) ? config.api : null;
   if (!api) return [];
@@ -6169,7 +6349,7 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs) {
   const seen = /* @__PURE__ */ new Set();
   const specs = [];
   for (const reference of references) {
-    const dedupeKey = `${reference.kind}:${reference.value}`;
+    const dedupeKey = `${reference.kind}:${reference.value}:${reference.tabLabel ?? ""}`;
     if (seen.has(dedupeKey)) continue;
     seen.add(dedupeKey);
     const tabSuffix = reference.tabLabel ? ` (tab "${reference.tabLabel}")` : "";
@@ -6181,7 +6361,7 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs) {
       continue;
     }
     if (/^https:\/\//i.test(reference.value)) {
-      remoteSpecs.push({ url: reference.value, ...reference.tabLabel ? { tabLabel: reference.tabLabel } : {} });
+      remoteSpecs.push({ url: reference.value, ...reference.tabLabel ? { tabLabel: reference.tabLabel } : {}, ...reference.parentTab ? { parentTab: reference.parentTab } : {}, ...reference.icon ? { icon: reference.icon } : {}, ...reference.hidden ? { hidden: true } : {} });
       warnings.push({
         code: "unsupported-config",
         message: `The remote OpenAPI spec "${reference.value}"${tabSuffix} requires a network download before this import is complete.`,
@@ -6212,15 +6392,19 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs) {
       filename: basename3(match.relativePath),
       content: readFileSync5(match.absolutePath),
       tabLabel: reference.tabLabel,
+      parentTab: reference.parentTab,
+      icon: reference.icon,
+      hidden: reference.hidden,
       sourcePath: match.relativePath,
       directory: reference.directory
     });
   }
   const filenameOwners = /* @__PURE__ */ new Map();
+  const filenameSources = /* @__PURE__ */ new Map();
   for (const spec of specs) {
     const groupKey = spec.tabLabel ?? "\0default";
     const owner = filenameOwners.get(spec.filename);
-    if (owner !== void 0 && owner !== groupKey) {
+    if (owner !== void 0 && owner !== groupKey && filenameSources.get(spec.filename) !== spec.sourcePath) {
       let disambiguated = spec.sourcePath.replace(/\//g, "-");
       while (filenameOwners.has(disambiguated) && filenameOwners.get(disambiguated) !== groupKey) {
         disambiguated = `${groupKey.replace(/\W+/g, "-")}-${disambiguated}`;
@@ -6228,6 +6412,7 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs) {
       spec.filename = disambiguated;
     }
     filenameOwners.set(spec.filename, groupKey);
+    filenameSources.set(spec.filename, spec.sourcePath);
   }
   return specs;
 }
@@ -6282,7 +6467,7 @@ function apiOperationLinkMap(sources, docsConfig) {
   const prefixLandings = /* @__PURE__ */ new Map();
   const apiTabs = docsConfig.tabs.filter((tab) => !tab.hidden && tab.api);
   apiTabs.forEach((tab, index) => {
-    const source = sources.find((entry) => tab.api?.source === `/${entry.filename}`);
+    const source = sources.find((entry) => tab.api?.source === specAssetPath(entry.filename));
     if (!source || !source.prefix) return;
     const specId = index === 0 ? "default" : slugifyApiSpecId(tab.tab);
     const prefix = source.prefix.replace(/^\/+|\/+$/g, "").toLowerCase();
@@ -6682,7 +6867,15 @@ function preserveLinkedAnchors(pages) {
       const key = comparable(cell.text);
       candidateIndexes.set(key, [...candidateIndexes.get(key) ?? [], { index: cell.index, kind: "table" }]);
     }
-    for (const heading of headings) existing.add(heading.text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, ""));
+    const headingSlugs = /* @__PURE__ */ new Map();
+    const slugCounts = /* @__PURE__ */ new Map();
+    for (const heading of headings) {
+      const slug2 = heading.text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
+      existing.add(slug2);
+      const seen = slugCounts.get(slug2) ?? 0;
+      slugCounts.set(slug2, seen + 1);
+      if (slug2) headingSlugs.set(seen === 0 ? slug2 : `${slug2}-${seen}`, heading.index);
+    }
     const headingAliases = /* @__PURE__ */ new Map();
     const tableAliases = /* @__PURE__ */ new Map();
     for (const fragment of fragments) {
@@ -6696,6 +6889,14 @@ function preserveLinkedAnchors(pages) {
         const selections = linkIndexes.map((index2) => matches.filter((candidate) => candidate.index < index2).at(-1));
         if (selections.length && selections.every((candidate) => candidate?.index === selections[0]?.index)) match = selections[0];
       }
+      if (!match && matches.length > 1) {
+        const headingMatches = matches.filter((candidate) => candidate.kind === "heading");
+        if (headingMatches.length === 1) match = headingMatches[0];
+      }
+      if (!match) {
+        const index2 = headingSlugs.get(fragment.toLowerCase());
+        if (index2 !== void 0) match = { index: index2, kind: "heading" };
+      }
       if (!match) continue;
       const { index, kind } = match;
       const aliases = kind === "heading" ? headingAliases : tableAliases;
@@ -6982,25 +7183,30 @@ ${result.slice(prefix.length)}`;
   return depth === 0 ? hoistMdxImports(result) : result;
 }
 function injectOpenApiSpecs(config, specs, warnings) {
-  let tabs = config.tabs.map((tab) => ({ ...tab }));
+  const tabs = config.tabs.map((tab) => ({ ...tab }));
   for (const spec of specs) {
     const apiTab = spec.tabLabel ? tabs.find((tab) => tab.tab === spec.tabLabel) : tabs.find((tab) => tab.tab.toLowerCase().includes("api"));
     if (apiTab) {
       if (apiTab.api && warnings) {
         warnings.push({
           code: "unsupported-config",
-          message: `Tab "${apiTab.tab}" already uses another OpenAPI spec, and Thally supports one API spec per tab, so "/${spec.filename}" was not added. Put it in its own tab to include it.`
+          message: `Tab "${apiTab.tab}" already uses another OpenAPI spec, and Thally supports one API spec per tab, so "${specAssetPath(spec.filename)}" was not added. Put it in its own tab to include it.`
         });
         continue;
       }
       apiTab.api = {
-        source: `/${spec.filename}`,
+        source: specAssetPath(spec.filename),
         // An API-only tab needs generated endpoint navigation; an authored
         // page tab keeps its own groups alongside the bound spec.
         ...apiTab.groups?.length || apiTab.pages?.length ? { navigation: false } : {}
       };
     } else {
-      tabs = [...tabs, { tab: spec.tabLabel ?? "API Reference", api: { source: `/${spec.filename}` } }];
+      insertApiTab(tabs, {
+        tab: spec.tabLabel ?? "API Reference",
+        ...spec.icon ? { icon: spec.icon } : {},
+        ...spec.hidden ? { hidden: true } : {},
+        api: { source: specAssetPath(spec.filename) }
+      }, spec.parentTab);
     }
   }
   return { ...config, tabs };
@@ -7498,28 +7704,35 @@ function migrateRepository(options) {
     ...assetCandidates.filter((candidate) => !isReferenced(candidate))
   ];
   let totalAssetBytes = 0;
+  const overBudgetAssets = [];
+  let overBudgetReferenced = 0;
+  const lfsPointerAssets = [];
   for (const { file, assetPath, size } of orderedAssetCandidates) {
     if (size > MAX_ASSET_BYTES || totalAssetBytes + size > MAX_TOTAL_ASSET_BYTES) {
-      const referencingPages = referencedAssetPaths.get(assetPath);
-      warnings.push({
-        code: "limit-reached",
-        message: "This file was not copied because it is larger than 25 MB or the copied files would exceed 500 MB in total. Add it to public/ manually" + (referencingPages ? `; it is used by ${[...referencingPages].slice(0, 3).join(", ")}${referencingPages.size > 3 ? `, and ${referencingPages.size - 3} more` : ""}.` : "."),
-        source: file.relativePath
-      });
+      overBudgetAssets.push(file.relativePath);
+      if (referencedAssetPaths.has(assetPath)) overBudgetReferenced++;
       continue;
     }
     const content = readFileSync5(file.absolutePath);
     if (isGitLfsPointer(content)) {
-      warnings.push({
-        code: "unsupported-config",
-        message: "This asset is a Git LFS pointer, not its real content (Git LFS was skipped during clone because the host has no git-lfs binary). Install git-lfs and re-run the migration, or add the real file to public/ manually.",
-        source: file.relativePath
-      });
+      lfsPointerAssets.push(file.relativePath);
       continue;
     }
     assets.push({ path: assetPath, content });
     totalAssetBytes += size;
   }
+  if (overBudgetAssets.length > 0) {
+    warnings.push({
+      code: "limit-reached",
+      message: `${overBudgetAssets.length} asset file${overBudgetAssets.length === 1 ? " was" : "s were"} not copied because files over ${MAX_ASSET_BYTES / 1e6} MB, or beyond ${MAX_TOTAL_ASSET_BYTES / 1e6} MB in total, are skipped: ${listAssetPaths(overBudgetAssets)}. ` + (overBudgetReferenced > 0 ? `${overBudgetReferenced} of them ${overBudgetReferenced === 1 ? "is" : "are"} used by pages, so those images will be broken until you copy ${overBudgetAssets.length === 1 ? "it" : "them"}. ` : "") + `Copy ${overBudgetAssets.length === 1 ? "it" : "them"} into public/ manually.`
+    });
+  }
+  if (lfsPointerAssets.length > 0) {
+    warnings.push({
+      code: "unsupported-config",
+      message: `${lfsPointerAssets.length} asset file${lfsPointerAssets.length === 1 ? " is a Git LFS pointer" : "s are Git LFS pointers"}, not real content, and ${lfsPointerAssets.length === 1 ? "was" : "were"} not copied (Git LFS was skipped during clone because the host has no git-lfs binary): ${listAssetPaths(lfsPointerAssets)}. Install git-lfs and re-run the migration, or copy the real files into public/ manually.`
+    });
+  }
   if (!discoveryBudgetApplied && files.length >= MAX_SOURCE_FILES) {
     warnings.push({ code: "limit-reached", message: `Stopped scanning after ${MAX_SOURCE_FILES} files, so the rest of the repository was not looked at. Run the migration on a smaller part of the repository with --docs-dir.` });
   }
@@ -7608,8 +7821,8 @@ function migrateRepository(options) {
         }
         specFilenameSources.set(filename, spec.absolutePath);
         const specContent = readFileSync5(spec.absolutePath);
-        if (!assets.some((asset) => asset.path === filename)) {
-          assets.push({ path: filename, content: specContent });
+        if (!assets.some((asset) => asset.path === specAssetPath(filename))) {
+          assets.push(specAsset(filename, specContent));
         }
         resolvedSpecs.push({ filename, tabLabel: section.tabLabel, content: specContent, routeSegments: section.routeSegments ?? [] });
         continue;
@@ -7650,8 +7863,8 @@ function migrateRepository(options) {
   } else if (platform === "mintlify") {
     const resolvedSpecs = resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteApiSpecs);
     for (const spec of resolvedSpecs) {
-      if (!assets.some((asset) => asset.path === spec.filename)) {
-        assets.push({ path: spec.filename, content: spec.content });
+      if (!assets.some((asset) => asset.path === specAssetPath(spec.filename))) {
+        assets.push(specAsset(spec.filename, spec.content));
       }
     }
     if (resolvedSpecs.length > 0) {
@@ -7665,8 +7878,8 @@ function migrateRepository(options) {
       const fallback = findOpenApi(files);
       if (fallback) {
         const filename = basename3(fallback.relativePath);
-        if (!assets.some((asset) => asset.path === filename)) {
-          assets.push({ path: filename, content: readFileSync5(fallback.absolutePath) });
+        if (!assets.some((asset) => asset.path === specAssetPath(filename))) {
+          assets.push(specAsset(filename, readFileSync5(fallback.absolutePath)));
         }
         docsConfig = injectOpenApiSpecs(docsConfig, [{ filename }]);
       }
@@ -8157,7 +8370,7 @@ function renderMigrationFiles(bundle, options = {}) {
       path: `src/content/${page.id}.mdx`,
       content: renderPage(bundle, page)
     })),
-    ...bundle.assets.map((asset) => ({ path: `public/${asset.path}`, content: asset.content })),
+    ...bundle.assets.map((asset) => ({ path: asset.projectRelative ? asset.path : `public/${asset.path}`, content: asset.content })),
     ...(bundle.componentFiles ?? []).flatMap((file) => file.path === "src/mdx/custom-components.tsx" && options.existingComponentRegistry !== void 0 && typeof file.content === "string" ? mergeComponentRegistry(options.existingComponentRegistry, file.content) : [file]),
     { path: "docs.json", content: `${JSON.stringify(config, null, 2)}
 ` }
@@ -9899,10 +10112,10 @@ async function hydrateRemoteApiSpecs(bundle, fetcher) {
       const body = await downloadSpec(reference.url, fetcher);
       const operations = parseOpenApi(body, extension);
       const filename = `openapi-${createHash2("sha256").update(reference.url).digest("hex").slice(0, 12)}.${extension}`;
-      assets.push({ path: filename, content: body });
+      assets.push({ path: `openapi/${filename}`, content: body, projectRelative: true });
       const tab = reference.tabLabel ? tabs.find((candidate) => candidate.tab === reference.tabLabel) : tabs.find((candidate) => candidate.tab.toLowerCase().includes("api"));
-      if (tab) tab.api = { source: `/${filename}` };
-      else tabs.push({ tab: reference.tabLabel ?? "API Reference", api: { source: `/${filename}` } });
+      if (tab) tab.api = { source: `openapi/${filename}` };
+      else insertApiTab(tabs, { tab: reference.tabLabel ?? "API Reference", ...reference.icon ? { icon: reference.icon } : {}, ...reference.hidden ? { hidden: true } : {}, api: { source: `openapi/${filename}` } }, reference.parentTab);
       const routes = /* @__PURE__ */ new Map();
       for (const operation of operations) {
         const key = `${slug(operation.tag)}/${slug(operation.summary)}`;