@thallylabs/migrate 0.2.23 → 0.2.24

package/dist/index.d.ts

@@ -255,6 +255,18 @@ interface MigrationWarning {
     message: string;
     source?: string;
 }
+/** A repository-configured remote OpenAPI spec, downloaded after the bundle is built. */
+interface RemoteApiSpec {
+    url: string;
+    tabLabel?: string;
+    parentTab?: string;
+    icon?: string;
+    hidden?: boolean;
+    /** Operation keys (`get /x`) only access-restricted pages document; marked `x-excluded` after download. */
+    withheldOperations?: Array<string>;
+    /** Operation keys published pages or docs.json also name; keeps a shared `$ref` path item public. */
+    keptOperations?: Array<string>;
+}
 interface MigrationBundle {
     sourceUrl: string;
     sourceKind: 'repository' | 'url';
@@ -262,13 +274,7 @@ interface MigrationBundle {
     pages: Array<MigrationPage>;
     assets: Array<MigrationAsset>;
     /** Repository-configured remote specs awaiting a bounded network fetch by the host. */
-    remoteApiSpecs?: Array<{
-        url: string;
-        tabLabel?: string;
-        parentTab?: string;
-        icon?: string;
-        hidden?: boolean;
-    }>;
+    remoteApiSpecs?: Array<RemoteApiSpec>;
     /** Customer-owned component source and registry; paths are repository-relative. */
     componentFiles?: Array<RenderedMigrationFile>;
     /** Access-restricted source pages, written outside every published path. */

package/dist/index.js

@@ -16,7 +16,7 @@ import {
 } from "fs";
 import { createRequire } from "module";
 import { basename as basename3, dirname as dirname4, extname as extname6, isAbsolute as isAbsolute2, posix as posix3, relative as relative5, resolve as resolvePath, sep as sep2 } from "path";
-import { parse as parseYaml4 } from "yaml";
+import { parse as parseYaml5 } from "yaml";
 import * as ts4 from "typescript";
 
 // src/components.ts
@@ -321,7 +321,7 @@ function playgroundDisplay(value, where, warn) {
   const mode = typeof value === "string" ? value.trim().toLowerCase() : "";
   if (mode === "interactive" || mode === "simple" || mode === "none") return mode;
   if (mode === "auth") {
-    warn?.(`${where} "auth" shows the playground only to signed-in readers, which Thally cannot tell; migrated as "simple" (no playground).`);
+    warn?.(`${where} "auth" requires reader sign-in, which Thally does not support. Migrated as "simple" (no Try it). Set it to "interactive" to allow everyone.`);
     return "simple";
   }
   warn?.(`${where} ${JSON.stringify(value)} is not one of interactive, simple, none, auth and was dropped.`);
@@ -451,7 +451,7 @@ function normalizeExplicitHeadingIds(raw, warn, options = {}) {
         if (usable && options.headingMarkers) return `${heading} ${headingIdMarker(id)}`;
         if (usable) return `<a id="${id}"></a>
 ${heading}`;
-        warn?.(`Heading anchor {#${id}} is not a valid HTML id and was removed from "${heading.replace(/^\s*#+\s*/, "")}".`);
+        warn?.(`Heading anchor {#${id}} ${options.headingMarkers ? 'contains whitespace or "*/"' : "is not a valid HTML id"} and was removed from "${heading.replace(/^\s*#+\s*/, "")}".`);
         return heading;
       }
     }
@@ -485,7 +485,7 @@ function typesetQuotes(text2) {
   }).join("");
 }
 function plainHeadingText(source) {
-  return source.replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/<\/?[A-Za-z][^>]*>/g, "").replace(/`([^`]*)`/g, "$1").replace(/(\*\*|__|~~|\*)/g, "").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/\\([\\`*_{}[\]()#+.!&<>|~-])/g, "$1");
+  return source.replace(/\{\/\*[\s\S]*?\*\/\}/g, " ").replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/<\/?[A-Za-z][^>]*>/g, "").replace(/`([^`]*)`/g, "$1").replace(/(\*\*|__|~~|\*)/g, "").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/\\([\\`*_{}[\]()#+.!&<>|~-])/g, "$1");
 }
 function markMintlifyHeadings(body) {
   let fence;
@@ -4040,19 +4040,28 @@ function projectedTheme(value) {
   if (["almond", "palm"].includes(String(value))) return "minimal";
   return typeof value === "string" ? "default" : void 0;
 }
-function projectedColors(value) {
+function projectedColors(value, warnings) {
   const colors = objectValue2(value);
-  if (!colors) return void 0;
-  const hex = (entry) => {
+  if (!colors) {
+    if (value !== void 0) warnings.push({ code: "unsupported-config", message: "colors is not an object with a primary hex colour and was dropped.", source: "docs.json" });
+    return void 0;
+  }
+  const hex = (entry, key) => {
     const match = typeof entry === "string" ? /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(entry.trim()) : null;
-    if (!match) return void 0;
+    if (!match) {
+      if (entry !== void 0) warnings.push({ code: "unsupported-config", message: `colors.${key} ${JSON.stringify(entry)} is not a 3- or 6-digit hex colour (for example #16a34a) and was dropped.`, source: "docs.json" });
+      return void 0;
+    }
     const digits = match[1].length === 3 ? [...match[1]].map((digit) => digit + digit).join("") : match[1];
     return `#${digits.toLowerCase()}`;
   };
-  const primary = hex(colors.primary);
-  const light = hex(colors.light) ?? primary;
-  const dark = hex(colors.dark) ?? primary;
-  if (!primary) return void 0;
+  const primary = hex(colors.primary, "primary");
+  const light = hex(colors.light, "light") ?? primary;
+  const dark = hex(colors.dark, "dark") ?? primary;
+  if (!primary) {
+    if (colors.primary === void 0) warnings.push({ code: "unsupported-config", message: "colors has no primary hex colour, so none of its colours were migrated.", source: "docs.json" });
+    return void 0;
+  }
   return { light: { accent: primary, primary: dark ?? primary }, dark: { accent: light ?? primary, primary: light ?? primary } };
 }
 function projectedNavbar(value) {
@@ -4157,8 +4166,16 @@ function projectedCompatibleConfig(config, warnings) {
   if (droppedContextual.length > 0) {
     warnings.push({ code: "unsupported-config", message: `contextual.options entries not supported by the page menu were dropped: ${droppedContextual.map((option) => typeof option === "string" ? option : "custom entry").join(", ")}.`, source: "docs.json" });
   }
-  const metatagEntries = Object.entries(objectValue2(seo?.metatags) ?? {}).filter((entry) => /^[\w:.-]+$/.test(entry[0]) && typeof entry[1] === "string" && entry[1].length <= 1e3);
+  const rawMetatags = Object.entries(objectValue2(seo?.metatags) ?? {});
+  const httpEquivNames = /* @__PURE__ */ new Set(["refresh", "set-cookie", "location", "content-security-policy", "content-security-policy-report-only", "content-type", "default-style", "x-ua-compatible"]);
+  const validMetatag = (entry) => /^[\w:.-]+$/.test(entry[0]) && !entry[0].toLowerCase().startsWith("http-equiv") && !httpEquivNames.has(entry[0].toLowerCase()) && typeof entry[1] === "string" && entry[1].length <= 1e3 && ![...entry[1]].some((character) => character.charCodeAt(0) < 32);
+  const metatagEntries = rawMetatags.filter(validMetatag);
+  const droppedMetatags = rawMetatags.filter((entry) => !validMetatag(entry)).map(([key]) => key);
+  if (droppedMetatags.length > 0) {
+    warnings.push({ code: "unsupported-config", message: `seo.metatags entries were dropped because the name is not a plain meta name, is an http-equiv directive, or the value is not a string of at most 1000 characters: ${droppedMetatags.join(", ")}.`, source: "docs.json" });
+  }
   const projectedMetatags = metatagEntries.length > 0 ? Object.fromEntries(metatagEntries) : void 0;
+  const projectedColorsValue = projectedColors(config.colors, warnings);
   const iconLibrary = objectValue2(config.icons)?.library;
   const projectedIconLibrary = iconLibrary === void 0 ? "fontawesome" : ["lucide", "fontawesome", "tabler"].includes(String(iconLibrary)) ? String(iconLibrary) : void 0;
   const docsNavbar = projectedNavbar(config.navbar);
@@ -4189,7 +4206,7 @@ function projectedCompatibleConfig(config, warnings) {
   return {
     ...projectedTheme(config.theme) ? { theme: projectedTheme(config.theme) } : {},
     ...projectedContextual.length > 0 ? { contextual: { options: projectedContextual } } : {},
-    ...projectedColors(config.colors) ? { colors: projectedColors(config.colors) } : {},
+    ...projectedColorsValue ? { colors: projectedColorsValue } : {},
     ...projectedIconLibrary ? { icons: { library: projectedIconLibrary } } : {},
     ...bannerContent ? {
       banner: {
@@ -6075,6 +6092,68 @@ function withSpecRef(ref, specRef) {
   return `${specRef} ${ref.operation}`;
 }
 
+// src/spec-exclude.ts
+import { parse as parseYaml4, stringify as stringifyYaml } from "yaml";
+function specRefMatches(ref, specPath, specFilename, isDefault) {
+  const prefix = /^(?:(\S+)\s+)?(?:GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS|TRACE|WEBHOOK)\s/i.exec(`${ref} `)?.[1];
+  if (!prefix) return isDefault;
+  const wanted = prefix.replace(/^\/+/, "").toLowerCase();
+  const lowerPath = specPath.toLowerCase();
+  return lowerPath === wanted || lowerPath.endsWith(`/${wanted}`) || specFilename.toLowerCase() === wanted;
+}
+function operationKey(operation) {
+  const [first, ...rest] = operation.trim().split(/\s+/);
+  return `${first.toLowerCase()} ${rest.join(" ")}`;
+}
+function keysFor(spec, refs) {
+  return [...new Set(
+    refs.filter((ref) => specRefMatches(ref, spec.sourcePath, spec.filename, true)).map((ref) => splitOpenApiRef(ref)?.operation).filter((op) => !!op).map(operationKey)
+  )];
+}
+function withheldOperationKeys(spec, withheldRefs, keptRefs) {
+  const kept = keysFor(spec, keptRefs);
+  return { withheld: keysFor(spec, withheldRefs).filter((key) => !kept.includes(key)), kept };
+}
+function markExcluded(content, operationKeys, keptKeys = []) {
+  const untouched = { content, excluded: [] };
+  if (operationKeys.length === 0) return untouched;
+  const text2 = content.toString("utf8");
+  let doc;
+  try {
+    doc = parseYaml4(text2);
+  } catch {
+    return untouched;
+  }
+  if (!doc || typeof doc !== "object") return untouched;
+  const excluded = [];
+  for (const key of operationKeys) {
+    const [method, ...rest] = key.split(" ");
+    const name = rest.join(" ");
+    if (method === "webhook") {
+      const entry2 = doc.webhooks?.[name] ?? doc["x-webhooks"]?.[name];
+      if (entry2 && typeof entry2 === "object") {
+        entry2["x-excluded"] = true;
+        excluded.push(`WEBHOOK ${name}`);
+      }
+      continue;
+    }
+    const entry = doc.paths?.[name];
+    if (!entry || typeof entry !== "object") continue;
+    const target = typeof entry.$ref === "string" ? keptKeys.some((k) => k.slice(k.indexOf(" ") + 1) === name) ? void 0 : entry : entry[method];
+    if (target && typeof target === "object") {
+      target["x-excluded"] = true;
+      excluded.push(`${method.toUpperCase()} ${name}`);
+    }
+  }
+  if (excluded.length === 0) return untouched;
+  const out = text2.trimStart().startsWith("{") ? `${JSON.stringify(doc, null, 2)}
+` : stringifyYaml(doc);
+  return { content: Buffer.from(out), excluded };
+}
+function sharedSpecMessage(path, excluded = []) {
+  return excluded.length ? `OpenAPI spec ${path} is shared with access-restricted pages and is published, but ${excluded.length} operation(s) documented only on those pages were withheld from it (${excluded.join(", ")}). Review the rest of the spec before publishing.` : `OpenAPI spec ${path} is shared with access-restricted pages and is published; it may describe restricted endpoints. Review it before publishing.`;
+}
+
 // src/analytics.ts
 var GA4_ID = /^G-[A-Z0-9]{4,20}$/;
 var GTM_ID = /^GTM-[A-Z0-9]{4,12}$/;
@@ -7056,12 +7135,23 @@ function normalizedReferenceKey(value) {
 function exactReferenceKey(value) {
   return value.split(/[?#]/, 1)[0].replace(/^\/+/, "").replace(/\\/g, "/").replace(/\.(?:mdx?|rst|txt)$/i, "");
 }
-function specRefMatches(ref, specPath, specFilename, isDefault) {
-  const prefix = /^(?:(\S+)\s+)?(?:GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS|TRACE|WEBHOOK)\s/i.exec(`${ref} `)?.[1];
-  if (!prefix) return isDefault;
-  const wanted = prefix.replace(/^\/+/, "").toLowerCase();
-  const lowerPath = specPath.toLowerCase();
-  return lowerPath === wanted || lowerPath.endsWith(`/${wanted}`) || specFilename.toLowerCase() === wanted;
+function navigationOperationRefs(config) {
+  const refs = [];
+  const visit = (node) => {
+    if (typeof node === "string") {
+      if (splitOpenApiRef(node)) refs.push(node);
+    } else if (Array.isArray(node)) node.forEach(visit);
+    else if (node && typeof node === "object") {
+      if (navigationGateReason(node)) return;
+      Object.values(node).forEach(visit);
+    }
+  };
+  visit(config?.navigation);
+  return refs;
+}
+function excludeWithheldOperations(spec, withheldRefs, keptRefs) {
+  const { withheld, kept } = withheldOperationKeys(spec, withheldRefs, keptRefs);
+  return markExcluded(spec.content, withheld, kept);
 }
 var TOKEN_SEPARATORS = /[\s"'()<>[\]{}=,;:|\\/`*!?#&]+/;
 var PATH_SEPARATORS = /[\s"'()<>[\]{}=,;:|\\`*!?#&]+/;
@@ -7221,7 +7311,7 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs, p
   }
   return specs;
 }
-function rewriteMintlifyPageSpecRefs(pages, specs, remoteUrls, warnings) {
+function rewriteMintlifyPageSpecRefs(pages, specs, remoteUrls, warnings, explainMissing = () => "no such file was found") {
   for (const page of pages) {
     const ref = page.openapi ? splitOpenApiRef(page.openapi) : null;
     if (!ref?.specRef) continue;
@@ -7238,7 +7328,7 @@ function rewriteMintlifyPageSpecRefs(pages, specs, remoteUrls, warnings) {
     if (match) {
       page.openapi = withSpecRef(ref, specAssetPath(match.filename));
     } else {
-      warnings.push({ code: "unsupported-config", message: `Page "${page.id}" references the OpenAPI spec "${ref.specRef}", which is not referenced from docs.json and was not migrated; the page will not render an endpoint. Add the spec to a tab's api setting.`, source: page.source });
+      warnings.push({ code: "unsupported-config", message: `Page "${page.id}" references the OpenAPI spec "${ref.specRef}", which was not migrated (${explainMissing(key)}); the page will not render an endpoint.`, source: page.source });
     }
   }
 }
@@ -7263,7 +7353,7 @@ function slugifyApiSpecId(value) {
 function parseOpenApiOperationsForLinking(content) {
   let document;
   try {
-    document = parseYaml4(content.toString("utf8"));
+    document = parseYaml5(content.toString("utf8"));
   } catch {
     return [];
   }
@@ -7395,7 +7485,7 @@ function fernGeneratorsUnsupportedSpecPaths(config) {
 }
 function readFernGeneratorsConfig(path) {
   if (!existsSync5(path) || !lstatSync5(path).isFile() || lstatSync5(path).size > MAX_FERN_GENERATORS_BYTES) return null;
-  const parsed = parseYaml4(readFileSync5(path, "utf8"));
+  const parsed = parseYaml5(readFileSync5(path, "utf8"));
   return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
 }
 function fernOpenApiCandidateDirs(fernRoot, apiName, apiNameExplicit) {
@@ -7842,7 +7932,7 @@ function globalSnippetAliases(files, repositoryRoot, siteRoot) {
   }
   return aliases;
 }
-function repositoryAssetHref(value, currentFile, siteRoot, onReferenced) {
+function repositoryAssetHref(value, currentFile, siteRoot, onReferenced, onRootFallback) {
   const isBracketed = value.startsWith("<") && value.endsWith(">");
   const raw = isBracketed ? value.slice(1, -1) : value;
   if (!raw || raw.startsWith("#") || /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(raw)) return null;
@@ -7857,10 +7947,14 @@ function repositoryAssetHref(value, currentFile, siteRoot, onReferenced) {
   }
   if (!ASSET_EXTENSIONS.has(extname6(decodedPath).toLowerCase())) return null;
   try {
+    let usedRootFallback = false;
     let candidate = decodedPath.startsWith("/") ? resolveWithin(siteRoot, decodedPath.replace(/^\/+/, "")) : resolveWithinRoot(dirname4(currentFile), decodedPath, siteRoot);
     if (!decodedPath.startsWith("/") && !existsSync5(candidate)) {
       const fromRoot = resolveWithin(siteRoot, decodedPath.replace(/^(?:\.\/)+/, ""));
-      if (existsSync5(fromRoot)) candidate = fromRoot;
+      if (existsSync5(fromRoot)) {
+        candidate = fromRoot;
+        usedRootFallback = true;
+      }
     }
     const realRoot = realpathSync2(siteRoot);
     const realCandidate = realpathSync2(candidate);
@@ -7874,6 +7968,7 @@ function repositoryAssetHref(value, currentFile, siteRoot, onReferenced) {
     const onDiskRelative = relative5(realRoot, realpathSync2.native(candidate)).replace(/\\/g, "/");
     const onDisk = onDiskRelative.toLowerCase() === siteRelative.toLowerCase() ? normalizeAssetPath(onDiskRelative) : null;
     onReferenced?.(normalized, onDisk ?? void 0);
+    if (usedRootFallback) onRootFallback?.(decodedPath, normalized);
     const rewritten = `/${normalized}${suffix}`;
     return isBracketed ? `<${rewritten}>` : rewritten;
   } catch {
@@ -7892,12 +7987,12 @@ function rewriteFernIdRenameLinks(body, renames) {
     return text2.replace(/(\]\()\/([^\s)]+)(?=[\s)]|$)/g, (_match, prefix, target) => `${prefix}${rewriteTarget(`/${target}`)}`).replace(/(\bhref=")\/([^"]+)(")/g, (_match, prefix, target, suffix) => `${prefix}${rewriteTarget(`/${target}`)}${suffix}`);
   });
 }
-function rewriteRepositoryAssetLinks(body, currentFile, siteRoot, onReferenced) {
+function rewriteRepositoryAssetLinks(body, currentFile, siteRoot, onReferenced, onRootFallback) {
   return body.replace(/(!?\[[^\]]*\]\()(<[^>]+>|[^)\s]+)([^)]*\))/g, (original, opening, destination, closing) => {
-    const rewritten = repositoryAssetHref(destination, currentFile, siteRoot, onReferenced);
+    const rewritten = repositoryAssetHref(destination, currentFile, siteRoot, onReferenced, onRootFallback);
     return rewritten ? `${opening}${rewritten}${closing}` : original;
   }).replace(/\b(src|img|image|href)=(['"])([^'"]+)\2/g, (original, property, quote, destination) => {
-    const rewritten = repositoryAssetHref(destination, currentFile, siteRoot, onReferenced);
+    const rewritten = repositoryAssetHref(destination, currentFile, siteRoot, onReferenced, onRootFallback);
     return rewritten ? `${property}=${quote}${rewritten}${quote}` : original;
   });
 }
@@ -8706,6 +8801,8 @@ function migrateRepository(options) {
     if (platform === "mintlify" && mintlifyProjectRoot) {
       page.body = rewriteRepositoryAssetLinks(page.body, file.absolutePath, mintlifyProjectRoot, (assetPath, onDiskSpelling) => {
         pageAssetReferences.push(publicAssetKey(onDiskSpelling ?? assetPath));
+      }, (spelled, used) => {
+        warnings.push({ code: "unsupported-config", message: `"${spelled}" was not found beside this page; the file "${used}" in the site root was used instead and will be published.`, source: file.relativePath });
       });
     }
     if (platform === "fern" && fernProjectRoot) {
@@ -9158,21 +9255,31 @@ function migrateRepository(options) {
       rewriteApiLinksInPages(pages, operationLinks, prefixLandings, warnings);
     }
   } else if (platform === "mintlify") {
-    const warnSharedSpec = (path) => {
-      warnings.push({
-        code: "gated-page",
-        message: `OpenAPI spec ${path} is shared with access-restricted pages and is published; it may describe restricted endpoints. Review it before publishing.`,
-        source: path
-      });
+    const warnSharedSpec = (path, excluded = []) => {
+      warnings.push({ code: "gated-page", message: sharedSpecMessage(path, excluded), source: path });
     };
+    const keptSpecRefs = [...publishedSpecRefs, ...navigationOperationRefs(mintlifyConfig)];
     const allSpecs = resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteApiSpecs, pages);
+    for (const remote of remoteApiSpecs) {
+      const { withheld, kept } = withheldOperationKeys({ sourcePath: remote.url, filename: remote.url }, withheldSpecRefs, keptSpecRefs);
+      if (withheld.length > 0) {
+        remote.withheldOperations = withheld;
+        remote.keptOperations = kept;
+      }
+    }
+    const withheldOperations = /* @__PURE__ */ new Map();
+    for (const spec of allSpecs) {
+      const result = excludeWithheldOperations(spec, withheldSpecRefs, keptSpecRefs);
+      spec.content = result.content;
+      withheldOperations.set(spec, result.excluded);
+    }
     const resolvedSpecs = allSpecs.filter((spec) => !spec.pageOnly);
     const pageOnlySpecs = allSpecs.filter((spec) => spec.pageOnly);
     for (const spec of resolvedSpecs) {
       if (!assets.some((asset) => asset.path === specAssetPath(spec.filename))) {
         assets.push(specAsset(spec.filename, spec.content));
       }
-      if (withheldSpecRefs.some((ref) => specRefMatches(ref, spec.sourcePath, spec.filename, true))) warnSharedSpec(spec.sourcePath);
+      if (withheldSpecRefs.some((ref) => specRefMatches(ref, spec.sourcePath, spec.filename, true))) warnSharedSpec(spec.sourcePath, withheldOperations.get(spec));
     }
     let pageSpecs = resolvedSpecs;
     if (resolvedSpecs.length > 0) {
@@ -9191,24 +9298,35 @@ function migrateRepository(options) {
           quarantinedFiles.push({ path: `${QUARANTINE_DIRECTORY}/assets/${specAssetPath(filename)}`, content: readFileSync5(fallback.absolutePath) });
           withheldAssetCount++;
         } else {
+          const pruned = excludeWithheldOperations({ sourcePath: fallback.relativePath, filename, content: readFileSync5(fallback.absolutePath) }, withheldSpecRefs, keptSpecRefs);
           if (!assets.some((asset) => asset.path === specAssetPath(filename))) {
-            assets.push(specAsset(filename, readFileSync5(fallback.absolutePath)));
+            assets.push(specAsset(filename, pruned.content));
           }
           docsConfig = injectOpenApiSpecs(docsConfig, [{ filename }]);
           pageSpecs = [{ filename, sourcePath: fallback.relativePath }];
-          if (withheldSpecRefs.some(matches)) warnSharedSpec(fallback.relativePath);
+          if (withheldSpecRefs.some(matches)) warnSharedSpec(fallback.relativePath, pruned.excluded);
         }
       }
     }
     for (const spec of pageOnlySpecs) {
       if (!assets.some((asset) => asset.path === specAssetPath(spec.filename))) assets.push(specAsset(spec.filename, spec.content));
-      if (withheldSpecRefs.some((ref) => specRefMatches(ref, spec.sourcePath, spec.filename, true))) warnSharedSpec(spec.sourcePath);
+      if (withheldSpecRefs.some((ref) => specRefMatches(ref, spec.sourcePath, spec.filename, true))) warnSharedSpec(spec.sourcePath, withheldOperations.get(spec));
     }
     if (pageOnlySpecs.length > 0) {
       docsConfig = injectOpenApiSpecs(docsConfig, pageOnlySpecs, warnings);
       pageSpecs = [...pageSpecs, ...pageOnlySpecs];
     }
-    rewriteMintlifyPageSpecRefs(pages, pageSpecs, new Set(remoteApiSpecs.map((spec) => spec.url)), warnings);
+    const explainMissingSpec = (key) => {
+      const sameName = scannedFiles.find((file) => file.relativePath.toLowerCase() === key.toLowerCase());
+      if (sameName && sameName.relativePath !== key) return `paths are case-sensitive; the file is at "${sameName.relativePath}"`;
+      if (sameName && mintignoreMatcher?.ignores(sameName.relativePath)) return "the file is excluded by .mintignore";
+      try {
+        if (lstatSync5(resolvePath(repositoryDir, key)).isSymbolicLink()) return "the file is a symbolic link, which is never followed";
+      } catch {
+      }
+      return sameName ? "the file could not be read as an OpenAPI document" : `no file exists at "${key}"`;
+    };
+    rewriteMintlifyPageSpecRefs(pages, pageSpecs, new Set(remoteApiSpecs.map((spec) => spec.url)), warnings, explainMissingSpec);
   }
   if (platform === "mintlify") {
     const sources = new Set((docsConfig.redirects ?? []).map((redirect) => redirect.source));
@@ -9750,7 +9868,7 @@ import remarkMdx3 from "remark-mdx";
 import remarkParse3 from "remark-parse";
 import TurndownService from "turndown";
 import { unified as unified3 } from "unified";
-import { parse as parseYaml5, stringify as stringifyYaml } from "yaml";
+import { parse as parseYaml6, stringify as stringifyYaml2 } from "yaml";
 var DEFAULT_MAX_PAGES = 1e3;
 var DEFAULT_MAX_TOTAL_BYTES = 1e8;
 var MAX_DISCOVERED_URLS = 5e3;
@@ -10475,7 +10593,7 @@ function extractEmbeddedOpenApi(content) {
   const match = fencePattern.exec(content);
   if (!match) return { content };
   try {
-    const parsed = parseYaml5(match[5], { maxAliasCount: 50 });
+    const parsed = parseYaml6(match[5], { maxAliasCount: 50 });
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return { content };
     const document = parsed;
     if (typeof document.openapi !== "string" && typeof document.swagger !== "string") return { content };
@@ -10589,7 +10707,7 @@ function mergeEmbeddedOpenApi(fragments) {
   if (Object.keys(combinedPaths).length === 0) return null;
   if (Object.keys(combinedComponents).length === 0) delete combined.components;
   if (tags.size > 0) combined.tags = [...tags.values()];
-  return new TextEncoder().encode(stringifyYaml(combined));
+  return new TextEncoder().encode(stringifyYaml2(combined));
 }
 function htmlPage(document, id) {
   const $ = load2(document.body);
@@ -11328,7 +11446,7 @@ import { createHash as createHash3 } from "crypto";
 import { lookup } from "dns/promises";
 import { request } from "https";
 import { isIP } from "net";
-import { parse as parseYaml6 } from "yaml";
+import { parse as parseYaml7 } from "yaml";
 var MAX_SPEC_BYTES = 25e6;
 var MAX_REDIRECTS = 3;
 function isPublicAddress(address, family) {
@@ -11424,7 +11542,7 @@ async function downloadSpec(value, fetcher) {
 }
 function parseOpenApi(content, extension) {
   const text2 = content.toString("utf8");
-  const parsed = extension === "yaml" || !text2.trimStart().startsWith("{") ? parseYaml6(text2) : JSON.parse(text2);
+  const parsed = extension === "yaml" || !text2.trimStart().startsWith("{") ? parseYaml7(text2) : JSON.parse(text2);
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("OpenAPI spec is not an object.");
   const document = parsed;
   if (typeof document.openapi !== "string" || !/^3\./.test(document.openapi)) {
@@ -11482,7 +11600,10 @@ async function hydrateRemoteApiSpecs(bundle, fetcher) {
     try {
       const url = validatedSpecUrl(reference.url);
       const extension = /\.ya?ml$/i.test(url.pathname) ? "yaml" : "json";
-      const body = await downloadSpec(reference.url, fetcher);
+      const downloaded = await downloadSpec(reference.url, fetcher);
+      const pruned = markExcluded(downloaded, reference.withheldOperations ?? [], reference.keptOperations);
+      const body = pruned.content;
+      if (reference.withheldOperations?.length) warnings.push({ code: "gated-page", message: sharedSpecMessage(reference.url, pruned.excluded), source: reference.url });
       const operations = parseOpenApi(body, extension);
       const filename = `openapi-${createHash3("sha256").update(reference.url).digest("hex").slice(0, 12)}.${extension}`;
       assets.push({ path: `openapi/${filename}`, content: body, projectRelative: true });