@thallylabs/migrate 0.2.41 → 0.2.43

package/dist/url-migration.js

@@ -1,9 +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 remarkParse4 from "remark-parse";
+import { parse as parse2, postprocess, preprocess } from "micromark";
+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";
@@ -496,15 +497,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);
@@ -1815,7 +1816,10 @@ var VIDEO_ATTRIBUTES = /* @__PURE__ */ new Set([
   "width",
   "height",
   "preload",
-  "aria-label"
+  "aria-label",
+  // Publisher asset provenance does not change playback and is never emitted.
+  // Keep this explicit: arbitrary data attributes may drive custom controls.
+  "data-path"
 ]);
 var YOUTUBE_ATTRIBUTES = /* @__PURE__ */ new Set([
   "src",
@@ -1880,16 +1884,27 @@ 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";
+
+// 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])?";
@@ -1901,8 +1916,8 @@ 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([
@@ -2339,13 +2354,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);
       }
@@ -2369,7 +2384,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 : {}
@@ -2383,13 +2398,103 @@ function parseFrontmatter(raw) {
   }
 }
 
+// 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);
+var descriptionParser = unified3().use(remarkParse3).use(remarkGfm2).use(remarkMdx2);
 function plainText(node) {
   if (node.type === "text" || node.type === "inlineCode") return node.value ?? "";
   if (node.type === "image") return node.alt ?? "";
@@ -3404,13 +3509,41 @@ 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);
@@ -3483,7 +3616,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);
@@ -3492,7 +3625,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 };
@@ -3605,6 +3738,32 @@ function projectCapturedTabs($, root) {
   }
 }
 
+// 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/url.ts
 var MAX_LOCAL_RESPONSE_BYTES = 8e6;
 var MAX_EMBEDDED_SCHEMA_BYTES = 2e6;
@@ -3684,8 +3843,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 {
@@ -3725,10 +3884,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",
@@ -4202,7 +4361,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 };
@@ -4732,7 +4891,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
@@ -4825,8 +4984,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));
@@ -4925,8 +5084,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") ?? "";
@@ -5059,8 +5218,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 = []) => {
@@ -5106,9 +5265,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;
@@ -5216,15 +5375,15 @@ function apiOperationCodeControls(body, specification, operation) {
 }
 
 // src/url-run.ts
-var CONVERTER_VERSION = "url-evidence-v6";
-var parser2 = unified4().use(remarkParse4).use(remarkMdx4);
-var ACCEPT = "text/markdown,text/html,application/xhtml+xml;q=0.9";
+var CONVERTER_VERSION = "url-evidence-v7";
+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;
@@ -5248,6 +5407,11 @@ function canonical(value, base) {
     return null;
   }
 }
+function sameRouteMarkdownRepresentation(alternate, primary) {
+  const target2 = new URL(alternate), source = new URL(primary);
+  const directory2 = (path) => path.replace(/\.mdx?$/i, "").replace(/\/index\/?$/i, "").replace(/\/$/, "");
+  return target2.origin === source.origin && target2.search === source.search && directory2(target2.pathname) === directory2(source.pathname) && /\.mdx?$/i.test(target2.pathname);
+}
 function classifyMigrationResponse(document) {
   if (document.status && document.status >= 400) return "unsupported";
   if (/\/(?:llms(?:-full)?|robots)\.txt$|\/sitemap[^/]*\.xml$|\/search(?:\.html)?$/i.test(document.finalUrl.pathname) || /\.(?:json|ya?ml)$/i.test(document.finalUrl.pathname) || /(?:xml|json)/i.test(document.contentType)) return "index";
@@ -5498,7 +5662,7 @@ function resolveMigrationRecord(records, record) {
   }
   return record;
 }
