@thallylabs/migrate 0.2.4 → 0.2.5

package/dist/index.js

@@ -1,18 +1,44 @@
 // src/repository.ts
 import { spawn } from "child_process";
 import {
-  existsSync as existsSync3,
-  lstatSync as lstatSync3,
-  readFileSync as readFileSync3,
+  existsSync as existsSync4,
+  lstatSync as lstatSync4,
+  readFileSync as readFileSync4,
   readdirSync
 } from "fs";
-import { basename, dirname as dirname2, extname as extname3, relative as relative3, resolve as resolvePath } from "path";
+import { basename, dirname as dirname3, extname as extname4, relative as relative4, resolve as resolvePath } from "path";
 
-// src/docusaurus.ts
+// src/components.ts
+import { createHash } from "crypto";
 import { existsSync, lstatSync, readFileSync } from "fs";
-import { extname, posix } from "path";
-import JSON5 from "json5";
+import { dirname, extname, relative as relative2, resolve as resolve2 } from "path";
+import remarkMdx from "remark-mdx";
+import remarkParse from "remark-parse";
+import ts from "typescript";
+import { unified } from "unified";
+
+// src/frontmatter.ts
 import { parse as parseYaml } from "yaml";
+function parseFrontmatter(raw) {
+  const source = raw.charCodeAt(0) === 65279 ? raw.slice(1) : raw;
+  const opening = /^---([^\r\n]*)\r?\n/.exec(source);
+  if (!opening || opening[1].startsWith("-")) return { content: source, data: {} };
+  const language = opening[1].trim().toLowerCase();
+  const remainder = source.slice(opening[0].length);
+  const closing = /^---[ \t]*\r?$/m.exec(remainder);
+  const matter = closing ? remainder.slice(0, closing.index) : remainder;
+  let content = closing ? remainder.slice(closing.index + closing[0].length) : "";
+  if (content.startsWith("\r\n")) content = content.slice(2);
+  else if (content.startsWith("\n")) content = content.slice(1);
+  if (matter.trim() === "" || !["", "yaml", "yml"].includes(language)) {
+    return { content, data: {} };
+  }
+  const parsed = parseYaml(matter);
+  return {
+    content,
+    data: parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {}
+  };
+}
 
 // src/path.ts
 import { isAbsolute, relative, resolve, sep } from "path";
@@ -51,6 +77,18 @@ function pageIdFromReference(value, preserveCase = false) {
   const segments = baseSegments.map((segment) => slugifySegment(segment, preserveCase)).filter(Boolean);
   return segments.join("/") || "introduction";
 }
