Merge tags and tagGroups with the same name in sidebar

Mimic the more permissive "Enhanced tags" behaviour from OpenAPI 3.2.0,
by allowing a tag to have both direct operations and nested child tags
from tagGroups. When a tag and x-tagGroup share the same name, they are
now combined into a single sidebar category instead of appearing twice.

However, this current implementation does not use `x-displayName` as,
these could still be different tags. Only the actual `name` of a tag is
considered when checking name equality.

Author: robinmoneybird

packages/zudoku/src/lib/plugins/openapi/util/buildTagCategories.test.ts

@@ -123,4 +123,86 @@ describe("buildTagCategories", () => {
 
     expect(result).toEqual([]);
   });
+
+  it("merges a tag and tagGroup with the same name", () => {
+    const tagCategories = new Map<string, NavigationItem>([
+      ["Contacts", makeTag("Contacts")],
+      ["Notes", makeTag("Notes")],
+    ]);
+
+    const result = buildTagCategories({
+      tagCategories,
+      tagGroups: [{ name: "Contacts", tags: ["Contacts", "Notes"] }],
+    });
+
+    expect(result).toHaveLength(1);
+
+    const contacts = result[0];
+    expect(contacts?.label).toBe("Contacts");
+    expect(contacts?.type).toBe("category");
+
+    if (contacts?.type === "category") {
+      // Operations from the "Contacts" tag come first, then "Notes" as a child
+      expect(contacts.items).toHaveLength(2);
+      expect(contacts.items[0]?.label).toBe("Contacts op");
+      expect(contacts.items[1]?.label).toBe("Notes");
+    }
+  });
+
+  it("excludes self-reference when tagGroup includes its own name in tags", () => {
+    const tagCategories = new Map<string, NavigationItem>([
+      ["Contacts", makeTag("Contacts")],
+      ["Notes", makeTag("Notes")],
+    ]);
+
+    const result = buildTagCategories({
+      tagCategories,
+      tagGroups: [{ name: "Contacts", tags: ["Contacts", "Notes"] }],
+    });
+
+    const contacts = result[0];
+    if (contacts?.type === "category") {
+      // "Contacts" tag should NOT appear as a nested child of itself
+      const childLabels = contacts.items.map((i) => i.label);
+      expect(childLabels).not.toContain("Contacts");
+    }
+  });
+
+  it("excludes merged tag from ungrouped results", () => {
+    const tagCategories = new Map<string, NavigationItem>([
+      ["Contacts", makeTag("Contacts")],
+      ["Notes", makeTag("Notes")],
+      ["Standalone", makeTag("Standalone")],
+    ]);
+
+    const result = buildTagCategories({
+      tagCategories,
+      tagGroups: [{ name: "Contacts", tags: ["Contacts", "Notes"] }],
+    });
+
+    // "Contacts" (merged) + "Standalone" (ungrouped) = 2 top-level entries
+    expect(result).toHaveLength(2);
+    expect(result.map((r) => r.label)).toEqual(["Contacts", "Standalone"]);
+  });
+
+  it("merges tag with tagGroup that has no additional child tags", () => {
+    const tagCategories = new Map<string, NavigationItem>([
+      ["Contacts", makeTag("Contacts")],
+    ]);
+
+    const result = buildTagCategories({
+      tagCategories,
+      tagGroups: [{ name: "Contacts", tags: ["Contacts"] }],
+    });
+
+    expect(result).toHaveLength(1);
+
+    const contacts = result[0];
+    expect(contacts?.label).toBe("Contacts");
+    if (contacts?.type === "category") {
+      // Only the original operations, no nested tags
+      expect(contacts.items).toHaveLength(1);
+      expect(contacts.items[0]?.label).toBe("Contacts op");
+    }
+  });
 });

packages/zudoku/src/lib/plugins/openapi/util/buildTagCategories.ts

@@ -13,33 +13,38 @@ export const buildTagCategories = ({
   tagGroups,
   expandAllTags,
 }: BuildTagCategoriesOptions): NavigationItem[] => {
-  const groupedTags = new Set(
-    tagGroups.flatMap((group) =>
-      group.tags.filter((name) => tagCategories.has(name)),
-    ),
-  );
+  const consumedTags = new Set<string>();
 
   const groupedCategories: NavigationItem[] = tagGroups.flatMap((group) => {
-    const items = group.tags
-      .map((name) => tagCategories.get(name))
-      .filter(Boolean) as NavigationItem[];
+    const matchingTag = tagCategories.get(group.name);
+    const base = matchingTag?.type === "category" ? matchingTag : undefined;
+
+    if (base) consumedTags.add(group.name);
+
+    const childTags = group.tags
+      .filter((name) => name !== group.name && tagCategories.has(name))
+      .flatMap((name) => {
+        consumedTags.add(name);
+        const tag = tagCategories.get(name);
+        return tag ? [tag] : [];
+      });
+
+    if (!base && childTags.length === 0) return [];
 
-    if (items.length === 0) {
-      return [];
-    }
     return [
       {
-        type: "category",
-        label: group.name,
-        items,
-        collapsible: true,
-        collapsed: !expandAllTags,
+        ...base,
+        type: "category" as const,
+        label: base?.label ?? group.name,
+        items: [...(base?.items ?? []), ...childTags],
+        collapsible: base?.collapsible ?? true,
+        collapsed: base?.collapsed ?? !expandAllTags,
       },
     ];
   });
 
   const ungroupedCategories = Array.from(tagCategories.entries())
-    .filter(([name]) => !groupedTags.has(name))
+    .filter(([name]) => !consumedTags.has(name))
     .map(([, cat]) => cat);
 
   return [...groupedCategories, ...ungroupedCategories].sort((a, b) =>