codesonar_gerrit_citool.py : Check Methods for -check

The analysis results can be "checked" for a variety of conditions. When a check specified with -check fails, the codesonar_gerrit_citool.py command will exit with a non-zero exit code. You can specify this exit code -fail-code.

There are several available check varieties. Most of these varieties inspect various properties of the warnings that CodeSonar has issued about potential weaknesses in the analyzed code; one variety applies to alerts about problems that have arisen with the CodeSonar build/analysis.

• -check alert [+<MESSAGE>] [+-<MESSAGE>] [+color=<COLORS>]
• -check warning [+columns=<COLUMNS>] [+tolerance=<N>] [+rows=<M>]
• -check warning-class [+<CLASS>] [+tolerance=<N>] [+rows=<M>]
• -check warning-priority [+<PRIORITY>] [+tolerance=<N>]
• -check warning-severity [+<SEVERITY>] [+scale=<SCALE>] [+tolerance=<N>]

When -summary is specified, the exported summary will contain a section for each check specified with -check.

-check alert [+<MESSAGE>] [+-<MESSAGE>] [+color=<COLORS>]

Check for the presence of alerts on the analysis. Alerts may signal problems with the analysis which may make the entire analysis invalid.

Argument	Default	Description	Can specify multiple times?
+<MESSAGE>	only alerts of the specified colors	An alert message to specifically include in this check.	YES
+-<MESSAGE>	none	An alert message to specifically exclude from this check.	YES
+color=<COLORS>	RED if no +<MESSAGE> arguments, none otherwise	Include all alerts of the specified <COLORS>: a comma-separated list of alert color names. Accepted alert color names are: {RED, YELLOW, BLUE, GREEN}.	no

For more information on alerts, see the CodeSonar manual: MANUAL: Using CodeSonar > GUI Reference > Alerts

Default alert check

If no explicit -check alert [...] is specified, the command will perform the default alert check, which is equivalent to:

-check alert +color=RED

Examples

• Example 1. No explicit -check alert [...] is specified. The default alert check is performed, and will fail if the analysis has issued any red alerts.

• Example 2. The following check is explicitly specified with no optional arguments, so defaults are used. The check will fail is the analysis has issued any red alerts.

  -check alert
  

  • There is no +color argument: the default setting of RED is used because there is also no +<MESSAGE> argument.
  • Because an explicit -check alert [...] is specified, the default alert check is not performed.

• Example 3. The following check always trivially passes.

  -check alert +color=
  

  • There is no +<MESSAGE> argument and the +colors argument is explicitly set to the empty list: there is nothing to check.
  • Because an explicit -check alert [...] is specified, the default alert check is not performed.

• Example 4. The following check will fail if the analysis issues any red or orange alerts other than "Bad File System".

  -check alert +colors="RED,ORANGE" +-"Bad File System"
  

  • Because an explicit -check alert [...] is specified, the default alert check is not performed.

• Example 5. The following check will fail if the analysis issues any "Analysis Stuck (No Slaves)" or "Analysis Stalled" alerts.

  -check alert +"Analysis Stuck (No Slaves)" +"Analysis Stalled"
  

  • Because an explicit -check alert [...] is specified, the default alert check is not performed.

-check warning [+columns=<COLUMNS>] [+tolerance=<N>] [+rows=<M>]

Did the analysis issue too many warnings?

Argument	Default	Description	Can specify multiple times?
+tolerance=<N>	0 (zero)	The check will fail if the analysis issued more than <N> warnings	no
+columns=<COLUMNS>	"score,class,file,lineNumber"	If -summary is specified, the summary section corresponding to this check will include the specified columns in the specified order. <COLUMNS> is a comma-separated list of column names. Accepted column names are: {id, class, score, file, lineNumber, procedure}. If -summary is not specified, this argument has no effect.	no
+rows=<M>	10	If -summary is specified, the summary section corresponding to this check will include a maximum of <M> rows. If -summary is not specified, this argument has no effect.	no

Examples

