[SirLouen]

Closes #197.

What

• A role nothing declares now reads "Nothing declares that role." (Spanish "Nada declara ese rol.").
• A role beyond your reach now reads "That role holds more than your own, or nothing declares it." The same sentence covers enabling an account whose role nothing declares.
• The New user form shows these sentences under the form when the server turns the chosen role down. Before, it showed the server's raw English, such as "unknown role", in every language.
• The GraphQL reference describes role_unknown as "nothing declares the role".

Why

Roles come from the code and the plugins that declare them, so "a role this deployment names" was the wrong idea. The invite form also lost the reason the server sent, so it could not show the translated sentence the role dialog already shows.

Testing Instructions

1. Open New user, pick a role and send the invitation while the server refuses that role: the sentence shows under the form, in Spanish too.
2. In the Change role dialog, pick a role nothing declares: the dialog reads "Nothing declares that role."

Summary by CodeRabbit

• Bug Fixes
  • Invitation refusals for unknown or out-of-reach roles now display the appropriate explanation instead of a generic error or raw server message.
  • Role validation messages now consistently describe roles as undeclared when no role declaration exists.
  • Spanish error messages have been updated to match the revised role explanations.
• Documentation
  • Updated GraphQL API reference descriptions for unknown and out-of-reach role errors.

[codescene-access]

Code Health Improved (1 files improve in Code Health)

Gates Passed
4 Quality Gates Passed

See analysis details in CodeScene

View Improvements

File	Code Health Impact	Categories Improved
graphTransport.ts	8.82 → 9.10	Overall Code Complexity, Primitive Obsession, String Heavy Function Arguments

Quality Gate Profile: Clean Code Collective
Install CodeScene MCP: safeguard and uplift AI-generated code. Catch issues early with our IDE extension and CLI tool.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Source mode: Auto
• Repository: gopherium/AlphOne
• Branch: fix/197-role-unknown
• File: .coderabbit.yaml
• Commit: b9d5ace
• Layers: Repository YAML
• Review profile: CHILL
• Plan: Advanced
• Run ID: bd76c8f9-3327-445d-9305-75d345b165de

📥 Commits

Reviewing files that changed from the base of the PR and between bacfca2 and b9d5ace.

📒 Files selected for processing: 11

• docs/src/content/docs/reference/graphql-api.md
• frontend/src/auth/graphTransport.ts
• frontend/src/i18n/errorTemplates.ts
• frontend/src/languages/es-ES.json
• frontend/src/test/invite-transport.test.ts
• frontend/src/test/users-new-role.test.tsx
• frontend/src/test/users-route.test.tsx
• frontend/src/users/NewUserScreen.tsx
• frontend/src/users/roles.ts
• languages/alphone.pot
• languages/es-ES.po

Included review availability: This review used your included allowance. Your plan provides up to 2 included reviews per hour; 1 remain after this review.

📝 Walkthrough

Invitation refusals for role_unknown and role_beyond_reach now map to typed errors and display localized role-specific messages in the New user flow. Related role descriptions and English and Spanish messages now describe undeclared roles rather than roles not named by the deployment.

Changes: Role refusal handling

Layer / File(s)	Summary
Map invitation refusal reasons frontend/src/auth/graphTransport.ts, frontend/src/test/invite-transport.test.ts	The invitation transport passes the refusal reason to error handling and maps role_unknown and role_beyond_reach to typed errors. Tests check the mapped errors and the existing validation error type.
Display localized role refusal messages frontend/src/users/roles.ts, frontend/src/users/NewUserScreen.tsx, frontend/src/i18n/errorTemplates.ts, frontend/src/languages/es-ES.json, frontend/src/test/users-new-role.test.tsx, frontend/src/test/users-route.test.tsx, docs/src/content/docs/reference/graphql-api.md, languages/alphone.pot, languages/es-ES.po	The New user screen selects a role-specific template for typed refusal errors. Tests check the displayed messages and confirm the server’s raw message is not shown. Role descriptions and related English and Spanish messages use undeclared-role wording.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant Invite as Invite mutation
  participant Transport as graphTransport
  participant Screen as NewUserScreen
  participant Roles as roles.ts
  participant Templates as appErrorTemplates
  participant User
  Invite-->>Transport: GraphQL refusal reason
  Transport-->>Screen: typed role refusal error
  Screen->>Roles: roleRefusal(error)
  Roles-->>Screen: refusal code
  Screen->>Templates: select refusal message
  Templates-->>Screen: localized message
  Screen-->>User: display refusal alert