-function navigationConfig(checkpoint, records) {
+function navigationConfig(checkpoint, records, occurrencePages = /* @__PURE__ */ new Map()) {
   const navigation = checkpoint.navigation;
   const shortcuts = [];
   const collectShortcuts = (nodes) => {
@@ -5523,7 +5687,7 @@ function navigationConfig(checkpoint, records) {
   const project = (nodes) => nodes.flatMap((node) => {
     const record = node.url ? records.get(canonical(node.url, node.url) ?? "") : void 0;
     const target2 = resolveMigrationRecord(records, record);
-    const page = target2?.page;
+    const page = occurrencePages.get(node) ?? target2?.page;
     const children = project(node.children ?? []);
     if (children.length) {
       const contains = (entries) => entries.some((entry) => typeof entry === "string" ? entry === (page && projection.navigationId(page)) : contains(entry.pages));
@@ -5740,7 +5904,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--;
@@ -5823,8 +5987,19 @@ async function runUrlMigration(options) {
     if (!record.evidence) continue;
     const final = canonical(record.evidence.finalUrl, sourceUrl);
     if (!final) continue;
-    if (record.outcome === "imported") enqueueArticleLinks(record.evidence.links, final, record.url);
-    else if (record.outcome === "excluded") {
+    if (record.outcome === "imported") {
+      enqueueArticleLinks(record.evidence.links, final, record.url);
+      for (const reference of record.evidence.markdownRepresentations ?? []) {
+        const alternate = canonical(reference, final);
+        if (!alternate || !sameRouteMarkdownRepresentation(alternate, final)) continue;
+        enqueue(alternate, final, "declared-markdown-representation");
+        const sibling = records.get(alternate);
+        if (sibling && sibling.representationOf !== record.url) {
+          sibling.representationOf = record.url;
+          changed.push(sibling);
+        }
+      }
+    } else if (record.outcome === "excluded") {
       if (classifyMigrationResponse({ finalUrl: new URL(final), contentType: record.evidence.contentType, body: "" }) === "index") {
         for (const link of record.evidence.links) enqueue(link, final, record.url);
       }
@@ -5907,6 +6082,7 @@ async function runUrlMigration(options) {
     let claimedId;
     let claimedFinal;
     let markdownRepresentation;
+    const markdownRepresentations = [];
     let exactKey;
     try {
       delete record.reason;
@@ -5999,13 +6175,13 @@ async function runUrlMigration(options) {
         $('link[rel="alternate"][type="text/markdown"][href]').each((_index, node) => {
           const alternate = canonical($(node).attr("href"), final);
           if (!alternate) return;
-          const target2 = new URL(alternate), primary = new URL(final);
-          const directory2 = (path) => path.replace(/\.mdx?$/i, "").replace(/\/index\/?$/i, "").replace(/\/$/, "");
-          if (target2.origin !== primary.origin || target2.search !== primary.search || directory2(target2.pathname) !== directory2(primary.pathname) || !/\.mdx?$/i.test(target2.pathname)) return;
+          if (!sameRouteMarkdownRepresentation(alternate, final)) return;
           enqueue(alternate, final, "declared-markdown-representation");
           const sibling = records.get(alternate);
+          if (!sibling) return;
           sibling.representationOf = record.url;
           markdownRepresentation ??= alternate;
+          markdownRepresentations.push(alternate);
           changed.push(sibling);
         });
       }
@@ -6018,7 +6194,8 @@ async function runUrlMigration(options) {
         }
         enqueueNavigation(observedNavigation, final);
       }
-      if (imported >= maxPages) {
+      const replacesRepresentation = imported >= maxPages && markdownRepresentations.some((url) => records.get(url)?.page);
+      if (imported >= maxPages && !replacesRepresentation) {
         record.outcome = "excluded";
         record.reason = "A discovery endpoint resolved to an article after the selected page limit.";
         return;
@@ -6037,14 +6214,17 @@ async function runUrlMigration(options) {
       const locale = language.locale;
       const navigationId = locale ? id.split("/").filter((segment) => segment.toLowerCase() !== locale.toLowerCase()).join("/") || "introduction" : id;
       const identityId = locale ? `${locale}/${navigationId}` : id;
-      if (usedIds.has(identityId) && usedIds.get(identityId) !== record.url) {
+      const owner = records.get(usedIds.get(identityId) ?? "");
+      const sharesDeclaredRepresentation = owner && (owner.representationOf === record.url || record.representationOf === owner.url);
+      if (owner && owner !== record && !sharesDeclaredRepresentation) {
         record.outcome = "failed";
         record.reason = `Destination collision for ${identityId}.`;
         return;
       }
-      usedIds.set(identityId, record.url);
+      if (!owner || owner === record || owner.representationOf === record.url) usedIds.set(identityId, record.url);
       claimedId = identityId;
       const evidence = evidenceOf(document);
+      if (markdownRepresentations.length) evidence.markdownRepresentations = markdownRepresentations;
       const page = convert(document, id);
       if (!page) {
         record.outcome = "failed";
@@ -6255,6 +6435,7 @@ ${difference}`;
       if (!primary || primary === record) continue;
       const winner = primary.outcome === "imported" ? primary : record.outcome === "imported" && primary.outcome === "failed" ? record : void 0;
       if (!winner) continue;
+      if (winner.page) usedIds.set(winner.page.id, winner.url);
       const alternate = winner === primary ? record : primary;
       if (alternate.outcome === "alias" && alternate.aliasOf === winner.url) continue;
       if (alternate.outcome === "imported") {
@@ -6276,7 +6457,17 @@ ${difference}`;
   settleArticleIdentities();
   while (cursor < pending.length && !options.signal?.aborted && !budgetExhausted && cursor < (options.maxCaptures ?? Infinity)) {
     if (imported >= maxPages) {
-      const index = pending.findIndex((record, position) => position >= cursor && isDiscoveryIndex(new URL(record.url), source));
+      const index = pending.findIndex((record, position) => {
+        if (position < cursor || record.outcome !== "pending") return false;
+        const url = new URL(record.url);
+        if (isDiscoveryIndex(url, source)) return true;
+        if (/\.mdx?$/i.test(url.pathname)) return false;
+        return [".md", ".mdx", "/index.md", "/index.mdx"].some((extension) => {
+          const alternate = new URL(url);
+          alternate.pathname = alternate.pathname.replace(/\/index$/i, "") + extension;
+          return records.get(alternate.href)?.outcome === "imported";
+        });
+      });
       if (index < 0) break;
       pending.splice(cursor, 0, pending.splice(index, 1)[0]);
     }
@@ -6300,19 +6491,60 @@ ${difference}`;
   }
   const navigationLabels = /* @__PURE__ */ new Map();
   const navigationIssues = [];
+  const navigationOccurrences = /* @__PURE__ */ new Map();
   const labelPages = (nodes) => {
     for (const node of nodes) {
       const entry = node.url ? records.get(canonical(node.url, sourceUrl) ?? "") : void 0;
       const target2 = resolveMigrationRecord(records, entry);
-      if (target2?.page && node.label && !node.children?.length && !entry?.aliasAnchor) {
-        const previous = navigationLabels.get(target2.url);
-        if (previous && previous !== node.label) navigationIssues.push({ code: "unsupported-component", source: target2.url, message: `This page has multiple source navigation labels (${previous}, ${node.label}); review the shared sidebar title.` });
-        else navigationLabels.set(target2.url, node.label);
+      if (entry && target2?.page && node.label && !node.children?.length && !entry.aliasAnchor) {
+        const occurrences = navigationOccurrences.get(target2) ?? [];
+        occurrences.push({ node, entry });
+        navigationOccurrences.set(target2, occurrences);
       }
       labelPages(node.children ?? []);
     }
   };
   labelPages(checkpoint.navigation);
+  const occurrencePages = /* @__PURE__ */ new Map();
+  const navigationAliases = /* @__PURE__ */ new Map();
+  const occupiedPageIds = new Set(checkpoint.records.flatMap((record) => record.page ? [projection.pageId(record.page)] : []));
+  const navigationRedirects = [];
+  for (const [target2, occurrences] of navigationOccurrences) {
+    const final = target2.evidence && canonical(target2.evidence.finalUrl, sourceUrl);
+    const primary = occurrences.find(({ entry }) => entry.url === final) ?? occurrences.find(({ entry }) => entry === target2) ?? occurrences[0];
+    navigationLabels.set(target2.url, primary.node.label);
+    for (const { node, entry } of occurrences) {
+      if (node.label === primary.node.label) continue;
+      const existing = navigationAliases.get(entry.url);
+      if (existing?.page.navTitle === node.label && existing.target === target2) {
+        occurrencePages.set(node, existing.page);
+        continue;
+      }
+      const sourceRoute = new URL(entry.url);
+      const id = inScope(sourceRoute, source, scopePath) ? idForUrl(sourceRoute, scopePath) : null;
+      const locale = projection.canonicalLocale(target2.page);
+      let navigationId = id && (locale ? id.split("/").filter((segment) => segment.toLowerCase() !== locale.toLowerCase()).join("/") || "introduction" : id);
+      const legacyPrefix = locale && `${locale.toLowerCase()}-`;
+      if (navigationId && legacyPrefix && projection.navigationId(target2.page) !== target2.page.navigationId && navigationId.toLowerCase().startsWith(legacyPrefix)) navigationId = navigationId.slice(legacyPrefix.length);
+      const page = navigationId ? {
+        ...target2.page,
+        id: locale ? `${locale}/${navigationId}` : navigationId,
+        navigationId,
+        ...locale ? { locale } : {},
+        navTitle: node.label,
+        source: entry.url,
+        noindex: true
+      } : void 0;
+      if (!page || existing || occupiedPageIds.has(projection.pageId(page))) {
+        navigationIssues.push({ code: "unsupported-component", source: target2.url, message: `This page has multiple source navigation labels (${primary.node.label}, ${node.label}); their source routes cannot retain distinct sidebar titles safely.` });
+        continue;
+      }
+      occupiedPageIds.add(projection.pageId(page));
+      navigationAliases.set(entry.url, { page, target: target2 });
+      occurrencePages.set(node, page);
+      navigationRedirects.push({ source: projection.route(page), destination: projection.route(target2.page), permanent: true });
+    }
+  }
   const pages = checkpoint.records.flatMap((record) => record.page ? [{ ...record.page, id: projection.pageId(record.page), navigationId: projection.navigationId(record.page), ...projection.canonicalLocale(record.page) ? { locale: projection.canonicalLocale(record.page) } : {}, ...navigationLabels.has(record.url) ? { navTitle: navigationLabels.get(record.url) } : {}, body: rewriteMarkdownDestinations(record.page.body, (value) => {
     let url;
     try {
@@ -6333,6 +6565,10 @@ ${difference}`;
     const hasBrokenSourceAnchor = Boolean(url.hash && destination?.outcome === "imported" && destination.evidence && !destination.evidence.anchors.includes(anchor));
     return `${route}${hasBrokenSourceAnchor ? "" : effectiveHash}`;
   }) }] : []);
+  const projectedPages = new Map(pages.map((page) => [page.id, page]));
+  for (const { page, target: target2 } of navigationAliases.values()) {
+    pages.push({ ...page, id: projection.pageId(page), body: projectedPages.get(projection.pageId(target2.page)).body });
+  }
   const validation = validateUrlMigration(checkpoint, Boolean(options.signal?.aborted));
   validation.issues.push(...navigationIssues);
   if (navigationIssues.length && validation.status === "passed") validation.status = "partial";
@@ -6353,12 +6589,12 @@ ${difference}`;
     platform: options.platform ?? "generic",
     pages,
     assets: [...assets.values()],
-    docsConfig: navigationConfig(checkpoint, records) ?? buildNavigationFromPages(pages),
+    docsConfig: navigationConfig(checkpoint, records, occurrencePages) ?? buildNavigationFromPages(pages),
     warnings: [...validation.issues, ...validation.warnings ?? []].map((issue) => ({ code: issue.code === "missing-page" ? "missing-page" : "unsupported-config", message: issue.message, source: issue.source })),
     urlMigrationValidation: validation,
     stats: { discovered: records.size, imported: pages.length, skipped: records.size - pages.length }
   };
-  if (projection.redirects.length) bundle.docsConfig.redirects = projection.redirects;
+  if (projection.redirects.length || navigationRedirects.length) bundle.docsConfig.redirects = [...projection.redirects, ...navigationRedirects];
   if (projection.locales.length) {
     const locales = [.../* @__PURE__ */ new Set([projection.defaultLocale, ...projection.locales])];
     bundle.docsConfig.i18n = { ...bundle.docsConfig.i18n, defaultLocale: projection.defaultLocale, locales: locales.map((code) => ({ code, label: code === "en" ? "English" : code })) };
@@ -6376,9 +6612,11 @@ function rewriteMarkdownDestinations(body, rewrite) {
     const original = body.slice(start, end);
     const replacement = rewrite(node.url);
     if (replacement === node.url) return null;
-    const index = original.lastIndexOf(node.url);
-    if (index < 0) return null;
-    return { start: start + index, end: start + index + node.url.length, replacement };
+    const destinations = postprocess(parse2().document().write(preprocess()(original, void 0, true))).filter(([event, token]) => event === "enter" && ["resourceDestinationString", "definitionDestinationString", "autolinkProtocol", "autolinkEmail"].includes(token.type));
+    const destination = destinations.at(-1)?.[1];
+    if (!destination) return null;
+    const escaped = replacement.replace(/[\\&()<>]/g, "\\$&").replace(/[\t\n\r ]/g, (character) => encodeURIComponent(character));
+    return { start: start + destination.start.offset, end: start + destination.end.offset, replacement: escaped };
   }).filter((edit) => edit !== null).sort((a, b) => b.start - a.start);
   for (const node of markdownNodes(body)) for (const attribute of node.attributes ?? []) {
     if (!attribute.name || !["src", "poster", "href", "srcSet", "srcset", "img", "primaryHref", "secondaryHref"].includes(attribute.name) || !attribute.position) continue;
@@ -6410,16 +6648,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 remarkMdx5 from "remark-mdx";
-import remarkParse5 from "remark-parse";
+import remarkParse6 from "remark-parse";
 import ts2 from "typescript";
-import { unified as unified5 } from "unified";
-var parser3 = unified5().use(remarkParse5).use(remarkMdx5);
+import { unified as unified6 } from "unified";
+var parser3 = unified6().use(remarkParse6).use(remarkMdx5);
 var DOCUSAURUS_THEME_SHIMS = {
   "@theme/CodeBlock": {
     filename: "docusaurus-code-block.tsx",
@@ -6459,7 +6697,7 @@ 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));
@@ -6536,6 +6774,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()));
@@ -6603,6 +6867,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,