Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Naming convention for scan rule constants in library packages

Open
  • Is something wrong?
#142 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
java
Domain
tooling

Research direction

Read the suggested convention options in the issue and check Ballerina's annotation rules for whether a constant mapping can be accessed in an annotation. Compare the namespace, completion, documentation, and import tradeoffs for each option; the issue is done when a convention is agreed on for rule constants across library packages.

Written by the indexing model from the issue text.

Description

Type/Improvement
Current Limitation

  • A @scan:Suppress annotation names rules by ID, such as ballerina:2 or ballerina/http:1, which does not say what is suppressed.

  • ballerina/scan is adding a constant for each core rule, named after the finding it suppresses, so the annotation reads as what is suppressed and why:

    @scan:Suppress {rules: [scan:UNUSED_FUNCTION_PARAMETER], reason: "Required by the listener interface"}

  • Packages that provide scan rules through an analyzer, such as the standard libraries, should provide constants for their rules too. Unlike ballerina/scan, whose API is only about scanning, a library's rule constants share its namespace with the rest of its API. Without a convention:

    • a rule constant can clash with, or be mistaken for, an existing API constant of the library;
    • completion and the API docs mix rule constants with the API;
    • each library names them differently.

  • A plain prefix such as SCAN_ solves those, but breaks the finding-based reading: http:SCAN_UNSECURED_RESOURCE reads as "scan unsecured resource" rather than "suppress the unsecured resource finding".

Suggested Improvement

Agree on a convention for rule constants in library packages, so that they read as the finding, stay apart from the library's API, and look the same in every library. Options to discuss (rule names are illustrative):

  1. No prefix, named after the finding: http:UNSECURED_RESOURCE. Reads best; relies on the name not clashing with the API and on the docs marking it as a rule.
  2. A suffix: http:UNSECURED_RESOURCE_RULE.
  3. A constant mapping of rules: http:SCAN_RULES.UNSECURED_RESOURCE. Groups the rules under one name; needs checking that member access on a constant mapping is accepted in the annotation.
  4. A separate module of the library, such as ballerina/http.rules: keeps the rules out of the main API, but needs an extra import in every file that suppresses a rule.
Version

0.13.0-SNAPSHOT

Dominant language
Java
Stars
15
Forks
12
Avg merge
12h 17m
Merged PRs (30d)
13

Getting set up

  • No Dockerfile or Docker Compose file
  • Has a pull request template
  • No contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from ballerina-platform/static-code-analysis-tool

All issues in ballerina-platform/static-code-analysis-tool

Similar issues

More Java issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.