In this section

Introduction

If you are using an analyzer that is not natively supported by the Parasoft Multi-Language Pack, you can transform your tool's static or metrics analysis results into a CSV file and use the CSV Importer extension to process the data and send it to Parasoft DTP. DTP displays the results in widgets and dashboards alongside other data points. The integration also adds scope, authorship, and source control support that further enhance the imported results. Additionally, the extension generates a Parasoft report that shows violations for each author and severity.

Requirements

• Supported operating systems: Windows, macOS, Linux
• The JAVA_HOME environment variable must be set and pointing to your Java installation folder
  
• A CSV file containing static analysis or metrics analysis run data. Refer to Expected Formats for details about how the data should be structured.   
• A CSV file containing rule information for the violations. Refer to Expected Formats for details about how the data should be structured, file encoding, and other details.

Usage

1. If you have not already done so: 
   1. Execute your static or metrics analysis tool and format the results into a CSV file as specified in the Expected Formats section.
   2. Format your analysis tool's rule file into a CSV file as specified in the Expected Formats section.  
2. Open a command prompt and navigate to the Parasoft Multi-Language Pack installation root directory.
3. Execute the multilanguage-pack.bat or multilanguage-pack.sh script with the required parameters all on one line, e.g.: 

multilanguage-pack.bat -tool csvimporter -results.file "C:\somePath\static-analysis-violations.csv" -source.dir "C:\somePath\sourceDir" -rules.file "C:\somePath\rules-definitions.csv" -analysis.type static_analysis 

Internal technical log files from the Multi-Language Pack execution are generated in the <INSTALL>/.mlp subdirectory.

Required Parameters

The following settings are required.

tool

This setting specifies the Parasoft extension to execute. Use -tool csvimporter to run the CSV Importer extension.

results.file

Specifies the path to the static or metrics analysis results file. Refer to Expected Formats for details about how to format your results file so that the CSV Importer extension can process your data. 

source.dir

Specifies the path to the folder containing the source code for which the analysis results were created. This value is used to collect source control metadata (e.g., authorship, last updated, etc.) for Parasoft DTP.

rules.file

Specifies the path to the analysis rules file. Refer to Expected Formats for details about how to format your results file so that the CSV Importer extension can process your tool's rules. 

analysis.type

Specifies the type of results. Possible values are static_analysis and metrics. For example:

-analysis.type=metrics

Expected Formats

This section describes the formats expected by the CSV Importer, as well as requirements for the CSV file.

CSV File Requirements

• Files must be encoded in Unicode UTF-8 and have the CSV file extension.
• The only acceptable delimiter is a comma.
• All fields are character fields.
• If the field contains a comma, either wrap it with quotation marks or escape the comma.
• The first line or row of each file is a header line. Header strings should not have spaces or characters that need escaping.
• Any headers or columns that are not relevant to the extension tool are ignored.
• A column does not have to be present if the field is optional. 

Static Analysis Violation Results Format

The static analysis results file is specified with the results.file parameter during execution. The results file must contain the following columns.

filename

Specifies the file name where the violation occurred. Values in this column can be absolute or relative paths to the project directory specified with the source.dir parameter during execution, e.g., warships.ts. 

ruleid

Defines the rule ID column. These values must match the ruleid values in the CSV rule file. 

startline

Values in this column indicate the line where a violation started. 

startcolumn

Values in this column indicate the column where a violation started.  

endline 

This column is optional. Values in this column indicate the line where the violation ended. If not specified, the value in the startline column is assumed. 

endcolumn

This column is optional.  Values in this column indicate the column where the violation ended. If not specified, the last column of the the start line is assumed. 

message

This column contains short messages about each violation, e.g., forbidden var keyword. 

The following static analysis results file shows two violations in a file called warship.ts: 

filename,ruleid,startline,startcolumn,endline,endcolumn,message
warship.ts,no-var-keyword,14,8,14,11,forbidden var keyword
warship.ts,semicolon,265,40,265,40,missing semicolon

Static Analysis Rule Description Format

A rule file specifies rule details (category, severity level, etc.). This is the file that you specify with the rules.file parameter during execution.

Your rule file should contain the following columns. The order of the columns has no impact and any columns that are not needed will be ignored.

category

Defines the rule category column. We recommend using the original static analysis tool’s rule scheme prefixed with the analyzer name, e.g.,  <analyzer_name>.<category_name><sub_category_name...>. 

An example entry in this column is TSLint.TypeScript

ruleid 

Defines the rule ID column. This may be the same as the rule name or an identifier used by the analyzer (e.g., member-access).

rulename

Defines the column containing the names of the rules (e.g., member-access).

severity

Defines the column containing the severities for each rule. Parasoft severities range from 1 (highest) to 5 (lowest).

ruledoc_url (Optional)

The CSV Importer generates HTML documentation files during execution and saves them in the <Multi-Language_Pack_INSTALL>/ruledocs/csvimporter directory. You can copy the files to the <DTP_HOME>/tomcat/webapps/grs/rulesdoc directory so that the DTP Violations Explorer shows rule documentation in the Documentation tab (also see Third-party Analyzer Rule Documentation).

