kubuszok/hearth

Hearth is a cross-platform Scala macro framework that provides unified APIs for type reflection, expression manipulation, and code generation across Scala 2.13, Scala 3, JVM, JS, and Native. It enables developers to inspect and transform Abstract Syntax Trees, derive type codecs, and generate code with platform-agnostic abstractions that bridge the gap between Scala 2 macros and Scala 3 quotes. The system includes comprehensive tooling for debugging macro expansions, structured data diffing, and robust testing utilities to verify cross-version compatibility.

30 changes.

This period focused on establishing the foundational infrastructure for the Hearth macro framework, including the core typed and untyped reflection APIs, cross-platform support for Scala 2 and 3, and the Cross-Quotes compiler plugin. The work also involved significant build system refactoring to unify plugin management and introducing comprehensive debugging utilities, data diffing capabilities, and documentation validation scripts to support development and testing.

9 changes.

This period focused on extending the library's macro capabilities to fully support Scala 3 features, including opaque types, immutable arrays, and automatic type name derivation. It also introduced comprehensive cross-version testing for Scala 2.13 and 3, alongside a new MUnit-based testing artifact with custom assertions and ScalaCheck integration.

This change introduces the Scala 2-specific implementations for the typed macro APIs in \hearth/src/main/scala-2/hearth/typed\. It provides \Expr.quote\ and \Expr.splice\ for portable expression quotation and splicing, \Type.of\ for type materialization, and \ExprCodec.derived\ for automatic codec derivation. The diff also includes the core \ExprsScala2\ and \TypesScala2\ traits, which implement type codecs for primitives and tuples, implicit summoning, and AST printing utilities, ensuring the typed API functions correctly on Scala 2.

hearth/src/main/scala-2/hearth/typed · high confidence

The tree printer now supports ANSI-colored output via a new \SyntaxHighlight\ strategy (used by \prettyPrint\), while \plainPrint\ uses a no-color strategy. To prevent excessive memory usage, output is truncated with a warning when the StringBuilder approaches the UTF-8 string length limit (65,536 characters), throwing a \StringBuildingTerminated\ exception to unwind the stack gracefully.

hearth-better-printers/src/main/scala · high confidence

New example type definitions have been added to the \hearth-sandwich-examples-213\ and \hearth-sandwich-examples-3\ modules to support cross-version compatibility testing. The Scala 2.13 examples include case classes, value classes, JavaBean-style classes, and sealed hierarchies, while the Scala 3 examples mirror these structures using Scala 3-specific features such as enums and opaque types. These files serve as the shared type layer for verifying that the sandwich library correctly handles type representations across Scala 2.13 and Scala 3.

hearth-sandwich-examples-213, hearth-sandwich-examples-3 · high confidence

Users can now automatically derive the \TypeName\ for types without manual implementation. This is achieved by adding the \TypeNameCompanion\ trait, which provides an implicit derivation mechanism: using a macro in Scala 2 and an inline given in Scala 3.

hearth/src/main/scala-2/hearth/typename, hearth/src/main/scala-3/hearth/typename · high confidence

This update introduces two new macro extensions for Scala 3: \IsValueTypeProviderForOpaque\ enables the library to recognize and handle opaque types by resolving their underlying runtime types and smart constructors, while \IsCollectionProviderForIArray\ adds support for Scala's immutable arrays by treating them as collections that can be converted to \Iterable\ and processed with standard factory patterns.

hearth/src/main/scala-3/hearth/std · high confidence

The standard macro extensions now include dedicated providers for a broader range of Scala standard library types. Collection support has been extended to include Scala arrays, iterators, and strings, in addition to existing collection support. New providers enable handling of Scala Option, Either, and Try types, with optimized zero-closure folding for Eithers. Additionally, support for AnyVal types with single-argument constructors has been added, and constructor-like providers now handle Either-based value wrappers (e.g., Either\[String, Value\]). These changes allow the framework to automatically recognize and process these common Scala types without requiring custom user-defined extensions.

hearth/src/main/scala/hearth/std/extensions · high confidence

