@thallylabs/migrate 0.2.42 → 0.2.44

package/dist/url-migration.js

@@ -1,10 +1,10 @@
 // src/url-run.ts
-import { createHash as createHash4 } from "crypto";
+import { createHash as createHash5 } from "crypto";
 import { load as load7 } from "cheerio";
 import { parse as parse2, postprocess, preprocess } from "micromark";
-import remarkParse4 from "remark-parse";
+import remarkParse5 from "remark-parse";
 import remarkMdx4 from "remark-mdx";
-import { unified as unified4 } from "unified";
+import { unified as unified5 } from "unified";
 
 // src/navigation.ts
 import { existsSync, lstatSync, readFileSync, realpathSync as realpathSync2 } from "fs";
@@ -56,6 +56,32 @@ function playgroundDisplay(value, where, warn) {
   return void 0;
 }
 
+// src/redirects.ts
+function trimTrailingSlashes(route) {
+  let end = route.length;
+  while (end > 0 && route[end - 1] === "/") end--;
+  return route.slice(0, end);
+}
+function exactRoute(route) {
+  return route.startsWith("/") && !/[?:*#()[\]{}]/.test(route) ? trimTrailingSlashes(route) || "/" : null;
+}
+function literalRoute(route) {
+  return exactRoute(route)?.toLowerCase() ?? null;
+}
+function resolveDotSegments(route) {
+  const segments = [];
+  for (const segment of route.split("/").slice(1)) {
+    const dots = segment.replace(/%2e/gi, ".");
+    if (dots === "..") segments.pop();
+    else if (dots !== ".") segments.push(segment);
+  }
+  return `/${segments.join("/")}`;
+}
+function destinationRoute(destination) {
+  const route = destination.startsWith("//") ? null : exactRoute(destination.split(/[?#]/, 1)[0]);
+  return route === null ? null : resolveDotSegments(route);
+}
+
 // src/navigation.ts
 function titleCase(value) {
   return value.split(/[-_]/).map((word) => ["api", "cli", "sdk", "ui"].includes(word.toLowerCase()) ? word.toUpperCase() : word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
@@ -497,15 +523,15 @@ function createMigrationAssetCache() {
     load(url, acquire) {
       const existing = get(url);
       if (existing) return existing;
-      const request = Promise.resolve().then(acquire).then((asset) => {
+      const request2 = Promise.resolve().then(acquire).then((asset) => {
         pending.delete(url);
         return remember(url, asset);
       }, (error) => {
         pending.delete(url);
         throw error;
       });
-      pending.set(url, request);
-      return request;
+      pending.set(url, request2);
+      return request2;
     },
     delete(url) {
       settled.delete(url);
@@ -1270,9 +1296,9 @@ function recoverFlightArticleCode($, root) {
   const projectionBudget = expansionBudget();
   recoverFlightTreeTabs($, root, projectionBudget);
   const renderedHeadings = root.find("h1,h2,h3,h4,h5,h6").toArray().filter((node) => $(node).attr("data-thally-static-disclosure-heading") === void 0);
-  const headingText = renderedHeadings.map((node) => labelText($(node).text()));
+  const headingText2 = renderedHeadings.map((node) => labelText($(node).text()));
   const existingCode = root.find("pre").toArray().map((node) => renderedCode($, node));
-  if (!headingText.length || !existingCode.length) return;
+  if (!headingText2.length || !existingCode.length) return;
   const prose = root.clone();
   prose.find("pre,button,script,style,nav,footer,aside").remove();
   const renderedProse = labelText(prose.text());
@@ -1285,7 +1311,7 @@ function recoverFlightArticleCode($, root) {
       const anchor = /\s+\[#([A-Za-z\d_.:-]+)\]$/.exec(text2);
       return anchor && $(renderedHeadings[index]).attr("id") === anchor[1] ? text2.slice(0, anchor.index) : text2;
     });
-    if (JSON.stringify(headings) !== JSON.stringify(headingText)) continue;
+    if (JSON.stringify(headings) !== JSON.stringify(headingText2)) continue;
     let proseCursor = 0;
     let hasMatchingProse = true;
     for (const paragraph of nodes.filter((node) => node.type === "paragraph" || node.type === "tableCell")) {
@@ -1884,29 +1910,42 @@ function projectMigrationMedia(html, base) {
 }
 
 // src/url-identity.ts
-import { createHash as createHash3 } from "crypto";
+import { createHash as createHash4 } from "crypto";
 import { load as load6 } from "cheerio";
 
 // src/url.ts
 import { load as load5 } from "cheerio";
 import remarkMdx3 from "remark-mdx";
-import remarkParse3 from "remark-parse";
+import remarkParse4 from "remark-parse";
 import TurndownService from "turndown";
-import { unified as unified3 } from "unified";
-import { parse as parseYaml2, stringify as stringifyYaml } from "yaml";
+import { unified as unified4 } from "unified";
+import { parse as parseYaml3, stringify as stringifyYaml2 } from "yaml";
+
+// src/url-openapi.ts
+import { createHash as createHash2 } from "crypto";
+
+// src/remote-spec.ts
+import { lookup } from "dns/promises";
+import { request } from "https";
+import { isIP } from "net";
+import { createGunzip } from "zlib";
+
+// src/spec-exclude.ts
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
 
 // src/analytics.ts
 var HOSTNAME_LABEL = "[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?";
 var HOSTNAME = new RegExp(`^${HOSTNAME_LABEL}(?:\\.${HOSTNAME_LABEL})*$`);
 
 // src/mdx.ts
+import { analyze } from "eslint-scope";
 import { posix } from "path";
 import { compileSync } from "@mdx-js/mdx";
 import { nameToEmoji } from "gemoji";
 import remarkGfm2 from "remark-gfm";
 import remarkMdx2 from "remark-mdx";
-import remarkParse2 from "remark-parse";
-import { unified as unified2 } from "unified";
+import remarkParse3 from "remark-parse";
+import { unified as unified3 } from "unified";
 
 // src/builtin-components.ts
 var THALLY_BUILTIN_COMPONENTS = /* @__PURE__ */ new Set([
@@ -2343,13 +2382,13 @@ function unresolvedExpressionNames(expression, pageNames) {
 }
 
 // src/frontmatter.ts
-import { parse as parseYaml } from "yaml";
+import { parse as parseYaml2 } from "yaml";
 function salvageFrontmatterLines(matter) {
   const data = {};
   for (const line of matter.split(/\r?\n/)) {
     if (!/^[A-Za-z_][\w-]*:\s?/.test(line)) continue;
     try {
-      const parsedLine = parseYaml(line);
+      const parsedLine = parseYaml2(line);
       if (parsedLine && typeof parsedLine === "object" && !Array.isArray(parsedLine)) {
         Object.assign(data, parsedLine);
       }
@@ -2373,7 +2412,7 @@ function parseFrontmatter(raw) {
     return { content, data: {} };
   }
   try {
-    const parsed = parseYaml(matter);
+    const parsed = parseYaml2(matter);
     return {
       content,
       data: parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {}
@@ -2387,18 +2426,136 @@ function parseFrontmatter(raw) {
   }
 }
 
+// src/source-styles.ts
+import postcss from "postcss";
+import selectorParser from "postcss-selector-parser";
+import ts2 from "typescript";
+var CONTENT_CONTAINER = ".thally-docs-prose";
+var SOURCE_PAGE_ATTRIBUTE = "data-thally-source-page";
+var SCOPE = `:where(${CONTENT_CONTAINER}, [${SOURCE_PAGE_ATTRIBUTE}])`;
+
+// src/fence-meta.ts
+import remarkParse2 from "remark-parse";
+import { unified as unified2 } from "unified";
+function delimitedEnd(meta, start) {
+  const opening = meta[start];
+  if (opening === '"' || opening === "'") {
+    let close = start + 1;
+    while (close < meta.length && meta[close] !== opening) close += meta[close] === "\\" && meta[close + 1] === opening ? 2 : 1;
+    return close < meta.length ? close + 1 : close;
+  }
+  if (opening !== "{") return void 0;
+  let depth = 0;
+  let quote = "";
+  for (let index = start; index < meta.length; index++) {
+    const char = meta[index];
+    if (quote) {
+      if (char === quote) quote = "";
+    } else if (char === '"' || char === "'") quote = char;
+    else if (char === "{") depth++;
+    else if (char === "}" && --depth === 0) return index + 1;
+  }
+  return meta.length;
+}
+function tokens(meta) {
+  const result = [];
+  let index = 0;
+  while (index < meta.length) {
+    if (/\s/.test(meta[index])) {
+      index++;
+      continue;
+    }
+    const start = index;
+    const delimited = delimitedEnd(meta, index);
+    if (delimited !== void 0) {
+      result.push({ start, end: delimited, value: meta.slice(start, delimited), quoted: meta[start] !== "{", group: meta[start] === "{" });
+      index = delimited;
+      continue;
+    }
+    const key = /^([A-Za-z][\w-]*)=/.exec(meta.slice(index));
+    if (key) {
+      index += key[0].length;
+      const groupEnd = delimitedEnd(meta, index);
+      if (groupEnd !== void 0) index = groupEnd;
+      else while (index < meta.length && !/\s/.test(meta[index])) index++;
+      result.push({ start, end: index, key: key[1], value: meta.slice(start, index) });
+      continue;
+    }
+    while (index < meta.length && !/\s/.test(meta[index])) {
+      if (index > start && meta[index] === "{" && /^\{[\d,\s-]*\}/.test(meta.slice(index))) break;
+      index++;
+    }
+    result.push({ start, end: index, value: meta.slice(start, index) });
+  }
+  return result;
+}
+function normalizeMintlifyCodeFences(body, warn) {
+  const tree = unified2().use(remarkParse2).parse(body);
+  const edits = [];
+  const removed = /* @__PURE__ */ new Set();
+  const unknown = /* @__PURE__ */ new Set();
+  const supported = /* @__PURE__ */ new Set(["title", "filename", "framework", "tag", "icon", "highlight", "focus", "wrap", "lines", "expandable", "nocopy"]);
+  function visit(node) {
+    if (node.type === "code" && node.position?.start.offset !== void 0) {
+      const start = node.position.start.offset;
+      const lineEnd = body.indexOf("\n", start);
+      const end = lineEnd < 0 ? body.length : lineEnd;
+      const line = body.slice(start, end);
+      const opening = /^([`~]{3,}[^\s]*)([ \t]+)(.*?)(\r?)$/.exec(line);
+      if (opening) {
+        const meta = opening[3];
+        const kept = tokens(meta).filter((token) => {
+          if (token.key === "theme" || !token.key && !token.quoted && !token.group && token.value === "twoslash") {
+            removed.add(token.key ?? token.value);
+            return false;
+          }
+          if (token.key && !supported.has(token.key)) unknown.add(token.key);
+          return true;
+        });
+        const normalized = kept.map((token) => meta.slice(token.start, token.end)).join(" ");
+        if (normalized !== meta && kept.length !== tokens(meta).length) edits.push({ start, end, value: `${opening[1]}${normalized ? ` ${normalized}` : ""}${opening[4]}` });
+      }
+    }
+    for (const child of node.children ?? []) visit(child);
+  }
+  visit(tree);
+  if (removed.size) warn?.(`Removed unsupported Mintlify code-fence options: ${[...removed].join(", ")}. Code examples and supported display options were preserved.`);
+  if (unknown.size) warn?.(`Unsupported Mintlify code-fence options are ignored: ${[...unknown].join(", ")}. Review these renderer-specific options.`);
+  return edits.sort((a, b) => b.start - a.start).reduce((text2, edit) => text2.slice(0, edit.start) + edit.value + text2.slice(edit.end), body);
+}
+
 // src/mdx.ts
 function titleFromId(id) {
   const value = id.split("/").at(-1) ?? id;
   if (value === "introduction") return "Introduction";
   return value.split(/[-_]/).filter(Boolean).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
 }
-var descriptionParser = unified2().use(remarkParse2).use(remarkGfm2).use(remarkMdx2);
-function plainText(node) {
+var descriptionParser = unified3().use(remarkParse3).use(remarkGfm2).use(remarkMdx2);
+function plainText(node, elements) {
+  if (elements && (node.type === "mdxJsxTextElement" || node.type === "mdxJsxFlowElement")) {
+    elements.found = true;
+    return "";
+  }
   if (node.type === "text" || node.type === "inlineCode") return node.value ?? "";
   if (node.type === "image") return node.alt ?? "";
   if (node.type === "break") return " ";
-  return (node.children ?? []).map(plainText).join("");
+  return (node.children ?? []).map((child) => plainText(child, elements)).join("");
+}
+function headingText(content, definitions, elements) {
+  const references = [...content.matchAll(/\[([^\]\n]+)\]/g)].map((match) => definitions?.get(match[1].trim().replace(/\s+/g, " ").toLowerCase()) ?? "").join("\n");
+  try {
+    return plainText(descriptionParser.parse(`# ${content}
+
+${references}`), elements).trim();
+  } catch {
+    return content;
+  }
+}
+function mdxTextWithoutInlineElements(content, definitions) {
+  if (!/<[A-Za-z]/.test(content)) return void 0;
+  const elements = { found: false };
+  const text2 = headingText(content, definitions, elements);
+  return elements.found && /[\p{L}\p{M}\p{N}]/u.test(text2) ? text2 : void 0;
 }
 function firstParagraph(content) {
   function findParagraph(node) {
@@ -2418,6 +2575,23 @@ function firstParagraph(content) {
     return "";
   }
 }
+var linkParser = unified3().use(remarkParse3);
+function withoutMarkdownLinks(text2) {
+  const links = [];
+  const collect = (node) => {
+    if (node.type === "link") {
+      const first = node.children?.[0]?.position?.start.offset;
+      const last = node.children?.at(-1)?.position?.end.offset;
+      const start = node.position?.start.offset;
+      const end = node.position?.end.offset;
+      if (start !== void 0 && end !== void 0) links.push({ start, end, textStart: first ?? start, textEnd: last ?? start });
+      return;
+    }
+    for (const child of node.children ?? []) collect(child);
+  };
+  collect(linkParser.parse(text2));
+  return links.reduceRight((result, link) => result.slice(0, link.start) + result.slice(link.textStart, link.textEnd) + result.slice(link.end), text2);
+}
 function docusaurusAdmonitionTag(kind) {
   if (kind === "danger") return "Error";
   if (kind === "info") return "Info";
@@ -2622,9 +2796,9 @@ ${trimmed.slice(0, marker).trimEnd()}`;
 function headingIdMarker(id) {
   return `{/* #${id} */}`;
 }
-var HEADING_ID_WORD = /[\p{L}\p{M}\p{N}_+&/@\u2019\u201c\u201d\u2014\u2013\u2192]/u;
+var HEADING_ID_WORD = /[\p{L}\p{M}\p{N}_+&/@%=<>|\u2019\u201c\u201d\u2014\u2013\u2192\u2026]/u;
 function mintlifyHeadingSlug(text2) {
-  const chars = [...text2.replace(/[\u200b*]/g, "").normalize("NFC").trim().toLowerCase()];
+  const chars = [...text2.replace(/[\u200b*]/g, "").replace(/(?<=[\p{L}\p{M}\p{N}_])\(s\)(?![\p{L}\p{M}\p{N}_])/gu, "s").normalize("NFC").trim().toLowerCase()];
   const isWord = (char) => char !== void 0 && HEADING_ID_WORD.test(char);
   let id = "";
   let afterDash = false;
@@ -2636,11 +2810,11 @@ function mintlifyHeadingSlug(text2) {
     if (isWord(char)) {
       id += char;
       afterDash = false;
-    } else if (/[\s-]/.test(char) || char === "." && isWord(after) || char === "(" && isWord(before) && (isWord(after) || after === "{") || char === ")" && after !== void 0 && !/\s/.test(after)) {
+    } else if (/[\s-]/.test(char) || char === "." && (isWord(after) || after === ",") || char === "(" && isWord(before) && (isWord(after) || after === "{") || char === ")" && after !== void 0 && !/\s/.test(after)) {
       if (id && !afterDash) id += "-";
       afterDash = true;
       endsWithDash = true;
-    } else if (char === "{" || char === ":" || char === '"') {
+    } else if (char === "{" || char === ":" || char === '"' || char === ",") {
       afterDash = false;
     }
   });
@@ -2650,17 +2824,77 @@ function thallyHeadingSlug(text2) {
   return text2.normalize("NFC").toLowerCase().replace(/[^\p{L}\p{M}\p{N}]+/gu, "-").replace(/(^-|-$)/g, "");
 }
 function typesetQuotes(text2) {
+  const opensClosed = text2.startsWith('"') && !text2.trimEnd().endsWith('"');
   return text2.split(/(`[^`]*`|<[^>]*>|\]\([^)]*\))/).map((part, index) => {
     if (index % 2) return part;
-    return part.replace(/(^|[\s([{\u2014\u2013])"/g, "$1\u201C").replace(/"/g, "\u201D").replace(/(^|[\s([{\u2014\u2013\u201c])'(?=\S)/g, "$1\u2018").replace(/'/g, "\u2019");
+    return part.replace(/(^|[\s([{\u2014\u2013])"/g, (match, before) => opensClosed && index === 0 && before === "" ? match : `${before}\u201C`).replace(/"/g, "\u201D").replace(/(^|[\s([{\u2014\u2013\u201c])'(?=\S)(?!&lt;|<)/g, "$1\u2018").replace(/'/g, "\u2019");
   }).join("");
 }
+function typesetEllipses(text2) {
+  return text2.split(/(`[^`]*`|<[^>]*>|\]\([^)]*\))/).map((part, index) => index % 2 ? part : part.replace(/\.{3}/g, "\u2026")).join("");
+}
 function plainHeadingText(source) {
-  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");
+  const unlinked = !source.includes("`") ? source : source.replace(/(`[^`]*`)|!?\[((?:`[^`]*`|[^\]`])*)\]\([^)]*\)/g, (_match, code, text2 = "") => code ?? text2);
+  return unlinked.split(/(`[^`]*`)/).map((part, index) => index % 2 ? part.slice(1, -1) : part.replace(/\{\/\*[\s\S]*?\*\/\}/g, " ").replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/<\/?[A-Za-z][^>]*>/g, "").replace(/(?<!\\)(\*\*|__|~~|\*)/g, "").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/\\([\\`*_{}[\]()#+.!&<>|~-])/g, "$1")).join("");
+}
+function staticAttributeString(value) {
+  if (typeof value === "string") return value;
+  const expression = value?.value;
+  if (typeof expression !== "string") return void 0;
+  return expression.match(/^\s*(?:"([^"\\]*)"|'([^'\\]*)'|`((?:[^`\\$]|\$(?!\{))*)`)\s*$/)?.slice(1).find((part) => part !== void 0);
+}
+function pageIdClaims(body) {
+  let tree;
+  try {
+    tree = descriptionParser.parse(body);
+  } catch {
+    return { free: () => false };
+  }
+  const owners = /* @__PURE__ */ new Map();
+  const headingLines = /* @__PURE__ */ new Set();
+  let claims = 0;
+  const root = (id) => id.toLowerCase().replace(/-\d+$/, "");
+  const claim = (owner, ...ids) => {
+    for (const id of ids) {
+      const key = root(id);
+      const held = owners.get(key);
+      if (!key) continue;
+      if (!held) owners.set(key, { owner, shared: false });
+      else if (held.owner !== owner) held.shared = true;
+    }
+  };
+  const visit = (node) => {
+    const line = node.position?.start.line ?? 0;
+    if (node.type === "heading" && (node.depth ?? 0) >= 2) {
+      headingLines.add(line);
+      const text2 = typesetQuotes(plainText(node));
+      claim(`heading ${line}`, mintlifyHeadingSlug(text2), thallyHeadingSlug(text2), thallyHeadingSlug(plainText(node, { found: false })));
+      for (const child of node.children ?? []) {
+        const authored = child.type === "mdxTextExpression" ? child.value?.match(/^\s*\/\*\s*#(\S+?)\s*\*\/\s*$/)?.[1] : void 0;
+        if (authored) claim(`claim ${claims++}`, authored);
+      }
+    } else if (node.type === "mdxJsxFlowElement" || node.type === "mdxJsxTextElement") {
+      for (const { type, name, value } of node.attributes ?? []) {
+        const text2 = type === "mdxJsxAttribute" ? staticAttributeString(value) : void 0;
+        if (text2 === void 0) continue;
+        if (name === "id") claim(`claim ${claims++}`, text2);
+        else if (name === "title") claim(`claim ${claims++}`, mintlifyHeadingSlug(text2), thallyHeadingSlug(text2));
+      }
+    }
+    for (const child of node.children ?? []) visit(child);
+  };
+  visit(tree);
+  return {
+    free: (id, line) => {
+      const held = owners.get(root(id));
+      return headingLines.has(line) && (!held || held.owner === `heading ${line}` && !held.shared);
+    }
+  };
 }
 function markMintlifyHeadings(body) {
   let fence;
-  return body.split("\n").map((line) => {
+  let claims;
+  return body.split("\n").map((line, index) => {
     const marker = line.match(/^ {0,3}(`{3,}|~{3,})/);
     if (marker) {
       if (!fence) fence = marker[1];
@@ -2674,8 +2908,13 @@ function markMintlifyHeadings(body) {
     const source = typesetQuotes(explicit ? explicit[1] : heading[2]);
     if (explicit) return `${heading[1]}${source}${explicit[2]}`;
     const text2 = plainHeadingText(source);
-    const id = mintlifyHeadingSlug(text2);
-    return `${heading[1]}${source}${id && id !== thallyHeadingSlug(text2) ? ` ${headingIdMarker(id)}` : ""}`;
+    const id = mintlifyHeadingSlug(plainHeadingText(typesetEllipses(source)));
+    let marked = id !== thallyHeadingSlug(text2);
+    if (id && !marked) {
+      const visible = mdxTextWithoutInlineElements(source);
+      if (visible !== void 0 && id !== thallyHeadingSlug(visible)) marked = (claims ??= pageIdClaims(body)).free(id, index + 1);
+    }
+    return `${heading[1]}${source}${id && marked ? ` ${headingIdMarker(id)}` : ""}`;
   }).join("\n");
 }
 var GLOBAL_DOCUSARUS_COMPONENTS = /* @__PURE__ */ new Set([
@@ -2691,6 +2930,7 @@ function removeGlobalDocusaurusImports(body) {
     (statement, component) => GLOBAL_DOCUSARUS_COMPONENTS.has(component) ? "" : statement
   ));
 }
+var PLAIN_TEXT = new RegExp("^\\p{L}(?:[\\p{L}\\p{N} ,.;'?%$=+-]*[\\p{L}\\p{N}.])?$", "u");
 function leadingPageHeading(body) {
   if (!/^ {0,3}(?:#(?:[ \t]|$)|=+[ \t\r]*$)/m.test(body)) return void 0;
   try {
@@ -2803,6 +3043,27 @@ function normalizeFernFileTrees(body) {
     }
   ));
 }
+function unwrapHtmlCommentInMdxComment(body) {
+  return replaceOutsideCode(body, (text2) => {
+    const opener = /\{\s*\/\*\s*<!--/g;
+    const closer = /\s*\*\/\s*\}/y;
+    let out = "";
+    let copied = 0;
+    let dash = -2;
+    let star = -2;
+    for (let found = opener.exec(text2); found; found = opener.exec(text2)) {
+      const inner = opener.lastIndex;
+      if (dash !== -1 && dash < inner) dash = text2.indexOf("-->", inner);
+      if (dash === -1) break;
+      if (star !== -1 && star < inner) star = text2.indexOf("*/", inner);
+      closer.lastIndex = dash + 3;
+      if (star !== -1 && star < dash || !closer.test(text2)) continue;
+      out += `${text2.slice(copied, found.index)}{/*${text2.slice(inner, dash)}*/}`;
+      copied = opener.lastIndex = closer.lastIndex;
+    }
+    return out + text2.slice(copied);
+  });
+}
 function normalizeFernCallouts(body) {
   return replaceOutsideCode(body, (whole) => {
     const openTags = [];
@@ -3367,6 +3628,7 @@ function normalizeMdx(body, platform, unwrapMdxCodeBlocks = true) {
     rewritten = rewritten.replace(/^\n{2,}/, "\n");
   }
   if (runMintlify) rewritten = normalizeMintlifyParameterAnchors(rewritten);
+  rewritten = unwrapHtmlCommentInMdxComment(rewritten);
   rewritten = replaceOutsideCode(rewritten, (segment) => {
     let result = convertHtmlStyleAttributes(segment).replace(/<!--([\s\S]*?)-->/g, (_match, content) => mdxComment(content)).replace(/<Danger(\s[^>]*)?>/g, "<Error$1>").replace(/<\/Danger>/g, "</Error>").replace(/<Warn(\s[^>]*)?>/g, "<Warning$1>").replace(/<\/Warn>/g, "</Warning>").replace(/<Tree\.Folder/g, "<Folder").replace(/<\/Tree\.Folder>/g, "</Folder>").replace(/<Tree\.File/g, "<File").replace(/<\/Tree\.File>/g, "</File>");
     if (runDocusaurus) {
@@ -3396,8 +3658,15 @@ function normalizeMdx(body, platform, unwrapMdxCodeBlocks = true) {
   }
   return normalizeFlowParagraphContainers(normalized);
 }
+var SITE_PATH_LINK = /^\/(?:[A-Za-z0-9._~-]+(?:\/[A-Za-z0-9._~-]+)*\/?)?(?:\?(?:[A-Za-z0-9._~=&-]|%[0-9A-Fa-f]{2})*)?(?:#[A-Za-z0-9._~-]+)?$/;
+var MAX_SITE_PATH_LINK_LENGTH = 2e3;
+function sitePathLink(url) {
+  if (url.length > MAX_SITE_PATH_LINK_LENGTH || url.includes("__ESC_") || !SITE_PATH_LINK.test(url)) return void 0;
+  return url.split(/[?#]/, 1)[0].split("/").some((segment) => segment === "." || segment === "..") ? void 0 : url;
+}
 function externalPageUrl(value) {
   const url = typeof value === "string" ? value.trim() : "";
+  if (url.startsWith("/")) return sitePathLink(url);
   if (!/^https?:\/\/[^\s]+$/i.test(url)) return void 0;
   try {
     new URL(url);
@@ -3408,16 +3677,46 @@ function externalPageUrl(value) {
 }
 function parseMarkdownPage(input) {
   const parsed = parseFrontmatter(input.raw);
+  if (input.platform === "mintlify") {
+    const supported = /* @__PURE__ */ new Set([
+      "title",
+      "description",
+      "sidebarTitle",
+      "navTitle",
+      "icon",
+      "iconType",
+      "tag",
+      "badge",
+      "keywords",
+      "mode",
+      "hidden",
+      "noindex",
+      "url",
+      "openapi",
+      "api",
+      "authMethod",
+      "playground",
+      // Access settings are enforced by the repository classifier, never lost here.
+      "groups",
+      "public",
+      ...PAGE_META_FIELDS.map(([field]) => field)
+    ]);
+    const dropped = Object.keys(parsed.data).filter((key) => !supported.has(key));
+    if (dropped.length) input.warn?.(`Unsupported Mintlify frontmatter fields were omitted: ${dropped.join(", ")}. Review their behavior before publishing.`);
+  }
   const fallbackIdentity = {
     id: input.id,
     navigationId: input.navigationId ?? input.id,
     ...input.locale ? { locale: input.locale } : {}
   };
   const identity = input.resolveIdentity?.(parsed.data, fallbackIdentity) ?? fallbackIdentity;
-  const body = removeUndefinedExpressions(injectReactHookImports(normalizeMdx(parsed.content, input.platform)), input.warn).trim();
+  const normalized = normalizeMdx(parsed.content, input.platform);
+  const body = removeUndefinedExpressions(injectReactHookImports(input.platform === "mintlify" ? normalizeMintlifyCodeFences(normalized, input.warn) : normalized), input.warn).trim();
   const keywords = Array.isArray(parsed.data.keywords) ? parsed.data.keywords.filter((value) => typeof value === "string") : [];
   const heading = leadingPageHeading(body);
-  const title = typeof parsed.data.title === "string" && parsed.data.title.trim() ? parsed.data.title.trim() : heading?.title ?? titleFromId(identity.navigationId);
+  const authoredTitle = typeof parsed.data.title === "string" && parsed.data.title.trim() ? parsed.data.title.trim() : heading?.title;
+  const title = authoredTitle ?? titleFromId(identity.navigationId);
+  const namesOperation = typeof parsed.data.openapi === "string" && Boolean(parsed.data.openapi.trim());
   const sidebarTitle = input.platform === "docusaurus" ? parsed.data.sidebar_label : parsed.data.sidebarTitle;
   const navTitle = typeof sidebarTitle === "string" && sidebarTitle.trim() ? sidebarTitle.trim() : typeof parsed.data.navTitle === "string" && parsed.data.navTitle.trim() ? parsed.data.navTitle.trim() : void 0;
   const icon = typeof parsed.data.icon === "string" && parsed.data.icon.trim() ? parsed.data.icon.trim() : void 0;
@@ -3430,18 +3729,25 @@ function parseMarkdownPage(input) {
   const badge = typeof parsed.data.tag === "string" && parsed.data.tag.trim() ? parsed.data.tag.trim() : typeof parsed.data.badge === "string" && parsed.data.badge.trim() ? parsed.data.badge.trim() : void 0;
   const sourceMode = typeof parsed.data.mode === "string" ? parsed.data.mode : void 0;
   const mode = sourceMode === "frame" ? "wide" : ["default", "wide", "custom", "center", "home"].includes(sourceMode ?? "") ? sourceMode : void 0;
+  if (input.platform === "mintlify" && typeof parsed.data.url === "string" && parsed.data.url.trim().startsWith("/") && !externalPageUrl(parsed.data.url)) {
+    const shown = parsed.data.url.trim();
+    input.warn?.(`Page "${identity.id}": its "url" frontmatter ${JSON.stringify(shown.length > 80 ? `${shown.slice(0, 80)}...` : shown)} was not turned into a link, so the page was kept with its own content. Only a site path made of letters, digits and . _ ~ - segments, with an optional ?key=value query and #id fragment, can become a link.`);
+  }
   const externalUrl = input.platform === "mintlify" ? externalPageUrl(parsed.data.url) : void 0;
-  const description = typeof parsed.data.description === "string" && parsed.data.description.trim() ? parsed.data.description.trim() : typeof parsed.data.openapi === "string" && parsed.data.openapi.trim() ? "" : firstParagraph(body);
+  const authoredDescription = typeof parsed.data.description === "string" && parsed.data.description.trim() ? parsed.data.description.trim() : void 0;
+  const description = authoredDescription ?? (namesOperation ? "" : firstParagraph(body));
   const page = {
     id: identity.id,
     navigationId: identity.navigationId,
     locale: identity.locale,
     title,
+    ...authoredTitle === void 0 && namesOperation ? { titleFromFileName: true } : {},
     navTitle,
     icon,
     iconType,
     description,
-    ...input.platform === "docusaurus" || input.platform === "fern" ? { descriptionPlacement: "body" } : {},
+    // A description taken from the body is the paragraph the body already shows, so it must not also appear under the title.
+    ...input.platform === "docusaurus" || input.platform === "fern" || authoredDescription === void 0 && description !== "" ? { descriptionPlacement: "body" } : {},
     badge,
     keywords,
     mode,
@@ -3456,6 +3762,12 @@ function parseMarkdownPage(input) {
     source: input.source,
     ...parsed.error ? { frontmatterError: parsed.error } : {}
   };
+  const writtenDescription = typeof parsed.data.description === "string" ? parsed.data.description.trim() : "";
+  const plainDescription2 = withoutMarkdownLinks(writtenDescription);
+  if (plainDescription2 !== writtenDescription) {
+    page.description = plainDescription2;
+    input.warn?.(`Page "${identity.id}": its description had links, which Thally shows as plain text; the link text was kept.`);
+  }
   resolvePageDisplayHeading(page, input.platform);
   return page;
 }
@@ -3487,7 +3799,7 @@ function apiFrontmatter(data, warn) {
 }
 
 // src/url-static-content.ts
-import { createHash as createHash2 } from "crypto";
+import { createHash as createHash3 } from "crypto";
 import { load as load4 } from "cheerio";
 function projectMigrationSvg(html) {
   const $ = load4(html, { xmlMode: true }, false);
@@ -3496,7 +3808,7 @@ function projectMigrationSvg(html) {
   if (svg.attr("xmlns") === void 0) svg.attr("xmlns", "http://www.w3.org/2000/svg");
   const content = Buffer.from($.xml(svg));
   if (!isPassiveSvg(content)) return null;
-  const sha256 = createHash2("sha256").update(content).digest("hex");
+  const sha256 = createHash3("sha256").update(content).digest("hex");
   const labelled = (svg.attr("aria-labelledby") ?? "").split(/\s+/).filter(Boolean).map((id) => svg.find("[id]").filter((_index, node) => $(node).attr("id") === id).text().trim()).filter(Boolean);
   const alternative = svg.attr("aria-label")?.trim() || labelled.join(" ") || svg.children("title").text().trim() || svg.children("desc").text().trim() || svg.find("text").text().trim();
   return { asset: { path: `migration-assets/${sha256}.svg`, content }, alternative };
@@ -3688,8 +4000,8 @@ var MINTLIFY_ARTICLE_LABELS = [
   { baseUrl: "Select base URL", permalink: "Navigate to header" },
   { baseUrl: "\u9009\u62E9\u57FA\u7840URL", permalink: "\u5BFC\u822A\u5230\u6807\u9898" }
 ];
-var remoteMarkdownParser = unified3().use(remarkParse3).use(remarkMdx3);
-var embeddedOpenApiParser = unified3().use(remarkParse3);
+var remoteMarkdownParser = unified4().use(remarkParse4).use(remarkMdx3);
+var embeddedOpenApiParser = unified4().use(remarkParse4);
 function validateMigrationUrl(value) {
   let url;
   try {
@@ -3729,10 +4041,10 @@ async function readResponseBody(response) {
   }
   return new TextDecoder().decode(body);
 }
-var defaultMigrationFetcher = async (url, request) => {
+var defaultMigrationFetcher = async (url, request2) => {
   const response = await fetch(url, {
     headers: {
-      Accept: request.accept,
+      Accept: request2.accept,
       "User-Agent": "Thally-Migrate/1.0 (+https://thally.io)"
     },
     redirect: "follow",
@@ -4206,7 +4518,7 @@ function extractEmbeddedOpenApi(content) {
     const opening = lines[0].match(/^ {0,3}(`{3,}|~{3,})/);
     const closing = lines.at(-1)?.match(/^ {0,3}(`{3,}|~{3,})[\t ]*$/);
     if (!opening || !closing || opening[1][0] !== closing[1][0] || closing[1].length < opening[1].length) return { content };
-    const parsed = parseYaml2(node.value ?? "", { maxAliasCount: 50 });
+    const parsed = parseYaml3(node.value ?? "", { 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 };
@@ -4667,6 +4979,8 @@ ${fence}
       navigationId: id,
       title,
       description: description || plainDescription(body) || `Documentation imported from ${document.finalUrl.hostname}.`,
+      // A description taken from the page text is already in the body; only one the site published is shown under the title.
+      ...description ? {} : { descriptionPlacement: "body" },
       keywords: [],
       body,
       source: document.finalUrl.toString()
@@ -4736,7 +5050,7 @@ function observedMigrationArticleIdentity(document) {
   canonical2.pathname = canonical2.pathname.replace(/\/+$/, "") || "/";
   const removed = [...source.searchParams].filter(([key, value]) => !canonical2.searchParams.getAll(key).includes(value));
   const sectionAnchor = removed.length === 1 && anchors.includes(removed[0][1]) ? removed[0][1] : void 0;
-  return { canonicalUrl: canonical2.href, articleSha256: createHash3("sha256").update(payload).digest("hex"), ...sectionAnchor ? { sectionAnchor } : {} };
+  return { canonicalUrl: canonical2.href, articleSha256: createHash4("sha256").update(payload).digest("hex"), ...sectionAnchor ? { sectionAnchor } : {} };
 }
 
 // src/url-api-schema-controls.ts
@@ -4829,8 +5143,8 @@ function apiSchemaTabGroups(body, document, operation) {
     let schema;
     let scope;
     if (title === "body") {
-      const request = resolve2(document, selected.requestBody);
-      schema = object2(object2(request?.content)?.[media[0]])?.schema;
+      const request2 = resolve2(document, selected.requestBody);
+      schema = object2(object2(request2?.content)?.[media[0]])?.schema;
       scope = `request:${media[0]}`;
     } else if (title === "response") {
       const statuses = heading.find('button[aria-haspopup="menu"]').toArray().map((button) => $(button).text().trim()).filter((text2) => /^(?:[1-5]\d{2}|default)$/.test(text2));
@@ -4929,8 +5243,8 @@ function apiSchemaDisclosureGroups(body, document, operation) {
       schemas = [object2(object2(response?.content)?.[media[0]])?.schema];
       prefix = "response";
     } else if (media.length === 1 && !statuses.length) {
-      const request = resolve2(document, selected.requestBody);
-      schemas = [object2(object2(request?.content)?.[media[0]])?.schema];
+      const request2 = resolve2(document, selected.requestBody);
+      schemas = [object2(object2(request2?.content)?.[media[0]])?.schema];
       prefix = "body";
     } else if (!media.length && !statuses.length) {
       const head = $(chain[0]).find(".param-head[id]").filter((_index, element) => $(element).closest(fieldSelector)[0] === chain[0]).first().attr("id") ?? "";
@@ -5063,8 +5377,8 @@ function apiOperationCodeControls(body, specification, operation) {
     const metadata = object2(resolveValue(value));
     const declaration = resolveValue(metadata?.openapi);
     if (typeof declaration !== "string") return false;
-    const tokens = declaration.trim().split(/\s+/);
-    return tokens.at(-2)?.toLowerCase() === operation.method.toLowerCase() && tokens.at(-1) === operation.path;
+    const tokens2 = declaration.trim().split(/\s+/);
+    return tokens2.at(-2)?.toLowerCase() === operation.method.toLowerCase() && tokens2.at(-1) === operation.path;
   };
   const active = /* @__PURE__ */ new Set();
   const visit = (input, provider, group, depth, owners = []) => {
@@ -5110,9 +5424,9 @@ function apiOperationCodeControls(body, specification, operation) {
             const hint = object2(resolveValue(scope?.pageMetadata)), metadata = object2(resolveValue(props.pageMetadata));
             const declaration = resolveValue(hint?.openapi);
             if (typeof declaration !== "string" || typeof hint?.href !== "string" || !hint.href || hint.href !== metadata?.href) return false;
-            const tokens = declaration.trim().split(/\s+/);
+            const tokens2 = declaration.trim().split(/\s+/);
             const template = (path) => path.split("/").map((segment) => /^\{[^{}\/]+\}$/.test(segment) ? "{}" : segment).join("/");
-            return tokens.at(-2)?.toLowerCase() === operation.method.toLowerCase() && template(tokens.at(-1) ?? "") === template(operation.path);
+            return tokens2.at(-2)?.toLowerCase() === operation.method.toLowerCase() && template(tokens2.at(-1) ?? "") === template(operation.path);
           })()) generatedControllers += 1;
         }
         let local = group;
@@ -5221,14 +5535,14 @@ function apiOperationCodeControls(body, specification, operation) {
 
 // src/url-run.ts
 var CONVERTER_VERSION = "url-evidence-v7";
-var parser2 = unified4().use(remarkParse4).use(remarkMdx4);
+var parser2 = unified5().use(remarkParse5).use(remarkMdx4);
 var ACCEPT = "text/html,application/xhtml+xml";
 var MAX_RESPONSE_BYTES = 8e6;
 var MAX_ASSET_BYTES = 1e7;
 var MAX_RECORDS = 1e5;
 var LOCALES = /* @__PURE__ */ new Set(["ar", "cs", "da", "de", "el", "en", "es", "fi", "fr", "he", "hi", "hu", "id", "it", "ja", "ko", "ms", "nl", "no", "pl", "pt", "pt-br", "ro", "ru", "sk", "sv", "th", "tr", "uk", "vi", "zh", "zh-cn", "zh-hans", "zh-hant"]);
 function hash(value) {
-  return createHash4("sha256").update(value).digest("hex");
+  return createHash5("sha256").update(value).digest("hex");
 }
 function canonicalJson(value) {
   const canonical2 = (value2) => Array.isArray(value2) ? value2.map(canonical2) : value2 !== null && typeof value2 === "object" ? Object.fromEntries(Object.entries(value2).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, field]) => [key, canonical2(field)])) : value2;
@@ -5749,7 +6063,7 @@ async function runUrlMigration(options) {
     } catch {
     }
   }
-  const capture = (request) => initial && canonical(request.url.href, sourceUrl) === sourceUrl ? initial : acquire(request);
+  const capture = (request2) => initial && canonical(request2.url.href, sourceUrl) === sourceUrl ? initial : acquire(request2);
   const requestedScope = options.scopePath ?? options.checkpoint?.scopePath ?? inferredScope ?? (source.pathname.endsWith("/") ? source.pathname : source.pathname.slice(0, source.pathname.lastIndexOf("/")) || "/");
   let scopeEnd = requestedScope.length;
   while (scopeEnd > 0 && requestedScope.charCodeAt(scopeEnd - 1) === 47) scopeEnd--;
@@ -6493,16 +6807,16 @@ function rewriteMarkdownDestinations(body, rewrite) {
 }
 
 // src/components.ts
-import { createHash as createHash5 } from "crypto";
+import { createHash as createHash6 } from "crypto";
 import { existsSync as existsSync2, lstatSync as lstatSync2, readFileSync as readFileSync2 } from "fs";
 import { basename, dirname as dirname2, extname as extname3, posix as posix2, relative as relative3, resolve as resolve3 } from "path";
-import postcss from "postcss";
-import selectorParser from "postcss-selector-parser";
+import postcss2 from "postcss";
+import selectorParser2 from "postcss-selector-parser";
 import remarkMdx5 from "remark-mdx";
-import remarkParse5 from "remark-parse";
-import ts2 from "typescript";
-import { unified as unified5 } from "unified";
-var parser3 = unified5().use(remarkParse5).use(remarkMdx5);
+import remarkParse6 from "remark-parse";
+import ts3 from "typescript";
+import { unified as unified6 } from "unified";
+var parser3 = unified6().use(remarkParse6).use(remarkMdx5);
 var DOCUSAURUS_THEME_SHIMS = {
   "@theme/CodeBlock": {
     filename: "docusaurus-code-block.tsx",
@@ -6542,32 +6856,32 @@ function applyReplacements(source, replacements) {
   );
 }
 function hash2(value) {
-  return createHash5("sha256").update(value).digest("hex").slice(0, 12);
+  return createHash6("sha256").update(value).digest("hex").slice(0, 12);
 }
 function sourceFile(source, filename) {
-  return ts2.createSourceFile(filename, source, ts2.ScriptTarget.Latest, true, scriptKindFor(filename));
+  return ts3.createSourceFile(filename, source, ts3.ScriptTarget.Latest, true, scriptKindFor(filename));
 }
 function mergeComponentRegistry(existing, incoming) {
   const fingerprint = hash2(incoming);
   const name = `MigratedRegistry${fingerprint}`;
   const registryPath = `./migrated-components-${fingerprint}`;
   const source = sourceFile(existing, "custom-components.tsx");
-  const alreadyImported = source.statements.some((statement) => ts2.isImportDeclaration(statement) && ts2.isStringLiteral(statement.moduleSpecifier) && statement.moduleSpecifier.text === registryPath);
+  const alreadyImported = source.statements.some((statement) => ts3.isImportDeclaration(statement) && ts3.isStringLiteral(statement.moduleSpecifier) && statement.moduleSpecifier.text === registryPath);
   let initializer;
   for (const statement of source.statements) {
-    if (!ts2.isVariableStatement(statement) || !statement.modifiers?.some((modifier) => modifier.kind === ts2.SyntaxKind.ExportKeyword)) continue;
+    if (!ts3.isVariableStatement(statement) || !statement.modifiers?.some((modifier) => modifier.kind === ts3.SyntaxKind.ExportKeyword)) continue;
     for (const declaration of statement.declarationList.declarations) {
-      if (ts2.isIdentifier(declaration.name) && declaration.name.text === "customComponents") initializer = declaration.initializer;
+      if (ts3.isIdentifier(declaration.name) && declaration.name.text === "customComponents") initializer = declaration.initializer;
     }
   }
-  while (initializer && (ts2.isAsExpression(initializer) || ts2.isSatisfiesExpression(initializer) || ts2.isParenthesizedExpression(initializer))) initializer = initializer.expression;
-  if (!initializer || !ts2.isObjectLiteralExpression(initializer)) {
+  while (initializer && (ts3.isAsExpression(initializer) || ts3.isSatisfiesExpression(initializer) || ts3.isParenthesizedExpression(initializer))) initializer = initializer.expression;
+  if (!initializer || !ts3.isObjectLiteralExpression(initializer)) {
     throw new Error("Cannot safely merge src/mdx/custom-components.tsx: export customComponents as an object literal before importing components. The existing registry was preserved.");
   }
   const content = alreadyImported ? existing : applyReplacements(existing, [
     {
-      start: source.statements.filter((statement) => ts2.isExpressionStatement(statement) && ts2.isStringLiteral(statement.expression)).at(-1)?.end ?? 0,
-      end: source.statements.filter((statement) => ts2.isExpressionStatement(statement) && ts2.isStringLiteral(statement.expression)).at(-1)?.end ?? 0,
+      start: source.statements.filter((statement) => ts3.isExpressionStatement(statement) && ts3.isStringLiteral(statement.expression)).at(-1)?.end ?? 0,
+      end: source.statements.filter((statement) => ts3.isExpressionStatement(statement) && ts3.isStringLiteral(statement.expression)).at(-1)?.end ?? 0,
       value: `
 import { customComponents as ${name} } from ${JSON.stringify(registryPath)}
 `
@@ -6619,6 +6933,32 @@ function renderPage(bundle, page) {
 function isIntegrationsObject(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
+function mergeRedirects(existing = [], incoming = []) {
+  const redirects = [...existing];
+  const key = (source) => literalRoute(source) ?? trimTrailingSlashes(source).toLowerCase();
+  const destinationKey = (destination) => literalRoute(destinationRoute(destination) ?? "");
+  const sources = new Set(existing.map((redirect) => key(redirect.source)));
+  for (const redirect of incoming) {
+    const source = key(redirect.source);
+    if (sources.has(source)) continue;
+    const visited = /* @__PURE__ */ new Set([source]);
+    let destination = destinationKey(redirect.destination);
+    let cycle = false;
+    while (destination) {
+      if (visited.has(destination)) {
+        cycle = true;
+        break;
+      }
+      visited.add(destination);
+      const next = redirects.find((candidate) => literalRoute(candidate.source) === destination);
+      destination = next ? destinationKey(next.destination) : null;
+    }
+    if (cycle) continue;
+    redirects.push(redirect);
+    sources.add(source);
+  }
+  return redirects;
+}
 function mergeMigrationConfig(existing, incoming) {
   const tabs = existing.tabs.filter((tab) => tab.tab.toLowerCase() !== "changelog");
   const names = new Set(tabs.map((tab) => tab.tab.toLowerCase()));
@@ -6686,6 +7026,10 @@ function mergeMigrationConfig(existing, incoming) {
     ...incoming,
     ...existing,
     tabs,
+    ...existing.redirects || incoming.redirects ? { redirects: mergeRedirects(existing.redirects, incoming.redirects) } : {},
+    // A starter's primary action must not discard a newly imported logo.
+    // Owner-authored fields, including an explicit null logo, remain authoritative.
+    ...incoming.navbar || existing.navbar ? { navbar: { ...incoming.navbar, ...existing.navbar } } : {},
     // Collection presentation belongs to the imported information
     // architecture; starter defaults must not coerce source dropdowns to tabs.
     navigation: incoming.navigation ?? existing.navigation,