Compile-Time Checks: the HKJ Checker

The HKJ checker is a javac compiler plugin (hkj-checker) that catches Higher-Kinded-J mistakes during compilation instead of at runtime — or, for the silent ones, instead of never. It is the authoritative reference for what is detected; the per-feature Common Compiler Errors chapters cross-link here.

Why a checker

Many HKJ mistakes are silent: the code type-checks (generics erasure hides the problem) and only fails at runtime — or, worse, carries the wrong value silently. A representative example:

MaybePath<Integer> r = Path.just(1).via(n -> Path.io(() -> n + 1)); // IOPath, not MaybePath

This compiles, then throws IllegalArgumentException at runtime. The checker turns this class of bug into a compile-time diagnostic.

What the checker detects

Each check has an id (used for configuration). Default is the severity when nothing is configured; warn-default checks are the "sole signal over javac-accepted code" ones, kept at warning during soak.

"Companion" checks add an actionable HKJ message beside javac's own cryptic error. "Sole signal" / "advisory" checks are the only compile-time signal (the code otherwise compiles), which is why the heuristic and advisory ones default to warn.

Configuration

Checks are configured through the plugin argument string. javac splits -Xplugin on whitespace into the plugin name and its arguments:

-Xplugin:HKJChecker disable=<id>[,<id>...] severity=error|warn severity:<id>=error|warn

• disable=<id>[,<id>...] — turn the listed checks off entirely (e.g. disable=map-nests-effect,discarded-effect).
• severity=error|warn — the global default for the error-default checks (default error). It does not silently promote the warn-default checks (error-type-mismatch, map-nests-effect, migration-nudge, raw-kind) — those stay warn unless promoted explicitly.
• severity:<id>=error|warn — override one check. Wins over the global default and over a check's built-in default, so a team can promote a warn-default check, e.g. severity:error-type-mismatch=error, or downgrade a single error-default check.

Resolution order for a check: an explicit severity:<id>=… override; else the warn-default checks stay warn; else the global severity.

Unknown ids and unparseable values are ignored rather than failing the build — a typo in a compiler argument must never break compilation.

The HKJ Gradle/Maven plugin enables the checker by default and passes this argument through; see Build Plugins. Manual setup without the build plugin:

Gradle

dependencies {
    annotationProcessor("io.github.higher-kinded-j:hkj-checker:<version>")
}
tasks.withType<JavaCompile>().configureEach {
    options.compilerArgs.add("-Xplugin:HKJChecker disable=effect-composition")
}

Maven

<annotationProcessorPaths>
  <path>
    <groupId>io.github.higher-kinded-j</groupId>
    <artifactId>hkj-checker</artifactId>
    <version>${hkj.version}</version>
  </path>
</annotationProcessorPaths>
<compilerArgs>
  <arg>-Xplugin:HKJChecker severity=warn</arg>
</compilerArgs>

How it works

A standard com.sun.source.util.Plugin hooks the ANALYZE phase (after type attribution). For each compilation unit a tree scanner runs the enabled checks, resolving types via the public javax.lang.model utilities (or, for the original mismatch check, javac's attributed types) and emitting diagnostics at the exact source location. It is part of normal compilation — no separate build step.

No false positives

The checker follows a strict no-false-positives policy: it is better to miss a real mistake than to report a false one. When a type cannot be resolved (type variables, wildcards, method references, indirect construction, runtime polymorphism) the check is skipped silently. The library's runtime checks remain the safety net for anything the compiler cannot see.

Previous: Manual Gradle and Maven Setup Next: Migration Recipes