@fern-api/fdr-sdk 1.2.35-8fa6be5a92 → 1.2.35-bc86801b51

package/dist/navigation/ledger-root-builder.js

@@ -1,906 +0,0 @@
-import * as FernNavigation from "./index.js";
-/** Zero-cost cast: trusts the transform pipeline wrote well-typed metadata. */
-const segMeta = (seg) => (seg.metadata ?? {});
-const routeMeta = (route) => (route.metadata ?? {});
-const detailMeta = (detail) => (detail.metadata ?? {});
-function createBuildContext(basePath) {
-    // Tracks how many times each id key has been handed out, so collisions get
-    // a deterministic `-N` suffix. NodeIds only need to be unique within a
-    // single tree; keying them off content (slug/scope) instead of a running
-    // counter makes them stable across builds — so client state keyed by
-    // node.id (e.g. playground form state in localStorage) survives republish
-    // as long as the node's slug/position is unchanged.
-    const seen = new Map();
-    // Nav `fullPath`s are stored relative to the docs root (no basepath);
-    // FernNavigation slugs include the basepath prefix, so content node slugs
-    // are joined onto this prefix.
-    const basePrefix = basePath.replace(/^\/+|\/+$/g, "");
-    return {
-        nodeId: (key) => {
-            const count = seen.get(key) ?? 0;
-            seen.set(key, count + 1);
-            return FernNavigation.NodeId(count === 0 ? key : `${key}-${count}`);
-        },
-        contentSlug: (relativePath) => {
-            const clean = relativePath.replace(/^\/+|\/+$/g, "");
-            return basePrefix === "" ? FernNavigation.Slug(clean) : FernNavigation.slugjoin(basePrefix, clean);
-        }
-    };
-}
-function asSlug(path) {
-    return FernNavigation.Slug(path.replace(/^\/+|\/+$/g, ""));
-}
-/** Map raw viewer role strings to branded RoleIds, or undefined when empty. */
-function toViewers(viewers) {
-    if (viewers == null || viewers.length === 0) {
-        return undefined;
-    }
-    return viewers.map((v) => FernNavigation.RoleId(v));
-}
-/**
- * Merge segment-level viewers with the owning variant's viewers so that
- * variant-level RBAC restrictions propagate into section/apiReference/changelog
- * nodes. Without this, removing the variant filter from `inScope` would allow
- * cross-variant prev/next links to disclose restricted content.
- */
-function mergeVariantViewers(seg) {
-    const all = [...(segMeta(seg).viewers ?? []), ...(seg.variant?.viewers ?? [])];
-    return all.length > 0 ? [...new Set(all)].map((v) => FernNavigation.RoleId(v)) : undefined;
-}
-function detailSlug(detail) {
-    return detailMeta(detail).slug ?? "";
-}
-function detailIsDefault(detail) {
-    return detailMeta(detail).default ?? false;
-}
-/** Resolve a detail's `pointsTo` into a basepath-prefixed slug, or undefined. */
-function pointsToSlug(ctx, meta) {
-    return meta.pointsTo != null ? ctx.contentSlug(meta.pointsTo) : undefined;
-}
-// ── scope grouping ───────────────────────────────────────────────────────
-/** Stable identity for a (product, version, variant, tab) scope. */
-function scopeKey(seg) {
-    return [seg.product?.id ?? "", seg.version?.id ?? "", seg.variant?.id ?? "", seg.tab?.id ?? ""].join("|");
-}
-// ── artifact → node conversion ─────────────────────────────────────────────
-function withMetadataDefaults(base) {
-    const { viewers, ...rest } = base;
-    return {
-        ...rest,
-        canonicalSlug: undefined,
-        authed: undefined,
-        collapsed: undefined,
-        // Normalise empty arrays to undefined so unrestricted nodes don't add
-        // filter-level noise; a non-empty array engages the RBAC view gate.
-        viewers: viewers != null && viewers.length > 0 ? viewers : undefined,
-        orphaned: undefined,
-        featureFlags: undefined
-    };
-}
-/**
- * Convert one sidebar nav artifact into a leaf navigation node. Returns
- * undefined for artifacts that don't become standalone sidebar nodes here
- * (endpoints live under paginated apiReferences; overview pages are folded
- * into their owning section).
- */
-function artifactToNode(ctx, route) {
-    const md = routeMeta(route);
-    const slug = ctx.contentSlug(route.fullPath ?? "");
-    switch (route.type) {
-        case "markdown": {
-            if (md.isOverview) {
-                return undefined;
-            }
-            return {
-                type: "page",
-                ...withMetadataDefaults({
-                    id: ctx.nodeId(`page:${slug}`),
-                    title: md.title ?? "",
-                    slug,
-                    icon: md.icon,
-                    hidden: route.hidden,
-                    viewers: toViewers(md.viewers)
-                }),
-                pageId: FernNavigation.PageId(md.pageId ?? ""),
-                noindex: md.noindex,
-                availability: undefined
-            };
-        }
-        case "link": {
-            return {
-                type: "link",
-                id: ctx.nodeId(`link:${md.url ?? route.fullPath ?? ""}`),
-                collapsed: undefined,
-                title: md.title ?? "",
-                icon: md.icon,
-                url: FernNavigation.Url(md.url ?? ""),
-                target: undefined
-            };
-        }
-        // API leaf types are handled by apiReferenceNode (which calls
-        // apiLeafNodeFromNavRouteInternal), not by section-level artifact
-        // conversion. Returning undefined here prevents them from appearing
-        // as duplicate siblings alongside the apiReference node.
-        default:
-            return undefined;
-    }
-}
-/**
- * Convert one API-leaf nav route into its navigation node, or undefined when
- * the route is not an API leaf carrying the required identifiers.
- *
- * @internal Exported for the ledger loader's scoped explorer methods.
- */
-export function apiLeafNodeFromNavRoute(route, basePath, segmentApiDefId) {
-    const ctx = createBuildContext(basePath);
-    return apiLeafNodeFromNavRouteInternal(ctx, route, segmentApiDefId);
-}
-function apiLeafNodeFromNavRouteInternal(ctx, route, segmentApiDefId) {
-    const md = routeMeta(route);
-    const slug = ctx.contentSlug(route.fullPath ?? "");
-    const base = {
-        ...withMetadataDefaults({
-            id: ctx.nodeId(`api-leaf:${slug}`),
-            title: md.title ?? "",
-            slug,
-            icon: md.icon,
-            hidden: route.hidden,
-            viewers: toViewers(md.viewers)
-        }),
-        apiDefinitionId: FernNavigation.ApiDefinitionId(md.apiDefinitionId ?? segmentApiDefId),
-        availability: undefined
-    };
-    switch (route.type) {
-        case "rest":
-            if (md.endpointId == null || md.method == null) {
-                return undefined;
-            }
-            return {
-                type: "endpoint",
-                ...base,
-                method: md.method,
-                endpointId: FernNavigation.EndpointId(md.endpointId),
-                isResponseStream: md.isResponseStream,
-                playground: undefined
-            };
-        case "webhook":
-            if (md.webhookId == null || md.method == null) {
-                return undefined;
-            }
-            return {
-                type: "webhook",
-                ...base,
-                method: md.method,
-                webhookId: FernNavigation.WebhookId(md.webhookId)
-            };
-        case "asyncapi":
-            if (md.webSocketId == null) {
-                return undefined;
-            }
-            return {
-                type: "webSocket",
-                ...base,
-                webSocketId: FernNavigation.WebSocketId(md.webSocketId),
-                playground: undefined
-            };
-        case "grpc":
-            if (md.grpcId == null || md.method == null) {
-                return undefined;
-            }
-            return {
-                type: "grpc",
-                ...base,
-                method: md.method,
-                grpcId: FernNavigation.GrpcId(md.grpcId)
-            };
-        case "graphql":
-            if (md.graphqlOperationId == null || md.operationType == null) {
-                return undefined;
-            }
-            return {
-                type: "graphql",
-                ...base,
-                operationType: md.operationType,
-                graphqlOperationId: FernNavigation.GraphQlOperationId(md.graphqlOperationId),
-                graphqlOperationIds: undefined,
-                playground: undefined
-            };
-        default:
-            return undefined;
-    }
-}
-/**
- * Collect every endpoint/webhook navigation node from a single API segment's
- * nav routes. The root builder now populates apiReference children directly,
- * but this helper is still used by the ledger loader's per-apiDefinitionId
- * explorer methods (getApiLeafNodes) which scope to a single API definition.
- *
- * @internal Exported for the ledger loader's scoped explorer methods.
- */
-export function collectApiLeafNodesFromNav(routes, basePath, segmentApiDefId) {
-    const ctx = createBuildContext(basePath);
-    return routes
-        .map((route) => apiLeafNodeFromNavRouteInternal(ctx, route, segmentApiDefId))
-        .filter((node) => node != null);
-}
-/** Read the apiDefinitionId off a segment's metadata, or undefined. */
-export function segmentApiDefinitionId(metadata) {
-    return metadata?.apiDefinitionId;
-}
-/** Find the overview artifact (isOverview) within a segment's nav, if any. */
-function overviewRoute(nav) {
-    for (const r of nav) {
-        if (r.type === "markdown") {
-            const meta = routeMeta(r);
-            if (meta.isOverview) {
-                return { route: r, meta };
-            }
-        }
-    }
-    return undefined;
-}
-function sectionNode(ctx, scoped, sectionChildren) {
-    const { seg, meta: sm, nav } = scoped;
-    const overview = overviewRoute(nav);
-    const overviewPageId = overview?.meta.pageId;
-    const slug = ctx.contentSlug(overview?.route.fullPath ?? seg.section);
-    const leafChildren = nav
-        .map((r) => artifactToNode(ctx, r))
-        .filter((n) => n != null);
-    const defaults = withMetadataDefaults({
-        id: ctx.nodeId(`section:${slug}`),
-        title: sm.title ?? "",
-        slug,
-        icon: sm.icon,
-        hidden: seg.hidden,
-        viewers: mergeVariantViewers(seg)
-    });
-    return {
-        type: "section",
-        ...defaults,
-        collapsed: sm.collapsed ?? defaults.collapsed,
-        overviewPageId: overviewPageId != null ? FernNavigation.PageId(overviewPageId) : undefined,
-        noindex: undefined,
-        collapsible: sm.collapsible,
-        collapsedByDefault: sm.collapsedByDefault,
-        availability: undefined,
-        pointsTo: undefined,
-        children: [...leafChildren, ...sectionChildren]
-    };
-}
-/** The immediate parent section path of a section path ("a/b/c" → "a/b", "a" → ""). */
-function parentSectionPath(sectionPath) {
-    const idx = sectionPath.lastIndexOf("/");
-    return idx === -1 ? "" : sectionPath.slice(0, idx);
-}
-/** Walk up the section path hierarchy to find the nearest ancestor that exists in the set. */
-function nearestExistingAncestor(sectionPath, existing) {
-    let current = parentSectionPath(sectionPath);
-    while (current !== "") {
-        if (existing.has(current)) {
-            return current;
-        }
-        current = parentSectionPath(current);
-    }
-    return "";
-}
-/**
- * Determine whether `sec` is a direct child of `parentPath`, accounting for
- * orphaned segments whose parent section doesn't exist but whose nearest
- * existing ancestor is `parentPath`.
- */
-function isDirectChildOf(sec, parentPath, sectionPaths) {
-    const parent = parentSectionPath(sec);
-    if (parent === parentPath) {
-        return true;
-    }
-    // Orphaned: parent doesn't exist, adopt if nearest ancestor is parentPath.
-    return !sectionPaths.has(parent) && nearestExistingAncestor(sec, sectionPaths) === parentPath;
-}
-/**
- * Find direct child apiPackage segments of `parentSection`. A direct child has
- * `parentSectionPath(seg.section) === parentSection`, or is an orphaned segment
- * whose nearest existing ancestor is `parentSection`.
- */
-function directChildApiPackages(parentSection, scopeSegs, sectionPaths) {
-    return scopeSegs
-        .filter((s) => s.meta.type === "apiPackage" && isDirectChildOf(s.seg.section, parentSection, sectionPaths))
-        .sort((a, b) => a.seg.sortOrder - b.seg.sortOrder);
-}
-/**
- * Build the children of an API section (apiReference or apiPackage) by combining
- * the segment's own leaf nodes with nested apiPackage children.
- */
-function buildApiChildren(ctx, scoped, scopeSegs, apiDefId, sectionPaths) {
-    const { nav } = scoped;
-    // Build leaf nodes from this segment's own nav routes (not descendants).
-    const rawLeafNodes = nav
-        .map((route) => apiLeafNodeFromNavRouteInternal(ctx, route, apiDefId))
-        .filter((node) => node != null);
-    // Merge stream/non-stream endpoint pairs into EndpointPairNodes.
-    const leafNodes = mergeEndpointPairs(ctx, rawLeafNodes, nav);
-    // Build nested ApiPackageNodes from direct child apiPackage segments.
-    const childPackages = directChildApiPackages(scoped.seg.section, scopeSegs, sectionPaths);
-    const packageNodes = childPackages.map((child) => apiPackageChildNode(ctx, child, scopeSegs, apiDefId, sectionPaths));
-    // Interleave: leaf nodes first (in their nav sort order), then package nodes
-    // (in their segment sort order). This matches v2's structure where direct
-    // artifacts precede sub-packages.
-    return [...leafNodes, ...packageNodes];
-}
-/**
- * Build an ApiPackageNode from an apiPackage segment, recursively nesting any
- * deeper sub-packages.
- */
-function apiPackageChildNode(ctx, scoped, scopeSegs, parentApiDefId, sectionPaths) {
-    const { seg, meta: sm, nav } = scoped;
-    const overview = overviewRoute(nav);
-    const overviewPageId = overview?.meta.pageId;
-    const apiDefId = sm.apiDefinitionId ?? parentApiDefId;
-    const slug = ctx.contentSlug(overview?.route.fullPath ?? nav[0]?.fullPath ?? seg.section);
-    const children = buildApiChildren(ctx, scoped, scopeSegs, apiDefId, sectionPaths);
-    return {
-        type: "apiPackage",
-        ...withMetadataDefaults({
-            id: ctx.nodeId(`api-pkg:${slug}`),
-            title: sm.title ?? "",
-            slug,
-            icon: sm.icon,
-            hidden: seg.hidden,
-            viewers: toViewers(sm.viewers)
-        }),
-        apiDefinitionId: FernNavigation.ApiDefinitionId(apiDefId),
-        availability: sm.availability,
-        overviewPageId: overviewPageId != null ? FernNavigation.PageId(overviewPageId) : undefined,
-        noindex: undefined,
-        pointsTo: undefined,
-        children,
-        playground: undefined
-    };
-}
-/**
- * Merge endpoint nodes that were originally part of an `endpointPair` in the V1
- * tree. The publish transform stamps both artifacts with a shared
- * `endpointPairKey` in their route metadata; this function groups endpoints by
- * that key and reconstructs `EndpointPairNode`s — matching the v2 nav tree
- * structure where stream/non-stream variants share a single page with a toggle.
- */
-function mergeEndpointPairs(ctx, leafNodes, allNav) {
-    // Build a lookup from endpointId → endpointPairKey using route metadata.
-    // Only REST routes carry `endpointPairKey`.
-    const endpointIdToPairKey = new Map();
-    for (const route of allNav) {
-        if (route.type !== "rest") {
-            continue;
-        }
-        const md = routeMeta(route);
-        if (md.endpointPairKey != null && md.endpointId != null) {
-            endpointIdToPairKey.set(md.endpointId, md.endpointPairKey);
-        }
-    }
-    // If no pair keys exist (pre-existing data without the key), return as-is.
-    if (endpointIdToPairKey.size === 0) {
-        return leafNodes;
-    }
-    const result = [];
-    // Track which pair keys we've already merged so we only emit the pair once.
-    const mergedPairKeys = new Map();
-    for (const node of leafNodes) {
-        if (node.type !== "endpoint") {
-            result.push(node);
-            continue;
-        }
-        const pairKey = endpointIdToPairKey.get(String(node.endpointId));
-        if (pairKey == null) {
-            result.push(node);
-            continue;
-        }
-        const existingIdx = mergedPairKeys.get(pairKey);
-        if (existingIdx == null) {
-            // First endpoint of the pair — push it and record its position.
-            mergedPairKeys.set(pairKey, result.length);
-            result.push(node);
-        }
-        else {
-            // Second endpoint — merge with the first into an EndpointPairNode.
-            const first = result[existingIdx];
-            if (first == null || first.type !== "endpoint") {
-                result.push(node);
-                continue;
-            }
-            // Determine which is stream and which is non-stream.
-            const stream = node.isResponseStream ? node : first;
-            const nonStream = node.isResponseStream ? first : node;
-            const pairNode = {
-                id: ctx.nodeId(`endpoint-pair:${pairKey}`),
-                type: "endpointPair",
-                collapsed: undefined,
-                stream,
-                nonStream
-            };
-            result[existingIdx] = pairNode;
-        }
-    }
-    return result;
-}
-function apiReferenceNode(ctx, scoped, scopeSegs, sectionPaths) {
-    const { seg, meta: sm, nav } = scoped;
-    const overview = overviewRoute(nav);
-    const overviewPageId = overview?.meta.pageId;
-    const apiDefId = sm.apiDefinitionId ?? "";
-    const slug = ctx.contentSlug(overview?.route.fullPath ?? nav[0]?.fullPath ?? seg.section);
-    const children = buildApiChildren(ctx, scoped, scopeSegs, apiDefId, sectionPaths);
-    return {
-        type: "apiReference",
-        ...withMetadataDefaults({
-            id: ctx.nodeId(`api:${slug}`),
-            title: sm.title ?? "",
-            slug,
-            icon: sm.icon,
-            hidden: seg.hidden,
-            viewers: mergeVariantViewers(seg)
-        }),
-        apiDefinitionId: FernNavigation.ApiDefinitionId(apiDefId),
-        availability: undefined,
-        overviewPageId: overviewPageId != null ? FernNavigation.PageId(overviewPageId) : undefined,
-        noindex: undefined,
-        paginated: true,
-        showErrors: sm.showErrors,
-        hideTitle: sm.hideTitle,
-        pointsTo: undefined,
-        children,
-        changelog: undefined,
-        playground: undefined,
-        postmanCollectionUrl: undefined
-    };
-}
-function changelogNode(ctx, scoped) {
-    const { seg, meta: sm, nav } = scoped;
-    const overview = overviewRoute(nav);
-    const overviewPageId = overview?.meta.pageId;
-    // Group changelog entries by year → month. Entry dates are ISO strings.
-    const entries = nav.filter((r) => r.type === "changelog");
-    const byYear = new Map();
-    for (const r of entries) {
-        const md = routeMeta(r);
-        const date = md.date != null ? new Date(md.date) : new Date(0);
-        const year = date.getUTCFullYear();
-        const month = date.getUTCMonth() + 1;
-        const entry = {
-            type: "changelogEntry",
-            ...withMetadataDefaults({
-                id: ctx.nodeId(`cl-entry:${r.fullPath ?? md.pageId ?? ""}`),
-                title: md.title ?? "",
-                slug: ctx.contentSlug(r.fullPath ?? ""),
-                icon: md.icon,
-                hidden: r.hidden,
-                viewers: toViewers(md.viewers)
-            }),
-            pageId: FernNavigation.PageId(md.pageId ?? ""),
-            noindex: undefined,
-            date: md.date ?? "",
-            tags: undefined
-        };
-        let months = byYear.get(year);
-        if (months == null) {
-            months = new Map();
-            byYear.set(year, months);
-        }
-        const arr = months.get(month) ?? [];
-        arr.push(entry);
-        months.set(month, arr);
-    }
-    const baseSlug = ctx.contentSlug(overview?.route.fullPath ?? seg.section);
-    const years = [...byYear.entries()]
-        .sort((a, b) => b[0] - a[0])
-        .map(([year, months]) => ({
-        type: "changelogYear",
-        ...withMetadataDefaults({
-            id: ctx.nodeId(`cl-year:${baseSlug}/${year}`),
-            title: String(year),
-            slug: asSlug(`${baseSlug}/${year}`),
-            icon: undefined,
-            hidden: undefined
-        }),
-        year,
-        children: [...months.entries()]
-            .sort((a, b) => b[0] - a[0])
-            .map(([month, children]) => ({
-            type: "changelogMonth",
-            ...withMetadataDefaults({
-                id: ctx.nodeId(`cl-month:${baseSlug}/${year}/${month}`),
-                title: String(month),
-                slug: asSlug(`${baseSlug}/${year}/${month}`),
-                icon: undefined,
-                hidden: undefined
-            }),
-            month,
-            children
-        }))
-    }));
-    return {
-        type: "changelog",
-        ...withMetadataDefaults({
-            id: ctx.nodeId(`changelog:${baseSlug}`),
-            title: sm.title ?? "",
-            slug: baseSlug,
-            icon: sm.icon,
-            hidden: seg.hidden,
-            viewers: mergeVariantViewers(seg)
-        }),
-        overviewPageId: overviewPageId != null ? FernNavigation.PageId(overviewPageId) : undefined,
-        noindex: undefined,
-        children: years
-    };
-}
-/**
- * Build the section/api/changelog nodes whose immediate parent is `parentPath`,
- * recursing into nested sections. Also picks up orphaned segments whose parent
- * section doesn't exist but whose nearest existing ancestor is `parentPath`.
- */
-function buildSectionTree(ctx, scopeSegs, parentPath, sectionPaths) {
-    const direct = scopeSegs
-        .filter((s) => {
-        const sec = s.seg.section;
-        return sec !== "" && s.meta.type !== "tabRoot" && isDirectChildOf(sec, parentPath, sectionPaths);
-    })
-        .sort((a, b) => a.seg.sortOrder - b.seg.sortOrder);
-    return direct.map((s) => {
-        const { type } = s.meta;
-        if (type === "apiReference" || type === "apiPackage") {
-            return apiReferenceNode(ctx, s, scopeSegs, sectionPaths);
-        }
-        if (type === "changelog") {
-            return changelogNode(ctx, s);
-        }
-        // section (or unrecognised) → recurse for nested sections.
-        return sectionNode(ctx, s, buildSectionTree(ctx, scopeSegs, s.seg.section, sectionPaths));
-    });
-}
-// ── build a sidebarRoot for a single scope ─────────────────────────────────
-/**
- * Assemble the children of a scope's sidebar root in cross-segment order.
- * `tabRoot` segments contribute their page/link artifacts inline at their
- * sort position; depth-0 `section`/`apiReference`/`changelog` segments become
- * their own nodes (with nested sections attached recursively).
- *
- * Segments whose parent section path doesn't correspond to any existing
- * segment are "orphaned" and emitted at the top level. This happens when
- * the publish transform skips segment creation for an apiReference with no
- * direct artifacts (e.g. no overview page), leaving only apiPackage children
- * like `rest-api/store` with no `rest-api` parent segment.
- */
-function buildSidebarRootChildren(ctx, scopeSegs) {
-    const ordered = [...scopeSegs].sort((a, b) => a.seg.sortOrder - b.seg.sortOrder);
-    const sectionPaths = new Set(ordered.map((s) => s.seg.section));
-    const flat = [];
-    for (const s of ordered) {
-        const { type } = s.meta;
-        const sec = s.seg.section;
-        if (type === "tabRoot" || sec === "") {
-            // Top-level pages/links of this sidebar root, in nav order.
-            for (const r of s.nav) {
-                const node = artifactToNode(ctx, r);
-                if (node != null) {
-                    flat.push(node);
-                }
-            }
-            continue;
-        }
-        // Emit segments at root level if they are depth-0 OR orphaned (nearest
-        // existing ancestor is root ""). Deeper segments with existing parents
-        // are attached via buildSectionTree recursion.
-        if (isDirectChildOf(sec, "", sectionPaths)) {
-            if (type === "apiReference" || type === "apiPackage") {
-                flat.push(apiReferenceNode(ctx, s, scopeSegs, sectionPaths));
-            }
-            else if (type === "changelog") {
-                flat.push(changelogNode(ctx, s));
-            }
-            else {
-                flat.push(sectionNode(ctx, s, buildSectionTree(ctx, scopeSegs, sec, sectionPaths)));
-            }
-        }
-    }
-    return groupSidebarRootChildren(ctx, flat);
-}
-/**
- * `SidebarRootChild` only permits SidebarGroupNode / ApiReferenceNode /
- * SectionNode / VariantedNode.  Non-collapsible sections and apiReferences
- * pass through as direct root children (rendered as static headings);
- * collapsible sections, pages, links, and changelogs are wrapped into a
- * SidebarGroupNode so they render via SidebarNavigationChild → collapsible
- * (mirroring the V1→latest migration in NavigationConfigConverter).
- */
-function groupSidebarRootChildren(ctx, children) {
-    const out = [];
-    let run = [];
-    const flushRun = () => {
-        if (run.length > 0) {
-            // Key off the first child's (already-stable) id so the group id is
-            // stable across builds and unique per run.
-            out.push({
-                type: "sidebarGroup",
-                id: ctx.nodeId(`sidebar-group:${run[0]?.id ?? ""}`),
-                collapsed: undefined,
-                children: run
-            });
-            run = [];
-        }
-    };
-    for (const child of children) {
-        if (child.type === "apiReference" || child.type === "varianted") {
-            flushRun();
-            out.push(child);
-        }
-        else if (child.type === "section" &&
-            (child.collapsible === false || (child.collapsible == null && child.collapsed === false))) {
-            // Match SidebarVariantedNode's isStaticHeader logic: a section
-            // is a static root heading only when explicitly non-collapsible
-            // or when collapsible is unset and collapsed is explicitly false.
-            flushRun();
-            out.push(child);
-        }
-        else {
-            run.push(child);
-        }
-    }
-    flushRun();
-    return out;
-}
-function buildSidebarRoot(ctx, scopeSegs) {
-    const first = scopeSegs[0];
-    return {
-        type: "sidebarRoot",
-        id: ctx.nodeId(`sidebar:${first != null ? scopeKey(first.seg) : "root"}`),
-        collapsed: undefined,
-        children: buildSidebarRootChildren(ctx, scopeSegs)
-    };
-}
-// ── public entrypoint ───────────────────────────────────────────────────────
-/**
- * Build a full (un-pruned) `RootNode` from the decomposed ledger model.
- */
-export function buildFullRootFromSegments(options) {
-    const { basePath, title, segments, navBySegment } = options;
-    // Per-call state — never shared across concurrent builds.
-    const ctx = createBuildContext(basePath);
-    const scoped = segments
-        .map((seg) => ({ seg, meta: segMeta(seg), nav: navBySegment.get(seg.segmentHash) ?? [] }))
-        // Infrastructure segments (files/redirects) are filtered server-side, but guard here too.
-        .filter((s) => s.meta.type !== "files" && s.meta.type !== "redirects");
-    const rootSlug = asSlug(basePath);
-    // Group by scope identity.
-    const scopesByKey = new Map();
-    for (const s of scoped) {
-        const key = scopeKey(s.seg);
-        const arr = scopesByKey.get(key) ?? [];
-        arr.push(s);
-        scopesByKey.set(key, arr);
-    }
-    const products = uniqueDetails(scoped, "product");
-    const versions = uniqueDetails(scoped, "version");
-    const tabs = uniqueDetails(scoped, "tab");
-    let child;
-    if (products.length > 0) {
-        child = buildProductGroup(ctx, products, scoped, rootSlug);
-    }
-    else if (versions.length > 0) {
-        child = buildVersioned(ctx, versions, scoped, rootSlug, undefined);
-    }
-    else {
-        child = buildUnversioned(ctx, scoped, tabs.length > 0);
-    }
-    // Derive root.pointsTo from the default child's metadata so root-slug
-    // visits redirect correctly even when mutableUpdatePointsTo is skipped
-    // (structure-only roots).  On the full root mutableUpdatePointsTo
-    // recomputes this via tree traversal; this seed value is only visible
-    // on structure-only roots where the traversal is intentionally skipped.
-    let rootPointsTo;
-    if (child.type === "productgroup") {
-        const defaultProduct = child.children.find((p) => p.default) ?? child.children[0];
-        rootPointsTo = defaultProduct?.type === "product" ? defaultProduct.pointsTo : undefined;
-    }
-    else if (child.type === "versioned") {
-        const defaultVersion = child.children.find((v) => v.default) ?? child.children[0];
-        rootPointsTo = defaultVersion?.pointsTo;
-    }
-    return {
-        type: "root",
-        version: "v2",
-        ...withMetadataDefaults({
-            id: ctx.nodeId("root"),
-            title,
-            slug: rootSlug,
-            icon: undefined,
-            hidden: undefined
-        }),
-        roles: undefined,
-        pointsTo: rootPointsTo,
-        child
-    };
-}
-// ── scaffolding builders ────────────────────────────────────────────────────
-/**
- * Collapse segment details by logical slug identity (not DB id).
- * Old publishes can leave stale detail rows that share the same slug
- * but lack metadata fields (e.g. `pointsTo`). When duplicates exist
- * we prefer the detail with the most complete metadata.
- */
-function uniqueDetails(scoped, dim) {
-    const bySlug = new Map();
-    for (const s of scoped) {
-        const d = s.seg[dim];
-        if (d == null) {
-            continue;
-        }
-        const dm = detailMeta(d);
-        const slug = dm.slug ?? "";
-        const existing = bySlug.get(slug);
-        if (existing == null || (dm.pointsTo != null && existing.meta.pointsTo == null)) {
-            bySlug.set(slug, { detail: d, meta: dm });
-        }
-    }
-    return [...bySlug.values()].map((e) => e.detail).sort((a, b) => a.sortOrder - b.sortOrder);
-}
-function scopeSlugPrefix(rootSlug, ...details) {
-    const parts = [rootSlug];
-    for (const d of details) {
-        if (d != null && !detailIsDefault(d)) {
-            const s = detailSlug(d);
-            if (s !== "") {
-                parts.push(s);
-            }
-        }
-    }
-    return FernNavigation.slugjoin(...parts);
-}
-function buildTabbedOrSidebar(ctx, scopeSegs, tabsPresent) {
-    if (!tabsPresent) {
-        return buildSidebarRoot(ctx, scopeSegs);
-    }
-    // Group this scope's segments by tab.
-    const tabDetails = uniqueDetails(scopeSegs, "tab");
-    const children = tabDetails.map((tab) => {
-        const tm = detailMeta(tab);
-        const tabSlug = asSlug(scopeSlugPrefix(FernNavigation.Slug(""), tab));
-        if (tm.tab_type === "link") {
-            return {
-                type: "link",
-                id: ctx.nodeId(`link:${tm.url ?? tabSlug}`),
-                collapsed: undefined,
-                title: tab.displayName,
-                icon: tab.icon ?? undefined,
-                url: FernNavigation.Url(tm.url ?? ""),
-                target: undefined
-            };
-        }
-        if (tm.tab_type === "changelog") {
-            const tabSegs = scopeSegs.filter((s) => s.seg.tab?.id === tab.id);
-            const changelogSeg = tabSegs.find((s) => s.meta.type === "changelog");
-            if (changelogSeg != null) {
-                return changelogNode(ctx, changelogSeg);
-            }
-            // Fallback: empty changelog node for the tab
-            return {
-                type: "changelog",
-                ...withMetadataDefaults({
-                    id: ctx.nodeId(`changelog:${tabSlug}`),
-                    title: tab.displayName,
-                    slug: tabSlug,
-                    icon: tab.icon ?? undefined,
-                    hidden: tab.hidden,
-                    viewers: toViewers(tab.viewers)
-                }),
-                overviewPageId: undefined,
-                noindex: undefined,
-                children: []
-            };
-        }
-        // Default: regular tab
-        const tabSegs = scopeSegs.filter((s) => s.seg.tab?.id === tab.id);
-        return {
-            type: "tab",
-            ...withMetadataDefaults({
-                id: ctx.nodeId(`tab:${tabSlug}`),
-                title: tab.displayName,
-                slug: tabSlug,
-                icon: tab.icon ?? undefined,
-                hidden: tab.hidden,
-                viewers: toViewers(tab.viewers)
-            }),
-            pointsTo: pointsToSlug(ctx, tm),
-            child: buildSidebarRoot(ctx, tabSegs)
-        };
-    });
-    const first = scopeSegs[0];
-    return {
-        type: "tabbed",
-        id: ctx.nodeId(`tabbed:${first != null ? scopeKey(first.seg) : "root"}`),
-        collapsed: undefined,
-        children
-    };
-}
-function buildUnversioned(ctx, scopeSegs, tabsPresent) {
-    const first = scopeSegs[0];
-    return {
-        type: "unversioned",
-        id: ctx.nodeId(`unversioned:${first?.seg.product?.id ?? "root"}`),
-        collapsed: undefined,
-        landingPage: undefined,
-        child: buildTabbedOrSidebar(ctx, scopeSegs, tabsPresent)
-    };
-}
-function buildVersioned(ctx, versions, scoped, rootSlug, productPrefix) {
-    const children = versions.map((version) => {
-        const vm = detailMeta(version);
-        const versionSegs = scoped.filter((s) => s.seg.version?.id === version.id);
-        const tabsPresent = uniqueDetails(versionSegs, "tab").length > 0;
-        const prefix = productPrefix ?? rootSlug;
-        const slug = vm.default ? prefix : scopeSlugPrefix(rootSlug, version);
-        return {
-            type: "version",
-            ...withMetadataDefaults({
-                id: ctx.nodeId(`version:${slug}`),
-                title: version.displayName,
-                slug: asSlug(slug),
-                icon: version.icon ?? undefined,
-                hidden: version.hidden,
-                viewers: toViewers(version.viewers)
-            }),
-            default: vm.default ?? false,
-            versionId: FernNavigation.VersionId(version.id),
-            availability: undefined,
-            landingPage: undefined,
-            announcement: undefined,
-            pointsTo: pointsToSlug(ctx, vm),
-            child: buildTabbedOrSidebar(ctx, versionSegs, tabsPresent)
-        };
-    });
-    return {
-        type: "versioned",
-        id: ctx.nodeId(`versioned:${productPrefix ?? "root"}`),
-        collapsed: undefined,
-        children
-    };
-}
-function buildProductGroup(ctx, products, scoped, rootSlug) {
-    const children = products.map((product) => {
-        const pm = detailMeta(product);
-        const productSegs = scoped.filter((s) => s.seg.product?.id === product.id);
-        const versions = uniqueDetails(productSegs, "version");
-        const tabsPresent = uniqueDetails(productSegs, "tab").length > 0;
-        const productPrefix = scopeSlugPrefix(rootSlug, product);
-        // ProductChild is VersionedNode | UnversionedNode — a version-less
-        // product wraps its sidebar/tabs in an UnversionedNode.
-        const productChild = versions.length > 0
-            ? buildVersioned(ctx, versions, productSegs, rootSlug, productPrefix)
-            : buildUnversioned(ctx, productSegs, tabsPresent);
-        return {
-            type: "product",
-            ...withMetadataDefaults({
-                id: ctx.nodeId(`product:${productPrefix}`),
-                title: product.displayName,
-                slug: asSlug(detailIsDefault(product) ? rootSlug : productPrefix),
-                icon: product.icon ?? undefined,
-                hidden: product.hidden,
-                viewers: toViewers(product.viewers)
-            }),
-            default: detailIsDefault(product),
-            productId: FernNavigation.ProductId(product.id),
-            subtitle: pm.subtitle ?? "",
-            image: undefined,
-            announcement: undefined,
-            pointsTo: pointsToSlug(ctx, pm),
-            child: productChild
-        };
-    });
-    return {
-        type: "productgroup",
-        id: ctx.nodeId("productgroup"),
-        collapsed: undefined,
-        landingPage: undefined,
-        children
-    };
-}
-// (root keeps the bare "root" id; it is the single tree root.)
-//# sourceMappingURL=ledger-root-builder.js.map