Adding new rules

The easiest way to extend ZPA with custom coding rules is to grab the template project from there and import in your favorite IDE: https://github.com/felipebz/zpa/releases/download/3.6.0/plsql-custom-rules.zip

The example project can be compiled using Maven or Gradle.

Customizing the pom.xml (if you're using Maven)

You probably want to customize some properties in the pom.xml file.

Properties such as groupId, artifactId, version, name and description can be freely modified.

The sonar-plugin-api dependency represents the minimum version of SonarQube your plugin will support. You also need a dependency on the sonar-zpa-plugin and, optionally, a dependency on zpa-checks-testkit for easier testing.

It is important to note that the sonar-packaging-maven-plugin is required and it contains the entry point of the plugin, as provided in the property pluginClass. If you refactor the code or rename the class extending org.sonar.api.SonarPlugin, you will have to change this configuration.

Customizing the build.gradle.kts (if you're using Gradle)

You probably want to customize some properties in the build.gradle.kts file.

Properties such as group, version and description can be freely modified.

The sonar-plugin-api dependency represents the minimum version of SonarQube your plugin will support. You also need a compileOnly dependency on the sonar-zpa-plugin and, optionally, a testImplementation dependency on zpa-checks-testkit for easier testing.

It is important to note that you'll may need to update the values in attributes map of the jar task.

Creating the repository

SonarQube groups the rules in repositories, so we need to declare a repository first. You can just change the repository key and name in the PlSqlCustomRulesDefinition class.

Writing a check

To create a check, you can create a subclass of org.sonar.plugins.plsqlopen.api.checks.PlSqlCheck. You can use the org.sonar.check.Rule and org.sonar.plugins.plsqlopen.api.annotations.ConstantRemediation annotations to configure the check metadata (name, description, key...).

Very often you'll need to override just two methods:

• init(): subscribe to the desired grammar rules
• visitNode(AstNode): analyze the nodes that match the subscribed grammar rules

Suppose you want to write a rule that check for DMLs targeting the USER table. First of all, we need to check the AST to plan how to write the check. The AST can be verified using the ZPA Toolkit:

Let's start subscribing the DML_TABLE_EXPRESSION_CLAUSE rule:

public void init() {
    subscribeTo(DmlGrammar.DML_TABLE_EXPRESSION_CLAUSE);
}

Every instance of the DML_TABLE_EXPRESSION_CLAUSE rule will trigger the visitNode method. Then we can check if it is a TABLE_REFERENCE to the table named USERS and create a violation indicating the table usage:

public void visitNode(AstNode node) {
    AstNode table = node.getFirstChildOrNull(DmlGrammar.TABLE_REFERENCE);

    if (table != null && table.getTokenOriginalValue().equalsIgnoreCase("user")) {
        addIssue(table, "Replace this query by a function of the USER_WRAPPER package.");
    }
}

After create the rule, you need to add it to the check list.

Testing the check

To test your check you only need two files.

1. A class to execute the tests:

public class ForbiddenDmlCheckTest {

    @Test
    public void test() {
        PlSqlCheckVerifier.verify("src/test/resources/forbidden-dml.sql", new ForbiddenDmlCheck());
    }
    
}

2. And the corresponding sql file:

select * 
  from user u; -- Noncompliant {{Replace this query by a function of the USER_WRAPPER package.}}
--     ^^^^

The -- Noncompliant comment is required to indicate that you are expecting an issue in this line. The double braces contains the message that you expect to see in the SonarQube UI.

Optionally, you can indicate the precise location of the issue using carets (like this example, with carets pointing to the "user" word).

Deploy the plugin

Just build the plugin and copy the .jar file created in the target directory to the SonarQube server (SONARQUBE_HOME/extensions/plugins).