Including Kotlin Components in a CodeSonar Project with codesonar kotlin

JavaScript is not currently enabled, but is required for full CodeSonar manual search and browse functionality.

If you are viewing this file in your hub's Web GUI, enable JavaScript in your browser: you will also need it for GUI functionality.

If you opened this file directly from disk, your browser may be directly suppressing JavaScript functionality: certain browsers perform this suppression on local files (but not files delivered by web servers) for security reasons.

If you access the manual through the hub's Web GUI, the functionality will not be suppressed because the hub is a web server.
Alternatively, your browser may allow you to explicitly disable the security setting that suppresses functionality. See the CodeSonar FAQ for more information.

CodeSonar^® 9.2p0

CONFIDENTIAL

CodeSecure Inc

General

Third-Party Included

Including Kotlin Components in a CodeSonar Project with codesonar kotlin_scan.py

This page describes how to extend your CodeSonar-facing build so that your CodeSonar project includes:

the Kotlin source files involved in your regular software build, and
analysis results for those files, produced by the Kotlin detekt analyzer.

If your Kotlin project targets the JVM you can also analyze it with cs-java-scan, which will produce warnings from a subset of the Java warning classes.

Overview
Including Kotlin Components In Your CodeSonar Project
Warning Classes
codesonar kotlin_scan.py
Example Makefile
Try the Example Makefile
Related Links

Overview

This page describes how to extend your CodeSonar-facing build so that your CodeSonar project includes:

the Kotlin source files involved in your regular software build, and
analysis results for those files, produced by the Kotlin detekt analyzer.

Incorporating Kotlin components follows the standard process for including a tier 3 component. The specializations to that process are summarized in the following table. For detailed instructions, see Including Kotlin Components In Your CodeSonar project, below. We also provide an example Makefile.

Language Tools	You do not need a Kotlin compiler in order to run detekt or add source files to your CodeSonar project.
Third-Party Analyzer	Kotlin detekt
Third-Party Analysis Step	You do not need to explicitly invoke detekt: it is invoked in the codesonar kotlin_scan.py subcommand.
Extend CodeSonar-facing Build	Invoke codesonar kotlin_scan.py on your Kotlin source files (.kt, .kts). This will analyze the files with detekt, then add the detekt SARIF results and the source files to the CodeSonar project.

Including Kotlin Components In Your CodeSonar Project

Incorporating Kotlin components follows the standard process for including a tier 3 component.

Install any required language tools, such as compilers.
There is nothing to do for this step. You do not need a Kotlin compiler in order to run detekt or add source files to your CodeSonar project.
Install the third-party analyzer.
You do not need to install detekt for this step, but you do need to identify the detekt installation you will be using and ensure that it can run.
Do you already have a detekt installation?
- Yes: use your existing Kotlin detekt installation. This ensures that detekt results in your CodeSonar project are consistent with results produced elsewhere in your organization.
- No: you can use the the Kotlin detekt analyzer binary that is shipped with CodeSonar: $CSONAR/win32-fetcher/detekt-cli/bin/detekt-cli
  (The binary will be built for the same target as your CodeSonar installation, but is always located under $CSONAR/win32-fetcher/.)
Note that detekt requires a JVM in order to run.
If you do not have a JVM, you can generally use the one shipped with CodeSonar.
Install the third-party SARIF converter, if needed.
There is nothing to do for this step: detekt can produce SARIF output.
Extend the regular build to invoke the third-party analyzer (and SARIF converter, if needed).
You do not need a separate analysis step.
Extend the CodeSonar-facing build.
Extend your CodeSonar-facing build by adding one or more invocations of codesonar kotlin_scan.py.
All the Kotlin source files must be present before codesonar kotlin_scan.py is invoked. Different build systems have different mechanisms for specifying this requirement. For example, you might be able to specify that the CodeSonar-facing build depends on the Kotlin source files, or that the CodeSonar-facing build can only take place if the steps required to produce the Kotlin source files have already occurred.
If you have not already set up a CodeSonar-facing build for your regular software project, you will need to create one.
Perform the CodeSonar build/analysis, observing the entire execution of your CodeSonar-facing build.

Diagram: including Kotlin components in a CodeSonar project

The following diagram illustrates the extended software build described above, and its interactions with the CodeSonar build/analysis.

The CodeSonar-facing build could include the entire regular build, or any part of the regular build, but it does not need to. In particular, it does not need to observe the execution of the Kotlin compiler.
The Kotlin compilation step in the regular build has no consequences for the CodeSonar-facing build, so is displayed with grey arrows and annotations.
We have shown a kotlinc compilation targeting the JVM here, but the situation is the same for other Kotlin compilers and targets.

Diagram illustrating the procedure described on this page: extend a build that executes detekt on Kotlin source files into a CodeSonar-facing build by adding invocations of 'codesonar import_sarif.py' to import the SARIF output from detekt and corresponding Kotlin source files.

Note

In this section (and throughout this manual), $CSONAR indicates the CodeSonar installation directory.

