@thallylabs/migrate 0.2.25 → 0.2.27

package/README.md

@@ -115,6 +115,12 @@ Docusaurus `mdx-code-block` wrappers are opened as live MDX when the resulting
 page compiles and its special fences contain no module declarations. Pages
 whose fragments still need Docusaurus theme imports or remark plugins remain
 fenced and are retained.
+Directories and files whose names start with `_`, and `__tests__` directories,
+are skipped, as Docusaurus does not treat them as documents. Pages with `unlisted`
+set stay routable but are left out of navigation. Partial imports of `toc`,
+`frontMatter`, `metadata` and `assets` are bound to values the page can use
+instead of failing. `<Admonition>` becomes a callout like the colon fence, and
+`<ThemedImage>` keeps its light image.
 
 Fern repositories are located by their `fern/docs.yml` + `fern/fern.config.json`
 pair. `docs.yml` is parsed as bounded YAML—never executed—and preserves tabs,
@@ -129,6 +135,8 @@ Internal links are adjusted for the site's domain path, selected version, and
 source-file routes. Links to sections not imported into Thally stay on the
 published Fern site and produce a migration warning, so the generated site can
 build while the remaining content is moved separately.
+`<Markdown src="...">` includes are inlined from the referenced file when it is
+inside the repository.
 Every `api:` section's OpenAPI document is resolved from its own
 `generators.yml` (`api.specs[].openapi`, or the legacy `api:` string) and
 imported into its own tab — a docs.yml with several API sections (e.g. a REST
@@ -332,30 +340,71 @@ 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
+Restricted Mintlify pages migrate as real pages with normalized access
+frontmatter that the Thally runtime enforces (see `/guides/authenticated-docs`):
+
+- Frontmatter `groups` becomes a list of trimmed group names (`groups: admin`
+  and `groups: "a, b"` become lists); `public` becomes a boolean (`"false"`,
+  `no`, `off`, `0` are `false`; `true`/`"true"` is `true`). Empty `groups`
+  restricts nothing.
+- Rules on navigation containers (a group, tab, version, dropdown, anchor,
+  language, or `menu` item) are pushed down into the frontmatter of every page
+  below them, because the runtime reads access only from pages: container
+  `groups` (a list of strings) and `public: false` restrict, and Mintlify's
+  group-level `public: true` opens pages that name no groups of their own.
+  Pages stay in navigation where they were.
+- Rules combine to the strictest: nested and page group lists intersect,
+  `public: false` anywhere wins, and a page listed under both an open and a
+  restricted container gets the restricted rule.
+
+A page whose rules cannot be carried over safely fails closed instead: a
+malformed value (`public: maybe`, `groups: [1]`), group lists that share no
+group, or frontmatter that declares `groups`/`public` but cannot be parsed or
+read. Such a page is not written to `src/content`, is removed from navigation,
+and its original is written unchanged to `migration-quarantine/<original path>`
+at the project root, which no runtime reader walks; `create-thally-docs` adds
+that folder to `.gitignore`. Each quarantined page gets a `gated-page` warning.
+
+Fern and Docusaurus have no runtime access mapping in Thally, so their restricted
+pages fail closed in the same way: they are quarantined (not written to
+`src/content`, removed from navigation, original saved under
+`migration-quarantine/`) and never inlined into other pages. Fern signals:
+frontmatter `viewers` (any non-empty value) or `authed`, `<If roles>` or
+`<If viewers>` content in a page, and `viewers` in `docs.yml` on pages, sections,
+tabs, products, versions and api nodes; the specs of a restricted api node are
+withheld too. Docusaurus: a `draft` page, where any value other than unset,
+`false` or `"false"` counts as a draft; the check is skipped for files under `_`
+directories and `__tests__`, which Docusaurus does not publish as documents. Links
+from other pages to a quarantined page are left as authored and will fail
+`thally check`.
+
+Fern migration stops with an explicit error if cyclic navigation, excessive
+nesting, or the node budget prevents complete access classification. It emits
+no pages, assets, or API specs, because an unvisited branch could restrict a
+file also listed under a public node. Simplify the source navigation and retry.
+
+Assets are copied to `public/` only when a published page, the site configuration,
+copied styles or a migrated component names them by their exact normalized path;
+a restricted page's text never makes an asset public. On a site that withholds
+anything, an asset nothing published names that way, one named only by a bare file
+name or in a different letter case, one built at runtime, and one that shares its
+public path with another file are saved under `migration-quarantine/assets/`
+instead, with a warning listing them so they can be copied back by hand. On every
+platform a page over 2 MB is not inlined, OpenAPI spec reads are capped at 50 MB,
+and a path that resolves outside the repository through a symlink is refused.
+
+What a restricted page uses must not leak through surfaces that are not access
+controlled: it is never inlined into another page (a `gated-page` warning names
+the importer), images and other assets used only by restricted pages are not
+copied to `public/` (they are saved under `migration-quarantine/assets/`), and
+OpenAPI operations documented only on restricted pages are withheld from the
+published spec. One `gated-page` summary counts the restricted pages and notes
+that Thally hides them from everyone until reader authentication is configured
+in `docs.json` `auth`; no `auth` block is generated, because Mintlify's
+dashboard settings cannot be read from a repository. 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.
+else), one more `gated-page` warning says every unrestricted page will be
+public until `auth` is configured.
 
 ### Site-wide scripts, styles, fonts, and settings
 
