Add mention about chimney-macro-commons and chimney-engine to docs, u…

…pdate build.sbt for chimney-engine

build.sbt

@@ -290,9 +290,16 @@ val ciCommand = (platform: String, scalaSuffix: String) => {
   def withCoverage(tasks: String*): Vector[String] =
     "coverage" +: tasks.toVector :+ "coverageAggregate" :+ "coverageOff"
 
-  val projects = (Vector("chimney", "chimneyCats", "chimneyProtobufs") ++ (if (isJVM) Vector("chimneyJavaCollections")
-                                                                           else Vector.empty))
-    .map(name => s"$name${if (isJVM) "" else platform}$scalaSuffix")
+  val projects = for {
+    name <- Vector(
+      "chimney",
+      "chimneyCats",
+      "chimneyProtobufs",
+      if (isJVM) "chimneyJavaCollections" else "",
+      "chimneyEngine"
+    )
+    if name.nonEmpty
+  } yield s"$name${if (isJVM) "" else platform}$scalaSuffix"
   def tasksOf(name: String): Vector[String] = projects.map(project => s"$project/$name")
 
   val tasks = if (isJVM) {
@@ -325,9 +332,12 @@ lazy val root = project
   .settings(settings)
   .settings(publishSettings)
   .settings(noPublishSettings)
-  .aggregate(
-    (chimneyMacroCommons.projectRefs ++ chimney.projectRefs ++ chimneyCats.projectRefs ++ chimneyJavaCollections.projectRefs ++ chimneyProtobufs.projectRefs) *
-  )
+  .aggregate(chimneyMacroCommons.projectRefs *)
+  .aggregate(chimney.projectRefs *)
+  .aggregate(chimneyCats.projectRefs *)
+  .aggregate(chimneyJavaCollections.projectRefs *)
+  .aggregate(chimneyProtobufs.projectRefs *)
+  .aggregate(chimneyEngine.projectRefs *)
   .settings(
     moduleName := "chimney-build",
     name := "chimney-build",
@@ -528,10 +538,11 @@ lazy val chimneyEngine = projectMatrix
     description := "Chimney derivation engine exposed for reuse in other libraries"
   )
   .settings(settings *)
-  .settings(versionSchemeSettings *)
+  .settings(versionScheme := None) // macros internal API is NOT stable yet
   .settings(publishSettings *)
-  .settings(mimaSettings *)
+  // .settings(mimaSettings *) // we need to get some feedback before we stabilize this
   .settings(
+    coverageExcludedPackages := "io.scalaland.chimney.internal.compiletime.*", // we're only checking if it compiles
     mimaFailOnNoPrevious := false // this hasn't been published yet
   )
   .settings(dependencies *)

chimney-engine/src/test/scala-2/io/scalaland/chimney/example/example.scala

@@ -4,7 +4,7 @@ package object example {
 
   implicit class ConvertOps[From](private val source: From) extends AnyVal {
 
-    /** Privides the extension method on Scala 2.
+    /** Provides the extension method on Scala 2.
       *
       * Would allow usage of user-provided `MyTypeClass` falling back on autoderived `MyTypeClass.AutoDerived` WITHOUT
       * the overhead normally associated with automatic derivation.

chimney-engine/src/test/scala-2/io/scalaland/chimney/example/macros/MyTypeClassDerivationPlatform.scala

@@ -1,7 +1,6 @@
 package io.scalaland.chimney.example.internal
 
 import io.scalaland.chimney.example.MyTypeClass
-import io.scalaland.chimney.example.internal.MyTypeClassDerivation
 import io.scalaland.chimney.internal.compiletime.{DerivationEnginePlatform, StandardRules}
 
 /** Scala-2-specifc implementations */

chimney-engine/src/test/scala-3/io/scalaland/chimney/example/example.scala

@@ -2,7 +2,7 @@ package io.scalaland.chimney.example
 
 extension [From](source: From) {
 
-  /** Privides the extension method on Scala 3.
+  /** Provides the extension method on Scala 3.
     *
     * Would allow usage of user-provided `MyTypeClass` falling back on autoderived `MyTypeClass.AutoDerived` WITHOUT the
     * overhead normally associated with automatic derivation.

chimney-engine/src/test/scala-3/io/scalaland/chimney/example/internal/MyTypeClassDerivationPlatform.scala

@@ -1,7 +1,6 @@
 package io.scalaland.chimney.example.internal
 
 import io.scalaland.chimney.example.MyTypeClass
-import io.scalaland.chimney.example.internal.MyTypeClassDerivation
 import io.scalaland.chimney.internal.compiletime.{DerivationEnginePlatform, StandardRules}
 
 /** Scala-3-specifc implementations */

docs/docs/cookbook.md

@@ -2348,3 +2348,50 @@ easier just like Neotype or other libraries described in
 
 You can find it on [GitHub](https://github.com/kevin-lee/refined4s) or
 [Scaladex](https://index.scala-lang.org/kevin-lee/refined4s/artifacts/refined4s-cats).
+
+## Reusing Chimney macros in your own macro library
+
+Some parts of the Chimney macros could be useful to developers of other libraries. As part of the 0.8.0 refactor,
+we developed:
+
+ - a platform-agnostic way of defining macro logic - see [Under the Hood](under-the-hood.md) for more information
+ - `chimney-macro-commons` - the module extracting non-Chimney-specific macro utilities: extracting fields/nullary
+   `def`s from classes, extracting constructors and all setters (if available), extracting enum subtypes/values,
+   exposing `blackbox.Context`/`Quotes` utilities in a platform-agnostic way, etc
+ - an automatic derivation without the standard automatic derivation overhead
+ - a recursive derivation engine based on the chain-of-responsibility pattern
+
+For now there aren't many people interested in them, so comments and Chimney-code-as-examples is the only documentation
+available.
+
+### `chimney-macro-commons`
+
+This module contains no dependencies on Chimney runtime types, not Chimney-specific macro logic. It could be used to
+reuse Chimney utilities for e.g.:
+
+ - extracting `val`ues and nullary `def`s from any class
+ - extracting public constructors and setters
+ - converting between singleton `Type[A]` and `Expr[A]`
+ - providing a platform-agnostic utilities for some common types and expressions
+
+!!! note
+
+    This module is checked by MiMa, its API should be considered stable.
+
+### `chimney-engine`
+
+This module exposes Chimney derivation engine to make it easier to use in one's own macros. It assumes that user would
+implement its macro the same way as Chimney does it, and with similar assumptions
+(see [Under the Hood](under-the-hood.md)).
+
+The only documentation is
+[the example code](https://github.com/scalalandio/chimney/blob/{{ git.short_commit }}/chimney-engine/src/test/) which
+illustrates how one would start developing a macro basing on Chimney engine.
+
+!!! warning
+
+    This module exposes Chimney internal macros, their API can change to enable new feature development, so consider it
+    unstable and experimental!
+
+    The module's version matches `chimney` version it was compiled against, but it should NOT be considered a semantic
+    version.