0.3.1 - Derivation Policy, Generation Logging & DI Wiring Graphs, on Hearth 0.4.1

Where 0.3.0 took Kindlings beyond derivation into DI, mocking and optics, 0.3.1 makes the whole catalogue governable and observable: a per-library derivation policy to opt out of automatic structural derivation, opt-in generation logging across the derivation and DI modules, DI wiring-graph diagnostics and a DI.plan endpoint, plus new cats collection providers and a batch of derivation fixes. All built on the freshly released Hearth 0.4.1, whose compile-time-performance lessons are applied throughout.

This is a source-compatible feature release (MiMa is now enabled against 0.3.0 and green, kindlings-macro-commons included).

New: per-library derivation policy (opt-in mode)

Kindlings keeps its single recursive derivation mechanism, but you can now globally restrict where instances may be structurally derived — the answer to the "automatic vs. semi-automatic" question (#158, closes #85). Configured entirely via -Xmacro-settings, reusing each module's existing settings namespace:

-Xmacro-settings:<ns>.policy.enabled=opt-in
-Xmacro-settings:<ns>.policy.allowedScopes=com.acme.json;com.acme.Codecs
-Xmacro-settings:<ns>.policy.optInByImport=true

• Modes: always-allowed (default, unchanged behavior) and opt-in.
• opt-in permits structural derivation only in allowedScopes (package-prefix-aware, matched against the macro's enclosingScope) or behind an imported AllowDerivation marker; everywhere else it is a compile error with an actionable message (current scope, configured scopes, and every fix).
• Gates only the structural case-class/enum rules — built-ins, collections, Option, value types, named tuples, and any pre-existing in-scope implicit are reached earlier and stay unconditional.
• Wired into every derivation module (fast-show-pretty, circe, jsoniter, ubjson, diff, yaml, xml, sconfig, pureconfig, avro, tapir-schema, scalacheck, cats, cats-tagless); di/mock/optics are excluded since they are not type-class derivation. Full namespace/marker table in the derivation-policy guide.

New: opt-in generation logging & DI wiring graphs

A shared opt-in GenerationLogging tracer now lets every derivation module surface what it generated and why behind a LogDerivation marker (parallel to the new AllowDerivation marker), and the DI modules gained a ZIO-Magic-style wiring graph and a DI.plan[A] endpoint for inspecting a resolution before committing to it:

• DI: generation logging, wiring-graph visualization, DI.plan, and an enum-argument DSL (defaultStorage / storeAs / debug).
• kindlings-di-cats: companion resource[F] support, resolution of explicit value parameters of a companion resource[F] from the graph, plus the same generation logging / wiring graph — still parametric in F[_] with no Sync/Async constraint.
• optics and mock also gained opt-in generation logging.

New: cats non-empty collection providers

kindlings-cats-integration adds IsCollection providers for NonEmptySeq and NonEmptyLazyList, so every derivation module (and optics' .each) handles them automatically alongside the existing NonEmptyList / NonEmptyVector / NonEmptyChain / NonEmptyMap / NonEmptySet support.

Fixes

• kindlings-avro-derivation: correct generic enum / sealed-trait derivation.
• kindlings-cats-derivation: derive Functor / Foldable / Traverse for enums with case-object (singleton) cases.

Runtime & macro-compile performance

The full round of Hearth 0.4.1 compile-time lessons was applied across the modules: 353 eager helper-object Type vals converted to Hearth's Type.Lazy, lazy provider registration, unsortedMethods on implicit ignore-sets, filter-first method sorting in the DI and diff-derivation macros, sizeHintForBuilder for O(1)-sized cats collections, and skippedLazily / mightMatch provider gates.

Build & dependencies

Built on Hearth 0.4.1 with MiMa enabled against 0.3.0 (now also checking kindlings-macro-commons), sbt 2.0.1, and updated dependencies: tapir 1.13.27, iron 3.3.2, jsoniter-scala-circe 2.39.1, refined 0.11.4, circe 0.14.16, quicklens 1.9.15, plus CI action bumps.

Summary

0.3.1 makes Kindlings' derivation catalogue both governable — a compile-time derivation policy that lets teams opt out of automatic structural derivation per library — and observable — opt-in generation logging and DI wiring-graph diagnostics with a DI.plan endpoint — while adding cats non-empty collection providers, avro/cats derivation fixes, and the full set of Hearth 0.4.1 compile-time-performance wins. Source-compatible with 0.3.0.

Be sure to look at the documentation, star the project ⭐ and leave us some feedback!