infinity.java-conventions.gradle

/**
 *  Conventions for all moss java-based modules.
 */

plugins {
    id 'java'
    id 'groovy'
    id 'checkstyle'
    id 'pmd'
    id 'jacoco'
    id 'com.diffplug.spotless'
    id 'net.ltgt.errorprone'
    id 'com.github.ben-manes.versions'
}

// Projects should use Maven Central for external dependencies.
//
// Simsilica/Moss snapshots resolve from the vendored libs/m2/ tree (single
// source of truth for both local builds and CI). Refresh after publishing
// from a Moss checkout — see libs/README.md. We override mavenLocal()'s URL
// rather than declaring a plain `maven {}` repo so Gradle keeps the local
// Maven layout semantics (maven-metadata-local.xml, '+' version resolution).
repositories {
    mavenLocal {
        url = rootProject.file('libs/m2').toURI()
    }
    mavenCentral()
    jcenter()  // deprecated but some old deps still there
    maven { url 'https://maven.scijava.org/content/repositories/public/' }  // for de.lighti:Clipper
}

// Standard dependencies that we expect all of the java projects
// to have/need.
dependencies {
    implementation "com.google.guava:guava:${guavaVersion}"

    testImplementation (
        "junit:junit:4.13.2"
    )

    implementation "org.codehaus.groovy:groovy-all:${groovyVersion}"

    implementation "org.slf4j:slf4j-api:$slf4jVersion"
    //A simple binding
    //implementation "org.slf4j:slf4j-simple:$slf4jVersion"
    //Log4j binding
    //log4j-slf4j-impl should be used with SLF4J 1.7.x releases or older.
    //log4j-slf4j2-impl should be used with SLF4J 2.0.x releases or newer.
    implementation "org.apache.logging.log4j:log4j-slf4j2-impl:$log4jVersion"
    implementation "org.apache.logging.log4j:log4j-api:$log4jVersion"
    implementation "org.apache.logging.log4j:log4j-core:$log4jVersion"

    // Static analysis (applied via Error Prone javac plugin)
    errorprone 'com.google.errorprone:error_prone_core:2.31.0'
    errorprone 'com.uber.nullaway:nullaway:0.11.3'
}

// =============================================================================
// Spotless — whitespace hygiene + unused imports.
// Run `./gradlew spotlessApply` to auto-fix violations.
//
// NOTE: license header enforcement is intentionally NOT configured.
// Spotless's licenseHeaderFile REPLACES any existing block comment above
// `package`, which would silently relicense upstream Simsilica/third-party
// code that carries its own BSD-3-clause header. Header correctness is a
// per-file judgement call — keep it manual.
// =============================================================================
spotless {
    java {
        target 'src/**/*.java'
        removeUnusedImports()
        trimTrailingWhitespace()
        endWithNewline()
    }
}

// =============================================================================
// Checkstyle — style + common-bug rules. Config at config/checkstyle/.
// Starts as warnings-only so existing violations don't break the build; flip
// `ignoreFailures` to false once the repo is clean.
// =============================================================================
checkstyle {
    toolVersion = '10.17.0'
    configFile = rootProject.file('config/checkstyle/checkstyle.xml')
    ignoreFailures = true
    showViolations = true
}

// =============================================================================
// PMD — focused dead-code rules (unused private fields/methods/locals,
// unnecessary imports, empty catch blocks). NOT a style/format tool —
// Spotless owns whitespace, Checkstyle owns convention. Config at
// config/pmd/ruleset.xml.
//
// Starts as warnings-only (ignoreFailures = true) so existing flags don't
// break the build; ratchet to failing once the codebase is clean.
// Test sources run through the same pipeline — the ceiling mechanism
// captures their baseline separately (`max<Project>PmdTestViolations`).
//
// ECS components in api/src/main/java/infinity/es/** carry no-arg constructors that
// PMD sees as unused: they're invoked via reflection by Zay-ES's
// FieldSerializer. Suppress that path explicitly so we don't drown in
// false positives there. Same shape as a Lombok-generated-code exclusion.
// =============================================================================
pmd {
    toolVersion = '7.7.0'
    ruleSets = []  // disable PMD's default ruleset; only use ours
    ruleSetFiles = files(rootProject.file('config/pmd/ruleset.xml'))
    ignoreFailures = true
    consoleOutput = true
}

tasks.withType(Pmd).configureEach {
    // Skip ECS components — no-arg ctors and final fields are reflection-
    // accessed and look "unused" to static analysis.
    exclude '**/infinity/es/**'
}

