Configure code quality
Configure Spotless, JaCoCo and ProGuard through Forge.
Forge configures three code-quality tools. It applies jacoco and com.diffplug.spotless itself,
each gated on a switch that defaults on, so most projects touch neither plugins { } nor these
properties for either one. ProGuard is different: it is not a plugin Forge applies, so a project adds
it to its own buildscript classpath and opts in explicitly.
Every flag reads as enabled only when its value is the literal true, in any casing; anything else
disables it, and the build reports the decision in the configuration log.
Spotless and JaCoCo
Both default on. Forge applies jacoco and com.diffplug.spotless itself, immediately after it
reads the project's properties, so neither belongs in your own plugins { } block. Declaring
id("com.diffplug.spotless") version "..." there cannot resolve — Spotless is already on the
buildscript classpath, at the version Forge pins.
Forge pins a JaCoCo tool version that understands class files through Java 21, the top of the
toolchain range the support matrix spans, and wires the report tasks. For Spotless it applies the
ktlint formatting and the license header from the project's spotless-header.txt. A missing or blank
header file fails the build — see
The licence header is required below.
The header step writes above the first line of file content, which in Kotlin is a @file:
annotation when the file carries one. @file:JvmName, @file:Suppress and every other @file:
target survive spotlessApply, in .kt sources and in .gradle.kts build scripts alike. A project
that excluded such a file through targetExclude may drop the exclusion and recover ktlint coverage
on it.
What Spotless formats
Forge declares four Spotless formats, each with its own generated spotlessX and spotlessXCheck
task.
| Format | Task | Target | Steps |
|---|---|---|---|
java | spotlessJava | src/**/*.java | licence header, googleJavaFormat().aosp(), import order, unused-import removal |
kotlin | spotlessKotlin | src/**/*.kt | licence header, ktlint() |
kotlinGradle | spotlessKotlinGradle | *.gradle.kts | licence header, ktlint() |
markup | spotlessMarkup | src/main/assembly/**/*.{xml,umd,html,htm} | licence header |
Every format also trims trailing whitespace and ends the file with a newline. A <pre> block in an
assembly HTML page loses its trailing spaces for that reason.
The markup format covers everything in the assembly that carries an SGML-family comment, because
the placement rule is the same for all of it: the licence block goes below any prolog and above the
first real element. An XML file keeps its declaration and its doctype on top; an HTML page keeps
<!DOCTYPE html> on top, since anything above a doctype drops a browser into quirks mode. A second
spotlessApply replaces the block a previous run wrote rather than stacking a second one.
HTML pages a resource ships as help therefore carry the same licence the rest of the distribution carries, without you listing them anywhere.
A build script or a CI job that invokes a per-format task by name calls
spotlessMarkuporspotlessMarkupCheckfor this format.spotlessApplyandspotlessCheckcover every format and need no per-format name.
Disable either tool independently:
com.mbseconsulting.forge.configure.jacoco=false
com.mbseconsulting.forge.configure.spotless=falseJaCoCo has one level of override: turn it off and configure the jacoco plugin yourself, the way any
Gradle project would. Spotless has three, described next.
Dokka is documented separately
Forge also applies Dokka and packages the rendered API reference, but that generates documentation rather than gating quality, so it has its own page: Generate an API reference.
Turning Spotless off, or taking it over
Forge applies Spotless and configures Java, Kotlin, Gradle Kotlin DSL and markup formats. Three levels of override are available, from lightest to heaviest.
Stop the formatting gate without losing spotlessApply:
spotless { isEnforceCheck = false }Change what a format targets, or what it ignores. These are plain settings, so the last write wins:
spotless { kotlin { targetExclude("src/main/kotlin/generated/**") } }Re-author a format completely. clearSteps() first, always:
spotless {
kotlin {
clearSteps()
licenseHeader("/* your header */")
ktlint("1.5.0")
endWithNewline()
}
}Adding a step Forge already added is a build failure, not an override —
Multiple steps with name 'ktlint' for spotless format 'kotlin'. Spotless rejects a duplicate step
name rather than replacing the step, so clearSteps() is the only way to change one Forge set.
A format you clear loses the licence header Forge builds from your resource.provider* and legal.*
keys, while generateResourceDescriptor and generatePluginDescriptor keep stamping that header into
the XML they generate. Your sources and your descriptors then carry different headers. Forge cannot
detect this — Spotless exposes no way to read a format's steps — so re-declare the header yourself if
you clear a format.
The licence header is required
Forge builds the header from your resource.provider* and legal.* keys and a spotless-header.txt
in your project root. Whenever Spotless is configured — on by default, or through your own
configure.spotless=true — a missing or blank spotless-header.txt fails the build, naming the file
it expected. The same failure covers the seven resource.* and legal.* keys the header substitutes:
one left blank fails the build the same way.
A project that does not want the header sets com.mbseconsulting.forge.configure.spotless=false.
Turning Spotless off entirely
Set com.mbseconsulting.forge.configure.spotless=false. Forge then applies
nothing and configures nothing. Spotless stays on your buildscript classpath, because Forge depends
on it, so declare it without a version if you want to apply it yourself:
plugins {
id("com.mbseconsulting.forge") version "9.0.0"
id("com.diffplug.spotless") // no version — a versioned request cannot resolve
}Your project still declares its repositories
Forge adds the CATIA Magic release and snapshot repositories, and nothing else. Every tool Forge
applies resolves its own artifacts from your repositories when its tasks run — Spotless downloads
ktlint and google-java-format, and Dokka its rendering engine — so your build.gradle.kts keeps:
repositories {
mavenCentral()
}Without it spotlessKotlin fails with Could not resolve all files for configuration ':detachedConfigurationN'.
ProGuard
ProGuard is not a plugin you apply, so put it on the buildscript classpath:
buildscript {
repositories {
gradlePluginPortal()
}
dependencies {
classpath("com.guardsquare:proguard-gradle:7.9.1")
}
}Then enable the wiring:
com.mbseconsulting.forge.configure.proguard=trueForge registers an obfuscate task and rewires assemblePlugin to consume the obfuscated jar
rather than the original, so the archive ships obfuscated code without any further configuration.
Disable it with com.mbseconsulting.forge.configure.proguard=false, which is also the
behaviour when the key is absent.
Coverage reports
With JaCoCo enabled, both test tasks produce an execution file:
./gradlew jacocoTestReport
./gradlew jacocoTestCoverageVerificationintegrationTest runs as a JavaExec rather than a Test task, so the JaCoCo plugin does not
attach to it on its own. Forge attaches the extension explicitly, which is what instruments
the forked JVM. See Write tests.
Both report tasks depend on every Test and IntegrationTest task, so they run the tests before
reading the execution data rather than reading whatever a previous run left behind. Two consequences
follow: the coverage gate that jacocoTestCoverageVerification enforces cannot pass vacuously
against empty execution data; and jacocoTestReport transitively launches integrationTest, which
forks a JVM against a real CATIA Magic install and consumes a licence. That second consequence
reaches only a project carrying a @Tag("IntegrationTest") test, because integrationTest skips
when none exists.
A task excluded with -x runs in no part of the build, so its execution file on disk comes from an
earlier run. Both tasks leave that file out. jacocoTestCoverageVerification also skips whenever a
test task is excluded, and logs which one: ./gradlew check -x integrationTest reports coverage from
unit tests alone and applies no gate.
check depends on both tasks, so ./gradlew build produces the report and applies the 80% gate. A
project below that floor fails its build. Raise coverage, or demote the gate:
tasks.jacocoTestCoverageVerification {
violationRules {
isFailOnViolation = false
}
}Generated profile bindings do not count toward that gate. generateProfileBindings stamps every type
it emits with @Generated, and JaCoCo drops each class carrying an annotation whose simple name
contains Generated. The filter runs inside the analyzer, so the generated layer leaves the report
and the gate's denominator together, and the number the gate reads measures the code the project
wrote. The annotation comes from Anvil, so a project must resolve a version that declares it. See
Generate profile bindings.
The edges exist only while com.mbseconsulting.forge.configure.jacoco=true. Setting the key to
false leaves the check graph as the jacoco plugin built it.