@thallylabs/migrate 0.2.17 → 0.2.18

package/README.md

@@ -11,7 +11,13 @@ 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
+compatible page frontmatter, site identity, and OpenAPI configuration.
+Analytics come across too: docs.json `integrations` and legacy mint.json
+`analytics` for GA4, Google Tag Manager, PostHog, and Plausible are validated
+and written to `docs.json` `integrations` (`integrations` wins per provider when
+both exist). Invalid values are skipped with a warning, and every other
+Mintlify provider (Amplitude, Mixpanel, Segment, and so on) is listed once in a
+warning instead of being dropped silently. 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

@@ -128,6 +128,24 @@ interface MigrationDocsConfig {
     analytics?: {
         enabled?: boolean;
     };
+    /** Third-party analytics in Mintlify's `integrations` shape; validated again by the renderer. */
+    integrations?: {
+        ga4?: {
+            measurementId: string;
+        };
+        gtm?: {
+            tagId: string;
+        };
+        posthog?: {
+            apiKey: string;
+            apiHost?: string;
+            sessionRecording?: boolean;
+        };
+        plausible?: {
+            domain: string;
+            server?: string;
+        };
+    };
     redirects?: Array<{
         source: string;
         destination: string;
@@ -447,6 +465,26 @@ declare function parseMarkdownPage(input: {
     resolveIdentity?: (frontmatter: Record<string, unknown>, fallback: MarkdownPageIdentity) => MarkdownPageIdentity;
 }): MigrationPage | null;
 
+/**
+ * Mintlify analytics -> Thally `docs.json` `integrations`.
+ *
+ * Reads docs.json `integrations` and the legacy mint.json `analytics` block.
+ * Values land in an inline script on the rendered site, so each is validated
+ * here with the same patterns the renderer applies (src/lib/analytics-config.ts;
+ * a test keeps the two in agreement). Invalid values are skipped with a warning,
+ * never coerced, and no warning echoes a full value.
+ */
+type MigrationIntegrations = NonNullable<MigrationDocsConfig['integrations']>;
+declare function projectMintlifyIntegrations(config: Record<string, unknown>): {
+    integrations?: MigrationIntegrations;
+    warnings: Array<MigrationWarning>;
+};
+/**
+ * Validate an authored Thally `docs.json` `integrations` value with the same
+ * rules as the import and the renderer; one value-free message per problem.
+ */
+declare function validateIntegrations(integrations: unknown): Array<string>;
+
 /** Render canonical migration bundles into a portable Thally repository tree. */
 
 /** Merge imported tabs into an existing site without duplicating changelog tabs. */
@@ -486,4 +524,4 @@ declare function migrateUrl(options: UrlMigrationOptions): Promise<MigrationBund
  */
 declare function hydrateRemoteApiSpecs(bundle: MigrationBundle, fetcher?: MigrationFetcher): Promise<MigrationBundle>;
 
-export { type GitHubRepositorySource, type MigrationAsset, type MigrationBundle, type MigrationDocsConfig, type MigrationFetchRequest, type MigrationFetchResponse, type MigrationFetcher, type MigrationNavigationGroup, type MigrationNavigationTab, type MigrationPage, type MigrationPlatform, type MigrationWarning, type RenderedMigrationFile, type RepositoryMigrationOptions, type UrlMigrationOptions, addMintlifyDirectoryRedirects, buildNavigationFromPages, cloneGitHubRepository, defaultMigrationFetcher, detectRepositoryDocsDir, detectRepositoryPlatform, gitmodulePaths, hydrateRemoteApiSpecs, mergeMigrationConfig, migrateRepository, migrateUrl, normalizeMdx, parseGitHubRepositoryUrl, parseMarkdownPage, projectFernNavigation, projectMintlifyNavigation, pruneMissingNavigationPages, readFernConfig, readMintlifyConfig, renderMigrationFiles, validateMigrationUrl };
+export { type GitHubRepositorySource, type MigrationAsset, type MigrationBundle, type MigrationDocsConfig, type MigrationFetchRequest, type MigrationFetchResponse, type MigrationFetcher, type MigrationNavigationGroup, type MigrationNavigationTab, type MigrationPage, type MigrationPlatform, type MigrationWarning, type RenderedMigrationFile, type RepositoryMigrationOptions, type UrlMigrationOptions, addMintlifyDirectoryRedirects, buildNavigationFromPages, cloneGitHubRepository, defaultMigrationFetcher, detectRepositoryDocsDir, detectRepositoryPlatform, gitmodulePaths, hydrateRemoteApiSpecs, mergeMigrationConfig, migrateRepository, migrateUrl, normalizeMdx, parseGitHubRepositoryUrl, parseMarkdownPage, projectFernNavigation, projectMintlifyIntegrations, projectMintlifyNavigation, pruneMissingNavigationPages, readFernConfig, readMintlifyConfig, renderMigrationFiles, validateIntegrations, validateMigrationUrl };

package/dist/index.js

@@ -326,8 +326,8 @@ function leadingPageHeading(body) {
     const root = descriptionParser.parse(body);
     const first = root.children?.find((node) => node.type !== "mdxjsEsm" && node.type !== "html");
     if (first?.type !== "heading" || first.depth !== 1) return void 0;
-    const text = (node) => node.type === "mdxTextExpression" || node.type === "mdxFlowExpression" ? "" : node.value ?? (node.children ?? []).map(text).join("");
-    const title = text(first).replace(/\s+/g, " ").trim();
+    const text2 = (node) => node.type === "mdxTextExpression" || node.type === "mdxFlowExpression" ? "" : node.value ?? (node.children ?? []).map(text2).join("");
+    const title = text2(first).replace(/\s+/g, " ").trim();
     const start = first.position?.start.offset;
     const end = first.position?.end.offset;
     return title && start !== void 0 && end !== void 0 ? { title, start, end } : void 0;
@@ -400,16 +400,16 @@ function collectEsmBindingsByPattern(source, declared) {
 var FENCE_OPEN = /^(`{3,}|~{3,})/;
 function maskInlineSpansForMath(line) {
   const blocks = [];
-  const stash = (text) => {
-    blocks.push(text);
+  const stash = (text2) => {
+    blocks.push(text2);
     return `\0${blocks.length - 1}\0`;
   };
   const codeMasked = line.split(/(`[^`]*`)/).map((segment, index) => index % 2 === 1 ? stash(segment) : segment).join("");
   const tagMasked = codeMasked.replace(/<\/?[a-zA-Z][^<>]*>/g, stash);
-  const masked = [tagMasked, tagMasked].reduce((text) => text.replace(/(?<!\$)\{[^{}]*\}/g, stash), tagMasked);
+  const masked = [tagMasked, tagMasked].reduce((text2) => text2.replace(/(?<!\$)\{[^{}]*\}/g, stash), tagMasked);
   return {
     masked,
-    unmask: (text) => text.replace(/\u0000(\d+)\u0000/g, (_match, index) => blocks[Number(index)])
+    unmask: (text2) => text2.replace(/\u0000(\d+)\u0000/g, (_match, index) => blocks[Number(index)])
   };
 }
 var TEX_SIGNAL = /\\[a-zA-Z]|[\^_{]/;
@@ -562,11 +562,11 @@ function splitFrontmatterBlock(raw) {
   return { front: bom + source.slice(0, end), body: source.slice(end) };
 }
 var MIGRATED_COMPONENT_TAG = /^Migrated[0-9a-f]{12}$/;
-function isSelfClosingJsx(text) {
-  return /\/>\s*$/.test(text);
+function isSelfClosingJsx(text2) {
+  return /\/>\s*$/.test(text2);
 }
-function renameTagOccurrences(text, name, newName) {
-  let result = text;
+function renameTagOccurrences(text2, name, newName) {
+  let result = text2;
   const openIndex = result.indexOf(`<${name}`);
   if (openIndex >= 0) result = `${result.slice(0, openIndex + 1)}${newName}${result.slice(openIndex + 1 + name.length)}`;
   const closeIndex = result.lastIndexOf(`</${name}`);
@@ -612,9 +612,9 @@ function replaceUnknownComponents(raw, warn, options = {}) {
     if (start === void 0 || end === void 0) return "";
     const isJsx = node.type === "mdxJsxFlowElement" || node.type === "mdxJsxTextElement";
     const tagRoot = node.name ? node.name.split(".")[0] : void 0;
-    const text = body.slice(start, end);
+    const text2 = body.slice(start, end);
     if (isJsx && tagRoot === "Link" && !declared.has("Link")) {
-      if (isSelfClosingJsx(text) || !node.children?.length) return renameTagOccurrences(text, node.name, "a");
+      if (isSelfClosingJsx(text2) || !node.children?.length) return renameTagOccurrences(text2, node.name, "a");
       const openEnd = node.children[0].position?.start.offset ?? start;
       const closeStart = node.children.at(-1).position?.end.offset ?? end;
       return renameTagOccurrences(body.slice(start, openEnd), node.name, "a") + renderChildrenSpan(node.children, openEnd, closeStart, body, renderNode) + renameTagOccurrences(body.slice(closeStart, end), node.name, "a");
@@ -624,7 +624,7 @@ function replaceUnknownComponents(raw, warn, options = {}) {
         warned.add(node.name);
         warn(node.name);
       }
-      if (isSelfClosingJsx(text)) return "";
+      if (isSelfClosingJsx(text2)) return "";
       if (!node.children?.length) return "<div></div>";
       const openEnd = node.children[0].position?.start.offset ?? start;
       const closeStart = node.children.at(-1).position?.end.offset ?? end;
@@ -635,7 +635,7 @@ ${children}
 
 </div>` : `<div>${children}</div>`;
     }
-    if (!node.children?.length) return text;
+    if (!node.children?.length) return text2;
     return renderChildrenSpan(node.children, start, end, body, renderNode);
   };
   return front + renderNode(root);
@@ -643,8 +643,8 @@ ${children}
 function maskCode(body) {
   const source = body.replace(/\u0000/g, "");
   const blocks = [];
-  const stash = (text) => {
-    blocks.push(text);
+  const stash = (text2) => {
+    blocks.push(text2);
     return `\0${blocks.length - 1}\0`;
   };
   const lines = [];
@@ -671,7 +671,7 @@ function maskCode(body) {
   if (fenceBuffer.length) lines.push(stash(fenceBuffer.join("\n")));
   return {
     masked: lines.join("\n"),
-    unmask: (text) => text.replace(/\u0000(\d+)\u0000/g, (_match, index) => blocks[Number(index)])
+    unmask: (text2) => text2.replace(/\u0000(\d+)\u0000/g, (_match, index) => blocks[Number(index)])
   };
 }
 function replaceOutsideCode(body, transform) {
@@ -690,7 +690,7 @@ function rewriteFernRelativePageLinks(body, currentSourcePath, routesBySourcePat
     const route = candidates.map((candidate) => routesBySourcePath.get(candidate)).find(Boolean);
     return route ? `/${route.replace(/^\/+/, "")}${suffix}` : target;
   };
-  return replaceOutsideCode(body, (text) => text.replace(
+  return replaceOutsideCode(body, (text2) => text2.replace(
     /(\]\()(<[^>\n]+>|[^\s)]+)(?=\s|\))/g,
     (_match, opening, target) => `${opening}${target.startsWith("<") && target.endsWith(">") ? `<${rewrite(target.slice(1, -1))}>` : rewrite(target)}`
   ).replace(
@@ -2165,7 +2165,7 @@ const MintlifyComponents = {
 }
 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),
+    (text2, edit) => text2.slice(0, edit.start) + edit.value + text2.slice(edit.end),
     source
   );
 }
@@ -2454,14 +2454,14 @@ function createComponentMigrator(siteRoot, confinementRoot, warnings, sourceIden
         }
         return;
       }
-      const text = content.toString("utf8");
-      const syntax = ts2.transpileModule(text, {
+      const text2 = content.toString("utf8");
+      const syntax = ts2.transpileModule(text2, {
         fileName: path,
         reportDiagnostics: true,
         compilerOptions: { jsx: ts2.JsxEmit.Preserve, target: ts2.ScriptTarget.ESNext, module: ts2.ModuleKind.ESNext }
       });
       if (syntax.diagnostics?.some((diagnostic) => diagnostic.category === ts2.DiagnosticCategory.Error)) throw new Error("component source contains unsupported JavaScript or TypeScript syntax");
-      const ast = sourceFile(text, path);
+      const ast = sourceFile(text2, path);
       if (ast.statements.some((statement) => ts2.isExpressionStatement(statement) && ts2.isStringLiteral(statement.expression) && statement.expression.text === "use server")) throw new Error("server-only component modules require manual migration");
       const edits = [];
       function dependency(literal, importDeclaration) {
@@ -2509,7 +2509,7 @@ function createComponentMigrator(siteRoot, confinementRoot, warnings, sourceIden
         ts2.forEachChild(node, inspect);
       }
       inspect(ast);
-      const replaced = applyReplacements(text, edits);
+      const replaced = applyReplacements(text2, edits);
       const shebangMatch = /^#!.*\r?\n/.exec(replaced);
       const prologue = "// @ts-nocheck\n'use client';\n\n";
       staged.set(destination, {
@@ -3016,10 +3016,10 @@ ${inlineSource}` });
       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}`);
+      const text2 = content.slice(start, end);
+      const opening = text2.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}`);
+      const closing = text2.lastIndexOf(`</${node.name}`);
       if (closing >= 0) edits.push({ start: start + closing + 2, end: start + closing + 2 + node.name.length, value: replacement });
     });
     walk(tree, (node) => {
@@ -5141,9 +5141,9 @@ function announcementMarkdown(message) {
     links.set(marker, destination && label ? `[${escapeText(label)}](${destination})` : escapeText(label));
     document(element).replaceWith(marker);
   });
-  let text = escapeText(document("body").text());
-  for (const [marker, link] of links) text = text.replaceAll(marker, link);
-  return text.trim();
+  let text2 = escapeText(document("body").text());
+  for (const [marker, link] of links) text2 = text2.replaceAll(marker, link);
+  return text2.trim();
 }
 function objectValue4(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
@@ -5661,6 +5661,179 @@ function projectFernNavigation(input) {
   };
 }
 
+// src/analytics.ts
+var GA4_ID = /^G-[A-Z0-9]{4,20}$/;
+var GTM_ID = /^GTM-[A-Z0-9]{4,12}$/;
+var POSTHOG_KEY = /^phc_[A-Za-z0-9]{20,64}$/;
+var HOSTNAME_LABEL = "[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?";
+var HOSTNAME = new RegExp(`^${HOSTNAME_LABEL}(?:\\.${HOSTNAME_LABEL})*$`);
+var SAFE_PATH = /^\/[A-Za-z0-9._~\-/]*$/;
+var MAX_PLAUSIBLE_DOMAINS = 10;
+var SUPPORTED = ["ga4", "gtm", "posthog", "plausible"];
+var LEGACY_GA4_ALIAS = "googleAnalytics";
+function own(record, key) {
+  return Object.prototype.hasOwnProperty.call(record, key) ? record[key] : void 0;
+}
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function redact(value) {
+  if (typeof value !== "string") return Array.isArray(value) ? "array" : value === null ? "null" : typeof value;
+  return value.length === 0 ? "empty string" : `"${value.trim().slice(0, 4).replace(/[^\x20-\x7e]/g, "?")}..." (${value.length} chars)`;
+}
+function isPublicHostname(hostname) {
+  return !/(^|\.)localhost$/.test(hostname) && !/(^|\.)\d+$/.test(hostname) && !hostname.includes(":") && !hostname.startsWith("[");
+}
+function normalizeHttpsUrl(value, allowPath) {
+  if (!/^https:\/\//i.test(value) || /[?#\\]/.test(value)) return null;
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return null;
+  }
+  if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash) return null;
+  if (!HOSTNAME.test(url.hostname) || !isPublicHostname(url.hostname) || url.port === "0") return null;
+  const fullPath = /^https:\/\/[^/]*(\/.*)?$/i.exec(value)?.[1] ?? "";
+  if (fullPath.includes("//")) return null;
+  const path = fullPath.replace(/\/+$/, "");
+  if (path && (!allowPath || !SAFE_PATH.test(path) || path.split("/").some((s) => s === ".." || s === "."))) return null;
+  return `${url.origin}${path}`;
+}
+function normalizeDomains(value) {
+  const parts = value.split(",").map((part) => part.trim().toLowerCase());
+  if (parts.length > MAX_PLAUSIBLE_DOMAINS) return null;
+  return parts.every((part) => part.length <= 253 && HOSTNAME.test(part)) ? parts.join(",") : null;
+}
+function normalizeServer(value) {
+  if (/^https:\/\//i.test(value)) {
+    const origin2 = normalizeHttpsUrl(value, false);
+    return origin2 ? origin2.replace(/^https:\/\//, "") : null;
+  }
+  const bare = /^([a-z0-9.-]+)(?::(\d{1,5}))?$/i.exec(value);
+  if (!bare || bare[2] !== void 0 && (Number(bare[2]) < 1 || Number(bare[2]) > 65535)) return null;
+  const origin = normalizeHttpsUrl(`https://${bare[1].toLowerCase()}${bare[2] === void 0 ? "" : `:${Number(bare[2])}`}`, false);
+  return origin ? origin.replace(/^https:\/\//, "") : null;
+}
+function text(value) {
+  return typeof value === "string" && value.trim() && value.length <= 2048 ? value.trim() : null;
+}
+function projectMintlifyIntegrations(config) {
+  if (!isRecord(config)) return { warnings: [] };
+  try {
+    return project(config);
+  } catch {
+    return { warnings: [{ code: "unsupported-config", message: "Mintlify analytics configuration could not be read; analytics were not imported." }] };
+  }
+}
+function project(config) {
+  const warnings = [];
+  const warn = (message) => warnings.push({ code: "unsupported-config", message });
+  const sources = [];
+  for (const [label, key] of [["integrations", "integrations"], ["analytics", "analytics"]]) {
+    const value = own(config, key);
+    if (value === void 0) continue;
+    if (isRecord(value)) sources.push({ label, block: value });
+    else warn(`Mintlify ${label} must be an object (found ${redact(value)}); analytics from it were not imported.`);
+  }
+  const integrations = {};
+  const pick = (name) => {
+    const found = [];
+    for (const source of sources) {
+      let value = own(source.block, name);
+      if (value === void 0 && name === "ga4" && source.label === "analytics") value = own(source.block, LEGACY_GA4_ALIAS);
+      if (value !== void 0) found.push({ label: `${source.label}.${name}`, value });
+    }
+    if (found.length > 1) {
+      warn(`Mintlify ${found[0].label} and ${found[1].label} are both set; using ${found[0].label} for ${name}.`);
+    }
+    return found;
+  };
+  const field = (label, block, key, required) => {
+    const raw = own(block, key);
+    if (raw === void 0) {
+      if (required) warn(`Mintlify ${label}.${key} is missing; ${label} was not imported.`);
+      return required ? null : void 0;
+    }
+    const value = text(raw);
+    if (value === null) warn(`Mintlify ${label}.${key} is not a usable string (found ${redact(raw)}); ${label} was not imported.`);
+    return value;
+  };
+  const objectFor = (entry) => {
+    if (isRecord(entry.value)) return entry.value;
+    warn(`Mintlify ${entry.label} must be an object (found ${redact(entry.value)}); provider was not imported.`);
+    return null;
+  };
+  const ga4 = pick("ga4")[0];
+  const ga4Block = ga4 ? objectFor(ga4) : null;
+  if (ga4 && ga4Block) {
+    const id = field(ga4.label, ga4Block, "measurementId", true);
+    if (id && GA4_ID.test(id)) integrations.ga4 = { measurementId: id };
+    else if (id) warn(`Mintlify ${ga4.label}.measurementId ${redact(id)} is not a GA4 ID (G-XXXXXXXXXX); Universal Analytics and lowercase IDs are not imported.`);
+  }
+  const gtm = pick("gtm")[0];
+  const gtmBlock = gtm ? objectFor(gtm) : null;
+  if (gtm && gtmBlock) {
+    const id = field(gtm.label, gtmBlock, "tagId", true);
+    if (id && GTM_ID.test(id)) integrations.gtm = { tagId: id };
+    else if (id) warn(`Mintlify ${gtm.label}.tagId ${redact(id)} is not a GTM container ID (GTM-XXXXXXX); GTM was not imported.`);
+  }
+  const plausible = pick("plausible")[0];
+  const plausibleBlock = plausible ? objectFor(plausible) : null;
+  if (plausible && plausibleBlock) {
+    const domainRaw = field(plausible.label, plausibleBlock, "domain", true);
+    const serverRaw = field(plausible.label, plausibleBlock, "server", false);
+    const domain = domainRaw ? normalizeDomains(domainRaw) : null;
+    const server = serverRaw ? normalizeServer(serverRaw) : serverRaw;
+    if (domainRaw && !domain) warn(`Mintlify ${plausible.label}.domain ${redact(domainRaw)} must be hostname(s) without a protocol or path; Plausible was not imported.`);
+    if (serverRaw && !server) warn(`Mintlify ${plausible.label}.server ${redact(serverRaw)} must be a hostname; Plausible was not imported.`);
+    if (domain && server !== null) integrations.plausible = { domain, ...server ? { server } : {} };
+  }
+  const posthog = pick("posthog")[0];
+  const posthogBlock = posthog ? objectFor(posthog) : null;
+  if (posthog && posthogBlock) {
+    const key = field(posthog.label, posthogBlock, "apiKey", true);
+    const hostRaw = field(posthog.label, posthogBlock, "apiHost", false);
+    const host = hostRaw ? normalizeHttpsUrl(hostRaw, true) : hostRaw;
+    const recording = own(posthogBlock, "sessionRecording");
+    if (recording !== void 0 && typeof recording !== "boolean") warn(`Mintlify ${posthog.label}.sessionRecording must be a boolean (found ${redact(recording)}); session recording disabled.`);
+    if (key && !POSTHOG_KEY.test(key)) warn(`Mintlify ${posthog.label}.apiKey ${redact(key)} is not a PostHog project key (phc_...); PostHog was not imported.`);
+    if (hostRaw && !host) warn(`Mintlify ${posthog.label}.apiHost ${redact(hostRaw)} must be an https URL without credentials, query, or fragment; PostHog was not imported.`);
+    if (key && POSTHOG_KEY.test(key) && host !== null) {
+      integrations.posthog = {
+        apiKey: key,
+        ...host ? { apiHost: host } : {},
+        // Fail closed: a present non-boolean value turns recording off.
+        ...recording !== void 0 ? { sessionRecording: recording === true } : {}
+      };
+    }
+  }
+  const unsupported = /* @__PURE__ */ new Set();
+  for (const source of sources) {
+    for (const key of Object.keys(source.block)) {
+      if (SUPPORTED.includes(key)) continue;
+      if (key === LEGACY_GA4_ALIAS && source.label === "analytics") continue;
+      unsupported.add(/^[A-Za-z0-9_-]{1,40}$/.test(key) ? key : "(invalid name)");
+    }
+  }
+  if (unsupported.size > 0) {
+    const names = [...unsupported].slice(0, 30);
+    warn(`Mintlify analytics/integration providers Thally cannot render were not imported: ${names.join(", ")}${unsupported.size > names.length ? ", ..." : ""}. Supported: ga4, gtm, posthog, plausible.`);
+  }
+  return { ...Object.keys(integrations).length > 0 ? { integrations } : {}, warnings };
+}
+function validateIntegrations(integrations) {
+  if (integrations === void 0) return [];
+  const result = projectMintlifyIntegrations({ integrations });
+  const messages = result.warnings.map(
+    (warning) => warning.message.replace(/^Mintlify analytics\/integration providers Thally cannot render were not imported: /, "docs.json integrations: Thally does not support these providers, so they will not be rendered: ").replace(/^Mintlify /, "docs.json ").replace(/\b(?:was|were|are) not imported\b/g, "will not be rendered")
+  );
+  if (result.integrations?.ga4 && result.integrations.gtm) {
+    messages.push("docs.json integrations enable both ga4 and gtm; a GA4 tag inside the GTM container would double-count page views.");
+  }
+  return messages;
+}
+
 // src/repository.ts
 var MAX_SOURCE_FILES = 5e3;
 var MAX_PAGE_BYTES = 2e6;
@@ -6477,8 +6650,8 @@ var PATH_SEPARATORS = /[\s"'()<>[\]{}=,;:|\\`*!?#&]+/;
 function publicAssetKey(repoRelative) {
   return repoRelative.split("/", 1)[0].toLowerCase() === "public" ? repoRelative.slice("public/".length) : repoRelative;
 }
-function addPathReferences(text, baseDir, exact, loose) {
-  for (const word of text.split(PATH_SEPARATORS)) {
+function addPathReferences(text2, baseDir, exact, loose) {
+  for (const word of text2.split(PATH_SEPARATORS)) {
     let token = word.replace(/\.+$/, "");
     if (!/\.[a-z0-9]{2,5}$/i.test(token) || token.startsWith("//")) continue;
     if (token.includes("%")) {
@@ -6520,8 +6693,8 @@ function classifyApiSpec(path) {
   } catch {
     return "unknown";
   }
-  const text = buffer.toString("utf8", 0, bytesRead);
-  const topLevel = text.match(/^(?:openapi|swagger|asyncapi)\s*:/m)?.[0] ?? text.match(/^\s*\{\s*"(?:openapi|swagger|asyncapi)"\s*:/m)?.[0];
+  const text2 = buffer.toString("utf8", 0, bytesRead);
+  const topLevel = text2.match(/^(?:openapi|swagger|asyncapi)\s*:/m)?.[0] ?? text2.match(/^\s*\{\s*"(?:openapi|swagger|asyncapi)"\s*:/m)?.[0];
   if (!topLevel) return "unknown";
   return /asyncapi/i.test(topLevel) ? "asyncapi" : "openapi";
 }
@@ -7009,12 +7182,12 @@ function externalizeMissingFernLinks(body, pageIds, sourceSiteUrl, externalized)
       return target;
     }
   };
-  return replaceOutsideCode(body, (text) => text.replace(/(\]\()\/(?!\/)([^\s)]+)(\))/g, (_match, before, target, after) => `${before}${rewrite(`/${target}`)}${after}`).replace(/(\b(?:href|to)=(['"]))\/(?!\/)([^'"\n]+)\2/g, (_match, before, quote, target) => `${before}${rewrite(`/${target}`)}${quote}`));
+  return replaceOutsideCode(body, (text2) => text2.replace(/(\]\()\/(?!\/)([^\s)]+)(\))/g, (_match, before, target, after) => `${before}${rewrite(`/${target}`)}${after}`).replace(/(\b(?:href|to)=(['"]))\/(?!\/)([^'"\n]+)\2/g, (_match, before, quote, target) => `${before}${rewrite(`/${target}`)}${quote}`));
 }
 function stripFernBasePathFromLinks(body, basePath) {
   if (!basePath) return body;
   const escaped = basePath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  return replaceOutsideCode(body, (text) => text.replace(new RegExp(`(\\]\\()${escaped}(?=\\/|[)#?])`, "g"), (match, prefix, offset, source) => prefix + (source[offset + match.length] === "/" ? "" : "/")).replace(new RegExp(`(\\b(?:href|to)=["'])${escaped}(?=\\/|["'#?])`, "g"), (match, prefix, offset, source) => prefix + (source[offset + match.length] === "/" ? "" : "/")));
+  return replaceOutsideCode(body, (text2) => text2.replace(new RegExp(`(\\]\\()${escaped}(?=\\/|[)#?])`, "g"), (match, prefix, offset, source) => prefix + (source[offset + match.length] === "/" ? "" : "/")).replace(new RegExp(`(\\b(?:href|to)=["'])${escaped}(?=\\/|["'#?])`, "g"), (match, prefix, offset, source) => prefix + (source[offset + match.length] === "/" ? "" : "/")));
 }
 function rewriteMintlifyMountedLinks(body, pageIds) {
   const rewrite = (target) => {
@@ -7031,7 +7204,7 @@ function rewriteMintlifyMountedLinks(body, pageIds) {
     }
     return target;
   };
-  return replaceOutsideCode(body, (text) => text.replace(/(\]\()(\/[^\s)]+)(\))/g, (_match, before, target, after) => `${before}${rewrite(target)}${after}`).replace(/(\b(?:href|to)=(['"]))(\/[^'"\n]+)\2/g, (_match, before, quote, target) => `${before}${rewrite(target)}${quote}`));
+  return replaceOutsideCode(body, (text2) => text2.replace(/(\]\()(\/[^\s)]+)(\))/g, (_match, before, target, after) => `${before}${rewrite(target)}${after}`).replace(/(\b(?:href|to)=(['"]))(\/[^'"\n]+)\2/g, (_match, before, quote, target) => `${before}${rewrite(target)}${quote}`));
 }
 function preserveLinkedAnchors(pages) {
   const pageById = new Map(pages.map((page) => [page.id, page]));
@@ -7055,10 +7228,10 @@ function preserveLinkedAnchors(pages) {
     if (id !== currentId) crossPageRequests.add(`${id}#${fragment}`);
   };
   for (const page of pages) {
-    replaceOutsideCode(page.body, (text) => {
-      for (const match of text.matchAll(/\]\(([^)\s]+)\)/g)) addTarget(match[1], page.id);
-      for (const match of text.matchAll(/\b(?:href|to)=(['"])([^'"\n]+)\1/g)) addTarget(match[2], page.id);
-      return text;
+    replaceOutsideCode(page.body, (text2) => {
+      for (const match of text2.matchAll(/\]\(([^)\s]+)\)/g)) addTarget(match[1], page.id);
+      for (const match of text2.matchAll(/\b(?:href|to)=(['"])([^'"\n]+)\1/g)) addTarget(match[2], page.id);
+      return text2;
     });
   }
   const comparable = (value) => value.replace(/&(?:lt|gt|amp|quot);/g, " ").toLowerCase().replace(/[^\p{L}\p{N}]+/gu, "");
@@ -7082,9 +7255,9 @@ function preserveLinkedAnchors(pages) {
       return match ? { index, text: match[1] } : null;
     }).filter((entry) => entry !== null);
     const existing = /* @__PURE__ */ new Set();
-    replaceOutsideCode(page.body, (text) => {
-      for (const match of text.matchAll(/\bid=(?:"([^"]+)"|'([^']+)')/g)) existing.add(match[1] ?? match[2]);
-      return text;
+    replaceOutsideCode(page.body, (text2) => {
+      for (const match of text2.matchAll(/\bid=(?:"([^"]+)"|'([^']+)')/g)) existing.add(match[1] ?? match[2]);
+      return text2;
     });
     const candidateIndexes = /* @__PURE__ */ new Map();
     for (const heading of headings) {
@@ -7246,7 +7419,7 @@ function repositoryAssetHref(value, currentFile, siteRoot, onReferenced) {
   }
 }
 function rewriteFernIdRenameLinks(body, renames) {
-  return replaceOutsideCode(body, (text) => {
+  return replaceOutsideCode(body, (text2) => {
     const rewriteTarget = (target) => {
       const suffixIndex = target.search(/[?#]/);
       const path = (suffixIndex >= 0 ? target.slice(0, suffixIndex) : target).replace(/^\/+/, "");
@@ -7254,7 +7427,7 @@ function rewriteFernIdRenameLinks(body, renames) {
       const renamed = renames.get(path);
       return renamed ? `/${renamed}${suffix}` : target;
     };
-    return text.replace(/(\]\()\/([^\s)]+)(?=[\s)]|$)/g, (_match, prefix, target) => `${prefix}${rewriteTarget(`/${target}`)}`).replace(/(\bhref=")\/([^"]+)(")/g, (_match, prefix, target, suffix) => `${prefix}${rewriteTarget(`/${target}`)}${suffix}`);
+    return text2.replace(/(\]\()\/([^\s)]+)(?=[\s)]|$)/g, (_match, prefix, target) => `${prefix}${rewriteTarget(`/${target}`)}`).replace(/(\bhref=")\/([^"]+)(")/g, (_match, prefix, target, suffix) => `${prefix}${rewriteTarget(`/${target}`)}${suffix}`);
   });
 }
 function rewriteRepositoryAssetLinks(body, currentFile, siteRoot, onReferenced) {
@@ -8778,6 +8951,9 @@ ${reasons.map((reason) => `- ${reason}`).join("\n")}` : "No importable Markdown
     docsConfig = { ...docsConfig, navbar: { ...docsConfig.navbar, logo: null } };
   }
   if (mintlifyConfig) {
+    const analytics = projectMintlifyIntegrations(mintlifyConfig);
+    warnings.push(...analytics.warnings);
+    if (analytics.integrations) docsConfig = { ...docsConfig, integrations: analytics.integrations };
     const appearance = mintlifyAppearance(mintlifyConfig, warnings);
     if (Object.keys(appearance).length > 0) {
       docsConfig = { ...docsConfig, appearance: { ...docsConfig.appearance, ...appearance } };
@@ -8896,6 +9072,9 @@ function renderPage(bundle, page) {
     ""
   ].filter((line) => line !== null).join("\n");
 }
+function isIntegrationsObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
 function mergeMigrationConfig(existing, incoming) {
   const tabs = existing.tabs.filter((tab) => tab.tab.toLowerCase() !== "changelog");
   const names = new Set(tabs.map((tab) => tab.tab.toLowerCase()));
@@ -8966,7 +9145,15 @@ function mergeMigrationConfig(existing, incoming) {
     // Collection presentation belongs to the imported information
     // architecture; starter defaults must not coerce source dropdowns to tabs.
     navigation: incoming.navigation ?? existing.navigation,
-    ...i18n ? { i18n } : {}
+    ...i18n ? { i18n } : {},
+    // Existing providers win per provider; imported ones fill the gaps.
+    // A malformed (string/array) existing value must not spread into index keys.
+    ...isIntegrationsObject(existing.integrations) || isIntegrationsObject(incoming.integrations) ? {
+      integrations: {
+        ...isIntegrationsObject(incoming.integrations) ? incoming.integrations : {},
+        ...isIntegrationsObject(existing.integrations) ? existing.integrations : {}
+      }
+    } : {}
   };
 }
 function renderMigrationFiles(bundle, options = {}) {
@@ -9957,7 +10144,7 @@ ${fence}
     }
   });
   const escape = turndown.escape.bind(turndown);
-  turndown.escape = (text) => escape(text).replace(/[<{]/g, (match) => `\\${match}`);
+  turndown.escape = (text2) => escape(text2).replace(/[<{]/g, (match) => `\\${match}`);
   const body = turndown.turndown(root.html() ?? "").trim();
   if (!title || body.length < 40 && $("article").length === 0) return { page: null, links };
   return {
@@ -10510,6 +10697,11 @@ async function migrateUrl(options) {
     topLevelNavigation
   });
   if (sourceMintlifyProjection) warnings.push(...sourceMintlifyProjection.warnings);
+  if (sourceMintlifyConfig) {
+    const analytics = projectMintlifyIntegrations(sourceMintlifyConfig);
+    warnings.push(...analytics.warnings);
+    if (analytics.integrations) docsConfig.integrations = analytics.integrations;
+  }
   if (docusaurusRedirects.length > 0) {
     docsConfig.redirects = [...new Map(docusaurusRedirects.map((redirect) => [
       `${redirect.source}:${redirect.destination}`,
@@ -10658,8 +10850,8 @@ async function downloadSpec(value, fetcher) {
   throw new Error("Remote OpenAPI spec redirected too many times.");
 }
 function parseOpenApi(content, extension) {
-  const text = content.toString("utf8");
-  const parsed = extension === "yaml" || !text.trimStart().startsWith("{") ? parseYaml6(text) : JSON.parse(text);
+  const text2 = content.toString("utf8");
+  const parsed = extension === "yaml" || !text2.trimStart().startsWith("{") ? parseYaml6(text2) : JSON.parse(text2);
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("OpenAPI spec is not an object.");
   const document = parsed;
   if (typeof document.openapi !== "string" || !/^3\./.test(document.openapi)) {
@@ -10769,11 +10961,13 @@ export {
   parseGitHubRepositoryUrl,
   parseMarkdownPage,
   projectFernNavigation,
+  projectMintlifyIntegrations,
   projectMintlifyNavigation,
   pruneMissingNavigationPages,
   readFernConfig,
   readMintlifyConfig,
   renderMigrationFiles,
+  validateIntegrations,
   validateMigrationUrl
 };
 //# sourceMappingURL=index.js.map