Apex Checks

Introduction

The apex-checks module represent the rules which are executed on source code and which generate issues in the sonarqube platform as seen in this picture.

Rules

The rules are visitors to navigate through an AST looking for errors.

Rules Details

Each rule has a number of details that help the user to resolve the error, for example:

How to create a custom rule

Create unit test

To test checks SourceFile instance is needed. The ApexAstScanner.scanFile method used to create a SourceFile from a File and a Check.

@Test
public void testCustomCheck() {
    File file = new File("src/test/resources/checks/Book.cls");
    CustomCheck customCheck = new CustomCheck();
    SourceFile sourceFile = ApexAstScanner.scanFile(file, customCheck);
    ...
}

Now it verified that there is a violation in a particular line by CheckMessagesVerifier.verify method.

@Test
public void testCustomCheck() {
    ...
    CheckMessagesVerifier.verify(sourceFile.getCheckMessages())
                .next().atLine(2).withMessage(ERROR_MESSAGE)
                .next().atLine(5).withMessage(ERROR_MESSAGE)
                .noMore();
}

ERROR_MESSAGE must be equal to that of violation message issued by custom check

noMore() method is used when there is no more checks at source.

Extends of SquidChecks<Grammar>

To create a custom rule is necessary extends a class of SquidCheck<Grammar> and override the following methods:

init This method defined in which AST node the analysis will be performed by suscribeTo method.

@Override
public void init() {
    subscribeTo(RuleKey.METHOD_DECLARATION);
}

visitNode This method is executed when found the node declared at the beginning. It also allows to declare an issue when it's not completed the condition of the rule by createLineViolation method.

@Override
public void visitNode(AstNode astNode) {
    if (isDeprecated(astNode)) {
        getContext().createLineViolation(this, ERROR_MESSAGE, astNode);
    }
}

Defines settings for checks

To define settings for checks it is necessary to create a json file with CHECK_KEY as name with .json extension

For example CHECK_KEY = "A1002", then file name would be "A1002.json", this file should have the following schema:

{
  "title": "here goes the title",
  "status": "ready",
  "remediation": {
    "func": "Constant\/Issue",
    "constantCost": "5min"
  },
  "sqaleSubCharacteristic": "INSTRUCTION_RELIABILITY",
  "tags": [
    "suspicious",
    "cert"
  ],
  "defaultSeverity": "Major"
}

status this parameter can be 'ready', 'deprecated', 'beta'.

sqaleSubCharacteristic Specifies the type of sub characteristic that Squale method used. For more information go to this page.

constantCost is the estimated time to solve this issue expressed in minutes.

tags are to classify and filter checks in sonar they may have more than one tag separated by comma, the list of available tags are here.

defaultSeverity this parameter can be 'Blocker', 'Critical', 'Major', 'Minor', 'Info'.

In check class add an annotation @Rule and write the key for this check.

@Rule(key = MethodNameCheck.CHECK_KEY)
public class MethodNameCheck extends SquidCheck<Grammar> {

Defines html description page

The html description should be named the same as the key of the rule.

This file contains a more detailed description of the rule, because of the problem and how to fix it.

Load Checks

Now, you must add ClassType of your check in ChecksList class.

public static List<Class> getChecks() {
    return ImmutableList.<Class>of(
            AssertMethodCheck.class,
            ClassNameCheck.class,
            ...

            YourCustomCheck.class

            ...
            TestMethodCheck.class);