@thallylabs/migrate 0.2.2 → 0.2.4

package/README.md

@@ -5,12 +5,13 @@ Cloud. It imports documentation repositories and public documentation URLs
 into one canonical bundle before any caller writes files.
 
 Repository migration includes dedicated Mintlify and Docusaurus adapters.
-Mintlify repositories are located inside monorepos automatically and their
-`docs.json`/`mint.json` configuration is projected without flattening the
-information architecture. The adapter preserves nested groups, tabs,
-dropdowns, products, versions, languages, reusable `$ref` navigation files,
-page route casing, redirects, local snippets, static assets, compatible page
-frontmatter, site identity, and OpenAPI configuration. For public Mintlify
+Mintlify repositories are located inside monorepos automatically. Their
+`docs.json`/`mint.json` page and group trees are projected without flattening
+authored nesting or order. The adapter supports tabs, dropdowns, products,
+versions, languages, and reusable `$ref` navigation files; it also preserves
+dropdown presentation, collection descriptions and icons, explicit default
+versions, page route casing, redirects, local snippets, static assets,
+compatible page frontmatter, site identity, and OpenAPI configuration. For public Mintlify
 sites, the URL adapter reads the structured configuration embedded in the
 rendered application before falling back to DOM link inference.
 

package/dist/index.d.ts

