This guide will help you through the process of creating a custom rule for Kiuwan.
If you are looking for a quick tutorial on how to execute a custom rule analysis in Kiuwan, please check the Quick start guide page.
You can read more detailed information on this topic in the Rule Development Manual, included in the Kiuwan Local Analyzer bundle, under the /development folder.
A rule for Kiuwan is a program that performs static analysis over the source code. How does this work?
As the diagram shows, the source code passes through a process named parsing to obtain an object called AST (Abstract Syntax Tree) which is a representation of the abstract syntactic structure of source code written in a programming language.
Each node of the tree denotes a construct occurring in the source code, so your rule has to travel among those nodes searching for the conditions which represent a violation of a certain good coding convention.
A rule is nothing more than a Java class which must accomplish the following rules:
- Extend AbstractRule (com.als.core.AbstractRule).
For some technologies, there are more concrete abstract rule classes to extend from: com.als.cobol.rules.AbstractCobolRule, com.optimyth.sql.rules.AbstractSqlRule… Each one of them extends from com.als.core.AbstractRule.
- Implement an initialize method.
This is where you can recover the values of the properties to customize your rule analysis. This method will be executed just once per launched analysis.
- Implement a visit method.
This is where the main functionality of the rule is placed. This method will be executed one time per analyzed file.
- Implement a post-process method.
This is where your rule can perform actions on information retrieved during the analysis of each file. This method will be executed just once per launched analysis.
- Report a RuleViolation (com.als.core.RuleViolation) in the RuleContext (com.als.core.RuleContext).
By using the APIs provided you can traverse the AST in a variety of different ways. For further information, please check the Rule Development Manual, section "API Alternatives", under the developer folder in the Kiuwan Local Analyzer distribution.
- Abstract Syntax Tree (low-level and high-level) API.
- NavigableNode / TreeNode API.
- XPath rules.
- Query API.
There are additional static analysis facilities also available*. For further information, please check the Rule Development Manual, section Additional Static Analysis facilities, under the developer folder in the Kiuwan Local Analyzer distribution.
- Control-flow graph (CFG) and data-flow analysis.
- Library metadata.
- Tainting propagation.
- Local / Global Symbol Table.
(*) Check the specific coverage of these facilities by language.
Let's get started!
The best way to get to know the API is by developing your first rule. We are going to implement a rule which is described as follows:
When developing java source code, there should not be defined methods with more than four parameters.
First of all, you will need an example of a violation of the convention set for the chosen programming language. This is usually a short example of how to code against the rule. You will need the same example with fixed violations as well. Once you have both code fragments, you can parse them using Kiuwan Rule Developer and then explore the AST corresponding to the code. For this example, we will condense a violation and a fix in the same Java class:
You can copy and paste this code into the Test Source Code tab in Kiuwan Rule Developer and click Generate AST. An Abstract Syntax Tree for the java class will be created:
When you have the AST, you can develop the best approach to traverse the nodes in order to find the way to determine whether there is a violation of the convention in the code or not. For that, there is a basic, very useful way to travel to each one of the nodes: the visitor strategy.
So, applying this strategy to our rule implementation is as simple as:
But what happens if we want to change the maximum number of parameters allowed in a method? Would we have to recompile the rule? No! We only need to add a parameter to the rule.
The parameter has to be defined in the rule definition (see Creating a rule in Kiuwan Rule Developer Quick start guide), so you can retrieve the value in your rule by using the initialize method.
You can define parameters of different types, as well as define parameters with a regular expression as value or even with a list of possible values.
A word about performance
The rules of thumb to optimize rules:
- Minimize the number of queries to the AST.
- Get the nodes you need and only the ones you need whenever possible.
- Avoid caching AST nodes. When you cache a node you are caching the whole tree.
- DO NOT use global variables (fields)*. Use local variables instead. Rules have to be thread-safe!!
- Take advantage of initialize() and postProcess() methods for unique operations like obtaining the rule’s properties. Both methods are executed just once per rule analysis execution, while visit() is executed once per analyzed file.
- Avoid using “TreeNode.findXXX” and other methods that produce a list of nodes. Instead of that use the visitor strategy.
( * ) Except for representing the properties of the rule. In this case, the value is the same during the rule execution, so you won’t have concurrency problems.
- No labels