Code Analysis

.deepsource.toml

This section covers .deepsource.toml configuration specific to the java analyzer. Please make sure to read the general configuration guide first.

The Java analyzer supports Gradle, Maven and Bazel projects. There is no difference in configuration between them, and all types of projects can be initialized through the simple workflow of the DeepSource configuration generator.

name

  • Type: String
  • Presence: mandatory
  • Description: Shortcode of the analyzer.
  • Example:
name = "java"

enabled

  • Type: Boolean
  • Presence: optional
  • Description: Toggle whether this analyzer should be run.
  • Example:
enabled = true

meta

  • Type: Table
  • Presence: mandatory
  • Description: Additional data used to configure the analyzer.
  • Example:
[analyzers.meta]
  runtime_version = "8"
runtime_version
  • Type: String
  • Presence: mandatory
  • Description: The Java runtime version to use when running the analyzer. OpenJDK versions 8 to 21 are currently supported.
  • Aliases: java_version
  • Example:
[analyzers.meta]
  runtime_version = "13"

if runtime_version is not specified, or is the wrong Java version, analysis may show incorrect results. Specify the Java version you use in CI for best results.

skip_doc_coverage
  • Type: Array
  • Presence: optional
  • Description: Specify which artifacts to skip when calculating documentation coverage.
  • Available Values: test, class, constructor and nonpublic
    • test - Ignore documentation coverage within tests
    • class - Ignore class documentation coverage
    • constructor - Ignore constructor documentation coverage
    • nonpublic - Ignore documentation coverage for any declaration not marked as public
  • Default Value: [ "test" ]
  • Example:
skip_doc_coverage = [ "nonpublic", "test" ]

If skip_doc_coverage is set, it will override any default configuration. That is, if this key is set, and you wish to ensure documentation coverage is skipped for elements that are skipped by default (like tests), you must specify those as well as the additional elements you wish to skip.

cyclomatic_complexity_threshold
  • Type: String
  • Presence: optional
  • Description: Specify the acceptable risk category for your project as the threshold. All functions with complexity beyond this threshold will raise an issue. For example, setting the threshold to low will flag all functions that have a cyclomatic complexity of more than 5, while setting the threshold to critical will not flag any function.
  • Available Values: low, medium, high, very-high and critical
Risk categoryCyclomatic complexity rangeRecommended action
low1-5No action is needed.
medium6-15Review and monitor.
high16-25Review and refactor. Recommended to add detailed comments if the function absolutely needs to be kept as it is.
very-high26-50Refactor to reduce the complexity.
critical>50Must refactor this. This can make the code untestable and very difficult to understand.
  • Default Value: medium
  • Example:
[analyzers.meta]
cyclomatic_complexity_threshold = "high"

Sample config

version = 1

[[analyzers]]
name = "java"
enabled = true

  [analyzers.meta]
  runtime_version = "8"

Code Coverage

Java

The test coverage analyzer supports test coverage metrics for Jacoco and Clover XML reports.

Jacoco

Setting up test coverage differs with each type of build system (Maven, Gradle, etc.). Here’s an example of the configuration needed to run Jacoco on a maven repo:

<!-- Within pom.xml -->
...
    <plugin>
        <groupId>org.jacoco</groupId>
        <artifactId>jacoco-maven-plugin</artifactId>
        <version>0.8.2</version>
        <executions>
            <execution>
                <goals>
                    <goal>prepare-agent</goal>
                </goals>
            </execution>
            <!-- attached to Maven test phase -->
            <execution>
                <id>report</id>
                <phase>test</phase>
                <goals>
                    <goal>report</goal>
                </goals>
            </execution>
        </executions>
    </plugin>

...

Once you’ve added Jacoco to your project’s pom.xml file, you should be able to run tests and generate the coverage report. The default location of the coverage report is target/site/jacoco/jacoco.xml.

mvn test

In case your project has multiple modules, you will need to use the jacoco:report-aggregate goal to merge all reports together.

After you have the XML test report, you can upload it to DeepSource using the cli:

# Install deepsource CLI
curl https://deepsource.io/cli | sh

# Set the DEEPSOURCE_DSN env variable from the reporting tab of
# your repository's DeepSource settings page.
export DEEPSOURCE_DSN=https://sampledsn@deepsource.io

# From the project's root directory, run the report coverage command
./bin/deepsource report --analyzer test-coverage --key java --value-file target/site/jacoco/jacoco.xml

You should be able to proceed similarly with other build systems such as Ant or Gradle.

Reference: Jacoco documentation

Clover

DeepSource also supports reports generated using Atlassian’s Clover coverage framework. Here’s an example of using it with Maven:

    ...

    <build>
        <plugins>

            ...

            <plugin>
                <groupId>org.openclover</groupId>
                <artifactId>clover-maven-plugin</artifactId>
                <version>4.4.1</version>
                <configuration>
                </configuration>
                <executions>
                    <execution>
                        <phase>verify</phase>
                        <goals>
                            <goal>instrument</goal>
                            <goal>aggregate</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

    ...

    <reporting>
        <plugins>
            <plugin>
                <groupId>org.openclover</groupId>
                <artifactId>clover-maven-plugin</artifactId>
                <version>4.4.1</version>
            </plugin>
        </plugins>
    </reporting>

    ...

Once you have added these elements to your project’s pom.xml file, you will be able to instrument and run tests:

mvn clean clover:setup test clover:aggregate clover:clover

This will run tests and in the case of a multimodule project, aggregate the results into a single clover report.

The default output directory for the report is target/site/clover/clover.xml.

After you have the XML test report, you can upload it to DeepSource using the cli:

# Install deepsource CLI
curl https://deepsource.io/cli | sh

# Set the DEEPSOURCE_DSN env variable from the reporting tab of
# your repository's DeepSource settings page.
export DEEPSOURCE_DSN=https://sampledsn@deepsource.io

# From the project's root directory, run the report coverage command
./bin/deepsource report --analyzer test-coverage --key java --value-file target/site/clover/clover.xml

You should be able to proceed similarly with other build systems such as Ant or Gradle.

Reference: Clover documentation

Code Formatter (Transformer)

google-java-format

Transform all incoming Java code with google-java-format, a formatter that follows Google’s Java style guide.

This section covers .deepsource.toml configuration specific to the google-java-format transformer. Please make sure to read the general configuration guide first.

name
  • Type: String
  • Presence: mandatory
  • Description: Shortcode of this transformer.
  • Example:
name = "google-java-format"
enabled
  • Type: Boolean
  • Presence: optional
  • Description: Toggle whether this transformer should be run.
  • Example:
enabled = true

Vulnerability Scanning

Supported target files:

  • pom.xml (Maven)
  • buildscript-gradle.lockfile (Gradle)
  • gradle.lockfile (Gradle)