+function mintlifyLocalizedReference(value, locale, defaultPageIds = /* @__PURE__ */ new Set()) {
+  const reference = value.replace(/^\/+/, "");
+  const localePrefix = `${locale.toLowerCase()}/`;
+  if (reference.toLowerCase().startsWith(localePrefix)) return reference.slice(localePrefix.length);
+  const sectionPrefix = `${locale.toLowerCase()}-`;
+  if (reference.toLowerCase().startsWith(sectionPrefix)) {
+    const candidate = reference.slice(sectionPrefix.length);
+    const candidateId = pageIdFromReference(candidate, true);
+    if (candidateId && defaultPageIds.has(candidateId)) return candidate;
+  }
+  return value;
+}
 function resolveWithin(root, candidate) {
   if (isAbsolute(candidate) || candidate.includes("\0")) {
     throw new Error(`Unsafe migration path: ${candidate}`);
@@ -70,7 +108,471 @@ function normalizeAssetPath(value) {
   return segments.join("/");
 }
 
+// src/components.ts
+var parser = unified().use(remarkParse).use(remarkMdx);
+var CODE_EXTENSIONS = /* @__PURE__ */ new Set([".js", ".jsx", ".ts", ".tsx", ".mjs"]);
+var DATA_EXTENSIONS = /* @__PURE__ */ new Set([".json", ".css", ".svg", ".png", ".jpg", ".jpeg", ".webp", ".gif", ".avif", ".woff", ".woff2"]);
+var SHARED_IMPORTS = /* @__PURE__ */ new Set(["react", "react/jsx-runtime", "react/jsx-dev-runtime"]);
+var REACT_GLOBALS = /* @__PURE__ */ new Set([
+  "useState",
+  "useEffect",
+  "useLayoutEffect",
+  "useMemo",
+  "useCallback",
+  "useRef",
+  "useReducer",
+  "useContext",
+  "useId",
+  "useTransition",
+  "useDeferredValue",
+  "useImperativeHandle",
+  "useSyncExternalStore",
+  "useInsertionEffect",
+  "useOptimistic",
+  "useActionState",
+  "use",
+  "createContext",
+  "forwardRef",
+  "memo"
+]);
+var MAX_COMPONENT_FILES = 300;
+var MAX_COMPONENT_BYTES = 2e7;
+var MAX_FILE_BYTES = 2e6;
+function applyReplacements(source, replacements) {
+  return replacements.sort((a, b) => b.start - a.start).reduce(
+    (text, edit) => text.slice(0, edit.start) + edit.value + text.slice(edit.end),
+    source
+  );
+}
+function hash(value) {
+  return createHash("sha256").update(value).digest("hex").slice(0, 12);
+}
+function portableSpecifier(path) {
+  return path.replace(/\.tsx?$/, "");
+}
+function sourceFile(source, filename) {
+  return ts.createSourceFile(
+    filename,
+    source,
+    ts.ScriptTarget.Latest,
+    true,
+    /\.[cm]?ts$/.test(filename) ? ts.ScriptKind.TS : ts.ScriptKind.TSX
+  );
+}
+function walk(node, visitor) {
+  visitor(node);
+  for (const child of node.children ?? []) walk(child, visitor);
+}
+function implicitReactImports(source) {
+  const bindings = /* @__PURE__ */ new Set();
+  const references = /* @__PURE__ */ new Set();
+  function bind(name) {
+    if (ts.isIdentifier(name)) bindings.add(name.text);
+    else for (const element of name.elements) if (ts.isBindingElement(element)) bind(element.name);
+  }
+  for (const statement of source.statements) {
+    if (ts.isImportDeclaration(statement) && statement.importClause) {
+      const clause = statement.importClause;
+      if (clause.name) bindings.add(clause.name.text);
+      if (clause.namedBindings) {
+        if (ts.isNamespaceImport(clause.namedBindings)) bindings.add(clause.namedBindings.name.text);
+        else for (const element of clause.namedBindings.elements) bindings.add(element.name.text);
+      }
+    }
+    if (ts.isVariableStatement(statement)) for (const declaration of statement.declarationList.declarations) bind(declaration.name);
+    if ((ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement)) && statement.name) bindings.add(statement.name.text);
+  }
+  function visit(node) {
+    if (ts.isIdentifier(node) && !(ts.isPropertyAccessExpression(node.parent) && node.parent.name === node) && !(ts.isPropertyAssignment(node.parent) && node.parent.name === node)) references.add(node.text);
+    ts.forEachChild(node, visit);
+  }
+  visit(source);
+  const hooks = [...REACT_GLOBALS].filter((name) => references.has(name) && !bindings.has(name)).sort();
+  return [
+    references.has("React") && !bindings.has("React") ? "import * as React from 'react';" : "",
+    hooks.length ? `import { ${hooks.join(", ")} } from 'react';` : ""
+  ].filter(Boolean).join("\n");
+}
+function imports(statement) {
+  if (!ts.isStringLiteral(statement.moduleSpecifier) || !statement.importClause) return [];
+  const clause = statement.importClause;
+  if (clause.isTypeOnly) return [];
+  const source = statement.moduleSpecifier.text;
+  const bindings = clause.name ? [{ local: clause.name.text, imported: "default", source }] : [];
+  if (clause.namedBindings && ts.isNamedImports(clause.namedBindings)) {
+    for (const element of clause.namedBindings.elements) {
+      if (!element.isTypeOnly) bindings.push({ local: element.name.text, imported: element.propertyName?.text ?? element.name.text, source });
+    }
+  }
+  return bindings;
+}
+function createComponentMigrator(siteRoot, warnings, sourceIdentity) {
+  const root = resolve2(siteRoot);
+  const destinationRoot = `src/mdx/migrated/${hash(sourceIdentity)}`;
+  const copied = /* @__PURE__ */ new Map();
+  const registrations = /* @__PURE__ */ new Map();
+  let copiedBytes = 0;
+  function warn(message, source) {
+    warnings.push({ code: "unsupported-config", message, source: relative2(root, source).replace(/\\/g, "/") });
+  }
+  function checkedFile(path) {
+    const local = relative2(root, path);
+    resolveWithin(root, local);
+    let current = root;
+    if (lstatSync(current).isSymbolicLink()) throw new Error("symbolic links are not imported");
+    for (const segment of local.split(/[\\/]/)) {
+      current = resolveWithin(current, segment);
+      if (lstatSync(current).isSymbolicLink()) throw new Error("symbolic links are not imported");
+    }
+    if (!lstatSync(path).isFile()) throw new Error("dependency is not a regular file");
+    return path;
+  }
+  function resolveDependency(specifier, importer) {
+    if (specifier.includes("\\") || specifier.includes("\0") || /[?#]/.test(specifier)) throw new Error("unsupported component dependency path");
+    const candidate = specifier.startsWith("/") ? resolveWithin(root, specifier.slice(1)) : resolveWithin(root, relative2(root, resolve2(dirname(importer), specifier)));
+    const candidates = [candidate];
+    if (!extname(candidate)) {
+      candidates.push(...[".tsx", ".jsx", ".ts", ".js", ".mjs", ".json"].map((extension) => candidate + extension));
+      candidates.push(...["index.tsx", "index.jsx", "index.ts", "index.js"].map((name) => resolve2(candidate, name)));
+    } else if (extname(candidate) === ".js") {
+      candidates.push(candidate.slice(0, -3) + ".ts", candidate.slice(0, -3) + ".tsx");
+    }
+    for (const path of candidates) {
+      if (existsSync(path) && lstatSync(path).isFile()) return checkedFile(path);
+    }
+    throw new Error(`component dependency ${specifier} was not found`);
+  }
+  function outputPath(path) {
+    return `${destinationRoot}/source/${relative2(root, path).replace(/\\/g, "/")}`;
+  }
+  function copyGraph(entry) {
+    const staged = /* @__PURE__ */ new Map();
+    let stagedBytes = 0;
+    function visit(path) {
+      const destination = outputPath(path);
+      if (copied.has(destination) || staged.has(destination)) return;
+      checkedFile(path);
+      const size = lstatSync(path).size;
+      if (size > MAX_FILE_BYTES || copiedBytes + stagedBytes + size > MAX_COMPONENT_BYTES || copied.size + staged.size >= MAX_COMPONENT_FILES) throw new Error("component migration budget exceeded");
+      const extension = extname(path).toLowerCase();
+      if (!CODE_EXTENSIONS.has(extension) && !DATA_EXTENSIONS.has(extension)) throw new Error(`unsupported dependency file type ${extension}`);
+      stagedBytes += size;
+      const content = readFileSync(path);
+      staged.set(destination, { path: destination, content });
+      if (!CODE_EXTENSIONS.has(extension)) {
+        if (extension === ".css" && /@import\b|url\s*\(/i.test(content.toString("utf8"))) throw new Error("CSS resource dependencies require manual migration");
+        return;
+      }
+      const text = content.toString("utf8");
+      const syntax = ts.transpileModule(text, {
+        fileName: path,
+        reportDiagnostics: true,
+        compilerOptions: { jsx: ts.JsxEmit.Preserve, target: ts.ScriptTarget.ESNext, module: ts.ModuleKind.ESNext }
+      });
+      if (syntax.diagnostics?.some((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error)) throw new Error("component source contains unsupported JavaScript or TypeScript syntax");
+      const ast = sourceFile(text, path);
+      if (ast.statements.some((statement) => ts.isExpressionStatement(statement) && ts.isStringLiteral(statement.expression) && statement.expression.text === "use server")) throw new Error("server-only component modules require manual migration");
+      const edits = [];
+      function dependency(literal) {
+        const specifier = literal.text;
+        if (SHARED_IMPORTS.has(specifier)) return;
+        if (!specifier.startsWith(".") && !specifier.startsWith("/")) {
+          throw new Error(`external package ${specifier} requires manual installation and review`);
+        }
+        const target = resolveDependency(specifier, path);
+        visit(target);
+        const nextPath = relative2(dirname(destination), outputPath(target)).replace(/\\/g, "/");
+        edits.push({ start: literal.getStart(ast), end: literal.end, value: JSON.stringify(portableSpecifier(nextPath.startsWith(".") ? nextPath : `./${nextPath}`)) });
+      }
+      function inspect(node) {
+        if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) dependency(node.moduleSpecifier);
+        if (ts.isCallExpression(node) && (node.expression.kind === ts.SyntaxKind.ImportKeyword || ts.isIdentifier(node.expression) && node.expression.text === "require")) {
+          const argument = node.arguments[0];
+          if (node.arguments.length !== 1 || !argument || !ts.isStringLiteralLike(argument)) throw new Error("computed component imports require manual migration");
+          dependency(argument);
+        }
+        ts.forEachChild(node, inspect);
+      }
+      inspect(ast);
+      staged.set(destination, { path: destination, content: `'use client';
+
+${implicitReactImports(ast)}
+${applyReplacements(text, edits)}` });
+    }
+    visit(entry);
+    for (const [path, file] of staged) copied.set(path, file);
+    copiedBytes += stagedBytes;
+    return outputPath(entry);
+  }
+  function register(path, imported) {
+    const name = `Migrated${hash(`${path}:${imported}`)}`;
+    registrations.set(name, { path, imported });
+    return name;
+  }
+  function transform(raw, currentFile) {
+    const content = parseFrontmatter(raw).content;
+    const frontmatter = raw.slice(0, raw.length - content.length);
+    let tree;
+    try {
+      tree = parser.parse(content);
+    } catch {
+      warn("Custom component analysis could not parse this MDX; its source was preserved for manual migration.", currentFile);
+      return raw;
+    }
+    const aliases = /* @__PURE__ */ new Map();
+    const edits = [];
+    const declarations = [];
+    const moduleImports = [];
+    const sharedImportEdits = [];
+    let hasUnsupportedImports = false;
+    function hasExpressionReference(names, options = {}) {
+      let found = false;
+      function inspect2(node) {
+        if (ts.isIdentifier(node) && names.has(node.text)) found = true;
+        ts.forEachChild(node, inspect2);
+      }
+      walk(tree, (node) => {
+        if (options.excludedNodes?.some((excluded) => node.position?.start.offset !== void 0 && node.position.end.offset !== void 0 && node.position.start.offset >= excluded.position.start.offset && node.position.end.offset <= excluded.position.end.offset)) return;
+        if (node.name && [...names].some((name) => node.name.startsWith(`${name}.`) || options.includeDirectTags && node.name === name)) found = true;
+        if (options.includeDeclarations !== false && node.type === "mdxjsEsm" && node.value) {
+          for (const statement of sourceFile(node.value, "expression.tsx").statements) {
+            if (!ts.isImportDeclaration(statement)) inspect2(statement);
+          }
+        }
+        const expressions = [
+          ...["mdxFlowExpression", "mdxTextExpression"].includes(node.type) ? [node.value ?? ""] : [],
+          ...(node.attributes ?? []).flatMap((attribute) => {
+            if (attribute.type === "mdxJsxExpressionAttribute" && typeof attribute.value === "string") return [attribute.value];
+            return attribute.value && typeof attribute.value === "object" ? [attribute.value.value ?? ""] : [];
+          })
+        ];
+        for (const expression of expressions) inspect2(sourceFile(expression, "expression.tsx"));
+      });
+      return found;
+    }
+    for (const node of tree.children ?? []) {
+      if (node.type !== "mdxjsEsm" || node.value === void 0 || node.position?.start.offset === void 0) continue;
+      const ast = sourceFile(node.value, "inline.tsx");
+      for (const statement of ast.statements) {
+        if (!ts.isImportDeclaration(statement)) {
+          let inspect2 = function(node2) {
+            if (ts.isCallExpression(node2) && (node2.expression.kind === ts.SyntaxKind.ImportKeyword || ts.isIdentifier(node2.expression) && node2.expression.text === "require")) unsupportedDependency = true;
+            ts.forEachChild(node2, inspect2);
+          };
+          var inspect = inspect2;
+          let unsupportedDependency = ts.isExportDeclaration(statement) && !!statement.moduleSpecifier;
+          inspect2(statement);
+          if (unsupportedDependency) {
+            hasUnsupportedImports = true;
+            warn("Inline MDX module dependencies require manual extraction; source was preserved.", currentFile);
+          }
+          declarations.push({
+            start: node.position.start.offset + statement.getStart(ast),
+            end: node.position.start.offset + statement.end,
+            source: statement.getText(ast)
+          });
+          continue;
+        }
+        const bindings = imports(statement);
+        const specifier = ts.isStringLiteral(statement.moduleSpecifier) ? statement.moduleSpecifier.text : "";
+        if (!specifier.startsWith(".") && !specifier.startsWith("/")) {
+          if (SHARED_IMPORTS.has(specifier)) {
+            moduleImports.push(statement.getText(ast));
+            sharedImportEdits.push({ start: node.position.start.offset + statement.getStart(ast), end: node.position.start.offset + statement.end, value: "" });
+          } else {
+            hasUnsupportedImports = true;
+            warn(`MDX import ${specifier} requires manual package installation or registration; the import was preserved.`, currentFile);
+          }
+          continue;
+        }
+        if (/\.mdx?$/.test(specifier)) continue;
+        if (!bindings.length || statement.importClause?.namedBindings && ts.isNamespaceImport(statement.importClause.namedBindings)) {
+          warn("Namespace or side-effect MDX imports require manual registration; the import was preserved.", currentFile);
+          hasUnsupportedImports = true;
+          continue;
+        }
+        if (bindings.some((binding) => !/^[A-Z]/.test(binding.local))) {
+          warn("MDX imports containing non-component values require manual migration; the import was preserved.", currentFile);
+          hasUnsupportedImports = true;
+          continue;
+        }
+        if (hasExpressionReference(new Set(bindings.map((binding) => binding.local)))) {
+          warn("Imported components used in MDX expressions, component props, or member tags require manual migration; the import was preserved.", currentFile);
+          hasUnsupportedImports = true;
+          continue;
+        }
+        try {
+          const path = copyGraph(resolveDependency(specifier, currentFile));
+          for (const binding of bindings) {
+            const name = register(path, binding.imported);
+            aliases.set(binding.local, name);
+            moduleImports.push(`import { ${binding.imported} as ${binding.local} } from ${JSON.stringify(portableSpecifier(`./${relative2(destinationRoot, path).replace(/\\/g, "/")}`))};`);
+          }
+          edits.push({ start: node.position.start.offset + statement.getStart(ast), end: node.position.start.offset + statement.end, value: "" });
+        } catch (error) {
+          hasUnsupportedImports = true;
+          warn(`Custom component was preserved for manual migration: ${error instanceof Error ? error.message : "unsupported dependency"}.`, currentFile);
+        }
+      }
+    }
+    const extracted = [];
+    for (const candidate of tree.children ?? []) {
+      const node = candidate.type === "paragraph" && candidate.children?.length === 1 ? candidate.children[0] : candidate;
+      if (!["mdxJsxFlowElement", "mdxJsxTextElement"].includes(node.type) || node.position?.start.offset === void 0 || node.position.end.offset === void 0) continue;
+      let interactive = false;
+      let supported = true;
+      walk(node, (child) => {
+        if (child.attributes?.some((attribute) => /^on[A-Z]/.test(attribute.name ?? ""))) interactive = true;
+        if (child.name && /^[A-Z]/.test(child.name) && !aliases.has(child.name)) supported = false;
+        if (!["mdxJsxFlowElement", "mdxJsxTextElement", "mdxFlowExpression", "mdxTextExpression", "text", "paragraph"].includes(child.type)) supported = false;
+      });
+      if (!interactive) continue;
+      if (!supported || hasUnsupportedImports) {
+        warn("Interactive MDX containing Markdown or unregistered components requires manual extraction; source was preserved.", currentFile);
+        continue;
+      }
+      const jsx = content.slice(node.position.start.offset, node.position.end.offset);
+      const result = ts.transpileModule(`export default function Inline() { return (${jsx}); }`, {
+        fileName: "inline.jsx",
+        compilerOptions: { jsx: ts.JsxEmit.Preserve },
+        reportDiagnostics: true
+      });
+      if (result.diagnostics?.some((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error)) {
+        warn("Interactive MDX could not be safely extracted as JSX; source was preserved.", currentFile);
+        continue;
+      }
+      extracted.push({ node, name: `Inline${extracted.length}`, jsx });
+    }
+    if (extracted.length && declarations.length) {
+      let bind2 = function(name) {
+        if (ts.isIdentifier(name)) declared.add(name.text);
+        else for (const element of name.elements) if (ts.isBindingElement(element)) bind2(element.name);
+      };
+      var bind = bind2;
+      const declared = /* @__PURE__ */ new Set();
+      for (const declaration of declarations) {
+        for (const statement of sourceFile(declaration.source, "declaration.tsx").statements) {
+          if ((ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement)) && statement.name) declared.add(statement.name.text);
+          if (ts.isVariableStatement(statement)) for (const variable of statement.declarationList.declarations) bind2(variable.name);
+        }
+      }
+      const hasSharedDeclarations = hasExpressionReference(declared, {
+        excludedNodes: extracted.map((entry) => entry.node),
+        includeDeclarations: false,
+        includeDirectTags: true
+      });
+      if (hasSharedDeclarations) {
+        warn("Interactive MDX shares declarations with remaining page content; source was preserved for manual extraction.", currentFile);
+        extracted.length = 0;
+      }
+    }
+    if (extracted.length && (copied.size >= MAX_COMPONENT_FILES || Buffer.byteLength(content) > MAX_FILE_BYTES || copiedBytes + Buffer.byteLength(content) > MAX_COMPONENT_BYTES)) {
+      warn("Interactive MDX exceeded the component migration budget; source was preserved.", currentFile);
+      extracted.length = 0;
+    }
+    if (extracted.length) {
+      const path = `${destinationRoot}/inline-${hash(relative2(root, currentFile))}.jsx`;
+      let declarationSource = [...new Set(declarations.map((entry) => entry.source))].join("\n\n");
+      declarationSource = declarationSource.replace(
+        /document\.getElementById\(\s*(['"])search-bar-entry\1\s*\)\.click\(\s*\)/g,
+        `document.dispatchEvent(new KeyboardEvent('keydown', { key: 'k', ctrlKey: true, bubbles: true }))`
+      );
+      const inlineSource = [
+        "'use client';",
+        "",
+        ...moduleImports,
+        "",
+        declarationSource,
+        "",
+        ...extracted.map(({ name, jsx }) => `export function ${name}() {
+  return (${jsx});
+}`),
+        ""
+      ].join("\n");
+      copied.set(path, { path, content: `'use client';
+${implicitReactImports(sourceFile(inlineSource, "inline.jsx"))}
+${inlineSource}` });
+      copiedBytes += Buffer.byteLength(inlineSource);
+      for (const { node, name } of extracted) {
+        edits.push({ start: node.position.start.offset, end: node.position.end.offset, value: `<${register(path, name)} />` });
+      }
+      edits.push(...declarations.map(({ start, end }) => ({ start, end, value: "" })), ...sharedImportEdits);
+    }
+    walk(tree, (node) => {
+      const replacement = node.name ? aliases.get(node.name) : void 0;
+      if (!replacement || node.position?.start.offset === void 0 || node.position.end.offset === void 0) return;
+      const start = node.position.start.offset;
+      const end = node.position.end.offset;
+      if (extracted.some((item) => start >= item.node.position.start.offset && end <= item.node.position.end.offset)) return;
+      const text = content.slice(start, end);
+      const opening = text.indexOf(`<${node.name}`);
+      if (opening >= 0) edits.push({ start: start + opening + 1, end: start + opening + 1 + node.name.length, value: replacement });
+      const closing = text.lastIndexOf(`</${node.name}`);
+      if (closing >= 0) edits.push({ start: start + closing + 2, end: start + closing + 2 + node.name.length, value: replacement });
+    });
+    return frontmatter + applyReplacements(content, edits);
+  }
+  function files() {
+    if (!registrations.size) return [];
+    const entries = [...registrations.entries()].sort(([a], [b]) => a.localeCompare(b));
+    return [...copied.values(), {
+      path: "src/mdx/custom-components.tsx",
+      content: [
+        "/** Repository components preserved by migration; this registry is customer-owned. */",
+        "import type { MDXComponents } from 'mdx/types'",
+        ...entries.map(([name, binding]) => {
+          const path = portableSpecifier(`./${relative2("src/mdx", binding.path).replace(/\\/g, "/")}`);
+          return `import { ${binding.imported} as ${name} } from ${JSON.stringify(path)}`;
+        }),
+        "",
+        "export const customComponents: MDXComponents = {",
+        ...entries.map(([name]) => `  ${name},`),
+        "}",
+        ""
+      ].join("\n")
+    }];
+  }
+  return { transform, files };
+}
+function mergeComponentRegistry(existing, incoming) {
+  const fingerprint = hash(incoming);
+  const name = `MigratedRegistry${fingerprint}`;
+  const registryPath = `./migrated-components-${fingerprint}`;
+  const source = sourceFile(existing, "custom-components.tsx");
+  const alreadyImported = source.statements.some((statement) => ts.isImportDeclaration(statement) && ts.isStringLiteral(statement.moduleSpecifier) && statement.moduleSpecifier.text === registryPath);
+  let initializer;
+  for (const statement of source.statements) {
+    if (!ts.isVariableStatement(statement) || !statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)) continue;
+    for (const declaration of statement.declarationList.declarations) {
+      if (ts.isIdentifier(declaration.name) && declaration.name.text === "customComponents") initializer = declaration.initializer;
+    }
+  }
+  while (initializer && (ts.isAsExpression(initializer) || ts.isSatisfiesExpression(initializer) || ts.isParenthesizedExpression(initializer))) initializer = initializer.expression;
+  if (!initializer || !ts.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) => ts.isExpressionStatement(statement) && ts.isStringLiteral(statement.expression)).at(-1)?.end ?? 0,
+      end: source.statements.filter((statement) => ts.isExpressionStatement(statement) && ts.isStringLiteral(statement.expression)).at(-1)?.end ?? 0,
+      value: `
+import { customComponents as ${name} } from ${JSON.stringify(registryPath)}
+`
+    },
+    { start: initializer.getStart(source) + 1, end: initializer.getStart(source) + 1, value: `
+  ...${name},` }
+  ]);
+  return [
+    { path: `src/mdx/migrated-components-${fingerprint}.tsx`, content: incoming },
+    { path: "src/mdx/custom-components.tsx", content }
+  ];
+}
+
 // src/docusaurus.ts
+import { existsSync as existsSync2, lstatSync as lstatSync2, readFileSync as readFileSync2 } from "fs";
+import { extname as extname2, posix } from "path";
+import JSON5 from "json5";
+import { parse as parseYaml2 } from "yaml";
 var MAX_CONFIG_BYTES = 1e6;
 var CATEGORY_FILENAMES = ["_category_.json", "_category_.yml", "_category_.yaml"];
 var SIDEBAR_FILENAMES = [
@@ -184,10 +686,10 @@ function rewriteDocusaurusLinks(body, current, descriptors) {
   }).join("\n");
 }
 function readBoundedText(path) {
-  if (lstatSync(path).size > MAX_CONFIG_BYTES) {
+  if (lstatSync2(path).size > MAX_CONFIG_BYTES) {
     throw new Error("Docusaurus sidebar config exceeded the 1 MB static-parser limit.");
   }
-  return readFileSync(path, "utf8");
+  return readFileSync2(path, "utf8");
 }
 function matchingObjectLiteral(source, start) {
   let depth = 0;
@@ -342,33 +844,33 @@ function matchingArrayLiteral(source, start) {
 function configuredSidebarPath(repositoryRoot) {
   for (const filename of ["docusaurus.config.js", "docusaurus.config.ts", "docusaurus.config.mjs"]) {
     const path = resolveWithin(repositoryRoot, filename);
-    if (!existsSync(path)) continue;
+    if (!existsSync2(path)) continue;
     const source = readBoundedText(path);
     const match = source.match(/\bsidebarPath\s*:\s*(?:require\.resolve\(\s*)?(['"])([^'"]+)\1/);
     if (!match) continue;
     const candidate = match[2].replace(/^\.\//, "");
     const resolved = resolveWithin(repositoryRoot, candidate);
-    if (existsSync(resolved) && lstatSync(resolved).isFile()) return candidate;
+    if (existsSync2(resolved) && lstatSync2(resolved).isFile()) return candidate;
   }
   return null;
 }
 function readDocusaurusSidebars(repositoryRoot) {
   const configured = configuredSidebarPath(repositoryRoot);
-  const sourcePath = [configured, ...SIDEBAR_FILENAMES].filter((value) => Boolean(value)).find((candidate) => existsSync(resolveWithin(repositoryRoot, candidate)));
+  const sourcePath = [configured, ...SIDEBAR_FILENAMES].filter((value) => Boolean(value)).find((candidate) => existsSync2(resolveWithin(repositoryRoot, candidate)));
   if (!sourcePath) return null;
   const absolutePath = resolveWithin(repositoryRoot, sourcePath);
   const source = readBoundedText(absolutePath);
-  const parsed = extname(sourcePath).toLowerCase() === ".json" ? objectValue(JSON5.parse(source)) : parseStaticSidebarModule(source);
+  const parsed = extname2(sourcePath).toLowerCase() === ".json" ? objectValue(JSON5.parse(source)) : parseStaticSidebarModule(source);
   if (!parsed) throw new Error("Docusaurus sidebar config must export an object.");
   return { config: parsed, sourcePath };
 }
 function readCategoryMetadata(contentRoot, directory) {
   for (const filename of CATEGORY_FILENAMES) {
     const path = resolveWithin(contentRoot, posix.join(directory, filename));
-    if (!existsSync(path) || !lstatSync(path).isFile()) continue;
+    if (!existsSync2(path) || !lstatSync2(path).isFile()) continue;
     try {
       const raw = readBoundedText(path);
-      const parsed = filename.endsWith(".json") ? JSON5.parse(raw) : parseYaml(raw);
+      const parsed = filename.endsWith(".json") ? JSON5.parse(raw) : parseYaml2(raw);
       const object = objectValue(parsed);
       if (!object) return {};
       return {
@@ -533,42 +1035,39 @@ function projectDocusaurusNavigation(input) {
   };
 }
 
-// src/frontmatter.ts
-import { parse as parseYaml2 } from "yaml";
-function parseFrontmatter(raw) {
-  const source = raw.charCodeAt(0) === 65279 ? raw.slice(1) : raw;
-  const opening = /^---([^\r\n]*)\r?\n/.exec(source);
-  if (!opening || opening[1].startsWith("-")) return { content: source, data: {} };
-  const language = opening[1].trim().toLowerCase();
-  const remainder = source.slice(opening[0].length);
-  const closing = /^---[ \t]*\r?$/m.exec(remainder);
-  const matter = closing ? remainder.slice(0, closing.index) : remainder;
-  let content = closing ? remainder.slice(closing.index + closing[0].length) : "";
-  if (content.startsWith("\r\n")) content = content.slice(2);
-  else if (content.startsWith("\n")) content = content.slice(1);
-  if (matter.trim() === "" || !["", "yaml", "yml"].includes(language)) {
-    return { content, data: {} };
-  }
-  const parsed = parseYaml2(matter);
-  return {
-    content,
-    data: parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {}
-  };
-}
-
 // src/mdx.ts
+import remarkMdx2 from "remark-mdx";
+import remarkParse2 from "remark-parse";
+import { unified as unified2 } from "unified";
 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(remarkMdx2);
 function firstParagraph(content) {
-  for (const block of content.split(/\n\s*\n/)) {
-    const value = block.replace(/\s+/g, " ").trim();
-    if (!value || /^(?:#|```|:::|<|import\s|export\s)/.test(value)) continue;
-    return value.replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").slice(0, 240);
+  function plainText(node) {
+    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("");
+  }
+  function findParagraph(node) {
+    if (node.type === "paragraph") {
+      const value = plainText(node).replace(/\s+/g, " ").trim();
+      if (value) return value.slice(0, 240);
+    }
+    for (const child of node.children ?? []) {
+      const value = findParagraph(child);
+      if (value) return value;
+    }
+    return "";
+  }
+  try {
+    return findParagraph(descriptionParser.parse(content));
+  } catch {
+    return "";
   }
-  return "";
 }
 function docusaurusAdmonitionTag(kind) {
   if (kind === "danger") return "Error";
@@ -646,24 +1145,94 @@ function parseMarkdownPage(input) {
 }
 
 // src/navigation.ts
-import { existsSync as existsSync2, lstatSync as lstatSync2, readFileSync as readFileSync2, realpathSync } from "fs";
-import { dirname, extname as extname2, relative as relative2 } from "path";
+import { existsSync as existsSync3, lstatSync as lstatSync3, readFileSync as readFileSync3, realpathSync } from "fs";
+import { dirname as dirname2, extname as extname3, relative as relative3 } from "path";
 var MAX_MINTLIFY_CONFIG_BYTES = 2e6;
 function addMintlifyDirectoryRedirects(config, pages) {
-  const pageIds = new Set(pages.filter((page) => !page.locale).map((page) => page.navigationId));
+  const pageIds = new Set(pages.map((page) => page.id));
   const redirects = [...config.redirects ?? []];
   const redirectSources = new Set(redirects.map((redirect) => redirect.source.replace(/\/$/, "") || "/"));
+  function hasAuthoredRedirect(source) {
+    if (redirectSources.has(source)) return true;
+    return (config.redirects ?? []).some((redirect) => {
+      const match = redirect.source.match(/^(.*)\/:[A-Za-z_][A-Za-z0-9_]*\*\/?$/);
+      return match ? source === match[1] || source.startsWith(`${match[1]}/`) : false;
+    });
+  }
   for (const page of pages) {
-    if (page.locale || !/(?:^|\/)(?:overview|introduction)$/.test(page.navigationId)) continue;
-    const parent = page.navigationId.replace(/\/(?:overview|introduction)$/, "");
+    if (!/\/(?:overview|introduction)$/.test(page.navigationId)) continue;
+    const parent = page.id.replace(/\/(?:overview|introduction)$/, "");
     if (!parent || pageIds.has(parent)) continue;
     const source = `/${parent}`;
-    if (redirectSources.has(source)) continue;
-    redirects.push({ source, destination: `/${page.navigationId}`, permanent: false });
+    if (hasAuthoredRedirect(source)) continue;
+    redirects.push({ source, destination: `/${page.id}`, permanent: false });
+    redirectSources.add(source);
+  }
+  const navigationOrder = [];
+  function collectPages(nodes) {
+    for (const node of nodes) {
+      if (typeof node === "string") navigationOrder.push(node);
+      else if (!node.hidden) collectPages(node.pages);
+    }
+  }
+  for (const tab of config.tabs) {
+    if (!tab.hidden) collectPages([...tab.pages ?? [], ...tab.groups ?? []]);
+  }
+  const pagesByNavigationId = /* @__PURE__ */ new Map();
+  for (const page of pages) {
+    if (page.hidden) continue;
+    const variants = pagesByNavigationId.get(page.navigationId) ?? [];
+    variants.push(page);
+    pagesByNavigationId.set(page.navigationId, variants);
+  }
+  const firstDescendantByDirectory = /* @__PURE__ */ new Map();
+  for (const navigationId of navigationOrder) {
+    for (const page of pagesByNavigationId.get(navigationId) ?? []) {
+      const segments = page.id.split("/");
+      for (let length = 1; length < segments.length; length++) {
+        const directory = segments.slice(0, length).join("/");
+        if (!firstDescendantByDirectory.has(directory)) firstDescendantByDirectory.set(directory, page);
+      }
+    }
+  }
+  for (const redirect of config.redirects ?? []) {
+    const destination = redirect.destination.split(/[?#]/, 1)[0].replace(/\/:[A-Za-z_][A-Za-z0-9_]*\*\/?$/, "");
+    if (!destination.startsWith("/") || destination.startsWith("//") || /[:*()[\]{}]/.test(destination)) continue;
+    const directory = trimEdgeSlashes(destination);
+    if (!directory || pageIds.has(directory)) continue;
+    const source = `/${directory}`;
+    if (hasAuthoredRedirect(source)) continue;
+    const landing = firstDescendantByDirectory.get(directory);
+    if (!landing) continue;
+    redirects.push({ source, destination: `/${landing.id}`, permanent: false });
     redirectSources.add(source);
   }
   return redirects.length > 0 ? { ...config, redirects } : config;
 }
+function addMintlifyHomepageRedirects(config, pages) {
+  const defaultPages = new Set(pages.filter((page) => !page.locale || page.locale === config.i18n?.defaultLocale).map((page) => page.navigationId));
+  function firstPage(nodes) {
+    for (const node of nodes) {
+      if (typeof node === "string") {
+        if (defaultPages.has(node)) return node;
+      } else if (!node.hidden) {
+        const page = firstPage(node.pages);
+        if (page) return page;
+      }
+    }
+  }
+  const homepage = config.tabs.filter((tab) => !tab.hidden).map((tab) => firstPage([...tab.pages ?? [], ...tab.groups ?? []])).find(Boolean);
+  if (!homepage || homepage === "introduction") return config;
+  const redirects = [...config.redirects ?? []];
+  const sources = new Set(redirects.map((redirect) => redirect.source.replace(/\/$/, "") || "/"));
+  const roots = ["", ...(config.i18n?.locales ?? []).filter((locale) => locale.code !== config.i18n?.defaultLocale).map((locale) => locale.code)];
+  for (const locale of roots) {
+    const source = locale ? `/${locale}` : "/";
+    if (sources.has(source)) continue;
+    redirects.push({ source, destination: `${locale ? `/${locale}` : ""}/${homepage}`, permanent: false });
+  }
+  return { ...config, redirects };
+}
 var LANGUAGE_LABELS = {
   ar: "Arabic",
   de: "German",
@@ -717,16 +1286,16 @@ function jsonPointer(root, pointer) {
   }, root);
 }
 function readMintlifyJson(path, repositoryRoot) {
-  if (!existsSync2(path) || !lstatSync2(path).isFile()) {
-    throw new Error(`Mintlify config reference is not a regular file: ${relative2(repositoryRoot, path)}`);
+  if (!existsSync3(path) || !lstatSync3(path).isFile()) {
+    throw new Error(`Mintlify config reference is not a regular file: ${relative3(repositoryRoot, path)}`);
   }
   const realPath = realpathSync(path);
   const realRoot = realpathSync(repositoryRoot);
-  resolveWithin(realRoot, relative2(realRoot, realPath));
-  if (lstatSync2(realPath).size > MAX_MINTLIFY_CONFIG_BYTES) {
-    throw new Error(`Mintlify config reference exceeded ${MAX_MINTLIFY_CONFIG_BYTES / 1e6} MB: ${relative2(repositoryRoot, path)}`);
+  resolveWithin(realRoot, relative3(realRoot, realPath));
+  if (lstatSync3(realPath).size > MAX_MINTLIFY_CONFIG_BYTES) {
+    throw new Error(`Mintlify config reference exceeded ${MAX_MINTLIFY_CONFIG_BYTES / 1e6} MB: ${relative3(repositoryRoot, path)}`);
   }
-  return JSON.parse(readFileSync2(realPath, "utf8"));
+  return JSON.parse(readFileSync3(realPath, "utf8"));
 }
 function resolveJsonReferences(value, currentFile, repositoryRoot, stack) {
   if (Array.isArray(value)) {
@@ -736,8 +1305,8 @@ function resolveJsonReferences(value, currentFile, repositoryRoot, stack) {
   if (!object) return value;
   if (typeof object.$ref === "string") {
     const [filePart, pointer = ""] = object.$ref.split("#", 2);
-    const referencedFile = filePart ? resolveWithin(dirname(currentFile), filePart) : currentFile;
-    const relativePath = relative2(repositoryRoot, referencedFile);
+    const referencedFile = filePart ? resolveWithin(dirname2(currentFile), filePart) : currentFile;
+    const relativePath = relative3(repositoryRoot, referencedFile);
     resolveWithin(repositoryRoot, relativePath);
     const stackKey = `${referencedFile}#${pointer}`;
     if (stack.has(stackKey)) throw new Error(`Circular Mintlify $ref: ${object.$ref}`);
@@ -762,7 +1331,7 @@ function resolveJsonReferences(value, currentFile, repositoryRoot, stack) {
   );
 }
 function readMintlifyConfig(repositoryRoot) {
-  const configPath = ["docs.json", "mint.json"].map((filename) => resolveWithin(repositoryRoot, filename)).find(existsSync2);
+  const configPath = ["docs.json", "mint.json"].map((filename) => resolveWithin(repositoryRoot, filename)).find(existsSync3);
   if (!configPath) return null;
   const raw = readMintlifyJson(configPath, repositoryRoot);
   return resolveJsonReferences(raw, configPath, repositoryRoot, /* @__PURE__ */ new Set());
@@ -794,8 +1363,7 @@ function containerPresentation(value) {
   };
 }
 function registerReference(value, context) {
-  const localePrefix = context.locale ? `${context.locale}/` : "";
-  const localizedValue = localePrefix && value.replace(/^\/+/, "").startsWith(localePrefix) ? value.replace(/^\/+/, "").slice(localePrefix.length) : value;
+  const localizedValue = context.locale ? mintlifyLocalizedReference(value, context.locale, context.defaultPageIds) : value;
   const navigationId = normalizePageRef(localizedValue, context.pathPrefix);
   if (!navigationId) return null;
   const key = `${context.locale ?? ""}:${value}`;
@@ -1037,15 +1605,25 @@ function projectMintlifyNavigation(config, options = {}) {
   const seenReferences = /* @__PURE__ */ new Set();
   const warningKeys = /* @__PURE__ */ new Set();
   const navigation = objectValue2(config.navigation) ?? config;
-  const languages = Array.isArray(navigation.languages) ? navigation.languages.map(objectValue2).filter((value) => Boolean(value)) : [];
+  const languages = Array.isArray(navigation.languages) ? navigation.languages.flatMap((value) => {
+    const language = objectValue2(value);
+    if (!language) return [];
+    try {
+      const code = Intl.getCanonicalLocales(String(language.language ?? language.locale ?? "en"))[0];
+      return [{ ...language, language: code }];
+    } catch {
+      warnings.push({ code: "unsupported-config", message: "A navigation language with an invalid locale code was skipped." });
+      return [];
+    }
+  }) : [];
   let tabs = [];
   let i18n;
   const projectionTrace = {};
   if (languages.length > 0) {
     const defaultLanguage = languages.find((entry) => entry.default === true) ?? languages[0];
-    const defaultLocale = String(defaultLanguage.language ?? defaultLanguage.locale ?? "en");
+    const defaultLocale = String(defaultLanguage.language);
     const locales = languages.map((entry) => {
-      const code = String(entry.language ?? entry.locale ?? "en");
+      const code = String(entry.language);
       let label = LANGUAGE_LABELS[code];
       try {
         label ??= new Intl.DisplayNames(["en"], { type: "language" }).of(code) ?? void 0;
@@ -1054,10 +1632,12 @@ function projectMintlifyNavigation(config, options = {}) {
       return { code, label: label ?? code.toUpperCase() };
     });
     i18n = { defaultLocale, locales };
-    for (const language of languages) {
-      const locale = String(language.language ?? language.locale ?? defaultLocale);
+    const defaultPageIds = /* @__PURE__ */ new Set();
+    for (const language of [defaultLanguage, ...languages.filter((entry) => entry !== defaultLanguage)]) {
+      const locale = String(language.language);
       const context = {
         locale,
+        defaultPageIds,
         pathPrefix: options.pathPrefix,
         references,
         seenReferences,
@@ -1070,7 +1650,10 @@ function projectMintlifyNavigation(config, options = {}) {
         "Documentation",
         language === defaultLanguage ? projectionTrace : void 0
       );
-      if (language === defaultLanguage) tabs = languageTabs;
+      if (language === defaultLanguage) {
+        tabs = languageTabs;
+        for (const reference of references) defaultPageIds.add(reference.navigationId);
+      }
     }
   } else {
     const context = { references, seenReferences, warnings, warningKeys, pathPrefix: options.pathPrefix };
@@ -1133,8 +1716,8 @@ function topLevelLabel(segment) {
 function groupsWithinSection(section, pageIds, sectionLabel = topLevelLabel(section)) {
   const groups = /* @__PURE__ */ new Map();
   for (const id of pageIds) {
-    const relative4 = id === "introduction" ? "" : id.startsWith(`${section}/`) ? id.slice(section.length + 1) : id;
-    const nestedSegment = relative4.includes("/") ? relative4.split("/", 1)[0] : "overview";
+    const relative5 = id === "introduction" ? "" : id.startsWith(`${section}/`) ? id.slice(section.length + 1) : id;
+    const nestedSegment = relative5.includes("/") ? relative5.split("/", 1)[0] : "overview";
     const group = groups.get(nestedSegment) ?? [];
     group.push(id);
     groups.set(nestedSegment, group);
@@ -1218,7 +1801,7 @@ function buildNavigationFromPages(pages, options = {}) {
   return { tabs: [{ tab: "Documentation", groups }] };
 }
 function isDocumentationExtension(filename) {
-  return [".md", ".mdx", ".rst", ".txt"].includes(extname2(filename).toLowerCase());
+  return [".md", ".mdx", ".rst", ".txt"].includes(extname3(filename).toLowerCase());
 }
 
 // src/repository.ts
@@ -1280,16 +1863,16 @@ var DOCUSAURUS_CONFIG_FILENAMES = [
 function hasDocusaurusConfig(directory) {
   return DOCUSAURUS_CONFIG_FILENAMES.some((filename) => {
     const path = resolveWithin(directory, filename);
-    return existsSync3(path) && lstatSync3(path).isFile();
+    return existsSync4(path) && lstatSync4(path).isFile();
   });
 }
 function hasMintlifyConfig(directory) {
   return ["docs.json", "mint.json"].some((filename) => {
     const path = resolveWithin(directory, filename);
-    if (!existsSync3(path) || !lstatSync3(path).isFile()) return false;
+    if (!existsSync4(path) || !lstatSync4(path).isFile()) return false;
     if (filename === "mint.json") return true;
     try {
-      const config = JSON.parse(readFileSync3(path, "utf8"));
+      const config = JSON.parse(readFileSync4(path, "utf8"));
       return String(config.$schema ?? "").includes("mintlify") || "navigation" in config;
     } catch {
       return false;
@@ -1303,7 +1886,7 @@ function findMintlifyProjectRoot(repositoryDir, docsDir) {
       const path = resolveWithin(repositoryDir, candidate || ".");
       if (hasMintlifyConfig(path)) return path;
       if (!candidate) break;
-      const parent = dirname2(candidate);
+      const parent = dirname3(candidate);
       candidate = parent === "." ? "" : parent;
     }
   }
@@ -1328,7 +1911,7 @@ function findDocusaurusProjectRoot(repositoryDir, docsDir) {
       const path = resolveWithin(repositoryDir, candidate || ".");
       if (hasDocusaurusConfig(path)) return path;
       if (!candidate) break;
-      const parent = dirname2(candidate);
+      const parent = dirname3(candidate);
       candidate = parent === "." ? "" : parent;
     }
   }
@@ -1350,9 +1933,9 @@ function findDocusaurusProjectRoot(repositoryDir, docsDir) {
   return null;
 }
 function readDocusaurusConfigSource(projectRoot) {
-  const path = DOCUSAURUS_CONFIG_FILENAMES.map((filename) => resolveWithin(projectRoot, filename)).find((candidate) => existsSync3(candidate) && lstatSync3(candidate).isFile());
-  if (!path || lstatSync3(path).size > 1e6) return "";
-  return readFileSync3(path, "utf8");
+  const path = DOCUSAURUS_CONFIG_FILENAMES.map((filename) => resolveWithin(projectRoot, filename)).find((candidate) => existsSync4(candidate) && lstatSync4(candidate).isFile());
+  if (!path || lstatSync4(path).size > 1e6) return "";
+  return readFileSync4(path, "utf8");
 }
 function primaryDocusaurusDocsDirectory(projectRoot) {
   const source = readDocusaurusConfigSource(projectRoot);
@@ -1361,7 +1944,7 @@ function primaryDocusaurusDocsDirectory(projectRoot) {
 }
 function additionalDocusaurusPluginRoots(repositoryDir, projectRoot) {
   const source = readDocusaurusConfigSource(projectRoot);
-  const projectRelative = relative3(repositoryDir, projectRoot).replace(/\\/g, "/");
+  const projectRelative = relative4(repositoryDir, projectRoot).replace(/\\/g, "/");
   const plugins = [];
   const matcher = /['"]@docusaurus\/plugin-content-docs['"][\s\S]{0,3000}?\bpath\s*:\s*(['"])([^'"]+)\1[\s\S]{0,1000}?\brouteBasePath\s*:\s*(['"])([^'"]+)\3/g;
   for (const match of source.matchAll(matcher)) {
@@ -1370,7 +1953,7 @@ function additionalDocusaurusPluginRoots(repositoryDir, projectRoot) {
     if (!localPath || !routePrefix) continue;
     const docsDir = [projectRelative, localPath].filter(Boolean).join("/");
     const absolute = resolveWithin(repositoryDir, docsDir);
-    if (!existsSync3(absolute) || !lstatSync3(absolute).isDirectory()) continue;
+    if (!existsSync4(absolute) || !lstatSync4(absolute).isDirectory()) continue;
     plugins.push({ docsDir, routePrefix });
   }
   return plugins;
@@ -1413,7 +1996,7 @@ async function cloneGitHubRepository(source, targetDir) {
   const args = ["clone", "--depth", "1", "--single-branch"];
   if (source.branch !== "HEAD") args.push("--branch", source.branch);
   args.push("--", source.cloneUrl, targetDir);
-  await new Promise((resolve2, reject) => {
+  await new Promise((resolve3, reject) => {
     const child = spawn("git", args, { stdio: ["ignore", "ignore", "pipe"] });
     let stderr = "";
     child.stderr.setEncoding("utf8");
@@ -1422,7 +2005,7 @@ async function cloneGitHubRepository(source, targetDir) {
     });
     child.on("error", reject);
     child.on("close", (code) => {
-      if (code === 0) resolve2();
+      if (code === 0) resolve3();
       else reject(new Error(`Failed to clone ${source.owner}/${source.repo}: ${stderr.trim() || `git exited ${code}`}`));
     });
   });
@@ -1431,19 +2014,19 @@ function detectRepositoryPlatform(repositoryDir, docsDir) {
   if (findMintlifyProjectRoot(repositoryDir, docsDir)) return "mintlify";
   const selectedRoot = docsDir === void 0 ? repositoryDir : resolveWithin(repositoryDir, docsDir || ".");
   const docsJson = resolveWithin(selectedRoot, "docs.json");
-  if (existsSync3(docsJson)) {
+  if (existsSync4(docsJson)) {
     try {
-      const config = JSON.parse(readFileSync3(docsJson, "utf8"));
+      const config = JSON.parse(readFileSync4(docsJson, "utf8"));
       if (Array.isArray(config.tabs)) return "thally";
     } catch {
     }
   }
-  if (["docusaurus.config.js", "docusaurus.config.ts", "docusaurus.config.mjs"].some((name) => existsSync3(resolveWithin(repositoryDir, name)))) return "docusaurus";
+  if (["docusaurus.config.js", "docusaurus.config.ts", "docusaurus.config.mjs"].some((name) => existsSync4(resolveWithin(repositoryDir, name)))) return "docusaurus";
   if (findDocusaurusProjectRoot(repositoryDir)) return "docusaurus";
-  if (existsSync3(resolveWithin(repositoryDir, "SUMMARY.md"))) return "gitbook";
-  if (existsSync3(resolveWithin(repositoryDir, ".vitepress"))) return "vitepress";
-  if (["astro.config.mjs", "astro.config.ts"].some((name) => existsSync3(resolveWithin(repositoryDir, name)))) return "starlight";
-  if (["pages/_meta.json", "_meta.json"].some((name) => existsSync3(resolveWithin(repositoryDir, name)))) return "nextra";
+  if (existsSync4(resolveWithin(repositoryDir, "SUMMARY.md"))) return "gitbook";
+  if (existsSync4(resolveWithin(repositoryDir, ".vitepress"))) return "vitepress";
+  if (["astro.config.mjs", "astro.config.ts"].some((name) => existsSync4(resolveWithin(repositoryDir, name)))) return "starlight";
+  if (["pages/_meta.json", "_meta.json"].some((name) => existsSync4(resolveWithin(repositoryDir, name)))) return "nextra";
   return "unknown";
 }
 function containsMarkdown(directory, depth = 0) {
@@ -1451,7 +2034,7 @@ function containsMarkdown(directory, depth = 0) {
   for (const entry of readdirSync(directory, { withFileTypes: true })) {
     if (IGNORED_DIRECTORIES.has(entry.name) || entry.isSymbolicLink()) continue;
     const path = resolveWithin(directory, entry.name);
-    if (entry.isFile() && [".md", ".mdx"].includes(extname3(entry.name).toLowerCase())) return true;
+    if (entry.isFile() && [".md", ".mdx"].includes(extname4(entry.name).toLowerCase())) return true;
     if (entry.isDirectory() && containsMarkdown(path, depth + 1)) return true;
   }
   return false;
@@ -1459,7 +2042,7 @@ function containsMarkdown(directory, depth = 0) {
 function detectRepositoryDocsDir(repositoryDir) {
   for (const candidate of ["docs", "documentation", "content", "pages", "src/content", "src/pages", "guide", "guides", ""]) {
     const path = resolveWithin(repositoryDir, candidate);
-    if (existsSync3(path) && lstatSync3(path).isDirectory() && containsMarkdown(path)) return candidate;
+    if (existsSync4(path) && lstatSync4(path).isDirectory() && containsMarkdown(path)) return candidate;
   }
   return "";
 }
@@ -1472,7 +2055,7 @@ function scanFiles(root) {
       if (IGNORED_DIRECTORIES.has(entry.name) || entry.isSymbolicLink()) continue;
       const path = resolveWithin(directory, entry.name);
       if (entry.isDirectory()) visit(path);
-      else if (entry.isFile()) files.push({ absolutePath: path, relativePath: relative3(root, path).replace(/\\/g, "/") });
+      else if (entry.isFile()) files.push({ absolutePath: path, relativePath: relative4(root, path).replace(/\\/g, "/") });
     }
   }
   visit(root);
@@ -1527,9 +2110,9 @@ function interpolateSnippet(snippet, attributes) {
   }).join("\n");
 }
 function resolveSnippetPath(sourcePath, currentFile, repositoryRoot, siteRoot) {
-  const repositoryRelative = sourcePath.startsWith("@site/") ? relative3(repositoryRoot, resolveWithin(siteRoot, sourcePath.slice("@site/".length))).replace(/\\/g, "/") : sourcePath.startsWith("/") ? relative3(repositoryRoot, resolveWithin(siteRoot, sourcePath.replace(/^\/+/, ""))).replace(/\\/g, "/") : relative3(repositoryRoot, resolvePath(dirname2(currentFile), sourcePath)).replace(/\\/g, "/");
+  const repositoryRelative = sourcePath.startsWith("@site/") ? relative4(repositoryRoot, resolveWithin(siteRoot, sourcePath.slice("@site/".length))).replace(/\\/g, "/") : sourcePath.startsWith("/") ? relative4(repositoryRoot, resolveWithin(siteRoot, sourcePath.replace(/^\/+/, ""))).replace(/\\/g, "/") : relative4(repositoryRoot, resolvePath(dirname3(currentFile), sourcePath)).replace(/\\/g, "/");
   const candidate = resolveWithin(repositoryRoot, repositoryRelative);
-  resolveWithin(repositoryRoot, relative3(repositoryRoot, candidate));
+  resolveWithin(repositoryRoot, relative4(repositoryRoot, candidate));
   return candidate;
 }
 function globalSnippetAliases(files, repositoryRoot, siteRoot) {
@@ -1543,12 +2126,12 @@ function globalSnippetAliases(files, repositoryRoot, siteRoot) {
     if (conventionalAlias) aliases.set(conventionalAlias, file.absolutePath);
   }
   for (const file of files) {
-    if (![".md", ".mdx"].includes(extname3(file.relativePath).toLowerCase())) continue;
-    const raw = readFileSync3(file.absolutePath, "utf8");
+    if (![".md", ".mdx"].includes(extname4(file.relativePath).toLowerCase())) continue;
+    const raw = readFileSync4(file.absolutePath, "utf8");
     for (const match of raw.matchAll(matcher)) {
       try {
         const candidate = resolveSnippetPath(match[2], file.absolutePath, repositoryRoot, siteRoot);
-        if (existsSync3(candidate) && lstatSync3(candidate).isFile()) {
+        if (existsSync4(candidate) && lstatSync4(candidate).isFile()) {
           aliases.set(match[1], candidate);
         }
       } catch {
@@ -1570,12 +2153,12 @@ function repositoryAssetHref(value, currentFile, siteRoot) {
   } catch {
     return null;
   }
-  if (!ASSET_EXTENSIONS.has(extname3(decodedPath).toLowerCase())) return null;
+  if (!ASSET_EXTENSIONS.has(extname4(decodedPath).toLowerCase())) return null;
   try {
-    const candidate = decodedPath.startsWith("/") ? resolveWithin(siteRoot, decodedPath.replace(/^\/+/, "")) : resolveWithin(dirname2(currentFile), decodedPath);
-    const siteRelative = relative3(siteRoot, candidate).replace(/\\/g, "/");
+    const candidate = decodedPath.startsWith("/") ? resolveWithin(siteRoot, decodedPath.replace(/^\/+/, "")) : resolveWithin(dirname3(currentFile), decodedPath);
+    const siteRelative = relative4(siteRoot, candidate).replace(/\\/g, "/");
     resolveWithin(siteRoot, siteRelative);
-    if (!existsSync3(candidate) || !lstatSync3(candidate).isFile()) return null;
+    if (!existsSync4(candidate) || !lstatSync4(candidate).isFile()) return null;
     const normalized = normalizeAssetPath(siteRelative);
     if (!normalized) return null;
     const rewritten = `/${normalized}${suffix}`;
@@ -1601,9 +2184,9 @@ function inlineMdxSnippets(raw, currentFile, repositoryRoot, warnings, depth = 0
     (_statement, componentName, sourcePath) => {
       try {
         const candidate = resolveSnippetPath(sourcePath, currentFile, repositoryRoot, siteRoot);
-        if (!existsSync3(candidate) || !lstatSync3(candidate).isFile()) throw new Error("file not found");
+        if (!existsSync4(candidate) || !lstatSync4(candidate).isFile()) throw new Error("file not found");
         const nested = inlineMdxSnippets(
-          withoutFrontmatter(readFileSync3(candidate, "utf8")),
+          withoutFrontmatter(readFileSync4(candidate, "utf8")),
           candidate,
           repositoryRoot,
           warnings,
@@ -1617,7 +2200,7 @@ function inlineMdxSnippets(raw, currentFile, repositoryRoot, warnings, depth = 0
         warnings.push({
           code: "missing-page",
           message: `Imported snippet ${sourcePath} could not be resolved and was left as a comment.`,
-          source: relative3(repositoryRoot, currentFile).replace(/\\/g, "/")
+          source: relative4(repositoryRoot, currentFile).replace(/\\/g, "/")
         });
         snippets.set(componentName, `{/* Missing imported snippet: ${sourcePath} */}`);
         return "";
@@ -1627,7 +2210,7 @@ function inlineMdxSnippets(raw, currentFile, repositoryRoot, warnings, depth = 0
   for (const [componentName, candidate] of globalAliases) {
     if (snippets.has(componentName) || !new RegExp(`<${componentName}(?:\\s|/?>)`).test(withoutImports)) continue;
     const nested = inlineMdxSnippets(
-      withoutFrontmatter(readFileSync3(candidate, "utf8")),
+      withoutFrontmatter(readFileSync4(candidate, "utf8")),
       candidate,
       repositoryRoot,
       warnings,
@@ -1654,6 +2237,11 @@ function injectOpenApi(config, filename) {
   else tabs.push({ tab: "API Reference", api: { source: `/${filename}` } });
   return { ...config, tabs };
 }
+function componentSourceIdentity(sourceUrl, repositoryDir, siteRoot) {
+  const url = new URL(sourceUrl);
+  const repository = url.hostname.toLowerCase() === "github.com" ? `https://github.com/${url.pathname.split("/").filter(Boolean).slice(0, 2).join("/").replace(/\.git$/i, "").toLowerCase()}` : `${url.origin}${trimTrailingSlashes(url.pathname)}`;
+  return JSON.stringify([repository, relative4(repositoryDir, siteRoot).replace(/\\/g, "/")]);
+}
 function migrateRepository(options) {
   const repositoryDir = options.repositoryDir;
   const platform = options.platform ?? detectRepositoryPlatform(repositoryDir, options.docsDir);
@@ -1663,21 +2251,23 @@ function migrateRepository(options) {
     if (options.docsDir !== void 0) {
       const selected = resolveWithin(repositoryDir, options.docsDir || ".");
       if (platform === "docusaurus" && hasDocusaurusConfig(selected)) {
-        const projectRelative = relative3(repositoryDir, selected).replace(/\\/g, "/");
+        const projectRelative = relative4(repositoryDir, selected).replace(/\\/g, "/");
         return [projectRelative, primaryDocusaurusDocsDirectory(selected)].filter(Boolean).join("/");
       }
       return options.docsDir;
     }
     if (docusaurusProjectRoot) {
-      const projectRelative = relative3(repositoryDir, docusaurusProjectRoot).replace(/\\/g, "/");
+      const projectRelative = relative4(repositoryDir, docusaurusProjectRoot).replace(/\\/g, "/");
       return [projectRelative, primaryDocusaurusDocsDirectory(docusaurusProjectRoot)].filter(Boolean).join("/");
     }
     if (platform === "mintlify" && mintlifyProjectRoot) {
-      return relative3(repositoryDir, mintlifyProjectRoot).replace(/\\/g, "/");
+      return relative4(repositoryDir, mintlifyProjectRoot).replace(/\\/g, "/");
     }
     return platform === "mintlify" ? "" : detectRepositoryDocsDir(repositoryDir);
   })();
   const warnings = [];
+  const componentRoot = mintlifyProjectRoot ?? repositoryDir;
+  const componentMigrator = platform === "mintlify" ? createComponentMigrator(componentRoot, warnings, componentSourceIdentity(options.sourceUrl, repositoryDir, componentRoot)) : void 0;
   let docsConfig = { tabs: [] };
   const referenceMap = /* @__PURE__ */ new Map();
   const exactReferenceMap = /* @__PURE__ */ new Map();
@@ -1694,9 +2284,10 @@ function migrateRepository(options) {
         warnings.push(...projected.warnings);
         for (const [index, reference] of projected.pageReferences.entries()) {
           const key = normalizedReferenceKey(reference.ref);
-          referenceMap.set(key, reference);
-          exactReferenceMap.set(exactReferenceKey(reference.ref), reference);
-          referenceOrder.set(key, index);
+          if (!referenceMap.has(key)) referenceMap.set(key, reference);
+          const exactKey = exactReferenceKey(reference.ref);
+          if (!exactReferenceMap.has(exactKey)) exactReferenceMap.set(exactKey, reference);
+          if (!referenceOrder.has(key)) referenceOrder.set(key, index);
         }
       }
     } catch (error) {
@@ -1717,7 +2308,7 @@ function migrateRepository(options) {
     }
   }
   const contentRoot = resolveWithin(repositoryDir, configuredDocsDir);
-  if (!existsSync3(contentRoot) || !lstatSync3(contentRoot).isDirectory()) {
+  if (!existsSync4(contentRoot) || !lstatSync4(contentRoot).isDirectory()) {
     throw new Error(`Documentation directory does not exist: ${configuredDocsDir || "."}`);
   }
   const files = scanFiles(contentRoot);
@@ -1728,6 +2319,8 @@ function migrateRepository(options) {
   let skipped = 0;
   let discovered = files.length;
   const localeConfig = docsConfig.i18n;
+  const defaultPageIds = new Set([...referenceMap.values()].filter((reference) => !reference.locale || reference.locale === localeConfig?.defaultLocale).map((reference) => reference.navigationId));
+  const routeAliases = [];
   const pageFiles = [...files].sort((left, right) => {
     const leftOrder = referenceOrder.get(normalizedReferenceKey(left.relativePath)) ?? Number.MAX_SAFE_INTEGER;
     const rightOrder = referenceOrder.get(normalizedReferenceKey(right.relativePath)) ?? Number.MAX_SAFE_INTEGER;
@@ -1746,12 +2339,12 @@ function migrateRepository(options) {
       skipped++;
       continue;
     }
-    if (![".md", ".mdx"].includes(extname3(file.relativePath).toLowerCase())) {
+    if (![".md", ".mdx"].includes(extname4(file.relativePath).toLowerCase())) {
       skipped++;
       warnings.push({ code: "skipped-file", message: "Only Markdown and MDX are imported without an explicit converter.", source: file.relativePath });
       continue;
     }
-    const size = lstatSync3(file.absolutePath).size;
+    const size = lstatSync4(file.absolutePath).size;
     if (size > MAX_PAGE_BYTES) {
       skipped++;
       warnings.push({ code: "skipped-file", message: "Page exceeded the 2 MB repository import limit.", source: file.relativePath });
@@ -1762,10 +2355,12 @@ function migrateRepository(options) {
     let locale = referenced?.locale;
     let navigationId = referenced?.navigationId ?? pageIdFromReference(file.relativePath, platform === "mintlify");
     if (!referenced && localeConfig) {
-      const prefix = file.relativePath.split("/", 1)[0];
-      if (localeConfig.locales.some((entry) => entry.code === prefix)) {
-        locale = prefix;
-        navigationId = pageIdFromReference(file.relativePath.slice(prefix.length + 1), platform === "mintlify");
+      for (const entry of localeConfig.locales) {
+        const localized = mintlifyLocalizedReference(file.relativePath, entry.code, defaultPageIds);
+        if (localized === file.relativePath) continue;
+        locale = entry.code;
+        navigationId = pageIdFromReference(localized, platform === "mintlify");
+        break;
       }
     }
     if (!navigationId) {
@@ -1775,8 +2370,8 @@ function migrateRepository(options) {
     }
     const isDefaultLocale = !locale || locale === localeConfig?.defaultLocale;
     const id = isDefaultLocale ? navigationId : `${locale}/${navigationId}`;
-    const raw = inlineMdxSnippets(
-      readFileSync3(file.absolutePath, "utf8"),
+    let raw = inlineMdxSnippets(
+      readFileSync4(file.absolutePath, "utf8"),
       file.absolutePath,
       repositoryDir,
       warnings,
@@ -1784,13 +2379,14 @@ function migrateRepository(options) {
       mintlifyProjectRoot ?? docusaurusProjectRoot ?? repositoryDir,
       snippetAliases
     );
+    if (componentMigrator) raw = componentMigrator.transform(raw, file.absolutePath);
     let docusaurusDescriptor;
     const page = parseMarkdownPage({
       id,
       navigationId,
       ...locale ? { locale } : {},
       raw,
-      source: `${options.sourceUrl}#${relative3(repositoryDir, file.absolutePath).replace(/\\/g, "/")}`,
+      source: `${options.sourceUrl}#${relative4(repositoryDir, file.absolutePath).replace(/\\/g, "/")}`,
       ...platform === "docusaurus" ? {
         resolveIdentity: (frontmatter, fallback) => {
           const resolved = resolveDocusaurusPageIdentity(file.relativePath, frontmatter, fallback);
@@ -1827,6 +2423,12 @@ function migrateRepository(options) {
     }
     seenPageIds.add(page.id);
     pages.push(page);
+    if (platform === "mintlify") {
+      const sourcePath = exactReferenceKey(file.relativePath);
+      if (sourcePath !== page.id && /^[A-Za-z0-9_./-]+$/.test(sourcePath)) {
+        routeAliases.push({ source: `/${sourcePath}`, destination: `/${page.id}`, permanent: false });
+      }
+    }
     if (docusaurusDescriptor) {
       docusaurusDescriptors.push({ ...docusaurusDescriptor, title: page.title });
     }
@@ -1840,7 +2442,7 @@ function migrateRepository(options) {
   const docusaurusAssetRoot = docusaurusProjectRoot ?? repositoryDir;
   const repositoryAssets = platform === "docusaurus" && configuredDocsDir && !options.docusaurusSkipAssets ? ["static", "public"].flatMap((directory) => {
     const root = resolveWithin(docusaurusAssetRoot, directory);
-    if (!existsSync3(root) || !lstatSync3(root).isDirectory()) return [];
+    if (!existsSync4(root) || !lstatSync4(root).isDirectory()) return [];
     return scanFiles(root).map((file) => ({
       ...file,
       relativePath: `${directory}/${file.relativePath}`
@@ -1849,9 +2451,9 @@ function migrateRepository(options) {
   let totalAssetBytes = 0;
   for (const file of [...files, ...repositoryAssets]) {
     const firstSegment = file.relativePath.split("/", 1)[0].toLowerCase();
-    if (!ASSET_EXTENSIONS.has(extname3(file.relativePath).toLowerCase())) continue;
+    if (!ASSET_EXTENSIONS.has(extname4(file.relativePath).toLowerCase())) continue;
     if (platform !== "mintlify" && !ASSET_DIRECTORIES.has(firstSegment)) continue;
-    const size = lstatSync3(file.absolutePath).size;
+    const size = lstatSync4(file.absolutePath).size;
     if (size > MAX_ASSET_BYTES || totalAssetBytes + size > MAX_TOTAL_ASSET_BYTES) {
       warnings.push({ code: "limit-reached", message: "An asset was skipped because the migration asset budget was exhausted.", source: file.relativePath });
       continue;
@@ -1859,7 +2461,7 @@ function migrateRepository(options) {
     const isDocusaurusStatic = platform === "docusaurus" && firstSegment === "static";
     const assetPath = normalizeAssetPath(firstSegment === "public" ? file.relativePath.slice("public/".length) : isDocusaurusStatic ? file.relativePath.slice("static/".length) : file.relativePath);
     if (!assetPath) continue;
-    assets.push({ path: assetPath, content: readFileSync3(file.absolutePath) });
+    assets.push({ path: assetPath, content: readFileSync4(file.absolutePath) });
     totalAssetBytes += size;
   }
   if (files.length >= MAX_SOURCE_FILES) {
@@ -1893,11 +2495,16 @@ function migrateRepository(options) {
   if (openApi) {
     const filename = basename(openApi.relativePath);
     if (!assets.some((asset) => asset.path === filename)) {
-      assets.push({ path: filename, content: readFileSync3(openApi.absolutePath) });
+      assets.push({ path: filename, content: readFileSync4(openApi.absolutePath) });
     }
     docsConfig = injectOpenApi(docsConfig, filename);
   }
-  if (platform === "mintlify") docsConfig = addMintlifyDirectoryRedirects(docsConfig, pages);
+  if (platform === "mintlify") {
+    const sources = new Set((docsConfig.redirects ?? []).map((redirect) => redirect.source));
+    const aliases = routeAliases.filter((redirect) => !sources.has(redirect.source));
+    if (aliases.length > 0) docsConfig = { ...docsConfig, redirects: [...docsConfig.redirects ?? [], ...aliases] };
+    docsConfig = addMintlifyHomepageRedirects(addMintlifyDirectoryRedirects(docsConfig, pages), pages);
+  }
   if (platform === "docusaurus" && docusaurusProjectRoot && !options.docusaurusSkipPlugins) {
     for (const plugin of additionalDocusaurusPluginRoots(repositoryDir, docusaurusProjectRoot)) {
       if (plugin.docsDir === configuredDocsDir) continue;
@@ -1938,6 +2545,7 @@ function migrateRepository(options) {
     platform,
     pages,
     assets,
+    ...componentMigrator ? { componentFiles: componentMigrator.files() } : {},
     docsConfig,
     ...mintlifyConfig ? {
       site: {
@@ -2054,6 +2662,7 @@ function renderMigrationFiles(bundle, options = {}) {
       content: renderPage(bundle, page)
     })),
     ...bundle.assets.map((asset) => ({ path: `public/${asset.path}`, content: asset.content })),
+    ...(bundle.componentFiles ?? []).flatMap((file) => file.path === "src/mdx/custom-components.tsx" && options.existingComponentRegistry !== void 0 && typeof file.content === "string" ? mergeComponentRegistry(options.existingComponentRegistry, file.content) : [file]),
     { path: "docs.json", content: `${JSON.stringify(config, null, 2)}
 ` }
   ];