This change introduces the foundational core of the Hearth macro framework, establishing the \MacroCommons\ trait as the root composition point for macro implementations. It adds \Environments\ to provide platform-agnostic position handling, environment introspection (Scala/JDK version, platform), and position-targeted reporting (\reportInfo\, \reportWarn\, \reportError\ with \Position\ overloads). The \MIOIntegrations\ trait defines the \runToExprOrFail\ entry point for executing macro computations with global timeouts, benchmarking/flame-graph support, and structured log rendering. New error types \HearthAssertionError\ (for internal bugs) and \HearthRequirementError\ (for user API misuse) are added to distinguish between library defects and user errors, including version and platform context in their messages. The \MacroExtension\ API and \loader\ service loader implementation allow for pluggable, priority-ordered macro extensions loaded via \ServiceLoader\, with robust error handling that skips failing providers rather than aborting the entire expansion. Utility classes for version detection (\HearthVersion\, \ScalaVersion\, \JDKVersion\) and package-level helpers for ANSI removal and macro suffix stripping are also included.

hearth/src/main/scala/hearth · high confidence

The Scala 2 tree printer now includes a new \RuntimeAwareTypePrinter\ that can substitute specific type arguments with runtime-provided expressions, and a \ShowCodePretty\ implementation that replaces the standard reflection printer with a version supporting syntax highlighting. These changes improve the readability of generated code and type signatures in macro output, particularly for complex generic types and anonymous classes.

hearth-better-printers/src/main/scala-2 · high confidence

The \hearth.data\ package now exposes the core \Data\ type and \Diff\ type in the main source tree (previously located in test data), making them available for pervasive use in Hearth tests. \Data\ provides a JSON-like model supporting primitives, lists, and maps, along with a \DataOps\ extension that offers pattern-matching via \fold\, optional accessors (e.g., \asInt\, \asMap\), structural diffing, and pretty rendering. This infrastructure backs the \\<==\>\ assertion operator, allowing fixtures to emit multiple results as a single, easily diffable structure.

hearth/src/main/scala-2/hearth/data, hearth/src/main/scala-3/hearth/data · high confidence

Adds the \hearth-micro-fp\ library, providing core functional programming type classes (\Functor\, \Applicative\, \Parallel\, \Traverse\) and their syntax extensions, alongside specialized data structures like \NonEmptyList\, \NonEmptyMap\, and \NonEmptyVector\. The library introduces a \DirectStyle\ execution model that allows effects to be run sequentially in a safe, stack-safe manner (via \DirectStyleExecutor\ using virtual threads on JDK 17+), and includes a structured logging system (\Log\, \LogRendering\) with support for rendering logs as speedscope-compatible flame graphs (\FlameGraph\).

hearth-micro-fp · high confidence

Adds a new Scala 3 compiler plugin (CrossQuotesPlugin) that rewrites Hearth's cross-platform \Expr.quote\, \Expr.splice\, and \Type.of\ calls into native Scala 3 quoted syntax (\'{ }\, \${ }\, \scala.quoted.Type.of\). This enables the existing cross-quotes functionality to work on Scala 3 by handling context injection for \Quotes\, managing nested quote scopes, and resolving type constructor givens, effectively bridging the gap between the Scala 2 macro implementation and Scala 3's built-in staging system.

hearth-cross-quotes/src/main/scala-3 · high confidence

Adds new Scala 3 implementations for type and tree printing: \RuntimeAwareTypePrinterScala3\ enables printing type names at runtime by substituting specific type arguments with runtime-provided expressions, while \ShowCodePrettyScala3\ provides indented tree printers (\FormattedTreeStructure\ and \FormattedTreeStructureAnsi\) that support syntax highlighting and handle large trees by limiting output size. These components form the core printing logic for the Scala 3 version of the better-printers module.

hearth-better-printers/src/main/scala-3 · high confidence

