@fern-api/fdr-sdk 1.2.18-2fa046eb41 → 1.2.18-607f792059

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

@@ -0,0 +1,670 @@
+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;
+}
+/** 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;
+        }
+        // Endpoints / websockets / webhooks / grpc / graphql are resolved via
+        // the paginated apiReference + on-demand API definition, not emitted as
+        // standalone sidebar children here.
+        case "rest":
+        case "asyncapi":
+        case "webhook":
+        case "grpc":
+        case "graphql":
+            return undefined;
+        default:
+            return undefined;
+    }
+}
+/**
+ * Convert one API-leaf nav route (a `rest`/`webhook` artifact) into its
+ * navigation node, or undefined when the route is not an API leaf carrying the
+ * required identifiers. `apiDefinitionId` falls back to the segment-level value
+ * because the per-route metadata always carries it (see
+ * `makeApiArtifact`/`makeEndpointArtifact` in docsPublishTransform), but the
+ * segment value is a safe default.
+ *
+ * @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
+        };
+    }
+    return undefined;
+}
+/**
+ * Collect every endpoint/webhook navigation node from a single API segment's
+ * nav routes. This is the route/segment-first replacement for walking the full
+ * root to enumerate endpoint nodes: the caller resolves the owning segment
+ * (`segment.metadata.apiDefinitionId`), fetches ONLY that segment's `nav`, and
+ * builds the leaf nodes here — so paginated apiReferences (whose persisted
+ * children are empty) still yield endpoint nodes. See ADR 0013.
+ *
+ * @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);
+    return {
+        type: "section",
+        ...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"))
+        }),
+        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]
+    };
+}
+function apiReferenceNode(ctx, scoped) {
+    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);
+    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);
+}
+/** Build the section/api/changelog nodes whose immediate parent is `parentPath`, recursing into nested sections. */
+function buildSectionTree(ctx, scopeSegs, parentPath) {
+    const direct = scopeSegs
+        .filter((s) => {
+        const sec = s.seg.section;
+        const type = metaStr(s.seg.metadata, "type");
+        if (sec === "" || type === "tabRoot") {
+            return false;
+        }
+        return parentSectionPath(sec) === parentPath;
+    })
+        .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);
+        }
+        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).
+ */
+function buildSidebarRootChildren(ctx, scopeSegs) {
+    const ordered = [...scopeSegs].sort((a, b) => a.seg.sortOrder - b.seg.sortOrder);
+    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 only depth-0 sections here; deeper sections are attached by
+        // their parent via buildSectionTree recursion.
+        if (parentSectionPath(sec) === "") {
+            if (type === "apiReference" || type === "apiPackage") {
+                flat.push(apiReferenceNode(ctx, s));
+            }
+            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. Sections and apiReferences pass through; any
+ * contiguous run of pages / links / changelogs is wrapped into a
+ * SidebarGroupNode (mirroring the V1→latest migration).
+ */
+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 === "section" || child.type === "apiReference" || child.type === "varianted") {
+            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);
+    }
+    const root = {
+        type: "root",
+        version: "v2",
+        ...withMetadataDefaults({ id: ctx.nodeId("root"), title, slug: rootSlug, icon: undefined, hidden: undefined }),
+        roles: undefined,
+        pointsTo: undefined,
+        child
+    };
+    FernNavigation.utils.mutableUpdatePointsTo(root);
+    return root;
+}
+// ── scaffolding builders ────────────────────────────────────────────────────
+function uniqueDetails(scoped, dim) {
+    const byId = new Map();
+    for (const s of scoped) {
+        const d = s.seg[dim];
+        if (d != null && !byId.has(d.id)) {
+            byId.set(d.id, d);
+        }
+    }
+    return [...byId.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 tabSegs = scopeSegs.filter((s) => s.seg.tab?.id === tab.id);
+        const tabSlug = asSlug(scopeSlugPrefix(FernNavigation.Slug(""), tab));
+        const node = {
+            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: undefined,
+            child: buildSidebarRoot(ctx, tabSegs)
+        };
+        return node;
+    });
+    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: 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: 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