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.

Path.just(1).peek(log);      // MaybePath: eager — log() has already run
Path.io(() -> 1).peek(log);  // IOPath: deferred — log() never runs

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.

Opting out one declaration

disable= is project-wide. To accept a single deliberate call site, name the check id in @SuppressWarnings on the enclosing class, method or variable — hkj-checker covers every check at once:

@SuppressWarnings("migration-nudge") // the ergonomic layer the nudge points at
public final class StateOps {
    public static <S, A> Free<StateOpKind.Witness<S>, A> view(Getter<S, A> optic) {
        // ...
        return Free.liftF(StateOpKindHelper.STATE_OP.widen(op), functor());
    }
}

A local variable takes the token too, which is the narrowest scope available:

@SuppressWarnings("path-type-mismatch") // deliberate: converted downstream
var mixed = Path.just(1).via(_ -> Path.io(() -> 2));

Suppression is per check and accumulates outward-in: a token on a class reaches everything inside it, other checks on the same statement keep running, and a sibling declaration is unaffected. HKJ's own smart- constructor layer (StateOps, ErrorOps, OpticPrograms) and the FreePath/FreeFactory fluent API use exactly this — they are the layer migration-nudge steers callers towards, so they must build the Free primitives directly.

Two deliberate limits. The tokens reach the error-default checks as well as the advisory ones, so @SuppressWarnings("path-type-mismatch") will silence a build-failing diagnostic — scope it narrowly. And javac's blanket "all" is not honoured: it is too common on legacy and generated code for a silent switch-off to be safe, so an HKJ opt-out is always spelled explicitly.

Manual setup

The HKJ Gradle/Maven plugin enables the checker by default and passes the -Xplugin argument through; see Build Plugins. 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, with 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