@thallylabs/migrate 0.2.18 → 0.2.19

package/README.md

@@ -40,6 +40,13 @@ instead of silently dropping that API tab's reference. AsyncAPI has no Thally
 renderer, so it always produces a clear warning naming the spec instead of
 disappearing.
 
+Page `openapi:` frontmatter with a spec prefix
+(`openapi: "specs/openapi-b.yaml GET /widgets/{id}"`) is rewritten to where the
+spec lands in the output (`/openapi-b.yaml GET /widgets/{id}`). A prefix naming
+a spec that was not migrated is kept and reported. Manual API pages keep their
+`api:` and `authMethod:` frontmatter, and `api.mdx.server` / `api.mdx.auth` map
+into `docs.json`; invalid values are dropped with a warning.
+
 In-content links to auto-generated API operation pages are rewritten to the
 matching Thally `/api/...` route. A link under a known API section that matches
 no operation points to that section's overview page instead, and one warning

package/dist/index.d.ts

@@ -128,6 +128,16 @@ interface MigrationDocsConfig {
     analytics?: {
         enabled?: boolean;
     };
+    /** Manual API pages: default server(s) and auth for `api:` frontmatter pages. */
+    api?: {
+        mdx?: {
+            server?: string | Array<string>;
+            auth?: {
+                method?: 'bearer' | 'basic' | 'key';
+                name?: string;
+            };
+        };
+    };
     /** Third-party analytics in Mintlify's `integrations` shape; validated again by the renderer. */
     integrations?: {
         ga4?: {
@@ -179,6 +189,10 @@ interface MigrationPage {
     noindex?: boolean;
     /** OpenAPI operation key rendered by Thally instead of ordinary MDX. */
     openapi?: string;
+    /** Manual API page: `METHOD <url-or-path>`; rendered by Thally's playground. */
+    api?: string;
+    /** Page-level playground auth override: bearer | basic | key | none. */
+    authMethod?: string;
     body: string;
     source: string;
     /** Set when the page's frontmatter was invalid YAML; the page is kept with a best-effort salvage. */
@@ -463,6 +477,8 @@ declare function parseMarkdownPage(input: {
     platform?: MigrationPlatform;
     /** Resolve platform-specific routes from the already-parsed frontmatter. */
     resolveIdentity?: (frontmatter: Record<string, unknown>, fallback: MarkdownPageIdentity) => MarkdownPageIdentity;
+    /** Receives a message when frontmatter is dropped or altered. */
+    warn?: (message: string) => void;
 }): MigrationPage | null;
 
 /**

package/dist/index.js

@@ -1290,11 +1290,26 @@ function parseMarkdownPage(input) {
     hidden: parsed.data.hidden === true ? true : void 0,
     noindex: parsed.data.noindex === true || parsed.data.noindex === "true" ? true : void 0,
     openapi: typeof parsed.data.openapi === "string" ? parsed.data.openapi.trim() : void 0,
+    ...apiFrontmatter(parsed.data, input.warn),
     body,
     source: input.source,
     ...parsed.error ? { frontmatterError: parsed.error } : {}
   };
 }
+var AUTH_METHODS = /* @__PURE__ */ new Set(["bearer", "basic", "key", "none"]);
+function apiFrontmatter(data, warn) {
+  const result = {};
+  if (data.api !== void 0 && data.api !== null) {
+    if (typeof data.api === "string" && data.api.trim()) result.api = data.api.trim();
+    else warn?.(`The page's "api" frontmatter is not a "METHOD url-or-path" string and was dropped.`);
+  }
+  if (data.authMethod !== void 0 && data.authMethod !== null) {
+    const method = typeof data.authMethod === "string" ? data.authMethod.trim().toLowerCase() : "";
+    if (AUTH_METHODS.has(method)) result.authMethod = method;
+    else warn?.(`The page's "authMethod" frontmatter ${JSON.stringify(data.authMethod)} is not one of bearer, basic, key, none and was dropped.`);
+  }
+  return result;
+}
 
 // src/path.ts
 import { isAbsolute, relative, resolve, sep } from "path";
@@ -3906,6 +3921,39 @@ function projectedCompatibleConfig(config, warnings) {
     ...typeof feedback?.thumbsRating === "boolean" ? { feedback: { thumbsRating: feedback.thumbsRating } } : {}
   };
 }
+function projectedApiMdx(config, warnings) {
+  const mdx = objectValue2(objectValue2(config.api)?.mdx);
+  if (!mdx) return {};
+  const warn = (message) => warnings.push({ code: "unsupported-config", message });
+  const rawServers = mdx.server === void 0 ? [] : Array.isArray(mdx.server) ? mdx.server : [mdx.server];
+  const servers = rawServers.filter((entry) => {
+    const valid = typeof entry === "string" && /^https?:\/\/[^\s/@?#]+(?:\/[^\s?#]*)?$/i.test(entry.trim());
+    if (!valid) warn(`api.mdx.server entry ${JSON.stringify(entry)} is not an absolute http(s) URL and was dropped.`);
+    return valid;
+  }).map((entry) => entry.trim());
+  const auth = objectValue2(mdx.auth);
+  const method = typeof auth?.method === "string" ? auth.method.toLowerCase() : void 0;
+  const name = typeof auth?.name === "string" && auth.name.trim() ? auth.name.trim() : void 0;
+  let projectedAuth;
+  if (mdx.auth !== void 0 && auth && method !== void 0) {
+    if (method === "bearer" || method === "basic" || method === "key" && name) {
+      projectedAuth = { method, ...name ? { name } : {} };
+    } else {
+      warn(`api.mdx.auth method ${JSON.stringify(auth.method)} is not supported (bearer, basic, or key with a name) and was dropped.`);
+    }
+  } else if (mdx.auth !== void 0 && !auth) {
+    warn("api.mdx.auth is not an object and was dropped.");
+  }
+  if (servers.length === 0 && !projectedAuth) return {};
+  return {
+    api: {
+      mdx: {
+        ...servers.length > 0 ? { server: servers.length === 1 && typeof mdx.server === "string" ? servers[0] : servers } : {},
+        ...projectedAuth ? { auth: projectedAuth } : {}
+      }
+    }
+  };
+}
 var NEXT_REDIRECT_PARAM_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 function translateRedirectWildcards(source, destination) {
   const sourceSegments = source.split("/");
@@ -4093,6 +4141,7 @@ function projectMintlifyNavigation(config, options = {}) {
       tabs,
       ...projectionTrace.rootContainerKind === "dropdowns" ? { navigation: { display: "dropdown" } } : {},
       ...projectedCompatibleConfig(config, warnings),
+      ...projectedApiMdx(config, warnings),
       ...i18n ? { i18n } : {},
       ...redirects.length > 0 ? { redirects } : {}
     },
@@ -5661,6 +5710,26 @@ function projectFernNavigation(input) {
   };
 }
 
+// src/openapi-ref.ts
+function unquote(value) {
+  const trimmed = value.trim();
+  const quote = trimmed[0];
+  return (quote === '"' || quote === "'") && trimmed.length >= 2 && trimmed.endsWith(quote) ? trimmed.slice(1, -1).trim() : trimmed;
+}
+function splitOpenApiRef(raw) {
+  const value = unquote(raw);
+  const match = /^(?:(.+?)\s+)?((?:webhook\s+[^\s/]\S*)|(?:[A-Za-z]+\s+\/.*))$/i.exec(value);
+  if (!match) return null;
+  const specRef = match[1] ? unquote(match[1]) : void 0;
+  return { ...specRef ? { specRef } : {}, operation: match[2] };
+}
+function specRefBaseName(specRef) {
+  return specRef.trim().replace(/\\/g, "/").split(/[?#]/, 1)[0].split("/").filter(Boolean).pop()?.toLowerCase() ?? "";
+}
+function withSpecRef(ref, specRef) {
+  return `${specRef} ${ref.operation}`;
+}
+
 // src/analytics.ts
 var GA4_ID = /^G-[A-Z0-9]{4,20}$/;
 var GTM_ID = /^GTM-[A-Z0-9]{4,12}$/;
@@ -6792,6 +6861,27 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs) {
   }
   return specs;
 }
+function rewriteMintlifyPageSpecRefs(pages, specs, remoteUrls, warnings) {
+  for (const page of pages) {
+    const ref = page.openapi ? splitOpenApiRef(page.openapi) : null;
+    if (!ref?.specRef) continue;
+    if (/^https?:\/\//i.test(ref.specRef)) {
+      if (!remoteUrls.has(ref.specRef)) {
+        warnings.push({ code: "unsupported-config", message: `Page "${page.id}" references the remote OpenAPI spec "${ref.specRef}", which is not referenced from docs.json and was not migrated; the page will not render an endpoint.`, source: page.source });
+      }
+      continue;
+    }
+    const key = ref.specRef.split(/[?#]/, 1)[0].replace(/\\/g, "/").replace(/^(?:\.\/)+/, "").replace(/^\/+/, "");
+    const byPath = specs.find((spec) => spec.sourcePath === key);
+    const byName = specs.filter((spec) => spec.filename.toLowerCase() === specRefBaseName(key));
+    const match = byPath ?? (byName.length === 1 ? byName[0] : void 0);
+    if (match) {
+      page.openapi = withSpecRef(ref, specAssetPath(match.filename));
+    } else {
+      warnings.push({ code: "unsupported-config", message: `Page "${page.id}" references the OpenAPI spec "${ref.specRef}", which is not referenced from docs.json and was not migrated; the page will not render an endpoint. Add the spec to a tab's api setting.`, source: page.source });
+    }
+  }
+}
 var OPENAPI_HTTP_METHODS = ["get", "post", "put", "patch", "delete", "options", "head", "trace"];
 var FERN_CRUD_METHOD_NAMES = {
   findall: "list",
@@ -8159,6 +8249,7 @@ function migrateRepository(options) {
     const page = parseMarkdownPage({
       id,
       navigationId,
+      warn: (message) => warnings.push({ code: "unsupported-config", message, source: relative5(repositoryDir, file.absolutePath).replace(/\\/g, "/") }),
       ...locale ? { locale } : {},
       raw,
       platform,
@@ -8619,6 +8710,7 @@ function migrateRepository(options) {
       }
       if (withheldSpecRefs.some((ref) => specRefMatches(ref, spec.sourcePath, spec.filename, true))) warnSharedSpec(spec.sourcePath);
     }
+    let pageSpecs = resolvedSpecs;
     if (resolvedSpecs.length > 0) {
       docsConfig = injectOpenApiSpecs(docsConfig, resolvedSpecs, warnings);
       const { operationLinks, prefixLandings } = apiOperationLinkMap(
@@ -8639,10 +8731,12 @@ function migrateRepository(options) {
             assets.push(specAsset(filename, readFileSync5(fallback.absolutePath)));
           }
           docsConfig = injectOpenApiSpecs(docsConfig, [{ filename }]);
+          pageSpecs = [{ filename, sourcePath: fallback.relativePath }];
           if (withheldSpecRefs.some(matches)) warnSharedSpec(fallback.relativePath);
         }
       }
     }
+    rewriteMintlifyPageSpecRefs(pages, pageSpecs, new Set(remoteApiSpecs.map((spec) => spec.url)), warnings);
   }
   if (platform === "mintlify") {
     const sources = new Set((docsConfig.redirects ?? []).map((redirect) => redirect.source));
@@ -9065,6 +9159,8 @@ function renderPage(bundle, page) {
     page.hidden ? "hidden: true" : null,
     page.noindex ? "noindex: true" : null,
     page.openapi ? `openapi: ${yamlString(page.openapi)}` : null,
+    page.api ? `api: ${yamlString(page.api)}` : null,
+    page.authMethod ? `authMethod: ${yamlString(page.authMethod)}` : null,
     bundle.sourceKind === "url" ? `source: ${yamlString(page.source)}` : null,
     "---",
     "",
@@ -10892,6 +10988,7 @@ async function hydrateRemoteApiSpecs(bundle, fetcher) {
   const tabs = bundle.docsConfig.tabs.map((tab) => ({ ...tab }));
   const redirects = [...bundle.docsConfig.redirects ?? []];
   const warnings = [...bundle.warnings];
+  const pages = bundle.pages.map((page) => ({ ...page }));
   const authoredLinks = /* @__PURE__ */ new Set();
   for (const page of bundle.pages) {
     for (const match of page.body.matchAll(/\/[a-z0-9_/-]+/gi)) {
@@ -10912,6 +11009,10 @@ async function hydrateRemoteApiSpecs(bundle, fetcher) {
       const operations = parseOpenApi(body, extension);
       const filename = `openapi-${createHash2("sha256").update(reference.url).digest("hex").slice(0, 12)}.${extension}`;
       assets.push({ path: `openapi/${filename}`, content: body, projectRelative: true });
+      for (const page of pages) {
+        const ref = page.openapi ? splitOpenApiRef(page.openapi) : null;
+        if (ref?.specRef === reference.url) page.openapi = withSpecRef(ref, `openapi/${filename}`);
+      }
       const tab = reference.tabLabel ? tabs.find((candidate) => candidate.tab === reference.tabLabel) : tabs.find((candidate) => candidate.tab.toLowerCase().includes("api"));
       if (tab) tab.api = { source: `openapi/${filename}` };
       else insertApiTab(tabs, { tab: reference.tabLabel ?? "API Reference", ...reference.icon ? { icon: reference.icon } : {}, ...reference.hidden ? { hidden: true } : {}, api: { source: `openapi/${filename}` } }, reference.parentTab);
@@ -10940,6 +11041,7 @@ async function hydrateRemoteApiSpecs(bundle, fetcher) {
   }
   return {
     ...bundle,
+    pages,
     assets,
     docsConfig: { ...bundle.docsConfig, tabs, ...redirects.length > 0 ? { redirects } : {} },
     warnings