• Example 1. No optional arguments are specified, so defaults are used: the following check will fail if the analysis reported any warnings (after search options are applied). If -summary is specified, the summary section corresponding to this check will have columns score, class, file, lineNumber (in that order), and a maximum of 10 rows.

  -check warning
  

• Example 2. The following check will fail if the analysis reported more than 10 warnings (after search options are applied). If -summary is specified, the summary section corresponding to this check will have columns id,class, and score (in that order), and a maximum of 20 rows.

  -check warning +tolerance=10 +rows=20 +columns="id,class,score"
  

-check warning-class [+<CLASS>] [+tolerance=<N>] [+rows=<M>]

Did the analysis issue too many warnings of the specified warning classes?

Argument	Default	Description	Can specify multiple times?
+<CLASS>	all warning classes are considered	Name of a warning class to include when counting warnings for this check.	YES
+tolerance=<N>	0 (zero)	The check will fail if the analysis issued more than <N> warnings of the specified warning classes. If any search options are specified, this count considers only warnings that meet the specified search conditions.	no
+rows=<M>	unlimited	If -summary is specified, the summary section corresponding to this check will include a maximum of <M> rows. If -summary is not specified, this argument has no effect.	no

Examples

• Example 1. No optional arguments are specified, so defaults are used: the following check will fail if the analysis reported any warnings (after search options are applied) of any class. If -summary is specified, the summary section corresponding to this check will have an unlimited number of rows.

  -check warning-class
  

• Example 2. The following check will fail if the analysis reported more than 1 warning (after search options are applied) of class "Leak" or "Buffer Overrun". If -summary is specified, the summary section corresponding to this check will have at most one row.

  -check warning-class +Leak +"Buffer Overrun" +tolerance=1 +rows=1
  

-check warning-priority [+<PRIORITY>] [+tolerance=<N>]

Did the analysis issue too many warnings with the specified priorities?

Argument	Default	Description	Can specify multiple times?
+<PRIORITY>	"P0: High"	Name of a warning priority to include when counting warnings for this check. The specified <PRIORITY> must be the name of a priority that is defined on the hub.	YES
+tolerance=<N>	0 (zero)	The check will fail if the analysis issued more than <N> warnings with one of the specified priorities. If any search options are specified, this count considers only warnings that meet the specified search conditions.	no

Examples

• Example 1. No optional arguments are specified, so defaults are used: the following check will fail if the analysis reported any warnings (after search options are applied) with priority "P0: High".

  -check warning-priority
  

• Example 2. The following check will fail if the analysis reported more than 5 warnings (after search options are applied) with priority "P0: High" or "P2: Medium".

  -check warning-priority +"P1: High" +"P2: Medium" +tolerance=5
  

-check warning-severity [+<SEVERITY>] [+scale=<SCALE>] [+tolerance=<N>]

Did the analysis issue too many warnings with scores in the specified severity classes?

Argument	Default	Description	Can specify multiple times?
+<SEVERITY>	High	Name of a severity class to include when counting warnings for this check. With the default +scale setting, the available classes are {High, Medium, Low}.	YES
+scale=<SCALE>	"Low:21:Medium:56:High"	Defines the set of severity classes to use for this check, as a list of severity class names alternating with warning score threshold values separated by a colon (:). The default setting specifies that "Low" severity class contains warnings with score 0-21, "Medium" is 21-56, and "High" is 56-100.	no
+tolerance=<N>	0 (zero)	The check will fail if the analysis issued more than <N> warnings have scores that fall into the specified severity classes. If any search options are specified, this count considers only warnings that meet the specified search conditions.	no

Examples

• Example 1. No optional arguments are specified, so defaults are used: the following check will fail if the analysis reported any warnings (after search options are applied) with score >= 56.

  -check warning-severity
  

• Example 2. The following check will fail if the analysis reported more than 6 warnings (after search options are applied) with score > 50.

  -check warning-severity +extreme +bad +scale="ok:20:moderate:50:bad:80:extreme" +tolerance=6
  

---