This guide will show you how to import external rulesets into Kiuwan.
- The ruleset import wizard
- Analyzing your code with imported rules
The Models Management in Kiuwan allows importing rule data from different sources.
If you work with PMD, Checkstyle, Findbugs or checKingQA, you can import your rule sets into Kiuwan, use them in your models and analyze your code with your own custom rules.
Open the hamburger menu next to the Rules title and select Import rulesets.
The ruleset import wizard
After clicking the "Import" button, a wizard will appear and will guide you through these steps:
- Selecting a file (Upload a ruleset file).
- Mapping categories (Map user rules categories to CQM values).
- Adding rules to models (Add rules to user's models).
- Preview the import (Import preview).
- Import results.
Selecting a file to import (Upload a ruleset file)
Select a file to upload by clicking the "Upload" button:
You can upload one of these files:
|A PMD ruleset file||When analyzing code with PMD, a unique XML file defines the rules to consider, their metadata and their behavior. Upload a PMD ruleset XML to begin with the import. Rules are mapped to PMD rules. Note that referenced rules or rulesets that belong to external files will not be imported.|
|A Checkstyle configuration file||Checkstyle defines its style checks in an XML configuration file. This file only contains execution parameters. The import wizard will automatically look for the latest Checkstyle version metadata to extract the rule information needed in the import. Just upload a Checkstyle configuration XML to begin with the import. Rules are mapped to Checkstyle checks.|
|A Findbugs plugin JAR file||Findbugs needs various files to define its analysis behavior. These files are usually packed in a JAR file forming a Findbugs plugin. Upload a Findbugs plugin JAR to begin with the import. Rules are mapped to bug patterns.|
|A checKingQA ruleset file||Similarly to PMD, checKingQA uses a unique XML file to define the behavior of an analysis. Upload a checKingQA ruleset XML to begin with the import. Rules are mapped to checKingQA rules.|
If the selected file can be read by the import wizard, a summary of the read data will be shown: the engine detected, the number of categories identified and the rules read.
Although you will be able to import rulesets from newer versions, only rules compliant with the previous library versions can be applied when analyzing. See Kiuwan Local Analyzer to read more about this topic.
Special features when importing checKingQA rulesets
In the previous situation, note that only priority and repair difficulty will be imported. The rule classification under the characteristic criterion will be taken from the library defaults for each rule. This is the reason why you will not see the "Mapping" step when importing rulesets containing only product rules.
Mapping the imported categories (Map user rules categories to CQM values)
Kiuwan needs the imported rules to be classified under CQM categories. In this section, you can map the read categories to CQM values through a simple interface. It is possible that not all rules read are associated with a category. Here you can map these rules to a CQM value as well.
Note that it is not necessary to map all the read categories in the import wizard, but you won't be able to add to a model any rule that is not classified under CQM. You can always classify the rules later accessing the rule details from your library.
Adding the imported rules to existing models (Add rules to user's models)
Once you have configured the CQM mapping, and if you have created at least one model, it is possible to add the imported rules to any of them:
A full CQM mapping is needed in the previous step to be able to add any rule to a model. You can also leave all the models unselected so the rules will only be imported in your account's library.
The preview page (Import preview)
Once you have completed the import configuration, a preview page will be shown.
Here you can see the rules that will be added/modified to your library or models selected. Furthermore, each rule contains information about its CQM value, Priority and the Action to do (Install or Merge).
The results page
Once the import has finished, a results pop-up will be shown:
This pop-up shows the summary result of the import run.
Analyzing your code with imported rules
First, you need to add the imported rules to an existing model (you can have done this with the import wizard already). You can mix any imported rule with the ones already in your library in the same model. To look for imported rules in your library you can select Engine in the filter Engine. This will help you identify which rules come from a PMD, Checkstyle or Findbugs import (checKingQA imported rules will be classified under "Kiuwan" engine value).
Once your model contains imported rules, you need to publish it, and then, you can run your analysis from the Kiuwan Local Analyzer.
You can analyze your code using your own rule implementations from PMD, Checkstyle, Findbugs or checKingQA as long as you add your custom libraries using the Kiuwan local analyzer extension mechanism. Read the Kiuwan local analyzer documentation on how to add custom libraries and how the extension mechanism works.
If your rules are based on the standard rules supplied in the supported versions of PMD, Checkstyle, Findbugs or checKingQA, the Kiuwan Local Analyzer will work out of the box.
- No labels