Adds a new \CrossQuotesSettings\ component that enables users to filter compiler plugin logs by specific file, line, and column positions. This feature allows developers to isolate debugging output for particular code locations using a pipe-separated syntax (e.g., \logging=file.scala:10:5\|file2.scala\), addressing the need for targeted visibility into cross-quoted compilation steps.

hearth-cross-quotes/src/main/scala · high confidence

This change adds new types and utilities to the standard library to improve diagnostic visibility and extensibility. It introduces \ProviderResult\ to capture whether a type provider matched or skipped, including lazy, per-provider reasons for failures, and \ProviderProvenance\ to identify whether a match came from a built-in or third-party extension. It also adds \Rule\ and \Rules\ to support a first-match-wins strategy with aggregated skip reasons, enabling rule-based derivation patterns.

hearth/src/main/scala/hearth/std · high confidence

This change introduces a new untyped reflection layer (\UntypedExprs\, \UntypedMethods\, \UntypedTypes\) that provides platform-agnostic access to macro internals (using \c.Tree\ on Scala 2 and \quotes.reflect\ on Scala 3). This layer allows macro operations to work with symbols and type structures without requiring full type knowledge, facilitating better separation between typed and untyped macro contexts. Key additions include support for opaque types, union types, IArrays, and improved handling of default values and varargs in method invocations.

hearth/src/main/scala/hearth/untyped · high confidence

This change introduces the Scala 3-specific implementations for Hearth's core typed macro APIs, including \Expr\, \Type\, and \Methods\. It replaces the previous Scala 2-style quasiquote approach with native Scala 3 \scala.quoted\ support, enabling cross-platform compatibility via the Cross-Quotes plugin. Key additions include native \Expr.quote\ and \Expr.splice\ wrappers, \Type.of\ materialization, and comprehensive \ExprCodec\/\TypeCodec\ implementations for primitives, tuples, and IArrays. The implementation also handles Scala 3-specific nuances such as splice owner management to prevent \-Xcheck-macros\ failures, proper handling of intersection/union types, and improved type printing and implicit summoning.

hearth/src/main/scala-3/hearth/typed · high confidence

A new \TypeName\ type class has been introduced in the \hearth.typename\ package, available since version 0.3.0. This feature allows users to obtain four distinct representations of a type's name—pretty (ANSI colored, fully qualified), plain (fully qualified), simple (short name with type parameters), and short (short name only)—via auto-derived instances. The implementation uses compile-time macros to resolve these names, including runtime-aware substitution of abstract type parameters, and employs caching and lazy evaluation to optimize performance during compilation.

hearth/src/main/scala/hearth/typename · high confidence

The \hearth.data\ package now includes core infrastructure for handling structured data values. \DataCommons\ provides a \parseString\ method to convert string representations into typed \Data\ objects (supporting integers, floats, booleans, and nested structures) and a \render\ method to serialize \Data\ back to human-readable strings. It also introduces a \diff\ function that compares two \Data\ structures and produces a list of mismatches. \DiffEntry\ models these mismatches, tracking the specific path (via map keys or list indices) where expected and actual values diverge, and provides a colored, pretty-printed output for debugging.

hearth/src/main/scala/hearth/data · high confidence

Added DebugMacros to provide utilities for printing the final code, AST, and inferred types during compilation. These tools allow users to view detailed debugging information directly in the IDE output, aiding in understanding how code is processed and what types are inferred.

hearth/src/main/scala/hearth/debug · high confidence

Added the \Debug\ and \DebugOps\ utilities in the \hearth.debug\ package to help developers understand macro behavior during development. These tools allow users to preview the final generated code, the Abstract Syntax Tree (AST), and the inferred types of expressions or summoned implicits directly in their IDE as hints. This aids in debugging complex macro expansions by providing visibility into what the compiler sees and generates.

hearth/src/main/scala-3/hearth/debug · high confidence

The hearth-munit module introduces a new testing base trait, hearth.Suite, which extends MUnit to provide Hearth-specific testing utilities. Users can now group tests using the group method, ignore tests on specific Scala versions or platforms via extension methods, and use custom assertion operators: ==\> for standard equality and \<==\> for structural comparison of Data or String values that renders a detailed diff on failure. Additionally, the module includes MacroSuite for asserting on compilation errors and ScalaCheckSuite, which reparents ScalaCheck property testing onto hearth.Suite to allow nested properties within test groups.