// Ad-hoc per-file / per-path PMD task — useful for scoping the report to
// just the files touched in the current change rather than re-scanning
// every source file in the module.
//
// Usage:
//   ./gradlew :infinity-server:pmdPath -PpmdPath=src/main/java/infinity/systems/ship/WeaponsSystem.java
//   ./gradlew :infinity-server:pmdPath -PpmdPath=src/main/java/infinity/systems/   # whole package
//   ./gradlew :infinity-server:pmdPath -PpmdPath=src/main/java/A.java,src/main/java/B.java   # multiple
//
// Path is comma-separated, relative to the module root. Uses the project
// ruleset and the same ignoreFailures + consoleOutput config as pmdMain
// so behaviour matches the full-scan baseline.
//
// Default (no -PpmdPath flag) is `src/main/java`, which is equivalent to
// pmdMain — so the task is safe to invoke without arguments.
tasks.register('pmdPath', Pmd) {
    description = "Run PMD against -PpmdPath=<file_or_dir,...> (default: src/main/java)"
    group = 'verification'
    // Read the -PpmdPath property via providers.gradleProperty rather than
    // project.findProperty('pmdPath'). findProperty walks the project's
    // dynamic-property chain, which includes tasks — so once this task is
    // registered, findProperty('pmdPath') returns the Pmd task itself,
    // not the command-line property. That breaks Tooling-API model builds
    // (Eclipse Buildship / jdtls import) which eagerly realize every task.
    def rawPath = providers.gradleProperty('pmdPath').getOrElse('src/main/java')
    def paths = rawPath.split(',').collect { it.trim() }.findAll { !it.isEmpty() }
    source = files(paths)
    classpath = sourceSets.main.runtimeClasspath
    pmdClasspath = configurations.pmd
    ruleSets = []
    ruleSetFiles = files(rootProject.file('config/pmd/ruleset.xml'))
    ignoreFailures = true
    consoleOutput = true
    reports {
        html.required = true
        xml.required = false
    }
}

// =============================================================================
// Static-analysis ceilings — strict pin per-tool per-module.
//
// Each tool above runs warn-only at task level (`ignoreFailures = true`).
// That preserves the per-touched-file ratchet (per
// `.claude/rules/pmd-on-touched-files.md`) and per-batch refactor work —
// neither breaks every commit on existing baseline violations. The
// ceilings below are the gate: anything ABOVE the captured baseline
// (stored in `gradle.properties`) fails the build with a message naming
// the tool, count, and ceiling.
//
// To ratchet down: after a cleanup batch reduces the real count, capture
// the new count, lower the matching property in `gradle.properties`,
// commit. Bumping a ceiling is an explicit property edit — never silent.
//
// Property naming: `max<ProjectName>Checkstyle[Test]Violations` /
// `max<ProjectName>Pmd[Test]Violations`. Missing property = no ceiling
// (skipped) — useful for tasks like `pmdPath` that don't write XML.
//
// Out of scope: Error Prone + NullAway warnings flow through javac
// stdout, not separate report files; ratcheting them needs a different
// mechanism (parse javac output / wrap javac) and is deferred.
// =============================================================================
tasks.withType(Checkstyle).configureEach { task ->
    def variant = task.name.substring('checkstyle'.length())  // 'Main' or 'Test'
    def variantSuffix = (variant == 'Main') ? '' : variant
    def ceilingKey = "max${project.name.capitalize()}Checkstyle${variantSuffix}Violations"
    def rawCeiling = project.findProperty(ceilingKey)

    // Register the ceiling value as a task input so property changes
    // invalidate the cache and force the doLast check to re-run.
    task.inputs.property("ceiling.${ceilingKey}", rawCeiling ?: 'absent')

    task.doLast {
        def reportFile = task.reports.xml.outputLocation.asFile.get()
        if (!reportFile.exists() || rawCeiling == null) {
            return  // no report or no ceiling configured for this variant
        }
        def ceiling = rawCeiling.toString().toInteger()
        def count = (reportFile.text =~ /<error /).size()
        if (count > ceiling) {
            throw new GradleException(
                "Checkstyle (${task.name}): ${count} violations in ${project.name} " +
                "exceeds ceiling ${ceiling} (${ceilingKey} in gradle.properties). " +
                "Either fix the new violations or — only after net cleanup — " +
                "lower the ceiling.")
        }
    }
}

