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

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.
Open a command prompt and navigate to the Parasoft Multi-Language Pack installation root directory.
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.

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.

Multi-Language Pack > CSV Importer > mlp-cvsimporter-ruledoc_url-col-542.png

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.

The CSV Importer extension will compare the metrics defined in the metrics definition (see rules.file) file with metrics defined in DTP. If a metric is defined in the file but not in DTP, the metric will be added to DTP. If the same metric is defined in both the rule file and DTP, the DTP metric definition (default level, aggregate, etc.) will be updated to match the values from the file.

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.

If the metric rule level is set to RESOURCE or TYPE, the metric row must contain:

module
namespace
type

If the metric rule level is set to METHOD, the metric row must contain the above data, as well as method. Otherwise, the DTP Metrics Explorer won’t display names properly.

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