@fern-api/fdr-sdk 1.2.42-b174eece86 → 1.2.42-e01a8637c3

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

@@ -569,6 +569,30 @@ function stripLeadingScopePrefix(section, scopePrefix) {
     }
     return section;
 }
+function computeDuplicateSiblingSortBoundaries(siblings) {
+    const result = new Map();
+    const byPath = new Map();
+    for (const sibling of siblings) {
+        if (metaStr(sibling.seg.metadata, "type") !== "section") {
+            continue;
+        }
+        const group = byPath.get(sibling.seg.section) ?? [];
+        group.push(sibling);
+        byPath.set(sibling.seg.section, group);
+    }
+    for (const [, group] of byPath) {
+        if (group.length <= 1) {
+            continue;
+        }
+        for (let i = 0; i < group.length; i++) {
+            result.set(group[i], {
+                lo: group[i].seg.sortOrder,
+                hi: i + 1 < group.length ? group[i + 1].seg.sortOrder : Number.MAX_SAFE_INTEGER
+            });
+        }
+    }
+    return result;
+}
 /**
  * Merge leaf children and section children by their original V1 tree position.
  * Leaves carry position via `displaySortOrder` (stored in nav routes), sections
@@ -642,13 +666,16 @@ function sectionNode(ctx, scoped, sectionChildren, scopePrefix) {
  * `parentSectionPath(seg.section) === parentSection`, or is an orphaned segment
  * whose nearest existing ancestor is `parentSection`.
  */