tasks.withType(Pmd).configureEach { task ->
    def variant = task.name.substring('pmd'.length())  // 'Main', 'Test', 'Path'
    def variantSuffix = (variant == 'Main') ? '' : variant
    def ceilingKey = "max${project.name.capitalize()}Pmd${variantSuffix}Violations"
    def rawCeiling = project.findProperty(ceilingKey)

    task.inputs.property("ceiling.${ceilingKey}", rawCeiling ?: 'absent')

    task.doLast {
        def reportFile = task.reports.xml.outputLocation.asFile.get()
        if (!reportFile.exists() || rawCeiling == null) {
            return  // e.g. pmdPath disables XML; or no ceiling configured
        }
        def ceiling = rawCeiling.toString().toInteger()
        def count = (reportFile.text =~ /<violation /).size()
        if (count > ceiling) {
            throw new GradleException(
                "PMD (${task.name}): ${count} violations in ${project.name} " +
                "exceeds ceiling ${ceiling} (${ceilingKey} in gradle.properties). " +
                "Either fix the new violations or — only after net cleanup — " +
                "lower the ceiling.")
        }
    }
}

// =============================================================================
// JaCoCo — test-coverage reporting + per-module ratchet floors.
//
// Same shape as PMD/Checkstyle ceilings above, inverted: PMD/Checkstyle count
// violations and gate on "AT or BELOW the captured baseline"; JaCoCo measures
// coverage ratio and gates on "AT or ABOVE the captured baseline". `test` runs
// without coverage failure; the verifier task is what gates `check`.
//
// Property naming: `min<ProjectName>LineCoverage` / `min<ProjectName>BranchCoverage`
// in `gradle.properties`. Default 0.0 (no gate) so new modules don't break
// the build before the property is captured.
//
// Reports: HTML (humans) + XML (SonarCloud) at
// `<module>/build/reports/jacoco/test/`.
// =============================================================================
jacocoTestReport {
    dependsOn tasks.named('test')
    reports {
        xml.required = true
        html.required = true
    }
}

// Always produce a report after `test` so HTML/XML are available without an
// explicit `jacocoTestReport` invocation.
tasks.named('test').configure {
    finalizedBy tasks.named('jacocoTestReport')
}

jacocoTestCoverageVerification {
    dependsOn tasks.named('test')
    def lineFloorKey = "min${project.name.capitalize()}LineCoverage"
    def branchFloorKey = "min${project.name.capitalize()}BranchCoverage"
    def lineFloor = (project.findProperty(lineFloorKey) ?: '0.0').toString().toBigDecimal()
    def branchFloor = (project.findProperty(branchFloorKey) ?: '0.0').toString().toBigDecimal()

    inputs.property("floor.${lineFloorKey}", lineFloor.toString())
    inputs.property("floor.${branchFloorKey}", branchFloor.toString())

    violationRules {
        rule {
            element = 'BUNDLE'
            limit {
                counter = 'LINE'
                value = 'COVEREDRATIO'
                minimum = lineFloor
            }
        }
        rule {
            element = 'BUNDLE'
            limit {
                counter = 'BRANCH'
                value = 'COVEREDRATIO'
                minimum = branchFloor
            }
        }
    }
}

tasks.named('check').configure {
    dependsOn tasks.named('jacocoTestCoverageVerification')
}

// =============================================================================
// Error Prone + NullAway — compile-time bug detection.
// Starts as warnings-only; tighten by removing `allErrorsAsWarnings` and
// promoting NullAway to error once the code is annotated.
// =============================================================================
tasks.withType(JavaCompile).configureEach {
    options.errorprone {
        disableWarningsInGeneratedCode = true
        allErrorsAsWarnings = true
        excludedPaths = '.*/build/generated/.*'
        warn('NullAway')
        option('NullAway:AnnotatedPackages', 'infinity')
    }
}

// Skip Error Prone for tests — too noisy for early adoption.
tasks.named('compileTestJava').configure {
    options.errorprone.enabled = false
}

compileJava { // compile-time options:
    options.encoding = 'UTF-8'
    options.compilerArgs << '-Xlint:unchecked'
    options.deprecation = true
}

java {
    sourceCompatibility = 21
    targetCompatibility = 21
    withJavadocJar()
    withSourcesJar()
}

javadoc {
    options.addStringOption('Xdoclint:none', '-quiet')
}

test {
    // Redirect JVM fatal-error logs (hs_err_pid*.log) to build/crash-logs/ per module.
    def crashLogDir = layout.buildDirectory.dir("crash-logs").get().asFile
    crashLogDir.mkdirs()
    jvmArgs "-XX:ErrorFile=${crashLogDir}/hs_err_pid%p.log"

    testLogging {
        // I want to see the tests that are run and pass, etc.
        events "passed", "skipped", "failed", "standardOut", "standardError"
        exceptionFormat "full"
    }
}

sourceSets {
    main {
        resources {
            exclude "**/.backups/**"
        }
    }
}