Skip to content

Create a plugin with custom rules

Jump to bottom
Felipe Zorzo edited this page Oct 17, 2021 · 20 revisions

WARNING: the documentation below uses the latest API version. If you want the documentation for older releases, please go to:

Index

Creating a new plugin

The easiest way to extend the SonarQube PL/SQL Community plugin with custom coding rules is to grab the template project from there and import in your favorite IDE: https://github.com/felipebz/zpa/tree/3.0.0/plsql-custom-rules

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 with the zpa-toolkit project:

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. A class to execute the tests:

public class ForbiddenDmlCheckTest {

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

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 contain 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).

Migrating a plugin from a previous version

First, update the Maven coordinates:

Old artifact New artifact
org.sonar.plsqlopen:sonar-plsql-open-plugin com.felipebz.zpa:sonar-zpa-plugin
org.sonar.plsqlopen:plsql-checks-testkit com.felipebz.zpa:zpa-checks-testkit

Change sonar-plugin-api version to 7.6.

Then include a dependency on your preferred test framework. The plsql-custom-rules example uses JUnit 5, but you're free to use whatever fits you.

The usage of SSLR was replaced by FLR, which means that most of the previous methods of AstNode won't return a null value anymore. You can use the corresponding "xxxxOrNull" method to return a null value if it's needed. To keep the previous behavior you'll need to:

Replace... By...
getToken getTokenOrNull
getParent getParentOrNull
getNextAstNode getNextAstNodeOrNull
getPreviousAstNode getPreviousAstNodeOrNull
getNextSibling getNextSiblingOrNull
getPreviousSibling getPreviousSiblingOrNull
getFirstChild getFirstChildOrNull
getLastChild getLastChildOrNull
getFirstDescendant getFirstDescendantOrNull
getLastToken getLastTokenOrNull

Official site

Clone this wiki locally