jQAssistant Gradle plugin

This is a Gradle plugin that facilitates the use of jQAssistant through Gradle. Currently supported are:

• all jQAssistant tasks: scan, analyze, server, report, available-scopes, available-rules, effective-rules, effective-configuration, reset, list-plugins

• giving any options defined for the CLI

• configuring the jQAssistant version (default is 2.5.0)

• configuring the neo4J Version (4 or 5, default depends on Java version)

• configuring additional plugins (Java plugin is added by default)

• configuring additional neo4j plugins

• configuring additional artifacts to be scanned (Java compile output is added by default)

• configuring .jqassistant config file location

• single module and multi module projects

Changelog

Version 3.0.0

• Changed Plugin ID from de.kontext_e.jqassistant.gradle to de.kontext-e.jqassistant.gradle to follow Gradle guidelines

• use of different Gradle API to remove classpath issues

• installation of jQAssistant now required (use installJQA task)

• enabled possibility to use existing jQAssistant installations

• removed use of deprecated Gradle features

Requirements

• Java 11 or 17 (see gradle compatibility below)

• Gradle 7.2—9.X (see gradle compatibility below)

Usage

For a sample project, check out the example project in this repository. The build.gradle file gives an overview of how to apply and configure the plugin. The .jqassistant.yml gives an example of how to configure jQAssistant. For more information, check out the jQAssistant User Manual

Add in your Gradle project in question the plugin via

plugins {
    id "de.kontext-e.jqassistant.gradle" version "3.0.0"
}

or

buildscript {
    repositories {
        mavenLocal()
    }
    dependencies {
        classpath 'de.kontext-e.jqassistant.gradle:jqassistant-gradle-plugin:3.0.0'
    }
}

and apply the plugin

apply plugin: 'de.kontext-e.jqassistant.gradle'

Note that you need an installation of jQA first. To install jQAssistant into the project, set the installLocation property in the jqassistant closure and run the installJQA task (see example project). If the configuration of the installation location is omitted, the plugin will default to ${projectRoot}/jqassistant

If you already have an installation that you wish to use, you can set the directory to the directory of the existing location and the plugin will use it. There is then no need to run the installation task.

Now you can call

./gradlew scan

or

./gradlew analyze

Troubleshooting

Should you encounter the error java.lang.IllegalAccessException: module java.base does not open java.nio to unnamed module add the following line to your jqassistant.cmd (above the last line) (Windows):

set JQASSISTANT_OPTS=--add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/sun.nio.ch=ALL-UNNAMED --add-opens java.base/java.io=ALL-UNNAMED --add-opens java.base/java.nio=ALL-UNNAMED

or in the jqassistant.sh (above the last line) (unix):

JQASSISTANT_OPTS=--add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/sun.nio.ch=ALL-UNNAMED --add-opens java.base/java.io=ALL-UNNAMED --add-opens java.base/java.nio=ALL-UNNAMED

Configuration

You can go with the defaults or configure the plugin, e.g. this way:

project.ext["jqaversion"] = "1.9.1"
project.ext["kejqapluginversion"] = "1.7.0"
jqassistant {
    toolVersion = "${project.jqaversion}"
    neo4jVersion 5
    configFile ".jqassistant.yml"
    //Deprecated but still work
    options "-Djqassistant.scan.reset=true"
    //Deprecated, only works when config file does not declafe files to be scanned
    scanDirs "./.git"
}

Note that if you have multiple options, config files or scanDirs, just add multiple lines as seen with plugins, e.g.

scanDirs ".git"
scanDirs "doc/arc42"

If there is no specific neo4J version declared, the plugin chooses the latest version compatible with the current java version (see compatibility matrix below).

If a version is specified, it is chosen, unless it is incompatible. In that case, the plugin falls back to the latest compatible version.

Note that when changing the neo4J version, the store folder in the jqassistant folder in the project root must be deleted.

Tested Gradle Versions

Compatibility Matrix: The contents of the cells are the jQAssistant neo4J-versions that work given the Gradle and java versions

	Java 11	Java 17	Java 21
gradle 8.5 - 9.x	v4	v4 & v5	v5
gradle 7.3 - 8.4	v4	v4 & v5
gradle 7.2	v4

7.1.1 and below: does not work (plugin version 2.1.0 works down to 6.9) 6.8 and below: does not work (version 1.0.1-SNAPSHOT works down to 4.10)

Tested jQAssistant Versions

• 2.1.0-2.5.0

• for jqa 1.X use version 1.0.1-SNAPSHOT version of this Plugin