README.md

Sample plugin that defines SonarQube custom rules for CSS, SCSS and Less files

Description

The SonarQube CSS / SCSS / Less Analyzer can be enhanced by writing custom rules through a plugin using SonarQube CSS / SCSS / Less API. This sample plugin is designed to help you get started writing your own plugin and custom rules.

Usage

1. Download and install SonarQube 6.7 or greater
2. Install the SonarQube CSS / SCSS / Less plugin (4.13 or greater) by a direct download
3. Install this sample plugin by a direct download
4. Start SonarQube
5. Activate some of the custom rules implemented in this sample plugin. "Forbidden properties should not be used" for example.
6. Install your favorite scanner (SonarQube Scanner, Maven, Ant, etc.)
7. Analyze your code
8. Browse the issues through the web interface

Writing Custom Rules

Creating a SonarQube Plugin

• Create a standard SonarQube plugin from scratch or start from this sample plugin
• Attach this plugin to the SonarQube CSS / SCSS / Less plugin through the POM:
  • Add the dependency to the CSS / SCSS / Less plugin
  • Base the plugin on the CSS / SCSS / Less plugin
  • Require a minimal version of the CSS / SCSS / Less plugin
• Implement the following extension points:
  • Plugin as in MyCssCustomRulesPlugin.java
  • RulesDefinition as in MyCssCustomRulesDefinition.java
• Declare the RulesDefinition implementation as an extension in the Plugin extension point.

Implementing a CSS Rule

• Create a class to define the implementation of a rule. It should:
  • Either extend SubscriptionVisitorCheck or DoubleDispatchVisitorCheck.
  • Define the rule's attributes: key, name, priority, etc.
• Declare this class in the class implementing RulesDefinition

There are two different ways to browse the AST:

Using DoubleDispatchVisitorCheck

To explore part of the AST, override a method from DoubleDispactchVisitor. For instance, if you want to explore property nodes, override DoubleDispactchVisitor#visitProperty. This method is called each time a key node is encountered in the AST. Note: When overriding a visit method, you must call the super method in order to allow the visitor to visit the children of the node. See ForbiddenPropertiesCheck for example.

Using SubscriptionVisitorCheck

To explore part of the AST, override SubscriptionVisitor#nodesToVisit by returning the list of Tree#Kind nodes you want to visit. For instance, if you want to explore URI content nodes the method should return a list containing Tree#Kind#URI_CONTENT. See ForbiddenUrlCheck for example.

Creating Issues

Precise issue or file issue or line issue can be created by calling the related method in Issues.

Testing

Testing is made easy by the CssCheckVerifier. There are two ways to assert that an issue should be raised:

• Through comments directly in the .css test file
• Or using assertions in the check class test

Examples of coding rule implementation and testing can be found in the CSS plugin css-checks module.

Implementing an SCSS Rule

The same as "Implementing a CSS Rule" applies. But, instead, look at:

• MyScssCustomRulesDefinition
• InterpolatedPropertiesCheck

Implementing a Less Rule

The same as "Implementing a CSS Rule" applies. But, instead, look at:

• MyLessCustomRulesDefinition
• InterpolatedPropertiesCheck

Make a rule apply to CSS and SCCS and Less

Just add the rule to MyCssCustomRulesDefinition and MyScssCustomRulesDefinition and MyLessCustomRulesDefinition