Tooling
Build-Time Safety for Higher-Kinded-J
"Make illegal states unrepresentable." -- Yaron Minsky
Every Path type in Higher-Kinded-J can only chain with the same type. Mix a MaybePath into an EitherPath chain, and you get an IllegalArgumentException at runtime. The code compiles; the tests pass (until someone hits that branch); production breaks at 2 AM.
The HKJ tooling catches these mistakes before your code ever runs. Both Gradle and Maven are supported with dedicated build plugins.
-
Build Plugins -- One-line setup for Gradle or Maven that configures dependencies, preview features, and compile-time checks automatically. This is the recommended way to add Higher-Kinded-J to a project; reach for it first.
-
Manual Gradle and Maven Setup -- Full
build.gradle.ktsandpom.xmlconfiguration for the projects that cannot use the build plugin (constrained environments, in-house build frameworks, or a conflicting plugin). The fallback, not the starting point. -
Compile-Time Checks -- A javac plugin that detects Path type mismatches at compile time, preventing runtime
IllegalArgumentExceptionerrors. Follows a strict no-false-positives policy. -
Migration Recipes -- The
hkj-openrewriterecipe catalogue for upgrading between Higher-Kinded-J releases. Covers the 0.2.x to 0.3.0 arity migration, detection-only effect-algebra helpers, and the 0.5.0 deprecation renames; runnable from Gradle or Maven. -
Diagnostics -- The
hkjDiagnosticsGradle task ormvn hkj:diagnosticsMaven goal that reports your current HKJ configuration, showing exactly which dependencies, compiler arguments, and checks are active. -
Traversal Generator Plugins -- The 30 built-in generators that power
@GenerateTraversals, covering JDK collections, HKJ core types, and five third-party libraries (Eclipse Collections, Guava, Vavr, Apache Commons, PCollections). Includes a guide to writing your own generator for custom container types. -
PCollections Integration -- Tests, benchmarks, and an example that confirm PCollections persistent collections (
PVector,PStack) compose with the existingListKindinfrastructure throughjava.util.Listcompatibility, with no production code changes. -
PCollections Optics -- Seven
@GenerateTraversalsplugins that recognisePVector,PStack,PSet,PSortedSet,PBag,PMap, andPSortedMapfields and generate type-correct traversals against them. -
Claude Code Skills -- Seven bundled skills that bring contextual HKJ guidance directly into your editor. Covers Path selection, optics, effect handlers, the effects-optics bridge, Spring Boot integration, functional core / imperative shell architecture, and AssertJ-based testing with hkj-test.
-
Testing With hkj-test -- A test-scope dependency that ships fluent AssertJ helpers for every HKJ type. Replaces hand-written unwrapping with assertions that read like the business intent:
isRight(),hasJustValue(...),whenExecuted().hasValue(...), and so on across discriminated unions, effect types, and monad transformers.
Chapter Contents
- Build Plugins - One-line project setup for Gradle and Maven (recommended)
- Manual Gradle and Maven Setup - Full manual build configuration (fallback)
- Compile-Time Checks - Path type mismatch detection
- Migration Recipes - OpenRewrite recipes for upgrading between releases
- Diagnostics - Configuration reporting and troubleshooting
- Traversal Generator Plugins - Supported types and custom generators
- PCollections Integration - PCollections compatibility through
ListKind - PCollections Optics -
@GenerateTraversalsplugins for PCollections types - Claude Code Skills - In-editor guidance via Claude Code
- Testing With hkj-test - Fluent assertions for HKJ types
Next: Build Plugins