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

  • Manual Gradle and Maven Setup -- Full build.gradle.kts and pom.xml configuration for projects that cannot use the HKJ build plugin. Covers dependencies, annotation processors, Java preview flags, and snapshot repositories.

  • Build Plugins -- One-line setup for Gradle or Maven that configures dependencies, preview features, and compile-time checks automatically. Replaces multi-block boilerplate configuration with a single plugin application.

  • 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.

  • 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 23 built-in generators that power @GenerateTraversals, covering JDK collections, HKJ core types, and four third-party libraries. Includes a guide to writing your own generator for custom container types.

  • Claude Code Skills -- Six bundled skills that bring contextual HKJ guidance directly into your editor. Covers Path selection, optics, effect handlers, the effects-optics bridge, Spring Boot integration, and functional core / imperative shell architecture.

Chapter Contents

  1. Manual Gradle and Maven Setup - Full manual build configuration
  2. Build Plugins - One-line project setup for Gradle and Maven
  3. Compile-Time Checks - Path type mismatch detection
  4. Diagnostics - Configuration reporting and troubleshooting
  5. Traversal Generator Plugins - Supported types and custom generators
  6. Claude Code Skills - In-editor guidance via Claude Code

Next: Manual Gradle and Maven Setup