hearth-munit · high confidence

Added standard macro extensions to treat Java collection types (including BitSet, Collection, Dictionary, Enumeration, Iterable, Iterator, Map, Optional, and Stream) as first-class collections. These extensions allow Java types to be converted to Scala Iterables and provide Factory implementations for building them, enabling seamless interoperability between Java and Scala collection APIs at compile time.

hearth/src/main/scalajvm/hearth/std · high confidence

Added \Debug\ and \DebugOps\ utilities in the \hearth.debug\ package that allow developers to inspect macro expansions, abstract syntax trees (ASTs), and inferred types directly within their IDE. These tools provide both static methods (e.g., \Debug.withFinalCodeInIDE\) and extension methods (e.g., \expr.withFinalCodeInIDE\) to preview the final generated code, the underlying AST, and type information without altering runtime behavior, aiding in the debugging of macro-based code generation.

hearth/src/main/scala-2/hearth/debug · high confidence

A new \scripts/test-snippets.scala\ script has been added to automatically run and validate code examples found in the documentation. This tool parses the MkDocs configuration, interpolates template variables (such as the project version), applies default Scala versions where missing, and executes the snippets to ensure they remain correct. It is designed to be run in CI or locally to catch broken examples in the user guide.

scripts · high confidence

The library now provides macros and types to capture source-code context at compile time. Users can access the enclosing method name, line number, file path, and file name via new \MethodName\, \Line\, \File\, and \FileName\ types. Additionally, a new \Text\[T\]\ case class allows capturing both a runtime value and its source-code representation (e.g., for assertion libraries), while a \Location\ class combines file and line information for easier debugging and error reporting.

hearth/src/main/scala/hearth/source · high confidence

This release introduces a comprehensive new API in the \hearth.typed\ package, providing cross-platform (Scala 2/3) utilities for inspecting and manipulating types and expressions at macro expansion time. The \Class\ trait offers a unified view of types, automatically narrowing to specific views like \CaseClass\, \Enum\, \SingletonValue\, or \JavaBean\ based on the underlying type structure. The \Method\ API replaces previous method handling with a builder-chain pattern (\OnInstance\ → \ApplyTypes\ → \ApplyValues\ → \Result\), enabling safe, step-by-step construction of method calls with support for type parameters, varargs, by-name parameters, and default values. Additionally, \ExprCodec.derived\ provides semi-automatic derivation for converting values to and from \Expr\s, supporting case classes, enums, and singletons with override maps for custom handling. The \Type\ API is enhanced with operations for decomposing type constructors, resolving runtime classes, and inspecting sealed hierarchies, while \Existential\ types allow safe handling of values with forgotten types.

hearth/src/main/scala/hearth/typed · high confidence

The repository is initialized with essential configuration files to support development and CI workflows. This includes an sbt launcher script, JVM options for local development, and SDK version pinning. The build is configured with scalafmt 3.11.5 and specific formatting rules for Scala 2.13 and Scala 3 source directories. Documentation infrastructure is set up using MkDocs and Read the Docs, and contribution guidelines are provided via CONTRIBUTING.md and AGENTS.md for AI agents. Additionally, Scala Steward is configured to ignore Scala compiler updates and pin sbt to the 1.x line.

(repo-wide) · high confidence

Added \CrossQuotesMacros.scala\ to provide Scala 2 support for the Cross-Quotes feature, enabling \Expr.quote\, \Expr.splice\, and \Type.of\ functionality via Scala 2 macros. This implementation handles type conversion, code printing with \showCodePretty\, and complex scenarios such as local type parameters, nested quotes, and implicit type resolution across enclosing methods, while addressing specific Scala 2 limitations like self-referential implicits and free type resolution.

hearth-cross-quotes/src/main/scala-2 · high confidence