If you have defined environment variable CSONAR to the location of the CodeSonar installation directory, you can use $CSONAR directly in your command lines. On Windows systems, use %CSONAR% in place of $CSONAR.
If you don't want to use environment variables, replace $CSONAR with the path to your CodeSonar installation directory before using the command lines.

Warning Classes

When a SARIF file is imported into a CodeSonar project, the SARIF importer determines an associated warning class for each rule object in the SARIF rules, creating this warning class if it does not already exist.

The SARIF importer has special handling for warning classes derived from SARIF produced by detekt. For more information, see Warning Classes Corresponding to detekt Rules.

codesonar kotlin_scan.py

To analyze Kotlin source files with detekt and then add the source files and analysis results to a project, CodeSonar observes the execution of a command that incorporates one or more invocations of codesonar kotlin_scan.py.

codesonar kotlin_scan.py [file_or_dir ...] [-C rundir, -directory rundir] \
[-include-sources file_pat] [-exclude-sources file_pat] \
[-detekt-cli detekt_path] [-use-external-jdk] [-Xdetekt_options_list] \
[-sarif-output sarif_fname] [-source-max-bytes num] [@infile]

where:

[file_or_dir ...]	is a space-separated list of source file or directory paths. Relative paths are interpreted with respect to the directory specified with -C/-directory. For each file path, that file is analyzed and imported into the CodeSonar project. For each directory path, all .kt and .kts files in the directory tree rooted at that directory are analyzed and imported. The set of files specified with file_or_dir arguments can be modified with -include-sources and -exclude-sources. Note: the file_or_dir arguments are not glob patterns (as used for -include-sources and -exclude-sources). However, your shell may expand patterns into file and directory names. If there are no file_or_dir arguments and no -include-sources arguments, the codesonar kotlin_scan.py subcommand will fail.
[-C rundir] [-directory rundir]	detekt will be run in rundir. If -C/-directory is not specified, detekt will be run in the current working directory. Any file_or_dir, -include-sources file_pat, and -exclude-sources file_pat arguments are interpreted relative to rundir. For example: codesonar kotlin_scan.py . Analyze all .kt and .kts files in the directory tree rooted at the current working directory. codesonar kotlin_scan.py . -C mymod Analyze all .kt and .kts files in the directory tree rooted at directory mymod. codesonar kotlin_scan.py dirA dirB/dirC -C mymod Analyze all .kt and .kts files in the directory tree rooted at directory mymod/dirA and all .kt and .kts files in the directory tree rooted at directory mymod/dirB/dirC
[-include-sources file_pat] [-exclude-sources file_pat]	All Kotlin source files (.kt, .kts) indicated by the -C/-directory and file_or_dir argument combination will be analyzed with detekt. By default, this set of Kotlin source files is then imported into the CodeSonar project. Use -include-sources and -exclude-sources to adjust the imported set by adding or removing files. file_pat is a recursive glob pattern representing a source file path. It matches all files whose file path matches file_pat. Relative paths are interpreted with respect to the directory specified with -C/-directory. When a single codesonar kotlin_scan.py invocation contains a combination of -include-sources and -exclude-sources options, they are applied in the order in which they appear on the command line. Note: Your shell may be configured to expand patterns into file and directory names. If so, make sure you quote the file_pat appropriately to indicate that the shell should pass it through to codesonar kotlin_scan.py. In most cases, this means using single quotes ('); for Windows cmd, use double quotes (").
[-detekt-cli detekt_path]	Specifies the path to the detekt installation to use for analysis. If -detekt-cli detekt_path is not specified, the detekt installation shipped with CodeSonar is used.
[-use-external-jdk]	Specifies that codesonar kotlin_scan.py should invoke detekt using the JDK from the local environment. If -use-external-jdk is specified, codesonar kotlin_scan.py must be invoked in an environment where: JAVA_HOME is set to the JDK installation directory, or the java executable is in the PATH. If -use-external-jdk is not specified, codesonar kotlin_scan.py will try to use the JDK shipped with CodeSonar.
[-X+detekt_options_list]	The +-separated list of options and values in detekt_options_list are passed to the detekt invocation. You can specify multiple detekt options in a single detekt_options_list; you can also specify -X multiple times in a single codesonar kotlin_scan.py invocation. For example, the following are equivalent: both specify that detekt should be invoked with --report+xml detekt_report.xml and --jvm-target 9. codesonar kotlin_scan.py -X+--report+xml:detekt_report.xml+--jvm-target+9 [... remaining kotlin_scan.py options] codesonar kotlin_scan.py -X+--report+xml:detekt_report.xml -X+--jvm-target+9 [... remaining kotlin_scan.py options] Do not use -X to pass detekt options that specify source file inputs. Specify this information directly in the codesonar kotlin_scan.py command with direct file_or_dir arguments, -include-sources, and -exclude-sources.
[-sarif-output sarif_fname]	Specifies that the SARIF output from detekt should be written to file sarif_fname. The primary use case for this option is in projects for which you wish to retain the SARIF results after the CodeSonar build/analysis has finished If -sarif_output sarif_fname is not specified, codesonar kotlin_scan.py will use a temporary file for the SARIF output.
[-source-max-bytes num]	Specifies a maximum size of num bytes for imported Kotlin source files: files larger than this maximum size will be ignored by the importer. If -source-max-bytes is not specified, the importer will ignore files larger than 500KB.
[@infile]	infile is a text file containing a list of arguments to be added to the codesonar kotlin_scan.py command line. Entries must be separated by one or more whitespace characters (including newline). Quoted whitespace is not treated as a separator. The entries will be added to the command line at the location where the @infile argument occurred, in the order in which they appear in infile.

Importing Kotlin source files with codesonar kotlin_scan.py

The codesonar kotlin_scan.py subcommand imports Kotlin source files into the CodeSonar project using the same mechanism as codesonar import_sarif.py, because CodeSonar does not have a full front end for Kotlin.

There are several consequences when files are directly imported with codesonar import_sarif.py.

The CodeSonar analysis checks are not applied to Kotlin source files.
Code Coloring and Interaction are not applied to Kotlin source files when they are displayed in the CodeSonar web GUI.
The Kotlin source files will have file-level IR only. Plug-ins that make use of other IR information will not cover these files.
The Extension API is not available for Kotlin source files. CodeSonar will not recognize or interpret Extension API directives that are present in these files.

Example Makefile

An example Makefile for a Kotlin project is shown below. We also provide an example Makefile for a mixed-language project that has a Kotlin component: see Including Tier 3 Components in a CodeSonar Project: Example Makefile

Unhighlighted rules and targets are those that would be in the Makefile if it only built the regular project.
Rules and targets that are highlighted like this have been added to define a CodeSonar-facing build, which incorporates the detekt analysis.

.PHONY: all clean csonar_facing

all: kotlin_component.jar

# For the sake of this example, target the JVM. The steps required to
# create a CodeSonar-facing build for Kotlin are the same regardless of
# the target platform.
kotlin_component.jar: $(SRCDIR)/kotlin_component.kt
	kotlinc "$(SRCDIR)/kotlin_component.kt" -d kotlin_component.jar

# Invoke codesonar kotlin_scan.py to analyze the Kotlin source code with detekt,
#  then import the SARIF results and the source file into the project.
csonar_facing: $(SRCDIR)/kotlin_component.kt
	"$(CSONAR)"/codesonar/bin/codesonar kotlin_scan.py \
	    "$(SRCDIR)/kotlin_component.kt"

clean:
	rm *.jar

Try the Example Makefile

We have provided a minimal sample project so you can experiment with the example Makefile.

Sign in to a machine where CodeSonar is installed.
Select or create a working directory. The working directory location must be outside both your CodeSonar installation directory and your hub directory.
Save the example files to the working directory (right-click on the link and select Save Target As... or equivalent).
- Makefile.Kotlin.txt
- kotlin_component.kt
cd to the working directory.
Rename the Makefile (this simplifies the CodeSonar analysis command later).
mv Makefile.Kotlin.txt Makefile

Edit Makefile to add a setting for SRCDIR at the top. If CSONAR isn't defined in your environment, set that as well.

SRCDIR=.

SRCDIR=.
CSONAR=path/to/your/codesonar/installation
# on Windows this will be CSONAR=C:\\Program Files\\CodeSecure\\CodeSonar or similar

Make any other required changes. In particular:
- If you are using your own detekt installation, add -detekt-cli detekt_path to the codesonar kotlin_scan.py invocation.
- If you are using your own JDK, add -use-external-jdk to the codesonar kotlin_scan.py invocation.
  Note: for a small number of platforms, the CodeSonar installer does not include a JDK (and the example Makefile will contain a comment noting this). On these platforms you will need to use your own JDK installation, even if you are using the detekt analyzer binary that is shipped with CodeSonar.
Build and analyze the CodeSonar project. If your hub is at the default location, your command will be something like:
codesonar analyze KotlinExample make csonar_facing
For full codesonar analyze command details, see Command Line Build/Analysis.
When the analysis finishes, view the Analysis page in the hub GUI.
- The Warnings tab shows a warning instance for each detekt result. Click any table entry to view the corresponding warning report.
- The Files tab has an entry for the Kotlin source file kotlin_component.kt. You can click on the file name to view a source listing: as noted above, there is no additional source highlighting or navigation.
- There are no entries in the Procedures tab: source files imported with codesonar import_sarif.py have file-level internal representation (IR) only.

Other Targets in the Example Makefile

If you are interested, you can try building other targets in the example Makefile.

Building the kotlin_component.jar target requires kotlinc to be installed. If it's installed but not in your PATH, edit the Makefile to specify the path to kotlinc.
You can invoke make clean before invoking codesonar analyze.
For this particular Makefile, doing so will not affect make csonar_facing.