@@ -12,8 +12,12 @@ interface MigrationNavigationGroup {
 }
 interface MigrationNavigationTab {
     tab: string;
+    description?: string;
+    icon?: string;
     href?: string;
     hidden?: boolean;
+    /** Root page/group nodes used when the source has no synthetic section heading. */
+    pages?: Array<string | MigrationNavigationGroup>;
     groups?: Array<MigrationNavigationGroup>;
     api?: {
         source: string;
@@ -54,6 +58,10 @@ interface MigrationFooterConfig {
 }
 interface MigrationDocsConfig {
     tabs: Array<MigrationNavigationTab>;
+    navigation?: {
+        /** How sibling documentation collections are presented to readers. */
+        display?: 'tabs' | 'dropdown';
+    };
     theme?: 'default' | 'maple' | 'sharp' | 'minimal';
     banner?: MigrationBannerConfig;
     navbar?: MigrationNavbarConfig;

package/dist/index.js

@@ -534,15 +534,26 @@ function projectDocusaurusNavigation(input) {
 }
 
 // src/frontmatter.ts
-import matter from "gray-matter";
-var FRONTMATTER_OPTIONS = {
-  engines: {
-    javascript: () => ({}),
-    js: () => ({})
-  }
-};
+import { parse as parseYaml2 } from "yaml";
 function parseFrontmatter(raw) {
-  return matter(raw, FRONTMATTER_OPTIONS);
+  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
@@ -776,6 +787,12 @@ function iconName(value) {
   const icon = objectValue2(value);
   return typeof icon?.name === "string" && icon.name ? icon.name : void 0;
 }
+function containerPresentation(value) {
+  return {
+    ...typeof value.description === "string" && value.description.trim() ? { description: value.description.trim() } : {},
+    ...iconName(value.icon) ? { icon: iconName(value.icon) } : {}
+  };
+}
 function registerReference(value, context) {
   const localePrefix = context.locale ? `${context.locale}/` : "";
   const localizedValue = localePrefix && value.replace(/^\/+/, "").startsWith(localePrefix) ? value.replace(/^\/+/, "").slice(localePrefix.length) : value;
@@ -825,56 +842,76 @@ function convertPage(value, context) {
   }
   return null;
 }
-function convertGroups(values, context, fallbackGroup) {
-  const groups = [];
-  const loosePages = [];
-  for (const value of values) {
-    const converted = convertPage(value, context);
-    if (!converted) continue;
-    if (typeof converted === "string") loosePages.push(converted);
-    else groups.push(converted);
-  }
-  if (loosePages.length > 0) groups.unshift({ group: fallbackGroup, pages: loosePages });
-  return groups;
+function convertNavigationValues(values, context) {
+  return values.flatMap((value) => {
+    const page = convertPage(value, context);
+    return page ? [page] : [];
+  });
 }
-function convertContainerToTabs(containerValue, context, fallbackTab) {
+function convertContainerToTabs(containerValue, context, fallbackTab, trace, depth = 0) {
   const container = objectValue2(containerValue);
   if (!container) return [];
-  for (const key of ["tabs", "anchors", "products", "dropdowns", "versions", "menus"]) {
+  const containerKeys = ["tabs", "anchors", "products", "dropdowns", "versions", "menus"];
+  for (const key of containerKeys) {
     if (!Array.isArray(container[key])) continue;
-    const tabs = container[key].flatMap((value, index) => {
+    const entries = [...container[key]];
+    if (key === "versions") {
+      entries.sort((left, right) => Number(objectValue2(right)?.default === true) - Number(objectValue2(left)?.default === true));
+    }
+    const tabs = entries.flatMap((value, index) => {
       const object = objectValue2(value);
       if (!object) return [];
       const tab = labelFor(object, `${fallbackTab} ${index + 1}`);
       const href = projectedHref(object.href);
-      if (href && !object.pages && !object.groups) {
-        return [{ tab, href, ...object.hidden === true ? { hidden: true } : {} }];
+      const hasNestedContainers = containerKeys.some((containerKey) => Array.isArray(object[containerKey]));
+      if (href && !object.pages && !object.groups && !hasNestedContainers) {
+        return [{
+          tab,
+          href,
+          ...containerPresentation(object),
+          ...object.hidden === true ? { hidden: true } : {}
+        }];
       }
-      const nested = convertContainerToTabs(object, context, tab);
+      const nested = convertContainerToTabs(object, context, tab, trace, depth + 1);
       if (nested.length > 0) {
         if (nested.length === 1) {
           return [{
             ...nested[0],
             tab,
+            ...containerPresentation(object),
             ...href ? { href } : {},
             ...object.hidden === true ? { hidden: true } : {}
           }];
         }
-        return nested.map((item) => ({ ...item, tab: `${tab}: ${item.tab}` }));
+        const presentation = containerPresentation(object);
+        return nested.map((item, childIndex) => ({
+          ...presentation,
+          ...item,
+          tab: `${tab}: ${item.tab}`,
+          ...childIndex === 0 && href && !item.href ? { href } : {},
+          ...object.hidden === true ? { hidden: true } : {}
+        }));
       }
       return [];
     });
-    if (tabs.length > 0) return tabs;
-  }
-  const rawPages = [
-    ...Array.isArray(container.groups) ? container.groups : [],
-    ...Array.isArray(container.pages) ? container.pages : []
+    if (tabs.length > 0) {
+      if (depth === 0 && trace) trace.rootContainerKind = key;
+      return tabs;
+    }
+  }
+  const rawGroups = Array.isArray(container.groups) ? container.groups : [];
+  const rawPages = Array.isArray(container.pages) ? container.pages : [];
+  const hasRootNodes = typeof container.root === "string" || rawPages.length > 0;
+  const values = [
+    ...typeof container.root === "string" ? [container.root] : [],
+    ...rawGroups,
+    ...rawPages
   ];
-  if (typeof container.root === "string") rawPages.unshift(container.root);
-  const groups = convertGroups(rawPages, context, "Overview");
-  return groups.length > 0 ? [{
+  const children = convertNavigationValues(values, context);
+  return children.length > 0 ? [{
     tab: fallbackTab,
-    groups,
+    ...hasRootNodes ? { pages: children } : { groups: children },
+    ...containerPresentation(container),
     ...projectedHref(container.href) ? { href: projectedHref(container.href) } : {},
     ...container.hidden === true ? { hidden: true } : {}
   }] : [];
@@ -1003,9 +1040,10 @@ function projectMintlifyNavigation(config, options = {}) {
   const languages = Array.isArray(navigation.languages) ? navigation.languages.map(objectValue2).filter((value) => Boolean(value)) : [];
   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 ?? "en");
+    const defaultLocale = String(defaultLanguage.language ?? defaultLanguage.locale ?? "en");
     const locales = languages.map((entry) => {
       const code = String(entry.language ?? entry.locale ?? "en");
       let label = LANGUAGE_LABELS[code];
@@ -1026,15 +1064,26 @@ function projectMintlifyNavigation(config, options = {}) {
         warnings,
         warningKeys
       };
-      const languageTabs = convertContainerToTabs(language, context, "Documentation");
+      const languageTabs = convertContainerToTabs(
+        language,
+        context,
+        "Documentation",
+        language === defaultLanguage ? projectionTrace : void 0
+      );
       if (language === defaultLanguage) tabs = languageTabs;
     }
   } else {
     const context = { references, seenReferences, warnings, warningKeys, pathPrefix: options.pathPrefix };
-    tabs = convertContainerToTabs(navigation, context, "Documentation");
+    tabs = convertContainerToTabs(navigation, context, "Documentation", projectionTrace);
     if (tabs.length === 0 && Array.isArray(config.navigation)) {
-      const groups = convertGroups(config.navigation, context, "Overview");
-      if (groups.length > 0) tabs = [{ tab: "Documentation", groups }];
+      const children = convertNavigationValues(config.navigation, context);
+      if (children.length > 0) {
+        const hasRootPages = children.some((page) => typeof page === "string");
+        tabs = [{
+          tab: "Documentation",
+          ...hasRootPages ? { pages: children } : { groups: children }
+        }];
+      }
     }
   }
   if (tabs.length === 0) {
@@ -1058,6 +1107,7 @@ function projectMintlifyNavigation(config, options = {}) {
   return {
     docsConfig: {
       tabs,
+      ...projectionTrace.rootContainerKind === "dropdowns" ? { navigation: { display: "dropdown" } } : {},
       ...projectedCompatibleConfig(config),
       ...i18n ? { i18n } : {},
       ...redirects.length > 0 ? { redirects } : {}
@@ -1927,41 +1977,56 @@ function mergeMigrationConfig(existing, incoming) {
   const tabs = existing.tabs.filter((tab) => tab.tab.toLowerCase() !== "changelog");
   const names = new Set(tabs.map((tab) => tab.tab.toLowerCase()));
   const seenPages = /* @__PURE__ */ new Set();
-  function recordPages(groups) {
-    for (const group of groups ?? []) {
-      for (const page of group.pages) {
-        if (typeof page === "string") seenPages.add(page);
-        else recordPages([page]);
-      }
+  function recordPages(pages = []) {
+    for (const page of pages) {
+      if (typeof page === "string") seenPages.add(page);
+      else recordPages(page.pages);
     }
   }
-  for (const tab of tabs) recordPages(tab.groups);
-  function uniqueGroups(groups) {
-    return (groups ?? []).flatMap((group) => {
-      const pages = group.pages.flatMap((page) => {
-        if (typeof page === "string") {
-          if (seenPages.has(page)) return [];
-          seenPages.add(page);
-          return [page];
-        }
-        const [nested] = uniqueGroups([page]);
-        return nested ? [nested] : [];
-      });
-      return pages.length > 0 ? [{ ...group, pages }] : [];
+  for (const tab of tabs) {
+    recordPages(tab.pages);
+    recordPages(tab.groups);
+  }
+  function uniquePages(pages = []) {
+    return pages.flatMap((page) => {
+      if (typeof page === "string") {
+        if (seenPages.has(page)) return [];
+        seenPages.add(page);
+        return [page];
+      }
+      const children = uniquePages(page.pages);
+      return children.length > 0 ? [{ ...page, pages: children }] : [];
     });
   }
+  function uniqueGroups(groups) {
+    return uniquePages(groups ?? []);
+  }
   for (const tab of incoming.tabs) {
     if (tab.tab.toLowerCase() === "changelog") continue;
-    const uniqueTab = { ...tab, ...tab.groups ? { groups: uniqueGroups(tab.groups) } : {} };
-    if (tab.groups && uniqueTab.groups?.length === 0 && !tab.href && !tab.api) continue;
+    const uniqueTab = {
+      ...tab,
+      ...tab.pages ? { pages: uniquePages(tab.pages) } : {},
+      ...tab.groups ? { groups: uniqueGroups(tab.groups) } : {}
+    };
+    if ((tab.pages || tab.groups) && !uniqueTab.pages?.length && !uniqueTab.groups?.length && !tab.href && !tab.api) continue;
     if (!names.has(tab.tab.toLowerCase())) {
       tabs.push(uniqueTab);
       names.add(tab.tab.toLowerCase());
       continue;
     }
     const target = tabs.find((item) => item.tab.toLowerCase() === tab.tab.toLowerCase());
-    if (!target || !uniqueTab.groups) continue;
-    target.groups = [...target.groups ?? [], ...uniqueTab.groups];
+    if (!target) continue;
+    const incomingRootNodes = [
+      ...uniqueTab.pages ?? [],
+      ...uniqueTab.groups ?? []
+    ];
+    if (uniqueTab.pages?.length) {
+      target.pages = [...target.pages ?? target.groups ?? [], ...incomingRootNodes];
+      delete target.groups;
+    } else if (uniqueTab.groups?.length) {
+      if (target.pages) target.pages = [...target.pages, ...uniqueTab.groups];
+      else target.groups = [...target.groups ?? [], ...uniqueTab.groups];
+    }
   }
   const changelog = existing.tabs.find((tab) => tab.tab.toLowerCase() === "changelog") ?? incoming.tabs.find((tab) => tab.tab.toLowerCase() === "changelog");
   if (changelog) tabs.push(changelog);
@@ -1975,6 +2040,9 @@ function mergeMigrationConfig(existing, incoming) {
     ...incoming,
     ...existing,
     tabs,
+    // Collection presentation belongs to the imported information
+    // architecture; starter defaults must not coerce source dropdowns to tabs.
+    navigation: incoming.navigation ?? existing.navigation,
     ...i18n ? { i18n } : {}
   };
 }
@@ -1994,7 +2062,7 @@ function renderMigrationFiles(bundle, options = {}) {
 // src/url.ts
 import { load } from "cheerio";
 import TurndownService from "turndown";
-import { parse as parseYaml2, stringify as stringifyYaml } from "yaml";
+import { parse as parseYaml3, stringify as stringifyYaml } from "yaml";
 var DEFAULT_MAX_PAGES = 1e3;
 var DEFAULT_MAX_TOTAL_BYTES = 1e8;
 var MAX_DISCOVERED_URLS = 5e3;
@@ -2556,7 +2624,7 @@ function extractEmbeddedOpenApi(content) {
   const match = fencePattern.exec(content);
   if (!match) return { content };
   try {
-    const parsed = parseYaml2(match[5], { maxAliasCount: 50 });
+    const parsed = parseYaml3(match[5], { maxAliasCount: 50 });
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return { content };
     const document = parsed;
     if (typeof document.openapi !== "string" && typeof document.swagger !== "string") return { content };
@@ -3025,15 +3093,17 @@ function htmlTopLevelNavigation(document, source, scopePath) {
 }
 function remapNavigationHome(config, sourceHomePageId) {
   if (!sourceHomePageId || sourceHomePageId === "introduction") return config;
+  const remapPages = (pages) => pages.map((page) => typeof page === "string" ? page === sourceHomePageId ? "introduction" : page : { ...page, pages: remapPages(page.pages) });
   const remapGroups = (groups) => groups.map((group) => ({
     ...group,
-    pages: group.pages.map((page) => typeof page === "string" ? page === sourceHomePageId ? "introduction" : page : remapGroups([page])[0])
+    pages: remapPages(group.pages)
   }));
   return {
     ...config,
     tabs: config.tabs.map((tab) => ({
       ...tab,
       ...tab.href === `/${sourceHomePageId}` ? { href: "/" } : {},
+      ...tab.pages ? { pages: remapPages(tab.pages) } : {},
       ...tab.groups ? { groups: remapGroups(tab.groups) } : {}
     }))
   };
@@ -3352,12 +3422,8 @@ async function migrateUrl(options) {
   const openApiAsset = mergeEmbeddedOpenApi(openApiFragments);
   if (openApiAsset) {
     const operationPageIds = new Set(pages.filter((page) => page.openapi).map((page) => page.navigationId));
-    const apiTab = docsConfig.tabs.find((tab) => tab.groups?.some((group) => {
-      const containsOperation = (pages2) => pages2.some((page) => {
-        return typeof page === "string" ? operationPageIds.has(page) : containsOperation(page.pages);
-      });
-      return containsOperation(group.pages);
-    })) ?? docsConfig.tabs[0];
+    const containsOperation = (navigationPages = []) => navigationPages.some((page) => typeof page === "string" ? operationPageIds.has(page) : containsOperation(page.pages));
+    const apiTab = docsConfig.tabs.find((tab) => containsOperation(tab.pages) || containsOperation(tab.groups)) ?? docsConfig.tabs[0];
     if (apiTab) {
       apiTab.api = { source: "/openapi.yaml", navigation: false };
     }