@thallylabs/migrate 0.2.11 → 0.2.14

package/README.md

@@ -18,10 +18,18 @@ rendered application before falling back to DOM link inference.
 An `openapi` (or `asyncapi`) reference is resolved wherever Mintlify allows
 it — the top-level `api.openapi`, or on any individual
 tab/anchor/dropdown/product/version, e.g. `navigation.tabs[].openapi` — and
-binds to that exact tab, not only the first one found. Remote `http://` and
+binds to that exact tab, not only the first one found. An `openapi` item inside
+a tab `menu` (string or `{ source, directory }`) becomes its own API tab named
+`<Tab>: <Item>`, so its endpoints appear in the sidebar; when it is the tab's
+only content it binds to the tab itself. The item's `icon` and `hidden` carry
+onto that tab, and a `directory` output folder is not used (a warning says so:
+endpoint pages are generated under `/api/`). An item Thally cannot represent
+produces a warning naming it. Specs that share a file name across folders are
+kept as separate files in `openapi/`. Remote `http://` and
 `https://` specs are not downloaded during migration. The report names each
-remote URL and tells you to add its spec to `public/`, then set the API source
-in `docs.json` to that local path. Missing local specs also produce warnings
+remote URL and tells you to add its spec to a project-root folder such as
+`openapi/`, then set the API source in `docs.json` to that path. Missing local
+specs also produce warnings
 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.
@@ -39,12 +47,20 @@ version first, then pages not listed in navigation, and one warning counts and
 names (the first three of) the pages left out and suggests `--docs-dir` to
 migrate a smaller part of the repository. Scanning itself stops after 100,000
 files with its own warning. Individual assets over 25 MB, or beyond 500 MB in
-total, are not copied and are warned about one by one.
+total, are not copied; one warning per reason gives the count, the first five
+paths, and the next step (copy them into `public/` manually).
 
 Headings written with an explicit `{#custom-id}` become a preceding
 `<a id="custom-id"></a>` anchor and keep their text, so links to that id still
 work and the page still compiles as MDX.
 
+Migrated specs are written to `openapi/`, never `public/`, because the host
+serves `public/` as-is and would publish operations marked `x-excluded` or
+`x-hidden`. Migrating into an existing site does not delete anything: an
+older copy of a spec already in `public/` stays publicly downloadable. The
+migration warns and lists such files, and `thally check` keeps flagging them;
+delete them manually.
+
 Docusaurus sidebars are parsed as bounded, data-only JSON5—never executed—and
 preserve explicit categories, autogenerated slices, document IDs/slugs,
 positions, generated indexes, admonitions, tabs, and `static/` assets where
@@ -167,6 +183,23 @@ the callback cannot be moved safely, it keeps the page and the control's child
 content as a passive fallback, with a warning identifying the control. A
 stateful local snippet component is kept as a client component instead of
 flattening away its hooks and state.
+A component a page declares itself (`export const Counter = () => ...`) that
+calls a React hook is moved into its own `'use client'` module, together with
+every page-local component, helper and constant it uses (a sibling it renders,
+a dependency that is itself stateful, a value only reached through a prop),
+in source order and under their original names. The imports that moved code
+needs move with it. What the page still renders stays reachable: a server-safe
+dependency the page also uses is kept in the page and copied, while a
+client-only one is imported from the module. A page-local name always wins
+over a same-named built-in. If any dependency cannot run in a client module
+(server-only APIs such as `process` or `await`, an undeclared name, a package
+the migration removed, a dynamic `import()`), the component is left where it
+is and a warning names it and the blocker.
+`<Snippet file="...">` accepts the documented `snippets/`-relative path as well
+as a `/snippets/...` or page-relative one. An outer code fence that contains a
+same-length nested fence is widened so the inner fence no longer closes it, and
+a bare placeholder tag in prose (`<Feature> requires a plan`) that would stop
+the page compiling is escaped as text rather than losing the page.
 The Mintlify `search-bar-entry` click trigger is mapped to Thally's search
 shortcut. Markdown mixed inside interactive JSX, computed imports, and
 namespace imports are reported for manual review; unsupported source is
@@ -228,18 +261,21 @@ dashboard's branding settings instead of leaving the loss silent.
 
 `cloneGitHubRepository` retries a transient network-class failure with
 backoff, and each underlying git process (the clone, and any submodule
-fetch) is killed and treated as a retryable failure if it stalls — a
-generous 10-minute default, configurable via
-`THALLY_MIGRATE_CLONE_TIMEOUT_MS` (milliseconds) for an unusually large
-repository on a slow link. The clone neutralizes the `filter.lfs.*`
+fetch) is killed and treated as a retryable failure if it stalls, meaning
+git prints no progress for 2 minutes (a large repository that is still
+downloading is never cut off; an hour is the absolute ceiling for one git
+process). The allowed silence is configurable via
+`THALLY_MIGRATE_CLONE_TIMEOUT_MS` (milliseconds) for an unusually slow link.
+The clone neutralizes the `filter.lfs.*`
 smudge/clean/process filter driver for that one process only (via
 `GIT_CONFIG_COUNT`/`GIT_CONFIG_KEY_n`/`GIT_CONFIG_VALUE_n`, never the user's
 global git config), so a repository that uses Git LFS still clones even when
 the host has no `git-lfs` binary installed — including a host where
 `filter.lfs.*` is still registered globally from a previous install,
 pointing at a command that no longer exists; an asset that's still a Git
-LFS pointer file afterward (not its real content) is skipped with a warning
-instead of being copied as if it were the real file. Submodules are
+LFS pointer file afterward (not its real content) is skipped, and one
+warning lists those files, instead of copying them as if they were the real
+files. Submodules are
 initialized one at a time, best-effort,
 after a successful clone — a submodule that can't be fetched (private,
 deleted, network trouble) is named in a warning instead of failing the

package/dist/index.d.ts

@@ -163,9 +163,11 @@ interface MigrationPage {
     frontmatterError?: string;
 }
 interface MigrationAsset {
-    /** Path below `public`, always normalized and traversal-free. */
+    /** Path below `public` (or below the project root when `projectRelative`), always normalized and traversal-free. */
     path: string;
     content: Uint8Array;
+    /** Write at the project root instead of `public/`, so the host never serves it statically. */
+    projectRelative?: boolean;
 }
 interface MigrationWarning {
     code: 'collision' | 'invalid-page' | 'missing-page' | 'unsupported-config' | 'limit-reached' | 'fetch-failed' | 'skipped-file';
@@ -182,6 +184,9 @@ interface MigrationBundle {
     remoteApiSpecs?: Array<{
         url: string;
         tabLabel?: string;
+        parentTab?: string;
+        icon?: string;
+        hidden?: boolean;
     }>;
     /** Customer-owned component source and registry; paths are repository-relative. */
     componentFiles?: Array<RenderedMigrationFile>;