Added Scala 3-specific implementations for untyped expression, method, and type reflection in the \hearth/untyped\ package. This includes \UntypedExprsScala3\ for term conversion, \UntypedMethodsScala3\ for parsing method signatures (with specific handling for varargs, by-name parameters, and default values), and \UntypedTypesScala3\ for type analysis (including opaque types, tuples, and visibility checks). These files provide the platform-specific bridge between Scala 3's \quotes.reflect\ API and Hearth's internal untyped representation.

hearth/src/main/scala-3/hearth/untyped · high confidence

Added Scala 2 and Scala 3 implementations of source-code utilities that allow capturing the source text of values at compile time. This includes implicit conversions for \MethodName\, \Line\, \File\, and \FileName\ to extract location metadata, as well as a \Text\[T\]\ materializer that captures the literal source code of an argument. These utilities enable macros and other compile-time constructs to access the original source text of expressions, supporting features like improved error reporting or debugging output.

hearth/src/main/scala-2/hearth/source, hearth/src/main/scala-3/hearth/source · high confidence

The library now includes platform-specific implementations for service loading and version tracking across Scala.js, JVM, and Scala Native. This introduces \loaderJs\, \loaderJvm\, and \loaderNative\ files that define how \ServiceLoader\ is instantiated on each platform, with Scala Native using a reflection-based workaround to bypass runtime limitations. Additionally, \versionsJs\, \versionsJvm\, and \versionsNative\ files expose the target platform (\Platform.Js\, \Platform.Jvm\, or \Platform.Native\) via a \byHearth\ value, enabling the library to identify its compilation target at runtime.

hearth/src/main/scalajs, hearth/src/main/scalajvm/hearth, hearth/src/main/scalanative · high confidence

The build configuration has been significantly restructured: the sbt version is upgraded to 1.13.0, and the previous collection of individual plugins (including sbt-scalafmt, sbt-projectmatrix, sbt-scalajs, sbt-scala-native, sbt-mima-plugin, and others) is replaced by the unified sbt-kubuszok plugin (v0.2.3). To support this, new build utilities are introduced, including ScalaTierAxis for custom versioning, Scala2Rows for platform matrix configuration, and a suite of code generators (ArityGen, TypeConstructorsGen, CrossQuotesMacrosGen, CrossCtorTestGen) that produce arity-based source code and test fixtures. Additionally, SourceGenPlugin and ServiceResourceGenPlugin are added to automate source generation and META-INF/services file creation from compile analysis.

project · high confidence

This change introduces the Scala 2-specific implementation layer for Hearth's macro infrastructure, enabling features that were previously Scala 3-only or incomplete. It adds \EnvironmentCrossQuotesSupport\ to strip free type symbols from expression trees, preventing compiler rejections when using \Expr.splice\ with local type parameters. It implements \EnvironmentsScala2\ to provide accurate source-position reporting (including corrections for macro parameter lists) and builds the lexical enclosure chain (\enclosingScope\), which allows dependency injection to resolve local \val\s within method bodies. Additionally, it provides \MacroCommonsScala2\ to wire these components together and \versionsScala2\ to detect the Scala and JDK versions at compile time via macros.

hearth/src/main/scala-2/hearth · high confidence

This change introduces the Scala 2-specific implementations for the library's core reflection abstractions, providing the concrete logic for handling untyped expressions, method signatures, parameters, and type metadata on the Scala 2 platform. It ensures cross-platform consistency by normalizing vararg types to \Seq\, resolving synthetic case-accessor visibility to match Scala 3 behavior, and implementing opaque type handling (returning \None\ as Scala 2 lacks native opaque types).

hearth/src/main/scala-2/hearth/untyped · high confidence

This change introduces the core Scala 3 implementation for Hearth's macro system, including \MacroCommonsScala3\ and platform-specific environment handling. It adds \withQuotes\ and \passQuotes\ utilities to correctly manage \scala.quoted.Quotes\ context when nesting \Expr.quote\ and \Expr.splice\ calls, and introduces \withMacroEntryCtx\ to fix scope exceptions (\#317/\#318) when derivations run inside splices. The update also implements \enclosingScope\ to expose lexical enclosures (methods, classes, objects) for dependency injection, and provides compile-time macros to detect the current Scala and JDK versions.

