Merge tags and tagGroups with the same name in sidebar

[robinmoneybird]

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.

Summary by CodeRabbit

• Tests

  • Added comprehensive unit tests for tag categorization and grouping logic covering various merging scenarios.

• Improvements

  • Enhanced tag and category merging strategy for improved organization of OpenAPI documentation categories.

[vercel]

@robinmoneybird is attempting to deploy a commit to the Zuplo Team on Vercel.

A member of the Team first needs to authorize it.

[github-actions]

Preview build of published Zudoku package

Warning

This PR is from an external contributor. To run the public package build workflow, a maintainer must add the approve public build label after reviewing the changes.

[robinmoneybird]

When an OpenAPI spec has a tag and an x-tagGroups entry that share the same name (e.g. "Contacts"), they previously rendered as two separate sidebar entries — one with the tag's operations, and one wrapping the group's child tags. This merges them into a single category: the tag's own operations appear first, followed by nested child tags from the group.

This is useful for specs that want to organize operations hierarchically — similar to how Enhanced Tags in OpenAPI 3.2.0 allow tags to have both direct paths and nested sub-tags. With this change, you can achieve the same structure today using x-tagGroups without ending up with duplicate sidebar entries.

Example

  tags:
    - name: Contacts
    - name: Notes

  x-tagGroups:
    - name: Contacts
      tags:
        - Notes

  paths:
    /contacts:
      get:
        tags: [Contacts]
    /contacts/{id}/notes:
      get:
        tags: [Notes]

Before — two sidebar entries:

▶ Contacts       ← from x-tagGroups, wrapping children
  ▶ Notes        ← tag nested within x-tagGroups
    GET /contacts/{id}/notes
▶ Contacts       ← direct tag outside x-tagGroups
  GET /contacts

After — single merged entry:

▶ Contacts           ← merged tag + tagGroup
  GET /contacts      ← operations from the "Contacts" tag
  ▶ Notes            ← nested child tag from the group
    GET /contacts/{id}/notes

[Copilot]

Pull request overview

This PR updates the OpenAPI sidebar tag navigation to mimic OpenAPI 3.2 “Enhanced tags” behavior by allowing a tag to simultaneously contain direct operations and nested child tags derived from x-tagGroups. When a tag name matches a tagGroup name, they are merged into a single sidebar category instead of appearing twice.

Changes:

• Merge tag + tagGroup entries when group.name matches a tag name, combining the tag’s operations with the group’s child tags.
• Prevent self-referential nesting when a tagGroup includes its own name in tags.
• Add test coverage for the new merging behavior and ungrouped exclusion.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
packages/zudoku/src/lib/plugins/openapi/util/buildTagCategories.ts	Implements “consumed tags” tracking and merges same-name tag/tagGroup into a single navigation category.
packages/zudoku/src/lib/plugins/openapi/util/buildTagCategories.test.ts	Adds tests validating merge behavior, self-reference exclusion, and removal from ungrouped results.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

📝 Walkthrough

Walkthrough

Updates the tag merging strategy in buildTagCategories to use a consumed tags tracker, optionally using base tags as group foundations and building child items from group definitions. Adds comprehensive unit tests validating the merging logic, tag exclusion from ungrouped results, and edge cases.

Changes

Cohort / File(s)	Summary
Tag Merging Strategy packages/zudoku/src/lib/plugins/openapi/util/buildTagCategories.ts, buildTagCategories.test.ts	Implementation refactors merging logic with consumedTags tracker, optional base tag support, and child tag item building. Tests validate merged tag categorization, ungrouped result filtering, and edge cases with no child tags.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 Tags and groups we merge with care,
With consumed trackers everywhere,
Base tags merge and children align,
Each test ensures the logic's fine,
Ungrouped stragglers find their place,
In this category-building race! 🏃‍♂️

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: merging tags and tagGroups with the same name in the sidebar, which is the primary objective of the pull request.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Merge Conflict Detection	✅ Passed	✅ No merge conflicts detected when merging into main

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

No actionable comments were generated in the recent review. 🎉

🧹 Recent nitpick comments

packages/zudoku/src/lib/plugins/openapi/util/buildTagCategories.ts (1)

18-46: Consider handling tags appearing in multiple tagGroups.

The current logic adds tags to consumedTags to prevent them from appearing in the ungrouped list, but it doesn't prevent a tag from being included as a child in multiple tagGroups. If the same tag (e.g., "Notes") is listed in two different tagGroups, it will appear as a child item in both resulting categories.

This may be intentional, but if not, you could check consumedTags.has(name) before adding a child:

     const childTags = group.tags.flatMap((name) => {
       if (name === group.name) return [];
       const tag = tagCategories.get(name);
-      if (!tag) return [];
+      if (!tag || consumedTags.has(name)) return [];
       consumedTags.add(name);
       return tag;
     });

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
zudoku-cosmo-cargo	Ready	Preview, Comment	Feb 14, 2026 7:36am
zudoku-dev	Ready	Preview, Comment	Feb 14, 2026 7:36am

[dan-lee]

Thanks for the contribution @robinmoneybird! 🚀
I rebased it and made some minor changes