Rules

Rules are a specific type of measure. They do not return a numeric value like other measures, but the location within the source code where the rule was broken.

We can define two types of rules in Squore: mapped and computed rules.

Mapped rules

In Squore, a mapping between the rules defined in the external tools^[1] that provide the compliance measure and internal concepts (and properties files) is required.

An example of mapped rule definition is provided below:

<Measure measureId="R_NOGOTO" type="RULE" categories="SCALE_SEVERITY.REQUIRED;SCALE_PRIORITY.HIGH" families="REQUIRED;ANALYSABILITY;MISRA;CF;STRP" targetArtefactTypes="FUNCTION" />

The Measure element of a mapped rule accepts the following attributes:

measureId is the unique identifier of the rule, as used in the properties files.
type is always set to RULE for rule measures.
categories defines the scale level returned by Squore when the rule is violated.
families the families associated with the measure.
targetArtefactTypes is the type of artefact targeted by this definition. For more information about artefact types, consult Artefact Types.
toolName (optional, default: empty) is the name of the tool, e.g. FindBugs, SQuORE, CPPTEST that submitted this metric, to be displayed in the Findings tab. It is generally only specified when you are defining a metric as a rule that will trigger a finding.
toolVersion (optional, default: empty) is the tool version displayed together with the toolName in the Findings tab.
manual (optional, default: false) is used when you want to define a rule that can be added manually to an artefact in the artefact tree. Manual findings can be added by users with the required permissions via a menu in the Artefact Tree.

Computed rules

It is also possible to define computed rules in order to take advantage of measures and indicators computations made in Squore.

An example of computed rule definition is provided below:

<Measure type="RULE" measureId="COMPLEX_MODULES">
   <Condition targetArtefactTypes="MODULES" test="VG&gt;10" />
</Measure>

The Measure element of a computed rule accepts the following attributes:

measureId is the unique identifier of the rule, as used in the properties files.
type is always set to RULE for rule measures.
categories defines the scale level returned by Squore when the rule is violated.
families the families associated with the measure.

The Condition element will help you define the computation for the rule. It accepts the following attributes:

targetArtefactTypes is the type of artefact targeted by this definition. For more information about artefact types, consult Artefact Types.
test is the computation for the rule. Only simple computation syntax is supported, no queries.

Multiple Condition elements can be defined for the same computed rule, following the classic inheritance strategy.

Overriding default rules

A simple way to override a rule that is defined somewhere in your model is to use an UpdateRules section in your Analysis bundle:

<UpdateRules>
	<UpdateRule measureId="R_NOGOTO" disabled="true" categories="SCALE_SEVERITY.CRITICAL"/>
</UpdateRules>

This syntax allows you to import a ruleset from the Shared folder and modify some of the rules if they do not fit your target model.

The UpdateRules element takes one or more UpdateRule elements where you need to define:

measureId (mandatory) is the ID of the rule you are overriding
disabled (optional, default: false) lets you specify that the rule should be turned off in your model when set to true
categories (optional, default: no override) allows adding new categories or adjusting existing categories for a rule

Building rulesets

A common use case when building a model for Squore is to define metrics that compute the rule compliance of your project. The rule compliance metric is generally a ratio of rules checked versus rules violated in a project.

Squore only takes into account the rules that are provided by Data Providers used in the current analysis to compute the rule compliance metrics.

This feature requires that you organise your rules into packages that declare which Data Provider checks them. This can be achieved with the use of a Package element with a providedBy attribute in your model. The following example is taken from the FindBugs ruleset:

<SQUORE_HOME>/configuration/models/Shared/data_provider/findbugs/ruleset.xml

<Package providedBy="Findbugs;Findbugs_auto">
	<Measure measureId="AT_OPERATION_SEQUENCE_ON_CONCURRENT_ABSTRACTION" type="RULE" targetArtefactTypes="JAVA" .../>
	<Measure measureId="BC_BAD_CAST_TO_ABSTRACT_COLLECTION" targetArtefactTypes="JAVA" .../>
...
</Package>

By specifying providedBy="Findbugs;Findbugs_auto", you instruct Squore to count this rule as a coding standard only if the analysis used Findbugs or Findbugs_auto. All rules in this package are ignored when this is not the case.

The value of the providedBy attribute is the name of the folder in configuration/tools that contains the Data Provider’s form.xml. You can also provide a ruleset standard identifier corresponding to what you defined in your Data Providers with the provide attribute.

Internally, this means that all queries reporting a rule count (COUNT RULE(<scope>) FROM … WHERE …) in your model ignore rules inside a package provided by a Data Provider that was not part of the analysis.

The UI is also impacted and displays only the subset of matching rules in the following locations:

The list of rules in the Rules Edition step of the project wizard
The Project ruleset list of findings in the Explorer

This behaviour is applied by default, unless you disable it for your entire installation by adding the following line to your main properties.xml:

configuration/properties.xml

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<Bundle version="1.2">
    ...
    <!-- Configuration options -->
    <option name="configuration.models.useProvidedBy" value="false"/>
</Bundle>

1. Many Data Providers provide rule compliance measures: CheckstyleCheckstyle, CheckerChecker, FindBugsFindBugs, etc.