hearth/src/main/scala-3/hearth · high confidence

Added Java class and enum fixtures for Hearth macro testing; Added cross-version sandwich tests for typed macros; Expanded test coverage for macro behavior and type system features.

This change updates several build dependencies, including bumping Scala 3 to 3.3.8, munit to 1.3.6, scalacheck to 1.20.0, scala-xml to 2.5.0, and kind-projector to 0.13.4, while dropping support for Scala 2.12. It also introduces a new \docs/requirements.txt\ file specifying versions for mkdocs (1.6.1), mkdocs-macros-plugin (1.3.7), and mkdocs-material (9.5.50) to support documentation generation.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• First survey — no prior run to compare against. CAI 66.

• Code Health 79
• Architecture 99
• Maturity 64
• Readiness 59
• Security 79

• 300 commits — 223 feature/other, 77 fixes

• hearth-tests/src — 103 commits
• hearth/src — 71 commits
• (root) — 43 commits
• docs/user-guide — 16 commits
• .github/workflows — 15 commits
• project/build.properties — 12 commits
• docs/contributing — 10 commits
• hearth-micro-fp/src — 8 commits
• hearth-cross-quotes/src — 7 commits
• project/plugins.sbt — 4 commits
• hearth-better-printers/src — 3 commits
• scripts/test-snippets.scala — 3 commits
• docs/site — 2 commits
• project/TypeConstructorsGen.scala — 2 commits
• docs/mkdocs.yml — 1 commit

• fix: Add Parameter.isVararg with cross-platform Seq[A] normalization, vararg splicing in Method.ApplyValues (seq: *), A signature rendering, AnonymousInstance vararg override support; fix Scala 3 Parameter.isByName always returning false
• fix: Add semiEval overrides, semiQuote utility, rework ExprCodec.derived with override maps; fix annotation type preservation with annotationTypes + constructor destructuring; update docs
• fix: AnonymousInstance: surface returnsThisType + fix Scala 3.8.4 context-function returns (Kindlings §5/§6)
• fix: Another fix for val _ =
• fix: Coverage + bug fixes: Type.parents was broken on BOTH platforms (Scala 2 infinite recursion via missing reflect member; Scala 3 NoSuchMethodException - TypeReprMethods.parents absent on 3.3.x) - now derived from linearization/ClassInfoType; tests for Method applied-state toString, class-view Incompatible reasons, and Type.isTrait/parents/baseClasses
• fix: Fix "free type" issue when using type parameters and passing them as Type.of
• fix: Fix #246: add CaseClass.copyMethod; enable MiMa against 0.4.0
• fix: Fix #300: sanitize scala.* references in Scala 2 Type.CtorN.of codegen
• fix: Fix #307 (round 2): match wildcard existential args in Scala 2 CtorN.unapply
• fix: Fix #307: don't widen extracted type args in Scala 2 Type.CtorN codegen
• fix: Fix #315: classify export-created aliases by their underlying class (Scala 3)
• fix: Fix #316: exclude sibling Type givens during their init (Scala 3 plugin)
• fix: Fix #317 (owner mismatch): follow CrossQuotes.ctx for fresh symbol creation
• fix: Fix #317 follow-up: fresh vals must not be owned by native quoted-lambda $anonfun
• fix: Fix #317/#318 (splice-scoped values): add withMacroEntryCtx
• fix: Fix #320: fully-qualify object references in Scala 2 cross-unit quotes
• fix: Fix #321: EnumSet provider factory uses Class.forName, not wildcard classOf literals
• fix: Fix #322: route EnumSet (Scala 2) quotes through a helper method
• fix: Fix #327: inherited constructor-val fields report correct metadata (Scala 3)
• fix: Fix #331: keep value/implicit clauses that follow a type-parameter clause
• …and 280 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

kubuszok/hearth was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.