@fern-api/fdr-sdk 1.2.39-cc5ce5c5b6 → 1.2.39-dc3805e7f9

package/dist/navigation/__test__/ledger-root-builder.metadataPreservation.test.js

@@ -0,0 +1,1031 @@
+import { describe, expect, it } from "vitest";
+import { buildFullRootFromSegments } from "../ledger-root-builder.js";
+/**
+ * Verify that metadata fields on ledger nodes are correctly read from segment
+ * and route metadata rather than hardcoded to undefined. Covers: availability,
+ * noindex, target, image, authed, orphaned, featureFlags, and changelog tags.
+ */
+function segment(opts) {
+    return {
+        segmentId: opts.segmentHash,
+        segmentHash: opts.segmentHash,
+        section: opts.section,
+        locale: "en",
+        sortOrder: opts.sortOrder,
+        hidden: false,
+        metadata: opts.metadata,
+        product: opts.product ?? null,
+        version: opts.version ?? null,
+        variant: opts.variant ?? null,
+        tab: opts.tab ?? null
+    };
+}
+function restRoute(opts) {
+    return {
+        type: "rest",
+        fullPath: opts.fullPath,
+        hidden: false,
+        metadata: {
+            title: opts.title,
+            endpointId: opts.endpointId,
+            method: opts.method,
+            apiDefinitionId: "api-def-1",
+            ...(opts.availability != null ? { availability: opts.availability } : {}),
+            ...(opts.authed != null ? { authed: opts.authed } : {})
+        }
+    };
+}
+function webhookRoute(opts) {
+    return {
+        type: "webhook",
+        fullPath: opts.fullPath,
+        hidden: false,
+        metadata: {
+            title: opts.title,
+            webhookId: opts.webhookId,
+            method: opts.method,
+            apiDefinitionId: "api-def-1",
+            ...(opts.availability != null ? { availability: opts.availability } : {})
+        }
+    };
+}
+function linkRoute(opts) {
+    return {
+        type: "link",
+        fullPath: null,
+        hidden: false,
+        metadata: {
+            title: opts.title,
+            url: opts.url,
+            ...(opts.target != null ? { target: opts.target } : {})
+        }
+    };
+}
+function pageRoute(opts) {
+    return {
+        type: "markdown",
+        fullPath: opts.fullPath,
+        hidden: false,
+        metadata: {
+            title: opts.title,
+            pageId: `${opts.fullPath}.mdx`,
+            ...(opts.authed != null ? { authed: opts.authed } : {}),
+            ...(opts.orphaned != null ? { orphaned: opts.orphaned } : {}),
+            ...(opts.featureFlags != null ? { featureFlags: opts.featureFlags } : {}),
+            ...(opts.noindex != null ? { noindex: opts.noindex } : {}),
+            ...(opts.tags != null ? { tags: opts.tags } : {}),
+            ...(opts.date != null ? { date: opts.date } : {})
+        }
+    };
+}
+function changelogRoute(opts) {
+    return {
+        type: "changelog",
+        fullPath: opts.fullPath,
+        hidden: false,
+        metadata: {
+            title: opts.title,
+            pageId: `${opts.fullPath}.mdx`,
+            date: opts.date,
+            ...(opts.tags != null ? { tags: opts.tags } : {})
+        }
+    };
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function collectByType(node, targetType) {
+    const results = [];
+    if (node == null || typeof node !== "object") {
+        return results;
+    }
+    if (node.type === targetType) {
+        results.push(node);
+    }
+    for (const child of node.children ?? []) {
+        results.push(...collectByType(child, targetType));
+    }
+    if (node.child != null) {
+        results.push(...collectByType(node.child, targetType));
+    }
+    return results;
+}
+describe("metadata preservation on API leaf nodes", () => {
+    it("reads availability from endpoint metadata", () => {
+        const root = buildFullRootFromSegments({
+            basePath: "",
+            title: "Test",
+            segments: [
+                segment({
+                    segmentHash: "seg-api",
+                    section: "api",
+                    sortOrder: 0,
+                    metadata: { type: "apiReference", title: "API", apiDefinitionId: "api-def-1" }
+                })
+            ],
+            navBySegment: new Map([
+                [
+                    "seg-api",
+                    [
+                        restRoute({
+                            fullPath: "api/create",
+                            title: "Create",
+                            endpointId: "create",
+                            method: "POST",
+                            availability: "Beta"
+                        })
+                    ]
+                ]
+            ])
+        });
+        const endpoints = collectByType(root, "endpoint");
+        expect(endpoints).toHaveLength(1);
+        expect(endpoints[0].availability).toBe("Beta");
+    });
+    it("reads availability from webhook metadata", () => {
+        const root = buildFullRootFromSegments({
+            basePath: "",
+            title: "Test",
+            segments: [
+                segment({
+                    segmentHash: "seg-api",
+                    section: "api",
+                    sortOrder: 0,
+                    metadata: { type: "apiReference", title: "API", apiDefinitionId: "api-def-1" }
+                })
+            ],
+            navBySegment: new Map([
+                [
+                    "seg-api",
+                    [
+                        webhookRoute({
+                            fullPath: "api/on-created",
+                            title: "On Created",
+                            webhookId: "on-created",
+                            method: "POST",
+                            availability: "Deprecated"
+                        })
+                    ]
+                ]
+            ])
+        });
+        const webhooks = collectByType(root, "webhook");
+        expect(webhooks).toHaveLength(1);
+        expect(webhooks[0].availability).toBe("Deprecated");
+    });
+    it("reads authed from endpoint metadata via withMetadataDefaults", () => {
+        const root = buildFullRootFromSegments({
+            basePath: "",
+            title: "Test",
+            segments: [
+                segment({
+                    segmentHash: "seg-api",
+                    section: "api",
+                    sortOrder: 0,
+                    metadata: { type: "apiReference", title: "API", apiDefinitionId: "api-def-1" }
+                })
+            ],
+            navBySegment: new Map([
+                [
+                    "seg-api",
+                    [
+                        restRoute({
+                            fullPath: "api/secure",
+                            title: "Secure",
+                            endpointId: "secure",
+                            method: "GET",
+                            authed: true
+                        })
+                    ]
+                ]
+            ])
+        });
+        const endpoints = collectByType(root, "endpoint");
+        expect(endpoints).toHaveLength(1);
+        expect(endpoints[0].authed).toBe(true);
+    });
+});
+describe("metadata preservation on section nodes", () => {
+    it("reads availability from section segment metadata", () => {
+        const root = buildFullRootFromSegments({
+            basePath: "",
+            title: "Test",
+            segments: [
+                segment({
+                    segmentHash: "seg-section",
+                    section: "guides",
+                    sortOrder: 0,
+                    metadata: { type: "section", title: "Guides", availability: "Beta" }
+                })
+            ],
+            navBySegment: new Map([["seg-section", [pageRoute({ fullPath: "guides/intro", title: "Intro" })]]])
+        });
+        const sections = collectByType(root, "section");
+        expect(sections).toHaveLength(1);
+        expect(sections[0].availability).toBe("Beta");
+    });
+    it("reads noindex from section segment metadata", () => {
+        const root = buildFullRootFromSegments({
+            basePath: "",
+            title: "Test",
+            segments: [
+                segment({
+                    segmentHash: "seg-section",
+                    section: "guides",
+                    sortOrder: 0,
+                    metadata: { type: "section", title: "Guides", noindex: true }
+                })
+            ],
+            navBySegment: new Map([["seg-section", [pageRoute({ fullPath: "guides/intro", title: "Intro" })]]])
+        });
+        const sections = collectByType(root, "section");
+        expect(sections).toHaveLength(1);
+        expect(sections[0].noindex).toBe(true);
+    });
+});
+describe("metadata preservation on apiReference nodes", () => {
+    it("reads availability and noindex from apiReference segment metadata", () => {
+        const root = buildFullRootFromSegments({
+            basePath: "",
+            title: "Test",
+            segments: [
+                segment({
+                    segmentHash: "seg-api",
+                    section: "api",
+                    sortOrder: 0,
+                    metadata: {
+                        type: "apiReference",
+                        title: "API",
+                        apiDefinitionId: "api-def-1",
+                        availability: "Generally Available",
+                        noindex: true
+                    }
+                })
+            ],
+            navBySegment: new Map([
+                [
+                    "seg-api",
+                    [
+                        restRoute({
+                            fullPath: "api/list",
+                            title: "List",
+                            endpointId: "list",
+                            method: "GET"
+                        })
+                    ]
+                ]
+            ])
+        });
+        const apis = collectByType(root, "apiReference");
+        expect(apis).toHaveLength(1);
+        expect(apis[0].availability).toBe("Generally Available");
+        expect(apis[0].noindex).toBe(true);
+    });
+});
+describe("metadata preservation on link nodes", () => {
+    it("reads target from link artifact metadata", () => {
+        const root = buildFullRootFromSegments({
+            basePath: "",
+            title: "Test",
+            segments: [
+                segment({
+                    segmentHash: "seg-root",
+                    section: "",
+                    sortOrder: 0,
+                    metadata: { type: "tabRoot" }
+                })
+            ],
+            navBySegment: new Map([
+                ["seg-root", [linkRoute({ title: "External", url: "https://example.com", target: "_blank" })]]
+            ])
+        });
+        const links = collectByType(root, "link");
+        expect(links).toHaveLength(1);
+        expect(links[0].target).toBe("_blank");
+    });
+    it("reads target from link tab metadata", () => {
+        const tab = {
+            id: "link-tab",
+            displayName: "External",
+            slug: "external",
+            icon: null,
+            sortOrder: 1,
+            hidden: false,
+            viewers: [],
+            orphaned: false,
+            featureFlags: [],
+            metadata: { tab_type: "link", url: "https://example.com", target: "_blank" }
+        };
+        const root = buildFullRootFromSegments({
+            basePath: "",
+            title: "Test",
+            segments: [
+                segment({
+                    segmentHash: "seg-root",
+                    section: "",
+                    sortOrder: 0,
+                    metadata: { type: "tabRoot" },
+                    tab: {
+                        id: "docs-tab",
+                        displayName: "Docs",
+                        slug: "docs",
+                        icon: null,
+                        sortOrder: 0,
+                        hidden: false,
+                        viewers: [],
+                        orphaned: false,
+                        featureFlags: [],
+                        metadata: {}
+                    }
+                }),
+                segment({
+                    segmentHash: "seg-link",
+                    section: "",
+                    sortOrder: 1,
+                    metadata: { type: "tabRoot" },
+                    tab
+                })
+            ],
+            navBySegment: new Map([
+                ["seg-root", [pageRoute({ fullPath: "docs/intro", title: "Intro" })]],
+                ["seg-link", []]
+            ])
+        });
+        const links = collectByType(root, "link");
+        expect(links.length).toBeGreaterThanOrEqual(1);
+        const externalLink = links.find((l) => l.title === "External");
+        expect(externalLink).toBeDefined();
+        expect(externalLink.target).toBe("_blank");
+    });
+});
+describe("metadata preservation on page nodes", () => {
+    it("reads authed, orphaned, and featureFlags from page metadata", () => {
+        const root = buildFullRootFromSegments({
+            basePath: "",
+            title: "Test",
+            segments: [
+                segment({
+                    segmentHash: "seg-section",
+                    section: "guides",
+                    sortOrder: 0,
+                    metadata: { type: "section", title: "Guides" }
+                })
+            ],
+            navBySegment: new Map([
+                [
+                    "seg-section",
+                    [
+                        pageRoute({
+                            fullPath: "guides/protected",
+                            title: "Protected",
+                            authed: true,
+                            orphaned: true,
+                            featureFlags: ["beta-feature"]
+                        })
+                    ]
+                ]
+            ])
+        });
+        const pages = collectByType(root, "page");
+        expect(pages).toHaveLength(1);
+        expect(pages[0].authed).toBe(true);
+        expect(pages[0].orphaned).toBe(true);
+        expect(pages[0].featureFlags).toEqual(["beta-feature"]);
+    });
+});
+describe("changelog tags preservation", () => {
+    it("reads tags from changelog entry metadata", () => {
+        const root = buildFullRootFromSegments({
+            basePath: "",
+            title: "Test",
+            segments: [
+                segment({
+                    segmentHash: "seg-changelog",
+                    section: "changelog",
+                    sortOrder: 0,
+                    metadata: { type: "changelog", title: "Changelog" }
+                })
+            ],
+            navBySegment: new Map([
+                [
+                    "seg-changelog",
+                    [
+                        changelogRoute({
+                            fullPath: "changelog/2026-01-15",
+                            title: "January Release",
+                            tags: ["feature", "bugfix"],
+                            date: "2026-01-15"
+                        }),
+                        changelogRoute({
+                            fullPath: "changelog/2026-02-01",
+                            title: "February Release",
+                            tags: ["security"],
+                            date: "2026-02-01"
+                        })
+                    ]
+                ]
+            ])
+        });
+        const entries = collectByType(root, "changelogEntry");
+        expect(entries).toHaveLength(2);
+        const jan = entries.find((e) => e.title === "January Release");
+        expect(jan).toBeDefined();
+        expect(jan.tags).toEqual(["feature", "bugfix"]);
+        const feb = entries.find((e) => e.title === "February Release");
+        expect(feb).toBeDefined();
+        expect(feb.tags).toEqual(["security"]);
+    });
+    it("returns undefined tags when metadata has no tags", () => {
+        const root = buildFullRootFromSegments({
+            basePath: "",
+            title: "Test",
+            segments: [
+                segment({
+                    segmentHash: "seg-changelog",
+                    section: "changelog",
+                    sortOrder: 0,
+                    metadata: { type: "changelog", title: "Changelog" }
+                })
+            ],
+            navBySegment: new Map([
+                [
+                    "seg-changelog",
+                    [
+                        changelogRoute({
+                            fullPath: "changelog/2026-03-01",
+                            title: "March Release",
+                            date: "2026-03-01"
+                        })
+                    ]
+                ]
+            ])
+        });
+        const entries = collectByType(root, "changelogEntry");
+        expect(entries).toHaveLength(1);
+        expect(entries[0].tags).toBeUndefined();
+    });
+    it("returns undefined for empty tags array in metadata", () => {
+        const root = buildFullRootFromSegments({
+            basePath: "",
+            title: "Test",
+            segments: [
+                segment({
+                    segmentHash: "seg-changelog",
+                    section: "changelog",
+                    sortOrder: 0,
+                    metadata: { type: "changelog", title: "Changelog" }
+                })
+            ],
+            navBySegment: new Map([
+                [
+                    "seg-changelog",
+                    [
+                        changelogRoute({
+                            fullPath: "changelog/2026-04-01",
+                            title: "April Release",
+                            tags: [],
+                            date: "2026-04-01"
+                        })
+                    ]
+                ]
+            ])
+        });
+        const entries = collectByType(root, "changelogEntry");
+        expect(entries).toHaveLength(1);
+        // metaStrArr returns undefined for empty arrays
+        expect(entries[0].tags == null || entries[0].tags.length === 0).toBe(true);
+    });
+    it("preserves multi-word tags with spaces", () => {
+        const root = buildFullRootFromSegments({
+            basePath: "",
+            title: "Test",
+            segments: [
+                segment({
+                    segmentHash: "seg-changelog",
+                    section: "changelog",
+                    sortOrder: 0,
+                    metadata: { type: "changelog", title: "Changelog" }
+                })
+            ],
+            navBySegment: new Map([
+                [
+                    "seg-changelog",
+                    [
+                        changelogRoute({
+                            fullPath: "changelog/2026-05-01",
+                            title: "May Release",
+                            tags: ["Breaking Change", "New Feature", "Bug Fix"],
+                            date: "2026-05-01"
+                        })
+                    ]
+                ]
+            ])
+        });
+        const entries = collectByType(root, "changelogEntry");
+        expect(entries).toHaveLength(1);
+        expect(entries[0].tags).toEqual(["Breaking Change", "New Feature", "Bug Fix"]);
+    });
+    it("preserves tags independently per entry (mixed tagged and untagged)", () => {
+        const root = buildFullRootFromSegments({
+            basePath: "",
+            title: "Test",
+            segments: [
+                segment({
+                    segmentHash: "seg-changelog",
+                    section: "changelog",
+                    sortOrder: 0,
+                    metadata: { type: "changelog", title: "Changelog" }
+                })
+            ],
+            navBySegment: new Map([
+                [
+                    "seg-changelog",
+                    [
+                        changelogRoute({
+                            fullPath: "changelog/2026-06-15",
+                            title: "Tagged Entry",
+                            tags: ["feature", "api"],
+                            date: "2026-06-15"
+                        }),
+                        changelogRoute({
+                            fullPath: "changelog/2026-06-10",
+                            title: "Untagged Entry",
+                            date: "2026-06-10"
+                        }),
+                        changelogRoute({
+                            fullPath: "changelog/2026-06-05",
+                            title: "Another Tagged",
+                            tags: ["deprecation"],
+                            date: "2026-06-05"
+                        })
+                    ]
+                ]
+            ])
+        });
+        const entries = collectByType(root, "changelogEntry");
+        expect(entries).toHaveLength(3);
+        const tagged = entries.find((e) => e.title === "Tagged Entry");
+        expect(tagged.tags).toEqual(["feature", "api"]);
+        const untagged = entries.find((e) => e.title === "Untagged Entry");
+        expect(untagged.tags).toBeUndefined();
+        const another = entries.find((e) => e.title === "Another Tagged");
+        expect(another.tags).toEqual(["deprecation"]);
+    });
+    it("preserves tags across year/month boundaries", () => {
+        const root = buildFullRootFromSegments({
+            basePath: "",
+            title: "Test",
+            segments: [
+                segment({
+                    segmentHash: "seg-changelog",
+                    section: "changelog",
+                    sortOrder: 0,
+                    metadata: { type: "changelog", title: "Changelog" }
+                })
+            ],
+            navBySegment: new Map([
+                [
+                    "seg-changelog",
+                    [
+                        changelogRoute({
+                            fullPath: "changelog/2026-01-10",
+                            title: "Jan 2026",
+                            tags: ["feature"],
+                            date: "2026-01-10"
+                        }),
+                        changelogRoute({
+                            fullPath: "changelog/2025-12-20",
+                            title: "Dec 2025",
+                            tags: ["bugfix", "security"],
+                            date: "2025-12-20"
+                        }),
+                        changelogRoute({
+                            fullPath: "changelog/2025-06-01",
+                            title: "Jun 2025",
+                            tags: ["deprecation"],
+                            date: "2025-06-01"
+                        })
+                    ]
+                ]
+            ])
+        });
+        const entries = collectByType(root, "changelogEntry");
+        expect(entries).toHaveLength(3);
+        const jan = entries.find((e) => e.title === "Jan 2026");
+        expect(jan.tags).toEqual(["feature"]);
+        const dec = entries.find((e) => e.title === "Dec 2025");
+        expect(dec.tags).toEqual(["bugfix", "security"]);
+        const jun = entries.find((e) => e.title === "Jun 2025");
+        expect(jun.tags).toEqual(["deprecation"]);
+    });
+});
+describe("metadata preservation on additional API leaf types", () => {
+    it("reads availability from websocket (asyncapi) metadata", () => {
+        const root = buildFullRootFromSegments({
+            basePath: "",
+            title: "Test",
+            segments: [
+                segment({
+                    segmentHash: "seg-api",
+                    section: "api",
+                    sortOrder: 0,
+                    metadata: { type: "apiReference", title: "API", apiDefinitionId: "api-def-1" }
+                })
+            ],
+            navBySegment: new Map([
+                [
+                    "seg-api",
+                    [
+                        {
+                            type: "asyncapi",
+                            fullPath: "api/ws-stream",
+                            hidden: false,
+                            metadata: {
+                                title: "Stream",
+                                webSocketId: "ws-stream",
+                                apiDefinitionId: "api-def-1",
+                                availability: "Beta"
+                            }
+                        }
+                    ]
+                ]
+            ])
+        });
+        const wsNodes = collectByType(root, "webSocket");
+        expect(wsNodes).toHaveLength(1);
+        expect(wsNodes[0].availability).toBe("Beta");
+    });
+    it("reads availability from grpc metadata", () => {
+        const root = buildFullRootFromSegments({
+            basePath: "",
+            title: "Test",
+            segments: [
+                segment({
+                    segmentHash: "seg-api",
+                    section: "api",
+                    sortOrder: 0,
+                    metadata: { type: "apiReference", title: "API", apiDefinitionId: "api-def-1" }
+                })
+            ],
+            navBySegment: new Map([
+                [
+                    "seg-api",
+                    [
+                        {
+                            type: "grpc",
+                            fullPath: "api/grpc-call",
+                            hidden: false,
+                            metadata: {
+                                title: "Call",
+                                grpcId: "grpc-call",
+                                method: "POST",
+                                apiDefinitionId: "api-def-1",
+                                availability: "Generally Available"
+                            }
+                        }
+                    ]
+                ]
+            ])
+        });
+        const grpcNodes = collectByType(root, "grpc");
+        expect(grpcNodes).toHaveLength(1);
+        expect(grpcNodes[0].availability).toBe("Generally Available");
+    });
+    it("reads availability from graphql metadata", () => {
+        const root = buildFullRootFromSegments({
+            basePath: "",
+            title: "Test",
+            segments: [
+                segment({
+                    segmentHash: "seg-api",
+                    section: "api",
+                    sortOrder: 0,
+                    metadata: { type: "apiReference", title: "API", apiDefinitionId: "api-def-1" }
+                })
+            ],
+            navBySegment: new Map([
+                [
+                    "seg-api",
+                    [
+                        {
+                            type: "graphql",
+                            fullPath: "api/gql-query",
+                            hidden: false,
+                            metadata: {
+                                title: "Query",
+                                graphqlOperationId: "gql-query",
+                                operationType: "query",
+                                apiDefinitionId: "api-def-1",
+                                availability: "Deprecated"
+                            }
+                        }
+                    ]
+                ]
+            ])
+        });
+        const gqlNodes = collectByType(root, "graphql");
+        expect(gqlNodes).toHaveLength(1);
+        expect(gqlNodes[0].availability).toBe("Deprecated");
+    });
+});
+describe("metadata preservation on variant and product nodes", () => {
+    it("reads image from variant metadata", () => {
+        const variantA = {
+            id: "variant-a",
+            displayName: "Variant A",
+            slug: "variant-a",
+            icon: null,
+            sortOrder: 0,
+            hidden: false,
+            viewers: [],
+            orphaned: false,
+            featureFlags: [],
+            metadata: { default: true }
+        };
+        const variantB = {
+            id: "variant-b",
+            displayName: "Variant B",
+            slug: "variant-b",
+            icon: null,
+            sortOrder: 1,
+            hidden: false,
+            viewers: [],
+            orphaned: false,
+            featureFlags: [],
+            metadata: { image: "img-variant-b.png" }
+        };
+        const root = buildFullRootFromSegments({
+            basePath: "",
+            title: "Test",
+            segments: [
+                segment({
+                    segmentHash: "seg-a",
+                    section: "variant-a",
+                    sortOrder: 0,
+                    metadata: { type: "section", title: "Section A" },
+                    variant: variantA
+                }),
+                segment({
+                    segmentHash: "seg-b",
+                    section: "variant-b",
+                    sortOrder: 1,
+                    metadata: { type: "section", title: "Section B" },
+                    variant: variantB
+                })
+            ],
+            navBySegment: new Map([
+                ["seg-a", [pageRoute({ fullPath: "variant-a/page", title: "Page A" })]],
+                ["seg-b", [pageRoute({ fullPath: "variant-b/page", title: "Page B" })]]
+            ])
+        });
+        const variants = collectByType(root, "variant");
+        expect(variants).toHaveLength(2);
+        const vb = variants.find((v) => v.variantId === "variant-b");
+        expect(vb).toBeDefined();
+        expect(vb.image).toBe("img-variant-b.png");
+        const va = variants.find((v) => v.variantId === "variant-a");
+        expect(va).toBeDefined();
+        expect(va.image).toBeUndefined();
+    });
+    it("reads image from product metadata", () => {
+        const productA = {
+            id: "prod-a",
+            displayName: "Product A",
+            slug: "product-a",
+            icon: null,
+            sortOrder: 0,
+            hidden: false,
+            viewers: [],
+            orphaned: false,
+            featureFlags: [],
+            metadata: { default: true, image: "img-prod-a.png" }
+        };
+        const productB = {
+            id: "prod-b",
+            displayName: "Product B",
+            slug: "product-b",
+            icon: null,
+            sortOrder: 1,
+            hidden: false,
+            viewers: [],
+            orphaned: false,
+            featureFlags: [],
+            metadata: {}
+        };
+        const root = buildFullRootFromSegments({
+            basePath: "",
+            title: "Test",
+            segments: [
+                segment({
+                    segmentHash: "seg-pa",
+                    section: "product-a",
+                    sortOrder: 0,
+                    metadata: { type: "section", title: "Section A" },
+                    product: productA
+                }),
+                segment({
+                    segmentHash: "seg-pb",
+                    section: "product-b",
+                    sortOrder: 1,
+                    metadata: { type: "section", title: "Section B" },
+                    product: productB
+                })
+            ],
+            navBySegment: new Map([
+                ["seg-pa", [pageRoute({ fullPath: "product-a/page", title: "Page A" })]],
+                ["seg-pb", [pageRoute({ fullPath: "product-b/page", title: "Page B" })]]
+            ])
+        });
+        const products = collectByType(root, "product");
+        expect(products).toHaveLength(2);
+        const pa = products.find((p) => p.productId === "Product A");
+        expect(pa).toBeDefined();
+        expect(pa.image).toBe("img-prod-a.png");
+        const pb = products.find((p) => p.productId === "Product B");
+        expect(pb).toBeDefined();
+        expect(pb.image).toBeUndefined();
+    });
+});
+describe("metadata preservation on apiPackage nodes", () => {
+    it("reads availability and noindex from apiPackage segment metadata", () => {
+        const root = buildFullRootFromSegments({
+            basePath: "",
+            title: "Test",
+            segments: [
+                segment({
+                    segmentHash: "seg-api",
+                    section: "api",
+                    sortOrder: 0,
+                    metadata: { type: "apiReference", title: "API", apiDefinitionId: "api-def-1" }
+                }),
+                segment({
+                    segmentHash: "seg-pkg",
+                    section: "api/users",
+                    sortOrder: 1,
+                    metadata: {
+                        type: "apiPackage",
+                        title: "Users",
+                        apiDefinitionId: "api-def-1",
+                        availability: "Beta",
+                        noindex: true
+                    }
+                })
+            ],
+            navBySegment: new Map([
+                ["seg-api", []],
+                [
+                    "seg-pkg",
+                    [
+                        restRoute({
+                            fullPath: "api/users/list",
+                            title: "List Users",
+                            endpointId: "list-users",
+                            method: "GET"
+                        })
+                    ]
+                ]
+            ])
+        });
+        const packages = collectByType(root, "apiPackage");
+        expect(packages).toHaveLength(1);
+        expect(packages[0].availability).toBe("Beta");
+        expect(packages[0].noindex).toBe(true);
+    });
+});
+describe("skipSharedSectionMerge option", () => {
+    const defaultVersion = {
+        id: "v-2026-02",
+        displayName: "2026-02-09",
+        slug: "2026-02-09",
+        icon: null,
+        sortOrder: 0,
+        hidden: false,
+        viewers: [],
+        orphaned: false,
+        featureFlags: [],
+        metadata: { default: true }
+    };
+    const olderVersion = {
+        id: "v-2024-12",
+        displayName: "2024-12-23",
+        slug: "2024-12-23",
+        icon: null,
+        sortOrder: 1,
+        hidden: false,
+        viewers: [],
+        orphaned: false,
+        featureFlags: [],
+        metadata: {}
+    };
+    const docsTab = {
+        id: "docs-tab",
+        displayName: "Documentation",
+        slug: "docs",
+        icon: null,
+        sortOrder: 0,
+        hidden: false,
+        viewers: [],
+        orphaned: false,
+        featureFlags: [],
+        metadata: {}
+    };
+    function buildVersionedRoot(skipMerge) {
+        return buildFullRootFromSegments({
+            basePath: "",
+            title: "Test",
+            segments: [
+                // Default version tab root
+                segment({
+                    segmentHash: "seg-default-root",
+                    section: "",
+                    sortOrder: 0,
+                    metadata: { type: "tabRoot" },
+                    version: defaultVersion,
+                    tab: docsTab
+                }),
+                // Default version section
+                segment({
+                    segmentHash: "seg-default-guides",
+                    section: "2026-02-09",
+                    sortOrder: 1,
+                    metadata: { type: "section", title: "Getting Started" },
+                    version: defaultVersion,
+                    tab: docsTab
+                }),
+                // Older version tab root
+                segment({
+                    segmentHash: "seg-older-root",
+                    section: "",
+                    sortOrder: 2,
+                    metadata: { type: "tabRoot" },
+                    version: olderVersion,
+                    tab: docsTab
+                }),
+                // Older version section
+                segment({
+                    segmentHash: "seg-older-guides",
+                    section: "2024-12-23",
+                    sortOrder: 3,
+                    metadata: { type: "section", title: "Getting Started" },
+                    version: olderVersion,
+                    tab: docsTab
+                }),
+                // Shared section (no version prefix path) — assigned to older version only
+                segment({
+                    segmentHash: "seg-shared-workflows",
+                    section: "workflows",
+                    sortOrder: 4,
+                    metadata: { type: "section", title: "Workflows" },
+                    version: olderVersion,
+                    tab: docsTab
+                })
+            ],
+            navBySegment: new Map([
+                ["seg-default-root", [pageRoute({ fullPath: "overview", title: "Overview" })]],
+                [
+                    "seg-default-guides",
+                    [pageRoute({ fullPath: "2026-02-09/getting-started", title: "Getting Started" })]
+                ],
+                ["seg-older-root", [pageRoute({ fullPath: "2024-12-23/overview", title: "Overview" })]],
+                [
+                    "seg-older-guides",
+                    [
+                        pageRoute({
+                            fullPath: "2024-12-23/getting-started",
+                            title: "Getting Started"
+                        })
+                    ]
+                ],
+                [
+                    "seg-shared-workflows",
+                    [
+                        pageRoute({
+                            fullPath: "2024-12-23/workflows/create",
+                            title: "Create Workflow"
+                        })
+                    ]
+                ]
+            ]),
+            skipSharedSectionMerge: skipMerge
+        });
+    }
+    it("merges shared sections into default version when skipSharedSectionMerge is false", () => {
+        const root = buildVersionedRoot(false);
+        const versions = collectByType(root, "version");
+        const defaultVer = versions.find((v) => v.default);
+        expect(defaultVer).toBeDefined();
+        // The default version should have the "Workflows" section merged in.
+        const sections = collectByType(defaultVer, "section");
+        const sectionTitles = sections.map((s) => s.title);
+        expect(sectionTitles).toContain("Workflows");
+    });
+    it("does NOT merge shared sections when skipSharedSectionMerge is true", () => {
+        const root = buildVersionedRoot(true);
+        const versions = collectByType(root, "version");
+        const defaultVer = versions.find((v) => v.default);
+        expect(defaultVer).toBeDefined();
+        // The default version should NOT have the "Workflows" section.
+        const sections = collectByType(defaultVer, "section");
+        const sectionTitles = sections.map((s) => s.title);
+        expect(sectionTitles).not.toContain("Workflows");
+    });
+});
+//# sourceMappingURL=ledger-root-builder.metadataPreservation.test.js.map