@fern-api/fdr-sdk 1.2.20-f9ee39a42e → 1.2.21-fd4e3f344c

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

@@ -1,871 +0,0 @@
-import * as FernNavigation from "./index.js";
-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, ""));
-}
-/** Read a string field off an unknown metadata blob. */
-function metaStr(metadata, key) {
-    if (metadata != null && typeof metadata === "object" && key in metadata) {
-        const v = metadata[key];
-        return typeof v === "string" ? v : undefined;
-    }
-    return undefined;
-}
-function metaBool(metadata, key) {
-    if (metadata != null && typeof metadata === "object" && key in metadata) {
-        const v = metadata[key];
-        return typeof v === "boolean" ? v : undefined;
-    }
-    return undefined;
-}
-/** Read the `collapsed` field which can be boolean or "open-by-default". */
-function metaCollapsed(metadata) {
-    if (metadata != null && typeof metadata === "object" && "collapsed" in metadata) {
-        const v = metadata.collapsed;
-        if (typeof v === "boolean") {
-            return v;
-        }
-        if (v === "open-by-default") {
-            return "open-by-default";
-        }
-    }
-    return undefined;
-}
-/** Extract a string array from a metadata blob (e.g. page-level `viewers`). */
-function metaStrArr(metadata, key) {
-    if (metadata != null && typeof metadata === "object" && key in metadata) {
-        const v = metadata[key];
-        if (Array.isArray(v)) {
-            return v.filter((x) => typeof x === "string");
-        }
-    }
-    return undefined;
-}
-/** 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));
-}
-function detailSlug(detail) {
-    return metaStr(detail.metadata, "slug") ?? "";
-}
-function detailIsDefault(detail) {
-    return metaBool(detail.metadata, "default") ?? false;
-}
-// ── 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 = route.metadata;
-    const title = metaStr(md, "title") ?? "";
-    const icon = metaStr(md, "icon");
-    const viewers = toViewers(metaStrArr(md, "viewers"));
-    const slug = ctx.contentSlug(route.fullPath ?? "");
-    switch (route.type) {
-        case "markdown": {
-            // Overview pages are represented on their section, not as a sibling.
-            if (metaBool(md, "isOverview")) {
-                return undefined;
-            }
-            const pageId = metaStr(md, "pageId") ?? "";
-            const node = {
-                type: "page",
-                ...withMetadataDefaults({
-                    id: ctx.nodeId(`page:${slug}`),
-                    title,
-                    slug,
-                    icon,
-                    hidden: route.hidden,
-                    viewers
-                }),
-                pageId: FernNavigation.PageId(pageId),
-                noindex: metaBool(md, "noindex"),
-                availability: undefined
-            };
-            return node;
-        }
-        case "link": {
-            const node = {
-                type: "link",
-                id: ctx.nodeId(`link:${metaStr(md, "url") ?? route.fullPath ?? ""}`),
-                collapsed: undefined,
-                title,
-                icon,
-                url: FernNavigation.Url(metaStr(md, "url") ?? ""),
-                target: undefined
-            };
-            return node;
-        }
-        // 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.
-        case "rest":
-        case "asyncapi":
-        case "webhook":
-        case "grpc":
-        case "graphql":
-            return undefined;
-        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, segmentApiDefinitionId) {
-    const ctx = createBuildContext(basePath);
-    return apiLeafNodeFromNavRouteInternal(ctx, route, segmentApiDefinitionId);
-}
-function apiLeafNodeFromNavRouteInternal(ctx, route, segmentApiDefinitionId) {
-    const md = route.metadata;
-    const apiDefinitionId = FernNavigation.ApiDefinitionId(metaStr(md, "apiDefinitionId") ?? segmentApiDefinitionId);
-    const slug = ctx.contentSlug(route.fullPath ?? "");
-    const title = metaStr(md, "title") ?? "";
-    const icon = metaStr(md, "icon");
-    const viewers = toViewers(metaStrArr(md, "viewers"));
-    const meta = withMetadataDefaults({
-        id: ctx.nodeId(`api-leaf:${slug}`),
-        title,
-        slug,
-        icon,
-        hidden: route.hidden,
-        viewers
-    });
-    if (route.type === "rest") {
-        const endpointId = metaStr(md, "endpointId");
-        const method = metaStr(md, "method");
-        if (endpointId == null || method == null) {
-            return undefined;
-        }
-        return {
-            type: "endpoint",
-            ...meta,
-            method: method,
-            endpointId: FernNavigation.EndpointId(endpointId),
-            apiDefinitionId,
-            isResponseStream: metaBool(md, "isResponseStream"),
-            availability: undefined,
-            playground: undefined
-        };
-    }
-    if (route.type === "webhook") {
-        const webhookId = metaStr(md, "webhookId");
-        const method = metaStr(md, "method");
-        if (webhookId == null || method == null) {
-            return undefined;
-        }
-        return {
-            type: "webhook",
-            ...meta,
-            method: method,
-            webhookId: FernNavigation.WebhookId(webhookId),
-            apiDefinitionId,
-            availability: undefined
-        };
-    }
-    if (route.type === "asyncapi") {
-        const webSocketId = metaStr(md, "webSocketId");
-        if (webSocketId == null) {
-            return undefined;
-        }
-        return {
-            type: "webSocket",
-            ...meta,
-            webSocketId: FernNavigation.WebSocketId(webSocketId),
-            apiDefinitionId,
-            availability: undefined,
-            playground: undefined
-        };
-    }
-    if (route.type === "grpc") {
-        const grpcId = metaStr(md, "grpcId");
-        const method = metaStr(md, "method");
-        if (grpcId == null || method == null) {
-            return undefined;
-        }
-        return {
-            type: "grpc",
-            ...meta,
-            method: method,
-            grpcId: FernNavigation.GrpcId(grpcId),
-            apiDefinitionId,
-            availability: undefined
-        };
-    }
-    if (route.type === "graphql") {
-        const graphqlOperationId = metaStr(md, "graphqlOperationId");
-        const operationType = metaStr(md, "operationType");
-        if (graphqlOperationId == null || operationType == null) {
-            return undefined;
-        }
-        return {
-            type: "graphql",
-            ...meta,
-            operationType: operationType,
-            graphqlOperationId: FernNavigation.GraphQlOperationId(graphqlOperationId),
-            apiDefinitionId,
-            availability: undefined,
-            playground: undefined
-        };
-    }
-    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, segmentApiDefinitionId) {
-    const ctx = createBuildContext(basePath);
-    return routes
-        .map((route) => apiLeafNodeFromNavRouteInternal(ctx, route, segmentApiDefinitionId))
-        .filter((node) => node != null);
-}
-/** Read the apiDefinitionId off a segment's metadata, or undefined. */
-export function segmentApiDefinitionId(metadata) {
-    return metaStr(metadata, "apiDefinitionId");
-}
-/** Find the overview artifact (isOverview) within a segment's nav, if any. */
-function overviewRoute(nav) {
-    return nav.find((r) => r.type === "markdown" && metaBool(r.metadata, "isOverview"));
-}
-function sectionNode(ctx, scoped, sectionChildren) {
-    const { seg, nav } = scoped;
-    const overview = overviewRoute(nav);
-    const overviewPageId = overview != null ? metaStr(overview.metadata, "pageId") : undefined;
-    const slug = ctx.contentSlug(overview?.fullPath ?? seg.section);
-    const leafChildren = nav
-        .map((r) => artifactToNode(ctx, r))
-        .filter((n) => n != null);
-    const defaults = withMetadataDefaults({
-        id: ctx.nodeId(`section:${slug}`),
-        title: metaStr(seg.metadata, "title") ?? "",
-        slug,
-        icon: metaStr(seg.metadata, "icon"),
-        hidden: seg.hidden,
-        viewers: toViewers(metaStrArr(seg.metadata, "viewers"))
-    });
-    return {
-        type: "section",
-        ...defaults,
-        collapsed: metaCollapsed(seg.metadata) ?? defaults.collapsed,
-        overviewPageId: overviewPageId != null ? FernNavigation.PageId(overviewPageId) : undefined,
-        noindex: undefined,
-        collapsible: metaBool(seg.metadata, "collapsible"),
-        collapsedByDefault: metaBool(seg.metadata, "collapsedByDefault"),
-        availability: undefined,
-        pointsTo: undefined,
-        children: [...leafChildren, ...sectionChildren]
-    };
-}
-/**
- * Collect nav routes from the apiReference segment itself plus all descendant
- * apiPackage segments. The publish transform creates a separate segment for
- * each apiPackage (e.g. section "rest-api/store"), so the apiReference segment
- * (section "rest-api") only contains its overview page. This gathers routes
- * from the full subtree.
- */
-function collectDescendantApiNav(root, scopeSegs) {
-    const rootSection = root.seg.section;
-    const prefix = rootSection === "" ? "" : `${rootSection}/`;
-    const routes = [...root.nav];
-    for (const s of scopeSegs) {
-        if (s === root) {
-            continue;
-        }
-        const type = metaStr(s.seg.metadata, "type");
-        if (type !== "apiPackage") {
-            continue;
-        }
-        if (s.seg.section === rootSection || s.seg.section.startsWith(prefix)) {
-            routes.push(...s.nav);
-        }
-    }
-    return routes;
-}
-function apiReferenceNode(ctx, scoped, scopeSegs) {
-    const { seg, nav } = scoped;
-    const overview = overviewRoute(nav);
-    const overviewPageId = overview != null ? metaStr(overview.metadata, "pageId") : undefined;
-    const apiDefinitionId = metaStr(seg.metadata, "apiDefinitionId") ?? "";
-    // Slug: prefer the overview route, else the first child's parent path.
-    const slug = ctx.contentSlug(overview?.fullPath ?? nav[0]?.fullPath ?? seg.section);
-    // Collect endpoint/webhook nav routes from this segment AND all descendant
-    // apiPackage segments. The publish transform creates separate segments for
-    // each apiPackage (e.g. "rest-api/store", "rest-api/plant"), so the
-    // apiReference segment itself only has its overview page. We gather routes
-    // from the full subtree so findNode and the slug map can locate all API
-    // leaf pages.
-    const allNav = collectDescendantApiNav(scoped, scopeSegs);
-    const children = allNav
-        .map((route) => apiLeafNodeFromNavRouteInternal(ctx, route, apiDefinitionId))
-        .filter((node) => node != null);
-    return {
-        type: "apiReference",
-        ...withMetadataDefaults({
-            id: ctx.nodeId(`api:${slug}`),
-            title: metaStr(seg.metadata, "title") ?? "",
-            slug,
-            icon: metaStr(seg.metadata, "icon"),
-            hidden: seg.hidden,
-            viewers: toViewers(metaStrArr(seg.metadata, "viewers"))
-        }),
-        apiDefinitionId: FernNavigation.ApiDefinitionId(apiDefinitionId),
-        availability: undefined,
-        overviewPageId: overviewPageId != null ? FernNavigation.PageId(overviewPageId) : undefined,
-        noindex: undefined,
-        paginated: true,
-        showErrors: metaBool(seg.metadata, "showErrors"),
-        hideTitle: metaBool(seg.metadata, "hideTitle"),
-        pointsTo: undefined,
-        children,
-        changelog: undefined,
-        playground: undefined,
-        postmanCollectionUrl: undefined
-    };
-}
-function changelogNode(ctx, scoped) {
-    const { seg, nav } = scoped;
-    const overview = overviewRoute(nav);
-    const overviewPageId = overview != null ? metaStr(overview.metadata, "pageId") : undefined;
-    // 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 dateStr = metaStr(r.metadata, "date");
-        const date = dateStr != null ? new Date(dateStr) : new Date(0);
-        const year = date.getUTCFullYear();
-        const month = date.getUTCMonth() + 1;
-        const entry = {
-            type: "changelogEntry",
-            ...withMetadataDefaults({
-                id: ctx.nodeId(`cl-entry:${r.fullPath ?? metaStr(r.metadata, "pageId") ?? ""}`),
-                title: metaStr(r.metadata, "title") ?? "",
-                slug: ctx.contentSlug(r.fullPath ?? ""),
-                icon: metaStr(r.metadata, "icon"),
-                hidden: r.hidden,
-                viewers: toViewers(metaStrArr(r.metadata, "viewers"))
-            }),
-            pageId: FernNavigation.PageId(metaStr(r.metadata, "pageId") ?? ""),
-            noindex: undefined,
-            date: dateStr ?? "",
-            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?.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: metaStr(seg.metadata, "title") ?? "",
-            slug: baseSlug,
-            icon: metaStr(seg.metadata, "icon"),
-            hidden: seg.hidden,
-            viewers: toViewers(metaStrArr(seg.metadata, "viewers"))
-        }),
-        overviewPageId: overviewPageId != null ? FernNavigation.PageId(overviewPageId) : undefined,
-        noindex: undefined,
-        children: years
-    };
-}
-/** 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 "";
-}
-/**
- * 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) {
-    const sectionPaths = new Set(scopeSegs.map((s) => s.seg.section));
-    const direct = scopeSegs
-        .filter((s) => {
-        const sec = s.seg.section;
-        const type = metaStr(s.seg.metadata, "type");
-        if (sec === "" || type === "tabRoot") {
-            return false;
-        }
-        const parent = parentSectionPath(sec);
-        if (parent === parentPath) {
-            return true;
-        }
-        // Orphaned segment: parent doesn't exist, walk up to find nearest
-        // existing ancestor. If it's parentPath, adopt this segment.
-        if (!sectionPaths.has(parent)) {
-            return nearestExistingAncestor(sec, sectionPaths) === parentPath;
-        }
-        return false;
-    })
-        .sort((a, b) => a.seg.sortOrder - b.seg.sortOrder);
-    return direct.map((s) => {
-        const type = metaStr(s.seg.metadata, "type");
-        if (type === "apiReference" || type === "apiPackage") {
-            return apiReferenceNode(ctx, s, scopeSegs);
-        }
-        if (type === "changelog") {
-            return changelogNode(ctx, s);
-        }
-        // section (or unrecognised) → recurse for nested sections.
-        return sectionNode(ctx, s, buildSectionTree(ctx, scopeSegs, s.seg.section));
-    });
-}
-// ── 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 = metaStr(s.seg.metadata, "type");
-        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.
-        const parent = parentSectionPath(sec);
-        const isRootLevel = parent === "" || (!sectionPaths.has(parent) && nearestExistingAncestor(sec, sectionPaths) === "");
-        if (isRootLevel) {
-            if (type === "apiReference" || type === "apiPackage") {
-                flat.push(apiReferenceNode(ctx, s, scopeSegs));
-            }
-            else if (type === "changelog") {
-                flat.push(changelogNode(ctx, s));
-            }
-            else {
-                flat.push(sectionNode(ctx, s, buildSectionTree(ctx, scopeSegs, sec)));
-            }
-        }
-    }
-    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
-        // Infrastructure segments (files/redirects) are filtered server-side,
-        // but guard here too.
-        .filter((seg) => {
-        const t = metaStr(seg.metadata, "type");
-        return t !== "files" && t !== "redirects";
-    })
-        .map((seg) => ({ seg, nav: navBySegment.get(seg.segmentHash) ?? [] }));
-    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, rootSlug, 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;
-    }
-    const root = {
-        type: "root",
-        version: "v2",
-        ...withMetadataDefaults({ id: ctx.nodeId("root"), title, slug: rootSlug, icon: undefined, hidden: undefined }),
-        roles: undefined,
-        pointsTo: rootPointsTo,
-        child
-    };
-    return root;
-}
-// ── 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 slug = detailSlug(d);
-        const existing = bySlug.get(slug);
-        if (existing == null) {
-            bySlug.set(slug, d);
-        }
-        else if (metaStr(d.metadata, "pointsTo") != null && metaStr(existing.metadata, "pointsTo") == null) {
-            bySlug.set(slug, d);
-        }
-    }
-    return [...bySlug.values()].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 tabType = metaStr(tab.metadata, "tab_type");
-        const tabSlug = asSlug(scopeSlugPrefix(FernNavigation.Slug(""), tab));
-        if (tabType === "link") {
-            return {
-                type: "link",
-                id: ctx.nodeId(`link:${metaStr(tab.metadata, "url") ?? tabSlug}`),
-                collapsed: undefined,
-                title: tab.displayName,
-                icon: tab.icon ?? undefined,
-                url: FernNavigation.Url(metaStr(tab.metadata, "url") ?? ""),
-                target: undefined
-            };
-        }
-        if (tabType === "changelog") {
-            const tabSegs = scopeSegs.filter((s) => s.seg.tab?.id === tab.id);
-            const changelogSeg = tabSegs.find((s) => metaStr(s.seg.metadata, "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);
-        const metaPointsTo = metaStr(tab.metadata, "pointsTo");
-        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: metaPointsTo != null ? ctx.contentSlug(metaPointsTo) : undefined,
-            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, rootSlug, tabsPresent) {
-    void rootSlug;
-    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 versionSegs = scoped.filter((s) => s.seg.version?.id === version.id);
-        const tabsPresent = uniqueDetails(versionSegs, "tab").length > 0;
-        const prefix = productPrefix != null ? productPrefix : rootSlug;
-        const slug = version.metadata != null && detailIsDefault(version) ? prefix : scopeSlugPrefix(rootSlug, version);
-        const node = {
-            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: detailIsDefault(version),
-            versionId: FernNavigation.VersionId(version.id),
-            availability: undefined,
-            landingPage: undefined,
-            announcement: undefined,
-            pointsTo: metaStr(version.metadata, "pointsTo") != null
-                ? ctx.contentSlug(metaStr(version.metadata, "pointsTo"))
-                : undefined,
-            child: buildTabbedOrSidebar(ctx, versionSegs, tabsPresent)
-        };
-        return node;
-    });
-    return {
-        type: "versioned",
-        id: ctx.nodeId(`versioned:${productPrefix ?? "root"}`),
-        collapsed: undefined,
-        children
-    };
-}
-function buildProductGroup(ctx, products, scoped, rootSlug) {
-    const children = products.map((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, rootSlug, tabsPresent);
-        const node = {
-            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: metaStr(product.metadata, "subtitle") ?? "",
-            image: undefined,
-            announcement: undefined,
-            pointsTo: metaStr(product.metadata, "pointsTo") != null
-                ? ctx.contentSlug(metaStr(product.metadata, "pointsTo"))
-                : undefined,
-            child: productChild
-        };
-        return node;
-    });
-    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