@thallylabs/migrate 0.2.14 → 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.
 
@@ -245,6 +251,56 @@ YouTube-embed package (e.g. a custom `LiteYouTube` wrapping
 page that imports that package directly, instead of losing the embed to the
 generic unknown-component fallback.
 
+### Access-restricted pages
+
+A gated Mintlify page must never migrate as public. A page is withheld when its
+frontmatter sets a non-empty `groups` (list or string) or `public: false`
+(also `"false"`, `no`, `off`, `0`; empty `groups` restricts nothing), or when it sits
+under a navigation group or tab that sets `groups` (a list of strings) or
+`public: false`. `public: true` alone is not gating. Withheld pages are not
+written to `src/content` and are removed from navigation (emptied groups and
+tabs included), whether or not navigation lists them. The original file is
+written unchanged to `migration-quarantine/<original path>` at the project
+root, which no runtime content reader, search index, or `llms` output walks;
+`create-thally-docs` also adds it to the project's `.gitignore` (appended once,
+existing entries kept) so it is never committed or pushed. A public page that
+imports a withheld page as a component does not inline it (a `gated-page`
+warning names the importer). Invalid frontmatter fails the run rather than
+importing the page. Each page gets a
+`gated-page` warning, plus a summary; `create-thally-docs` prints these last
+under an "ACCESS-RESTRICTED CONTENT" heading and the report records them and a
+`quarantined` count. Links from other pages to a withheld page are left as
+authored and will fail `thally check`; images and other assets used only by
+gated pages are still copied to `public/`. Mintlify's site-wide authentication mode lives in its
+dashboard and cannot be read from a repository, so when any page sets
+`public: true` (which implies the source site required sign-in for everything
+else) one `gated-page` warning says Thally will publish every imported page.
+Restricted-container `groups` and `public: false` are honored fail-closed even
+though Mintlify documents only `"public": true` on a group.
+
+### Site-wide scripts, styles, fonts, and settings
+
+Mintlify serves every `.css` and `.js` file in the content directory on every
+page. Those files are copied to `public/` (tooling config such as
+`*.config.js`, `tailwind.*`, `postcss.*`, plus `dist`/`build`/`coverage`
+output, dot-directories, and `node_modules` are not) under the normal asset
+size limits. Scripts are added to `docs.json` `customScripts` (URL-encoded),
+except modules that pages import as components, which are copied as components
+instead. Thally cannot
+load a stylesheet from `docs.json`, so each `.css` is preserved with a warning
+that it is not applied and likely targets Mintlify's DOM. Fonts named by
+`fonts.source` (top level, `heading`, `body`) that are local `.woff`, `.woff2`,
+`.ttf`, or `.otf` files are copied; Thally's `fonts` setting loads Google Fonts
+by family only, so a warning says the file is not applied. Remote font URLs
+are not downloaded, and unsafe or missing paths are warned about.
+
+Legacy `mint.json` `topbarLinks` and `topbarCtaButton` (including
+`type: github`) map to `navbar.links` and `navbar.primary`; `docs.json`
+`navbar` fields win, with a warning. `appearance.default`, `appearance.strict`
+(`showToggle: false`), and legacy `modeToggle.default` / `isHidden` map to
+`appearance`; invalid values are skipped with a warning. Mintlify sources set
+`markdown.enabled: true`, matching Mintlify's default Markdown mirrors.
+
 ## Branding
 
 A source site's logo, favicon, and theme accent color(s) are extracted where

package/dist/index.d.ts

@@ -113,6 +113,10 @@ interface MigrationDocsConfig {
     feedback?: {
         thumbsRating?: boolean;
     };
+    customScripts?: Array<{
+        src: string;
+        strategy?: 'beforeInteractive' | 'afterInteractive' | 'lazyOnload';
+    }>;
     ai?: {
         chat?: boolean;
         label?: string;
@@ -124,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;
@@ -170,7 +192,9 @@ interface MigrationAsset {
     projectRelative?: boolean;
 }
 interface MigrationWarning {
-    code: 'collision' | 'invalid-page' | 'missing-page' | 'unsupported-config' | 'limit-reached' | 'fetch-failed' | 'skipped-file';
+    code: 'collision' | 'invalid-page' | 'missing-page' | 'unsupported-config' | 'limit-reached' | 'fetch-failed' | 'skipped-file'
+    /** Access-restricted source page withheld from the published site (or a site-wide auth risk). */
+     | 'gated-page';
     message: string;
     source?: string;
 }
@@ -190,6 +214,10 @@ interface MigrationBundle {
     }>;
     /** Customer-owned component source and registry; paths are repository-relative. */
     componentFiles?: Array<RenderedMigrationFile>;
+    /** Access-restricted source pages, written outside every published path. */
+    quarantinedFiles?: Array<RenderedMigrationFile>;
+    /** Access-restricted pages the file limit dropped: neither published nor saved in quarantinedFiles. */
+    droppedGatedPages?: number;
     docsConfig: MigrationDocsConfig;
     site?: {
         name?: string;
@@ -265,6 +293,8 @@ interface RepositoryMigrationOptions {
     docusaurusSidebarPath?: string;
     /** @internal Static assets are shared across docs-plugin instances. */
     docusaurusSkipAssets?: boolean;
+    /** @internal Test seam: lowers the 5,000-file budget so budget behaviour can be exercised with small fixtures. */
+    maxSourceFiles?: number;
     /** @internal Redirects are global config, read once, not per plugin instance. */
     docusaurusSkipRedirects?: boolean;
 }
@@ -303,9 +333,16 @@ interface MintlifyPageReference {
     navigationId: string;
     locale?: string;
 }
+/** A page listed under an access-restricted navigation container. */
+interface MintlifyGatedReference {
+    ref: string;
+    reason: string;
+}
 interface MintlifyNavigationResult {
     docsConfig: MigrationDocsConfig;
     pageReferences: Array<MintlifyPageReference>;
+    /** Pages under a restricted container; withheld from `docsConfig` and `pageReferences`. */
+    gatedReferences: Array<MintlifyGatedReference>;
     warnings: Array<MigrationWarning>;
 }
 interface MintlifyProjectionOptions {
@@ -428,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. */
@@ -467,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 };