@thallylabs/migrate 0.2.32 → 0.2.34

package/README.md

@@ -81,18 +81,25 @@ 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 a project-root folder such as
-`openapi/`, then set the API source in `docs.json` to that path. Missing local
-specs also produce warnings
+kept as separate files in `openapi/`. A remote `https://` spec is not
+downloaded by `migrateRepository`; the bundle lists it and warns, and
+`hydrateRemoteApiSpecs` (which `create-thally-docs migrate` runs after the
+conversion) downloads it from a public host, up to 25 MB, saves it as `.json`
+or `.yaml` by its content rather than its URL, and binds it to its tab. A
+download that fails leaves a warning naming the URL. An `http://` spec is never
+imported. 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.
 
 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
+spec lands in the output (`/openapi-b.yaml GET /widgets/{id}`). As in Mintlify,
+the prefix may name the spec by path, by file name, or by file name without its
+extension (`v3-openapi GET /tasks`); a name that fits more than one spec is kept
+and reported with its candidates. A declared spec that a published page names
+but that cannot be its tab's spec is bound through a hidden tab, so the page
+still renders its endpoint. 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.
@@ -100,9 +107,53 @@ 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
-lists the affected links (up to ten). A Mintlify default version's pages also
-get a redirect from their address without the version segment, since the
-original site serves them both ways.
+lists the affected links (up to ten). A link to an address the site answers
+itself (a guide authored inside an API directory, trailing slash or `/index` or
+not, or the source of an authored redirect) is never rewritten. A spec that
+Mintlify mounted under a `directory` also gets a redirect from each endpoint URL that directory served,
+to the matching endpoint page, and never to an operation the published spec
+withholds with `x-hidden` or `x-excluded`. A remote spec gets every directory
+each of its tabs mounted it under, limited to the operations the navigation
+listed under a directory when it listed any. A local spec gets one directory
+per tab (the first) and every operation of the spec. When directories nest
+(`reference` and `reference/v2`), an address belongs to the longest directory it
+lies under, whether the specs are local or remote: the shorter one never
+rewrites a link to it or redirects it. When a site has a remote spec, links and
+endpoint redirects under every directory are generated by
+`hydrateRemoteApiSpecs` once all specs are bound (a tab's position decides the
+id its spec is served under), so they stay as authored until then. A remote
+directory whose download failed still owns the addresses under it: they stay as
+authored, never rewritten or redirected. A link under any
+directory reaches only that directory's own endpoint URLs; a link under none is
+redirected by its last two segments (tag and summary) only when exactly one
+published operation across every spec carries them, to the id its spec is
+served under. A Mintlify default version's pages also get a redirect from their
+address without the version segment, since the original site serves them both
+ways.
+
+Redirects are checked once, after every platform and step has added its own.
+Next.js applies a redirect before it looks for a page and compares a source
+without regard to a trailing slash, so a redirect whose source is a page of the
+migrated site would hide that page, and two redirects that send a visit back to
+each other never settle. Each such redirect is left out, and a warning
+lists the first ten of each kind; the earlier redirect of a loop is kept. A
+generated redirect (a version alias, an endpoint URL) for an address that
+already serves a page is left out without a warning, since the page is still
+reachable there. These checks ignore letter case, because a site can run on
+`next start`, which matches a redirect source without regard to case, or on the
+Cloudflare build, which matches it exactly, and a redirect must be safe on
+both. So `/Guide` to `/guide` is left out when `guide` is a page (it would loop
+and hide the page where case is ignored), `/a` to `/B` together with `/b` to
+`/A` is a loop whose second redirect is left out, and a generated redirect
+whose address differs from a page only in case is never created. When letter
+case alone is the conflict, the warning names each redirect left out (the
+first ten), says that its address differs only in letter case from a page or
+another redirect, and says to add it back to `docs.json` if your host matches
+URLs case-sensitively. Next.js reads a redirect source as a route pattern, so one
+whose address has a `+ ? ( ) [ ] { }` character (a `directory` such as
+`sdk/c++`) would fail the build; every redirect from authored config, a local
+spec or a downloaded spec is left out instead, and one warning lists the first
+ten of them.
 
 A repository is limited to 5,000 documentation files and, separately, 5,000
 asset files. Past that, files are kept in navigation order with the default

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { M as MigrationPage, a as MigrationAsset, b as MigrationNavigationGroup, R as RenderedMigrationFile, c as MigrationWarning, d as MigrationFetcher, e as MigrationPlatform, f as MigrationBundle, g as MigrationDocsConfig } from './url-migration-Coy62q1L.js';
-export { h as MigrationCapture, i as MigrationCaptureProvider, j as MigrationCaptureState, k as MigrationCapturedAsset, l as MigrationEvidence, m as MigrationFetchRequest, n as MigrationFetchResponse, o as MigrationJournalAsset, p as MigrationNavigationOccurrence, q as MigrationNavigationTab, U as UrlMigrationCheckpoint, r as UrlMigrationCheckpointDelta, s as UrlMigrationIssue, t as UrlMigrationRecord, u as UrlMigrationRun, v as UrlMigrationRunOptions, w as UrlMigrationValidation, x as classifyMigrationResponse, y as mergeMigrationConfig, z as renderMigrationFiles, A as runUrlMigration, B as validateUrlMigration } from './url-migration-Coy62q1L.js';
+import { M as MigrationPage, a as MigrationAsset, b as MigrationNavigationGroup, R as RenderedMigrationFile, c as MigrationWarning, d as MigrationFetcher, e as MigrationPlatform, f as MigrationBundle, g as MigrationDocsConfig } from './url-migration-EwtII4P-.js';
+export { h as MigrationCapture, i as MigrationCaptureProvider, j as MigrationCaptureState, k as MigrationCapturedAsset, l as MigrationEvidence, m as MigrationFetchRequest, n as MigrationFetchResponse, o as MigrationJournalAsset, p as MigrationNavigationOccurrence, q as MigrationNavigationTab, U as UrlMigrationCheckpoint, r as UrlMigrationCheckpointDelta, s as UrlMigrationIssue, t as UrlMigrationRecord, u as UrlMigrationRun, v as UrlMigrationRunOptions, w as UrlMigrationValidation, x as classifyMigrationResponse, y as mergeMigrationConfig, z as renderMigrationFiles, A as runUrlMigration, B as validateUrlMigration } from './url-migration-EwtII4P-.js';
 export { isPassiveSvg } from './svg-policy.js';
 
 /**
@@ -344,9 +344,17 @@ declare const defaultMigrationFetcher: MigrationFetcher;
 declare function migrateUrl(options: UrlMigrationOptions): Promise<MigrationBundle>;
 
 /**
- * Attach safely downloaded specs to the exact authored API tabs. Source links
- * to Mintlify's tag/summary routes receive redirects only when an operation
- * can be identified uniquely; guessing would silently route to wrong APIs.
+ * Attach safely downloaded specs to the exact authored API tabs. A spec
+ * mounted under Mintlify `directory` folders gets a redirect from each
+ * endpoint URL those folders served, and a link under a mount (this bundle's
+ * or any other's) reaches nothing else. A link no mount covers is redirected by
+ * its tag and summary only when exactly one published operation across every
+ * spec carries them, to the id its spec is served under: guessing would
+ * silently route to the wrong API. A redirect never takes the place of a page
+ * the site serves. Every spec is bound before any link is read, so mounts
+ * nested in one another (`reference` and `reference/v2`) are told apart by
+ * their longest prefix, and the repository's own mounts are linked here too:
+ * a tab's position decides the id its spec is served under.
  */
 declare function hydrateRemoteApiSpecs(bundle: MigrationBundle, fetcher?: MigrationFetcher): Promise<MigrationBundle>;