-function directChildApiPackages(parentSection, scopeSegs) {
+function directChildApiPackages(parentSection, scopeSegs, apiDefinitionId) {
     const sectionPaths = new Set(scopeSegs.map((s) => s.seg.section));
     return scopeSegs
         .filter((s) => {
         if (metaStr(s.seg.metadata, "type") !== "apiPackage") {
             return false;
         }
+        if (metaStr(s.seg.metadata, "apiDefinitionId") !== apiDefinitionId) {
+            return false;
+        }
         const parent = parentSectionPath(s.seg.section);
         if (parent === parentSection) {
             return true;
@@ -673,11 +700,37 @@ function buildApiChildren(ctx, scoped, scopeSegs, apiDefinitionId, scopePrefix)
     // API leaf types.
     const leafNodes = positionedApiLeafChildren(ctx, nav, apiDefinitionId);
     // Build nested ApiPackageNodes from direct child apiPackage segments.
-    const childPackages = directChildApiPackages(seg.section, scopeSegs);
+    let childPackages = directChildApiPackages(seg.section, scopeSegs, apiDefinitionId);
+    // When multiple API-type segments share the same section path (skipUrlSlug
+    // group packages that collapse to their parent's section), children from
+    // different groups get mixed together. Scope children to this segment's DFS
+    // subtree using sortOrder boundaries to restore correct ownership.
+    const samePathApiSiblings = scopeSegs.filter((s) => s.seg.section === seg.section &&
+        s.seg.sortOrder !== seg.sortOrder &&
+        API_NODE_SEGMENT_TYPES.has(metaStr(s.seg.metadata, "type") ?? ""));
+    const hasCollapsedGroups = samePathApiSiblings.length > 0;
+    if (hasCollapsedGroups && metaStr(seg.metadata, "type") !== "apiReference") {
+        // This is a group package sharing its section with siblings.
+        // Only claim children whose sortOrder falls within our DFS subtree.
+        const nextSibling = samePathApiSiblings
+            .filter((s) => s.seg.sortOrder > seg.sortOrder)
+            .sort((a, b) => a.seg.sortOrder - b.seg.sortOrder)[0];
+        const lo = seg.sortOrder;
+        const hi = nextSibling?.seg.sortOrder ?? Number.MAX_SAFE_INTEGER;
+        childPackages = childPackages.filter((c) => c.seg.sortOrder > lo && c.seg.sortOrder < hi);
+    }
     const packageNodes = childPackages.map((child) => ({
         node: apiPackageChildNode(ctx, child, scopeSegs, apiDefinitionId, scopePrefix),
         childIndex: metaNum(child.seg.metadata, "childIndex")
     }));
+    // When collapsed groups are detected at apiReference level, children's
+    // childIndex values are relative to different parent groups and cannot be
+    // used for interleaving. Fall back to sortOrder (DFS creation order).
+    if (hasCollapsedGroups && metaStr(seg.metadata, "type") === "apiReference") {
+        return [...leafNodes, ...packageNodes.map((p, i) => ({ node: p.node, pos: leafNodes.length + i }))]
+            .sort((a, b) => a.pos - b.pos)
+            .map((p) => p.node);
+    }
     // Interleave by position when childIndex metadata is available
     const hasChildIndex = packageNodes.some((p) => p.childIndex != null);
     if (!hasChildIndex) {
@@ -834,7 +887,7 @@ function apiReferenceNode(ctx, scoped, scopeSegs, scopePrefix) {
         availability: metaAvailability(seg.metadata),
         overviewPageId: overviewPageId != null ? FernNavigation.PageId(overviewPageId) : undefined,
         noindex: metaBool(overview?.metadata, "noindex") ?? metaBool(seg.metadata, "noindex"),
-        paginated: true,
+        paginated: metaBool(seg.metadata, "paginated"),
         showErrors: metaBool(seg.metadata, "showErrors"),
         hideTitle: metaBool(seg.metadata, "hideTitle"),
         pointsTo: metaPointsTo != null ? pointsToSlug(metaPointsTo) : undefined,
@@ -852,7 +905,12 @@ function attachedApiChangelogNode(ctx, scoped, scopeSegs, apiDefinitionId, scope
         }
         return metaStr(candidate.seg.metadata, "apiDefinitionId") === apiDefinitionId;
     });
-    const changelogSeg = candidates.find((candidate) => parentSectionPath(candidate.seg.section) === seg.section) ?? candidates[0];
+    const apiReferenceCount = scopeSegs.filter((candidate) => {
+        return (metaStr(candidate.seg.metadata, "type") === "apiReference" &&
+            metaStr(candidate.seg.metadata, "apiDefinitionId") === apiDefinitionId);
+    }).length;
+    const changelogSeg = candidates.find((candidate) => parentSectionPath(candidate.seg.section) === seg.section) ??
+        (apiReferenceCount === 1 ? candidates[0] : undefined);
     return changelogSeg != null ? changelogNode(ctx, changelogSeg, scopePrefix) : undefined;
 }
 function hasOwningApiReference(scoped, scopeSegs) {
@@ -860,12 +918,14 @@ function hasOwningApiReference(scoped, scopeSegs) {
     if (apiDefinitionId == null || metaStr(scoped.seg.metadata, "type") !== "changelog") {
         return false;
     }
-    return scopeSegs.some((candidate) => {
+    const candidates = scopeSegs.filter((candidate) => {
         if (metaStr(candidate.seg.metadata, "type") !== "apiReference") {
             return false;
         }
         return metaStr(candidate.seg.metadata, "apiDefinitionId") === apiDefinitionId;
     });
+    return (candidates.some((candidate) => parentSectionPath(scoped.seg.section) === candidate.seg.section) ||
+        candidates.length === 1);
 }
 /**
  * True when this segment is an `apiPackage` that will be nested under an in-scope
@@ -1046,6 +1106,12 @@ function buildSectionTree(ctx, scopeSegs, parentPath, scopePrefix, changelogScop
         if (hasOwningApiReference(s, scopeSegs) || isNestedApiPackage(s, scopeSegs)) {
             return false;
         }
+        // Segments marked as sidebar depth 0 are V1 root-level peers and
+        // must never be adopted as children of another section.
+        const depth = metaNum(s.seg.metadata, "sidebarDepth");
+        if (depth === 0) {
+            return false;
+        }
         const parent = parentSectionPath(sec);
         if (parent === parentPath) {
             return true;
@@ -1058,6 +1124,7 @@ function buildSectionTree(ctx, scopeSegs, parentPath, scopePrefix, changelogScop
         return false;
     })
         .sort((a, b) => a.seg.sortOrder - b.seg.sortOrder);
+    const siblingBoundaries = computeDuplicateSiblingSortBoundaries(direct);
     return direct.map((s) => {
         const type = metaStr(s.seg.metadata, "type");
         const childIndex = metaNum(s.seg.metadata, "childIndex");
@@ -1070,7 +1137,11 @@ function buildSectionTree(ctx, scopeSegs, parentPath, scopePrefix, changelogScop
         }
         else {
             // section (or unrecognised) → recurse for nested sections.
-            node = sectionNode(ctx, s, buildSectionTree(ctx, scopeSegs, s.seg.section, scopePrefix, changelogScopePrefix), scopePrefix);
+            const boundary = siblingBoundaries.get(s);
+            const childScopeSegs = boundary != null
+                ? scopeSegs.filter((candidate) => candidate.seg.sortOrder >= boundary.lo && candidate.seg.sortOrder < boundary.hi)
+                : scopeSegs;
+            node = sectionNode(ctx, s, buildSectionTree(ctx, childScopeSegs, s.seg.section, scopePrefix, changelogScopePrefix), scopePrefix);
         }
         return { node, childIndex };
     });
@@ -1090,16 +1161,26 @@ function buildSectionTree(ctx, scopeSegs, parentPath, scopePrefix, changelogScop
 function computeSiblingSortBoundaries(ordered) {
     const result = new Map();
     // Collect root-level sections grouped by their section path.
+    // Sections with sec==="" (skip-slug sections) are included: when multiple
+    // skip-slug sections exist at the root, they share path "" and need
+    // boundaries so each only adopts its own children.
     const sectionPaths = new Set(ordered.map((s) => s.seg.section));
     const rootSections = [];
     for (const s of ordered) {
         const type = metaStr(s.seg.metadata, "type");
         const sec = s.seg.section;
-        if (type !== "section" || sec === "") {
+        if (type !== "section") {
+            continue;
+        }
+        if (sec === "") {
+            rootSections.push(s);
             continue;
         }
+        const depth = metaNum(s.seg.metadata, "sidebarDepth");
         const parent = parentSectionPath(sec);
-        const isRootLevel = parent === "" || (!sectionPaths.has(parent) && nearestExistingAncestor(sec, sectionPaths) === "");
+        const isRootLevel = depth === 0 ||
+            parent === "" ||
+            (!sectionPaths.has(parent) && nearestExistingAncestor(sec, sectionPaths) === "");
         if (isRootLevel) {
             rootSections.push(s);
         }
@@ -1144,6 +1225,17 @@ function buildSidebarRootChildren(ctx, scopeSegs, scopePrefix, changelogScopePre
     // segments. Both index into the SAME child list at write time, so they
     // interleave directly (e.g. [page 0, page 1, section 2…15, page 16, 17]).
     const annotated = [];
+    // ── Sibling section ownership ────────────────────────────────────────
+    //
+    // Multiple root-level sections can share the same section path (e.g.
+    // three sections all with path equal to the version slug). When this
+    // happens, buildSectionTree would incorrectly give ALL child subsections
+    // to each sibling. We resolve ownership via sortOrder: a section owns
+    // segments whose sortOrder falls between its own and the next sibling's.
+    //
+    // Computed first because hasRootSection (below) uses it to decide
+    // whether bounded skip-slug siblings should activate adoption.
+    const siblingBoundaries = computeSiblingSortBoundaries(ordered);
     // ── Root-section adoption flow ──────────────────────────────────────
     //
     // A scope may contain a "root section" — a segment with type "section"
@@ -1155,28 +1247,42 @@ function buildSidebarRootChildren(ctx, scopeSegs, scopePrefix, changelogScopePre
     //   │      → emit pages/links inline at their displaySortOrder
     //   │
     //   ├─ (B) the root section itself (sec=="", type=="section")
-    //   │      → buildSectionTree adopts ALL depth-0 children as its own
-    //   │      → emit one sectionNode wrapping the whole subtree
+    //   │      → buildSectionTree adopts nested children (depth > 0)
+    //   │      → emit one sectionNode wrapping the subtree
     //   │
-    //   └─ (C) depth-0 sections (parentSectionPath=="")
-    //          → SKIP — already adopted by (B) via buildSectionTree
+    //   └─ (C) depth-0 sections (sidebarDepth==0 or parentSectionPath=="")
+    //          → emit directly as root children (not adopted by B)
     //
     // Without a root section, depth-0 sections are emitted directly.
-    const hasRootSection = ordered.some((s) => metaStr(s.seg.metadata, "type") === "section" && s.seg.section === "");
-    // ── Sibling section ownership ────────────────────────────────────────
     //
-    // Multiple root-level sections can share the same section path (e.g.
-    // three sections all with path equal to the version slug). When this
-    // happens, buildSectionTree would incorrectly give ALL child subsections
-    // to each sibling. We resolve ownership via sortOrder: a section owns
-    // segments whose sortOrder falls between its own and the next sibling's.
-    const siblingBoundaries = computeSiblingSortBoundaries(ordered);
+    // A section with sec=="" AND `childIndex` in its metadata is a sibling
+    // inside a V1 sidebarGroup that has skipUrlSlug — not a true structural
+    // wrapper. `walkNavSubTrees` always passes `childIndex`; direct
+    // sidebarRoot children (true wrappers) never receive one.
+    //
+    // Such siblings only activate adoption when they have sortOrder
+    // boundaries (multiple sec="" sections sharing the same path), which
+    // correctly scope each section's children. A *single* unbounded
+    // skip-slug sibling (e.g. mangopay's "Introduction") must NOT adopt
+    // its depth-0 peers — doing so produces spurious breadcrumb entries.
+    const hasRootSection = ordered.some((s) => metaStr(s.seg.metadata, "type") === "section" &&
+        s.seg.section === "" &&
+        (metaNum(s.seg.metadata, "childIndex") == null || siblingBoundaries.has(s)));
     for (const s of ordered) {
         const type = metaStr(s.seg.metadata, "type");
         const sec = s.seg.section;
         if (hasOwningApiReference(s, scopeSegs) || isNestedApiPackage(s, scopeSegs)) {
             continue;
         }
+        // Skip apiPackage segments that share their section path with an
+        // apiReference sibling (skipUrlSlug structural wrappers). Their
+        // children are already claimed by the apiReference via DFS ordering.
+        if (type === "apiPackage") {
+            const hasApiRefSibling = ordered.some((sib) => sib.seg.section === sec && metaStr(sib.seg.metadata, "type") === "apiReference");
+            if (hasApiRefSibling) {
+                continue;
+            }
+        }
         if (type === "tabRoot" && metaBool(s.seg.metadata, "landingPage") === true) {
             continue;
         }
@@ -1193,21 +1299,33 @@ function buildSidebarRootChildren(ctx, scopeSegs, scopePrefix, changelogScopePre
             continue;
         }
         // (B) Root section wrapper — adopts depth-0 children via buildSectionTree.
-        if (type === "section" && sec === "") {
-            const sectionChildren = buildSectionTree(ctx, scopeSegs, "", scopePrefix);
+        // Only applies to true root wrappers (no childIndex); sibling
+        // sections with skipUrlSlug (have childIndex) fall through to (C).
+        // When multiple sections share sec==="" (skip-slug), scope children
+        // to each section's sortOrder range so subsections aren't duplicated.
+        if (type === "section" && sec === "" && hasRootSection) {
+            const bounds = siblingBoundaries.get(s);
+            const ownedSegs = bounds != null
+                ? scopeSegs.filter((seg) => seg.seg.sortOrder >= bounds.lo && seg.seg.sortOrder < bounds.hi)
+                : scopeSegs;
+            const sectionChildren = buildSectionTree(ctx, ownedSegs, "", scopePrefix, changelogScopePrefix);
             const node = sectionNode(ctx, s, sectionChildren, scopePrefix);
             annotated.push({ node, pos: metaNum(s.seg.metadata, "childIndex"), isLeaf: false });
             continue;
         }
         // (C) Depth-0 or orphaned sections — emit at root unless already
         // adopted by a root section (B).
+        const depth = metaNum(s.seg.metadata, "sidebarDepth");
         const parent = parentSectionPath(sec);
-        const isRootLevel = parent === "" || (!sectionPaths.has(parent) && nearestExistingAncestor(sec, sectionPaths) === "");
-        // Skip depth-0 sections already adopted by the root section wrapper (B),
-        // but NOT structural types with sec="" (skip-slug). buildSectionTree
-        // filters out sec="" segments (line 1249), so they wouldn't be adopted
-        // and must be emitted here directly.
-        if (isRootLevel && hasRootSection && sec !== "") {
+        const isRootLevel = depth === 0 ||
+            parent === "" ||
+            (!sectionPaths.has(parent) && nearestExistingAncestor(sec, sectionPaths) === "");
+        // Skip depth-0 sections already adopted by the root section wrapper (B).
+        // When sidebarDepth is available, depth-0 sections are V1 root peers
+        // that buildSectionTree now excludes, so they must NOT be skipped.
+        // Only skip sections without sidebarDepth (old data) that would still
+        // be adopted by path-based hierarchy in buildSectionTree.
+        if (isRootLevel && hasRootSection && sec !== "" && depth == null) {
             continue;
         }
         if (isRootLevel) {
@@ -1225,7 +1343,20 @@ function buildSidebarRootChildren(ctx, scopeSegs, scopePrefix, changelogScopePre
                 const ownedSegs = bounds != null
                     ? scopeSegs.filter((seg) => seg.seg.sortOrder >= bounds.lo && seg.seg.sortOrder < bounds.hi)
                     : scopeSegs;
-                node = sectionNode(ctx, s, buildSectionTree(ctx, ownedSegs, sec, scopePrefix, changelogScopePrefix), scopePrefix);
+                // A section with sec="" that reaches here (not adopted as a
+                // root wrapper in case B) is a skipUrlSlug sibling.
+                // When sortOrder boundaries exist (multiple sec="" sections),
+                // the scoped ownedSegs correctly limits which subsections
+                // each section can adopt. When there are NO boundaries
+                // (single sec="" section, e.g. mangopay's "Introduction"),
+                // buildSectionTree("") would re-adopt all depth-0 peers;
+                // pass an empty child list instead — its leaf artifacts are
+                // already in its own segment nav.
+                const isUnboundedSkipSlugSibling = sec === "" && metaNum(s.seg.metadata, "childIndex") != null && bounds == null;
+                const sectionChildren = isUnboundedSkipSlugSibling
+                    ? []
+                    : buildSectionTree(ctx, ownedSegs, sec, scopePrefix, changelogScopePrefix);
+                node = sectionNode(ctx, s, sectionChildren, scopePrefix);
             }
             // Shared/merged sections (paths not rooted in scopePrefix) must not
             // carry childIndex — their source-version positions would sort them
@@ -1295,11 +1426,6 @@ function groupSidebarRootChildren(ctx, children) {
             flushRun();
             out.push(child);
         }
-        else if (child.type === "changelog") {
-            flushRun();
-            run.push(child);
-            flushRun();
-        }
         else {
             run.push(child);
         }
@@ -1466,7 +1592,7 @@ function buildVariantedNode(ctx, variants, scopeSegs, scopePrefix) {
             ? asSlug(FernNavigation.slugjoin(scopePrefix, variantIndividualSlug))
             : scopePrefix;
         const metaPointsTo = metaStr(variant.metadata, "pointsTo");
-        const children = buildSidebarRootChildren(ctx, variantSegs, scopePrefix);
+        const children = buildSidebarRootChildren(ctx, variantSegs, variantSlug);
         return {
             type: "variant",
             ...withMetadataDefaults({
@@ -2002,6 +2128,14 @@ function buildProductGroup(ctx, products, scoped, rootSlug, skipSharedSectionMer
         };
         return node;
     });
+    // Cross-product canonical slug deduplication (V2 parity).
+    // V2's migrator deduplicates pages across products via a global pageId map:
+    // the first product to register a pageId wins, and subsequent products'
+    // pages with the same pageId receive a canonicalSlug pointing to the
+    // canonical (default-product) page. Without this, shared content that is
+    // materialized under every product scope (e.g. merge-api-basics pages)
+    // appears as separate sitemap entries per product.
+    markCrossProductCanonicalSlugs(children);
     return {
         type: "productgroup",
         id: ctx.nodeId("productgroup"),
@@ -2010,5 +2144,43 @@ function buildProductGroup(ctx, products, scoped, rootSlug, skipSharedSectionMer
         children
     };
 }
+/**
+ * Deduplicate pages across products using pageId as a content-identity key.
+ * Pages with the same pageId in different products are the same content
+ * materialized per-scope; the default product's slug becomes canonical and
+ * non-default copies receive `canonicalSlug` so the sitemap collapses them.
+ *
+ * API leaf nodes (endpoints, websockets, etc.) are unaffected — `getPageId`
+ * returns undefined for those types, so product-specific API surface is
+ * never suppressed.
+ */
+function markCrossProductCanonicalSlugs(productNodes) {
+    const pageIdToCanonical = new Map();
+    // Process default product first so its slugs become the canonical targets.
+    const sorted = [...productNodes].sort((a, b) => {
+        if (a.default !== b.default) {
+            return a.default ? -1 : 1;
+        }
+        return 0;
+    });
+    for (const product of sorted) {
+        FernNavigation.traverseDF(product, (child) => {
+            if (FernNavigation.hasMetadata(child) && FernNavigation.isPage(child)) {
+                const pid = FernNavigation.getPageId(child);
+                if (pid == null) {
+                    return;
+                }
+                const key = `pid:${pid}`;
+                const canonical = pageIdToCanonical.get(key);
+                if (canonical != null && !product.default) {
+                    child.canonicalSlug = canonical;
+                }
+                else if (canonical == null) {
+                    pageIdToCanonical.set(key, child.canonicalSlug ?? child.slug);
+                }
+            }
+        });
+    }
+}
 // (root keeps the bare "root" id; it is the single tree root.)
 //# sourceMappingURL=ledger-root-builder.js.map