[BI]Handle special character fields in names

[samithkavishke]

Purpose

Fixes: wso2/product-ballerina-integrator#979

Goals

Describe the solutions that this feature/fix will introduce to resolve the problems described above

Approach

Describe how you are implementing the solutions. Include an animated GIF or screenshot if the change affects the UI (email [email protected] to review all UI text). Include a link to a Markdown file or Google doc if the feature write-up is too long to paste here.

UI Component Development

Specify the reason if following are not followed.

• Added reusable UI components to the ui-toolkit. Follow the intructions when adding the componenent.
• Use ui-toolkit components wherever possible. Run npm run storybook from the root directory to view current components.
• Matches with the native VSCode look and feel.

Manage Icons

Specify the reason if following are not followed.

• Added Icons to the font-wso2-vscode. Follow the instructions.

User stories

Release note

Brief description of the new feature or bug fix as it will appear in the release notes

Documentation

Link(s) to product documentation that addresses the changes of this PR. If no doc impact, enter “N/A” plus brief explanation of why there’s no doc impact

Training

Link to the PR for changes to the training content in https://github.com/wso2/WSO2-Training, if applicable

Certification

Type “Sent” when you have provided new/updated certification questions, plus four answers for each question (correct answer highlighted in bold), based on this change. Certification questions/answers should be sent to [email protected] and NOT pasted in this PR. If there is no impact on certification exams, type “N/A” and explain why.

Marketing

Link to drafts of marketing content that will describe and promote this feature, including product page changes, technical articles, blog posts, videos, etc., if applicable

Automation tests

• Unit tests

  Code coverage information

• Integration tests

  Details about the test cases and coverage

Security checks

• Followed secure coding standards in http://wso2.com/technical-reports/wso2-secure-engineering-guidelines? yes/no
• Ran FindSecurityBugs plugin and verified report? yes/no
• Confirmed that this PR doesn't commit any keys, passwords, tokens, usernames, or other secrets? yes/no

Samples

Provide high-level details about the samples related to this feature

Related PRs

List any other related PRs

Migrations (if applicable)

Describe migration steps and platforms on which migration has been tested

Test environment

List all JDK versions, operating systems, databases, and browser/versions on which this feature/fix was tested

Learning

Describe the research phase and any blog posts, patterns, libraries, or add-ons you used to solve the problem.

Summary by CodeRabbit

• New Features
  • Support for attaching structured annotations to members, enabling richer metadata on model elements.
  • Attribute labels now prefer custom names derived from annotations when present, improving diagram readability.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Adds optional annotationAttachments to the Member interface and introduces an AnnotationAttachment type; updates the AttributeCard UI to extract and use custom display names from member annotations with error handling and a fallback to the original name.

Changes

Cohort / File(s)	Change Summary
Type system — annotation types workspaces/ballerina/ballerina-core/src/interfaces/extended-lang-client.ts	Added optional annotationAttachments?: AnnotationAttachment[] to Member and added new AnnotationAttachment interface with modulePrefix: string, name: string, and properties: Property[].
UI — attribute display name resolution workspaces/ballerina/type-diagram/src/components/entity-relationship/EntityNode/Attribute/AttributeCard.tsx	Added a helper to extract custom display names from jsondata Name annotations (handling array and object shapes), added isMember type guard, computed displayName from annotations with error handling/console logging, and used displayName when rendering attribute names.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20–25 minutes

• Review the new AnnotationAttachment shape for compatibility with existing annotation consumers.
• Verify annotationAttachments usage does not break serialization/deserialization of Member.
• Validate the helper handles both annotation array and object forms and that console logging is appropriate.
• Confirm isMember type guard matches actual Member and TypeFunctionModel definitions and that fallback behavior is correct.

Poem

🐰 I nibble through annotations bright,
Hunting names that hide from sight.
I pull the label, clean and clear,
Hop back to show what we should hear.
A small hop for code, a joyful cheer!

Pre-merge checks and finishing touches

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The PR description is largely incomplete template text with only minimal concrete information. Key sections like Goals, Approach, Release note, Documentation, tests, and security checks lack substantive content.	Complete the Goals and Approach sections explaining how annotation attachments solve special character handling. Add Release notes, test details, and security confirmations.
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title "[BI]Handle special character fields in names" directly relates to the main objective of handling JSON fields with special characters that are invalid Ballerina identifiers, aligning with issue #979.
Linked Issues check	✅ Passed	The code changes extend the Member interface with AnnotationAttachment support and implement logic to extract display names from annotations, directly addressing issue #979's requirement to handle special character field names in Ballerina record type generation.
Out of Scope Changes check	✅ Passed	All changes are directly aligned with issue #979. The interface extensions and display name extraction logic target special character handling without introducing unrelated modifications.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

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

---

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 and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (3)