@@ -382,6 +431,17 @@ Legacy `mint.json` `topbarLinks` and `topbarCtaButton` (including
 
 ## Branding
 
+Docusaurus custom CSS projects Infima palette, typography, header spacing,
+announcement styling, and local Prism colors into a portable stylesheet.
+For Sass or Tailwind expressions, provide locally compiled
+`build/assets/css/styles.*.css`; unresolved expressions produce a migration
+warning. Configuration and theme modules are read as static data.
+
+Remote Fern `global-theme` references fall back to local overrides and base
+Thally tokens with a structured warning. The NVIDIA theme uses `#76B900`
+when no local accent is configured. No remote theme assets are fetched.
+Authored section expansion defaults are retained on desktop and mobile.
+
 A source site's logo, favicon, and theme accent color(s) are extracted where
 each platform's config exposes them (Mintlify's `colors`, Fern's
 `colors.accent-primary`, Docusaurus's classic theme `customCss`). A valid

package/dist/index.d.ts

@@ -5,6 +5,7 @@
  */
 type MigrationPlatform = 'mintlify' | 'docusaurus' | 'fern' | 'gitbook' | 'nextra' | 'vitepress' | 'starlight' | 'thally' | 'generic' | 'unknown';
 interface MigrationNavigationGroup {
+    defaultOpen?: boolean;
     group: string;
     icon?: string;
     hidden?: boolean;
@@ -218,6 +219,8 @@ interface MigrationPage {
     navigationId: string;
     locale?: string;
     title: string;
+    /** Authored display H1 when the source uses a different metadata title. */
+    headingTitle?: string;
     navTitle?: string;
     /** Sidebar icon name or image URL from page frontmatter, with its optional style. */
     icon?: string;
@@ -230,6 +233,13 @@ interface MigrationPage {
     mode?: 'default' | 'wide' | 'custom' | 'center' | 'home';
     hidden?: boolean;
     noindex?: boolean;
+    /**
+     * Reader access groups (frontmatter `groups`): trimmed, non-empty names the
+     * runtime matches exactly. The page needs a signed-in reader in one of them.
+     */
+    groups?: Array<string>;
+    /** Frontmatter `public`: `true` opens the page to anyone, `false` needs any signed-in reader. */
+    public?: boolean;
     /** Social/SEO overrides from `og:*` and `twitter:*` frontmatter, keyed by the migrated frontmatter field. */
     meta?: Partial<Record<'ogTitle' | 'ogDescription' | 'ogImage' | 'twitterTitle' | 'twitterDescription' | 'twitterImage', string>>;
     /** OpenAPI operation key rendered by Thally instead of ordinary MDX. */
@@ -254,7 +264,7 @@ interface MigrationAsset {
 }
 interface MigrationWarning {
     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). */
+    /** Access-restricted source content: migrated with access rules, withheld (quarantined), or a site-wide auth risk. */
      | 'gated-page';
     message: string;
     source?: string;
@@ -281,7 +291,11 @@ interface MigrationBundle {
     remoteApiSpecs?: Array<RemoteApiSpec>;
     /** Customer-owned component source and registry; paths are repository-relative. */
     componentFiles?: Array<RenderedMigrationFile>;
-    /** Access-restricted source pages, written outside every published path. */
+    /**
+     * Restricted content that cannot be published safely (pages whose access
+     * rules are malformed or contradictory, and assets used only by restricted
+     * pages), written outside every published path.
+     */
     quarantinedFiles?: Array<RenderedMigrationFile>;
     /** Access-restricted pages the file limit dropped: neither published nor saved in quarantinedFiles. */
     droppedGatedPages?: number;
@@ -448,6 +462,30 @@ declare function detectRepositoryDocsDir(repositoryDir: string): string;
 /** Import an already-available repository directory into a canonical bundle. */
 declare function migrateRepository(options: RepositoryMigrationOptions): MigrationBundle;
 
+/**
+ * Mintlify-only helpers: page access rules, site-wide CSS/JS/font assets,
+ * and appearance settings. Kept apart from the generic repository walk so the
+ * rules that decide how restricted pages migrate (and what is quarantined)
+ * are auditable in one place.
+ *
+ * Access invariant: a restricted page migrates with normalized `groups` /
+ * `public` frontmatter that the Thally runtime enforces; anything ambiguous
+ * (malformed values, group lists that share no group) fails closed and the
+ * page is quarantined instead.
+ */
+
+/** Access imposed by every navigation container above one appearance of a page. */
+interface NavigationAccess {
+    /** Intersection of every container group list on the path. */
+    groups?: Array<string>;
+    /** Some container on the path sets `public: false`. */
+    hasPublicFalse: boolean;
+    /** Some container on the path sets `public: true` (Mintlify's documented group flag). */
+    hasPublicTrue: boolean;
+    /** Set when a container value is malformed or nested group lists share no group. */
+    problem?: string;
+}
+
 /**
  * Navigation projection for imported sites. Mintlify's schema is intentionally
  * more expressive than Thally's tab/group model, so complex containers are
@@ -459,16 +497,24 @@ interface MintlifyPageReference {
     navigationId: string;
     locale?: string;
 }
-/** A page listed under an access-restricted navigation container. */
-interface MintlifyGatedReference {
+/**
+ * One appearance of a page reference in navigation, with the access rules of
+ * every container above it. Thally reads access only from page frontmatter,
+ * so these are pushed down into the frontmatter of the pages they cover.
+ */
+interface MintlifyReferenceAccess {
     ref: string;
-    reason: string;
+    access: NavigationAccess;
 }
 interface MintlifyNavigationResult {
     docsConfig: MigrationDocsConfig;
     pageReferences: Array<MintlifyPageReference>;
-    /** Pages under a restricted container; withheld from `docsConfig` and `pageReferences`. */
-    gatedReferences: Array<MintlifyGatedReference>;
+    /**
+     * Access imposed by navigation containers, one entry per appearance of a
+     * page (open appearances included, so a page listed in several places can
+     * be given the strictest rule). Restricted pages stay in `docsConfig`.
+     */
+    referenceAccess: Array<MintlifyReferenceAccess>;
     /** `sourceRef` mounts under a restricted container; never resolved, so nothing of theirs is imported. */
     gatedSourceRefs: Array<string>;
     warnings: Array<MigrationWarning>;
@@ -527,6 +573,8 @@ interface FernPageDescriptor {
     navTitle?: string;
     /** Keep routable pages excluded by Fern's `hidden` navigation flag. */
     hidden?: boolean;
+    /** Listed under a docs.yml node that sets `viewers` or `authed`: Fern shows it only to signed-in roles. */
+    restricted?: boolean;
 }
 /** One `api:` navigation node, resolved to the name/tab Thally needs to bind its spec. */
 interface FernApiSection {
@@ -547,11 +595,15 @@ interface FernApiSection {
     routeSegments: Array<string>;
 }
 interface FernNavigationResult {
+    /** A bounded walk skipped nodes whose access rules and API bindings are unknown. */
+    navigationIncomplete: boolean;
     docsConfig: MigrationDocsConfig;
     descriptors: Array<FernPageDescriptor>;
     warnings: Array<MigrationWarning>;
     /** Every `api:` node found in navigation, in document order. A repo can declare several (e.g. a REST and a WebSocket API in separate tabs). */
     apiSections: Array<FernApiSection>;
+    /** `api:` nodes under a restricted node; their specs must not be published. */
+    restrictedApiSections: Array<FernApiSection>;
     /** Fern changelog tabs render their entries as a feed at the bare route. */
     changelogIndexes: Array<{
         route: string;