Rules

Rules allow you to define practices that you would like to follow or enforce in your process workflow. When a deviation from a defined practice is reported, a finding is created in Squore. Three types of rules can be defined: mapped, computed and standard rules.

Mapped rules

Mapped rules allow to define a mapping between the coding practices defined in third party tools[1] and Squore practices details and configuration.

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 rule.

  • targetArtefactTypes (mandatory) defines the types of artifacts this rule applies to. For more information about artifact types, consult Artifact Types.

  • toolName (optional, default: empty) is the name of the tool, e.g. FindBugs, SQuORE, PC-lint Plus that is normally responsible for checking this rule.

  • 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 artifact in the artifact tree. Manual findings can be added by users with the required permissions via a menu in the Artifact Tree.

Computed rules

Computed rules allow you to define your own practices, coding or otherwise, and 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 rule.

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

  • targetArtefactTypes (mandatory) defines the types of artifacts this computation applies to. For more information about artifact types, consult Artifact 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.

Standard rules

Standard rules allow you to define a set of practices that will form what is called a standard in Squore.

An example of standard rule definition is provided below:

<StandardRule id="MISRA_C_2004_20_10" categories="MISRA_LEVEL.REQUIRED" artefactTypes="CTYPES;CPP" standard="MISRA_C_2004"/>

The StandardRule element accepts the following attributes:

  • id is the unique identifier of the rule, as used in the properties files.

  • standard is the unique identifier of the standard, as used in the properties files.

  • artefactTypes is the types of artifacts this rule applies to. For more information about artifact types, consult Artifact Types.

  • categories defines the scale level returned by Squore when the rule is violated.

  • excludingTypes allows refining artefactTypes to exclude certain types that may have been included via an alias.

Overriding default rules

A simple way to override a mapped or computed rule (not possible for a standards 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.