Loading

Merge Risk: ⚪ Minimal · up to b9d5a

The localized invitation refusals are connected to the server’s responses, and no merge-blocking issue was found.

Pre-merge checks: 5

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly summarizes the two main changes: updated role wording and localized invitation refusal messages.
Linked Issues check		The reviewed head satisfies the coding requirements in [#197]. router.tsx places /users and /users/new behind MANAGE_USERS; coreNav.tsx provides the API-token fallback; TokensScreen.tsx sh…
Out of Scope Changes check		The changes stay within [#197]. The modified transport logic, error templates, Spanish catalog, GraphQL reference, invitation form, role mapping, and tests all support role refusal wording, invitation…
Docstring Coverage		Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 11 functions across 7 files. (4 skipped: 4…

Full details: Linked Issues check

Explanation

The reviewed head satisfies the coding requirements in [#197]. router.tsx places /users and /users/new behind MANAGE_USERS; coreNav.tsx provides the API-token fallback; TokensScreen.tsx shows the Users tab only when the reader can reach Users. roles.ts and RoleSelect.tsx provide shared role labels, grantable-role order, and the Member default. NewUserScreen.tsx sends the selected role and displays localized refusal text. The reviewed changes also map role_unknown and role_beyond_reach, update the English and Spanish messages, update the GraphQL reference, and add focused tests.

Full details: Out of Scope Changes check

Explanation

The changes stay within [#197]. The modified transport logic, error templates, Spanish catalog, GraphQL reference, invitation form, role mapping, and tests all support role refusal wording, invitation role errors, or the related role-selection behavior.

Full details: Docstring Coverage

Explanation

Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 11 functions across 7 files. (4 skipped: 4 unsupported.)

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

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

[gitar-bot]

Code Review ✅ Approved

🟡 Medium risk · Mapping invitation refusal reasons to typed frontend errors changes error handling; mismatched server reasons could show a generic or incorrect message.

Fixes the role-unknown and role-beyond-reach messages to say nothing declares the role, and shows the server's invite refusal under the New user form in the reader's language instead of raw English. No issues found.

Verification

Rules No rules evaluated

Functional validation Not enabled

Set up

_{For more verification details, comment gitar display:verbose.}

Options

Auto-apply is off → Gitar will not commit updates to this branch.
Display: compact → Showing compact verification results.

Comment with these commands to change the behavior for this request:

Auto-apply	Compact
gitar auto-apply:on	gitar display:verbose

_{Was this helpful? React with 👍 / 👎 | Powered by Gitar — free for open source}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[greptile-apps]

Confidence Score: 5/5

[Medium impact] Safe to merge within the reviewed scope; the invitation transport and rendered refusal messages behaved as intended.

Summary

Invitations now keep the server’s role refusal reason and show the matching translated message under the form.

• Role refusal messages now say when nothing declares the role.
• Invitations show translated reasons when a role is refused.

All 106 targeted frontend tests passed. A focused 15-case invitation transport check confirmed the correct role errors, unchanged successful invitations, and continued priority for authentication and rate-limit failures. Six browser scenarios confirmed the translated invitation messages and updated Change role and Enable wording.

No actionable issues found. Safe to merge within the reviewed scope.

_{Reviews (1) · Last reviewed commit: "docs(reference): say nothing declares th..." · Reviewed by Greptile}