Specify a URL in this column to include a link to the third-party rule documentation. The URL is added to the generated documentation files copied to DTP.

If the column header is not included or if there are no entries under the column, no documentation will be generated. The extension, however, will still execute properly. 

The HTML template file (doc-template.html) used to generate the contents of the HTML documentation files is located in the <Multi-Language_Pack_INSTALL>/example/CSVImporter directory. You can edit this file to customize the content of the generated rules documentation files.

Example Rule Map File

The following is an example rule file based on the TSLint analyzer. Each entry between the spaces is entered as a single line without any line breaks.

category,ruleid,rulename,severity,ruledoc_url
TSLint.TypeScript,member-access,member-access,1,https://palantir.github.io/tslint/rules/member-access/
TSLint.TypeScript,member-ordering,member-ordering,2,https://palantir.github.io/tslint/rules/member-ordering/

Metrics Analysis Rule File Format

A metrics analysis rule file specifies rule details (rule ID, levels, etc.). This is the file specified with the rules.file parameter during execution.

Your rule file should contain the following columns; note that the order of the columns has no impact and any columns that are not needed will be ignored. 

metricid 

The metric ID must be unique and should not override any IDs that are already defined in DTP. Otherwise, metric in the file will overwrite the built-in metrics in DTP. To review the metrics available in DTP, go to http://<DTP URL>/grs/apidoc/ and use /metrics/types to query all available metrics.

metric_names

Defines the localized metric names. Make sure to escape any commas and semicolons inside of the name value.

To define multiple languages, use the format <locale>=<name>;<local>=<name>. For example, en=Gather how many lines of source code;jp=<Japanese translation>;cn=<Chinese translation>.

metric_levels

Defines the level of metrics that will be collected and aggregated. This column contains multiple levels separated by semicolons.

Only the following case-sensitive values are allowed: 

• module: Project/module level
• namespace: Package/namespace/directory level
• type: Class level
• resource: file level
• method: Method or function level

Example:

module;namespace;type;method

module;namespace;type

metric_level

Defines the default metric level to be used when the metric is reported to DTP. Only one of the following three levels can be set and reported to DTP server:

• type
• resource
• method

aggregates

Defines how metrics results are aggregated at each level. This column contains multiple aggregate values separated by semicolons. The following case-sensitive values are allowed: AVG, MIN, MAX, SUM. For example:

AVG;MIN;MAX;SUM

AVG

MIN;MAX

default_aggregate

Defines the default aggregation method used when reporting to DTP. Only one of the aggregates values should be used.

The following is an example rule file. Each entry between the spaces is entered as a single line without any line breaks.

metricid,metric_names,metric_level,metric_levels,default_aggregate,aggregates
METRIC.CC1,en=McCabe Complexity,type,namespace;type;method,MAX,AVG;MIN;MAX;SUM
METRIC.CC2,en=McCabe Complexity,resource,module;resource,MIN,AVG;MIN;MAX;SUM

Metrics Analysis Results Format

The metrics results file is specified with the results.file parameter during execution. This section describes the columns expected in the metrics results file. All column headers are case sensitive. The order of the columns, however, has no impact. 

filename

Specifies the file name where a metrics violation occurred. Values in this column can be absolute or relative paths to the project directory specified with the source.dir parameter during execution, e.g.,  warships.ts. 

Examples:

INCORRECT: C:\project\ABCD\foo\bar\Test.java

OK: foo/bar/Test.java (assuming the project root is C:\project\ABCD)

OK: src/main/java/com/parasoft/xtest/analyzer/csvanalyzer/CSVAnalyzer.java

metricid

Specifies the metric ID. These values must match the metricid values in the CSV rule file. 

value

Values of the metrics for the file reported; should be a number (double number type).

module

Name of the module or project.

namespace

This column contains values that are either the package name (Java), namespace (C++/C#), or directory path (in other languages) to the source. For example, for Java, a value may be com.parasoft.xtest.analyzer.csvanalyzer

type

Either the class (in Object Oriented Languages) or file name. For example, CSVAnalyzer.

method

Name of the method with the parameter signature. For example, processReport(String, String).

To ensure proper aggregation, be sure to use a consistent method value across all instances of a metric.  If one metric row uses processReport(), another row for that metric should not use processReport(String, String).

startline

Values in this column indicate the starting line for the metric. For method-level, the value should point to where the line starts for the method. For type-level, it should be 0. 

startcol

Values in this column indicate the starting column for the metrics. For method-level, the value should point to the column where the method starts. For other levels, it should be 0.  

endline

Line where the reported metric ends. For method-level, it should point to the line where the method ends. For type-level, it should be 0 or the end of the line for the file.

endcol

Position where the reported metric ends. For method-level, it should point to the column where methods ends. For others, it should be 0.

The following is an example results file for metrics analysis.

filename,metricid,value,module,namespace,type,method,startline,startcol,endline,endcol
cart.ts,METRIC.CC1,5,com.analyzers.CSVImporterTests,com.analyzers.csvimporter,CSVImporterTest,,1,0,221,4
cart.ts,METRIC.CC2,10,com.analyzers.CSVImporterTests,com.analyzers.csvimporter,CSVImporterTest,,1,0,221,4