workspaces/ballerina/ballerina-core/src/interfaces/extended-lang-client.ts (1)

1461-1479: Align AnnotationAttachment.properties typing with actual runtime shapes

The new annotationAttachments?: AnnotationAttachment[] on Member is fine and backward compatible, but AnnotationAttachment.properties is strictly typed as Property[] while the UI helper (getCustomNameFromAnnotation in AttributeCard.tsx) explicitly handles both array and non-array/object-like shapes via any casting.

If the language server can send non-Property[] structures here (e.g., nested { value: { value: string } } objects), consider widening the type to something like Property[] | Record<string, unknown> (or even unknown) and tightening the helper around that shape. Otherwise, if it’s guaranteed to always be Property[], the extra object-path handling in the helper should be removed to keep types and usage consistent.

If you’re unsure about the LS payload shape, please verify against the actual JSON schema or sample responses before deciding which side (type vs. helper) to adjust.

workspaces/ballerina/type-diagram/src/components/entity-relationship/EntityNode/Attribute/AttributeCard.tsx (2)

36-83: Tighten typing and remove noisy logging in getCustomNameFromAnnotation

The extraction logic for jsondata:Name looks robust, but a couple of points:

• annotation.properties is typed as Property[], while here you treat it as Property[] | object and fall back to (properties as any).value.*. Once the LS payload shape is confirmed, it would be better either to:

  • keep only the Property[] path and delete the object-path fallbacks, or
  • widen the type on AnnotationAttachment.properties and model the alternative shapes explicitly instead of relying on any.

• The console.log (and to a lesser extent the broad console.error including the full member) will spam the extension’s console in normal use. These should either be removed before merge or guarded behind a debug flag / environment check.

Functionally this is OK, but cleaning up the types and logs will make it safer and less noisy.

---

94-101: Type guard and displayName logic are fine; consider small simplification

Using a type guard to gate access to annotationAttachments and preferring the custom name via displayName while keeping all IDs/ports based on attribute.name is a good approach and fits the requirement (“show the jsondata.name if available”).

Given that getCustomNameFromAnnotation already handles missing annotationAttachments, you could simplify this to always call it with attribute as Member and avoid the custom isMember guard, but that’s purely a readability preference and not required for correctness.

Also applies to: 129-129

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between a91be70 and 189a403.

📒 Files selected for processing (2)

• workspaces/ballerina/ballerina-core/src/interfaces/extended-lang-client.ts (1 hunks)
• workspaces/ballerina/type-diagram/src/components/entity-relationship/EntityNode/Attribute/AttributeCard.tsx (3 hunks)

🧰 Additional context used

🧬 Code graph analysis (2)

workspaces/ballerina/ballerina-core/src/interfaces/extended-lang-client.ts (1)

workspaces/ballerina/ballerina-core/src/interfaces/bi.ts (1)

• Property (124-144)

workspaces/ballerina/type-diagram/src/components/entity-relationship/EntityNode/Attribute/AttributeCard.tsx (1)

workspaces/ballerina/ballerina-core/src/interfaces/extended-lang-client.ts (2)

• Member (1461-1473)
• TypeFunctionModel (1424-1437)

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

workspaces/ballerina/ballerina-core/src/interfaces/extended-lang-client.ts (1)

1497-1501: Add JSDoc documentation to the AnnotationAttachment interface.

The AnnotationAttachment interface represents a new public type and would benefit from documentation that clarifies:

• The purpose and expected usage pattern
• Examples like how @json:Name maps to modulePrefix: "json" and name: "Name"
• Whether modulePrefix can be absent (some built-in annotations like @deprecated don't have a module prefix)
• The expected structure of the properties array

The reuse of the Property type is reasonable for consistency, though consider documenting which Property fields are semantically relevant for annotation metadata (as some like editable, hidden, placeholder are UI-specific).

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 189a403 and b82713a.

📒 Files selected for processing (1)

• workspaces/ballerina/ballerina-core/src/interfaces/extended-lang-client.ts

🧰 Additional context used

🧬 Code graph analysis (1)

workspaces/ballerina/ballerina-core/src/interfaces/extended-lang-client.ts (1)

workspaces/ballerina/ballerina-core/src/interfaces/bi.ts (1)

• Property (176-194)

🔇 Additional comments (1)

workspaces/ballerina/ballerina-core/src/interfaces/extended-lang-client.ts (1)

1494-1495: LGTM! Already integrated for handling JSON field names with special characters.

The optional annotationAttachments field addition to the Member interface is backward compatible and properly integrated. The AnnotationAttachment interface (with required modulePrefix, name, and properties fields) is already in use in AttributeCard.tsx to extract custom field names from the @jsondata:Name annotation pattern, enabling mapping of JSON keys with special characters to valid Ballerina identifiers.