feat(utils): add resolvePriorityRole for picking one role by priority

[anetasliwinska]

Summary

• Adds resolvePriorityRole to @o2s/utils.api-harmonization: given a priority-ordered list of roles and a fallback, returns the first role the user actually holds.
• Deliberately generic - no project-specific role names baked in. Each project passes its own role vocabulary and fallback.
• Motivated by a downstream project (built on this framework) that had the same priority-role-resolution logic copy-pasted across five blocks, with one of the copies drifting to return a role name that did not match its own label map.

Test plan

• Unit tests added (roles.spec.ts): priority order, order-independence of the input roles, fallback to lower-priority role, fallback to default, missing roles list.
• npm run lint and npm run test pass for @o2s/utils.api-harmonization.
• Changeset included (minor)

Summary by CodeRabbit

• New Features

  • Added a reusable helper for selecting a user’s highest-priority role from multiple assigned roles.
  • Supports configurable role priorities and a fallback when no prioritized role matches.
  • Exported the role utilities for broader use.

• Tests

  • Added coverage for priority ordering, fallback behavior, empty role lists, and missing role data.

• Chores

  • Updated ignore rules for local Node.js version files.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: ed68cadb-4a74-4546-91b1-4249761e47f4

📥 Commits

Reviewing files that changed from the base of the PR and between 1a6e136 and ff2dfd6.

📒 Files selected for processing (5)

• .changeset/lazy-brooms-invent.md
• .gitignore
• packages/utils/api-harmonization/src/utils/index.ts
• packages/utils/api-harmonization/src/utils/roles.spec.ts
• packages/utils/api-harmonization/src/utils/roles.ts

Included review availability: Your plan provides up to 2 included reviews per hour; 1 remains after this review.

---

Walkthrough

The change adds and exports a generic resolvePriorityRole helper, tests its selection and fallback behavior, records a minor release, and ignores personal .nvmrc files.

Changes

Priority role helper

Layer / File(s)	Summary
Role resolution and validation packages/utils/api-harmonization/src/utils/roles.ts, packages/utils/api-harmonization/src/utils/index.ts, packages/utils/api-harmonization/src/utils/roles.spec.ts, .changeset/lazy-brooms-invent.md	Adds resolvePriorityRole, exports it through Roles, tests priority and fallback behavior, and adds a minor release changeset.

Local Node configuration

Layer / File(s)	Summary
Personal Node version ignore rule .gitignore	Ignores personal .nvmrc files used for local Node version pins.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Feature

Suggested reviewers: marcinkrasowski

Merge Risk: ⚪ Minimal · up to ff2df

This PR adds the priority-role helper and its tests without an identified merge-blocking behavior change.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely identifies the main change: adding resolvePriorityRole to select one role by priority.
Description check	✅ Passed	The description explains the utility, its generic design, motivation, test coverage, validation results, and changeset. It does not explicitly describe side effects, related tickets, or detailed setup…
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 3…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{I sort the roles from high to low,
And choose the one the users show.
If none appear within the list,
The fallback role will not be missed.
A tidy helper hops along.}

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

[github-actions]

Coverage Report for packages/configs/vitest-config

Status	Category	Percentage	Covered / Total
🔵	Lines	82.05%	2286 / 2786
🔵	Statements	81.18%	2403 / 2960
🔵	Functions	75.89%	642 / 846
🔵	Branches	68.35%	1574 / 2303

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
packages/utils/api-harmonization/src/utils/roles.ts	100%	100%	100%	100%

Generated in workflow #961 for commit ff2dfd6 by the Vitest Coverage Report Action