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.


In This Chapter

  • 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.kts and pom.xml configuration 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 IllegalArgumentException errors. Follows a strict no-false-positives policy.

  • Migration Recipes -- The hkj-openrewrite recipe 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 hkjDiagnostics Gradle task or mvn hkj:diagnostics Maven 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 existing ListKind infrastructure through java.util.List compatibility, with no production code changes.

  • PCollections Optics -- Seven @GenerateTraversals plugins that recognise PVector, PStack, PSet, PSortedSet, PBag, PMap, and PSortedMap fields 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

  1. Build Plugins - One-line project setup for Gradle and Maven (recommended)
  2. Manual Gradle and Maven Setup - Full manual build configuration (fallback)
  3. Compile-Time Checks - Path type mismatch detection
  4. Migration Recipes - OpenRewrite recipes for upgrading between releases
  5. Diagnostics - Configuration reporting and troubleshooting
  6. Traversal Generator Plugins - Supported types and custom generators
  7. PCollections Integration - PCollections compatibility through ListKind
  8. PCollections Optics - @GenerateTraversals plugins for PCollections types
  9. Claude Code Skills - In-editor guidance via Claude Code
  10. Testing With hkj-test - Fluent assertions for HKJ types

Next: Build Plugins