Merge branch 'master' into mn420

.github/workflows/central-sync.yml

@@ -20,7 +20,7 @@ jobs:
           ref: v${{ github.event.inputs.release_version }}
       - uses: gradle/wrapper-validation-action@v1
       - name: Set up JDK
-        uses: actions/setup-java@v3
+        uses: actions/setup-java@v4
         with:
           distribution: 'temurin'
           java-version: '17'

.github/workflows/gradle.yml

@@ -45,7 +45,7 @@ jobs:
           fetch-depth: 0
 
       - name: "🔧 Setup GraalVM CE"
-        uses: graalvm/[email protected].4
+        uses: graalvm/[email protected].5
         with:
           distribution: 'graalvm'
           java-version: ${{ matrix.java }}

.github/workflows/publish-snapshot.yml

@@ -18,7 +18,7 @@ jobs:
           restore-keys: |
             ${{ runner.os }}-gradle-
       - name: Set up JDK
-        uses: actions/setup-java@v3
+        uses: actions/setup-java@v4
         with:
           distribution: 'temurin'
           java-version: '17'

.github/workflows/release.yml

@@ -19,7 +19,7 @@ jobs:
           token: ${{ secrets.GH_TOKEN }}
       - uses: gradle/wrapper-validation-action@v1
       - name: Set up JDK
-        uses: actions/setup-java@v3
+        uses: actions/setup-java@v4
         with:
           distribution: 'temurin'
           java-version: '17'
@@ -146,7 +146,7 @@ jobs:
     if: startsWith(github.ref, 'refs/tags/')
     steps:
       - name: Checkout repository
-        uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Download artifacts
         uses: actions/download-artifact@9bc31d5ccc31df68ecc42ccf4149144866c47d8a # v3.0.2
         with:

.gitignore

@@ -32,4 +32,4 @@ src/main/docs/resources/style/*.html
 src/main/docs/resources/img/micronaut-logo-white.svg
 
 # Ignore files generated by test-resources
-**/.micronaut/test-resources/
+**/.micronaut/test-resources/

MAINTAINING.md

@@ -102,14 +102,14 @@ The consequence of having both approaches in place is that we get multiple depen
 `micronaut-build` via our automation, and one or many (one per dependency) created by Renovate. When merging those, it
 is better to prefer the `micronaut-build` ones, if possible, for 2 reasons: a) they attempt to upgrade multiple dependencies
 in a single PR, which creates less noise in the Git history; b) Once you merge that, Renovate will react and automatically
-close its own PRs if the dependecy is up-to-date.
+close its own PRs if the dependency is up-to-date.
 
 When an upgrade to a new version arrives, we need to be careful when merging, so that we don't introduce an
 unnecessary upgrade burden on our users. Read the
 [Module Upgrade Strategy](https://github.com/micronaut-projects/micronaut-core/wiki/Module-Upgrade-Strategy) for more
 information.
 
-Note that if a new version arrives and we are not ready yet to do the upgrade, you need to
+Note that if a new version arrives, and we are not ready yet to do the upgrade, you need to
 [pin the old version](https://github.com/micronaut-projects/micronaut-build/#configuration-options), because otherwise,
 Renovate and our workflow will keep sending PRs. You should also create an issue to upgrade so that it's not forgotten.
 
@@ -162,7 +162,7 @@ First of all, all the repos have an automatic changelog generation mechanism: wh
 release notes will contain pull requests merged and issues closed since the last release.
 
 When the module is ready for a new release, check the generated release notes, and make changes if needed (for example,
-you can add an introduction paragraph highligting some items included in the release). If the version you are going to
+you can add an introduction paragraph highlighting some items included in the release). If the version you are going to
 publish is not a new patch version, but a new minor or major, update the release notes text to reflect the new version.
 If you are publishing a milestone or release candidate, check the pre-release checkbox.
 

SECURITY.md

@@ -4,7 +4,7 @@ We release patches for security vulnerabilities. Which versions are eligible
 receiving such patches depend on the CVSS v3.0 Rating:
 
 | CVSS v3.0 | Supported Versions                        |
-| --------- | ----------------------------------------- |
+|-----------|-------------------------------------------|
 | 9.0-10.0  | Releases within the previous three months |
 | 4.0-8.9   | Most recent release                       |
 

buildSrc/src/main/groovy/io.micronaut.build.internal.sourcegen-testsuite.gradle

@@ -1,6 +1,6 @@
 plugins {
     id("io.micronaut.build.internal.sourcegen-base")
-    id("io.micronaut.build.internal.base-module")
+    id("io.micronaut.build.internal.common")
 }
 
 tasks.withType(Test).configureEach {
@@ -11,12 +11,6 @@ tasks.withType(Checkstyle).configureEach {
     enabled = false
 }
 
-micronautBuild {
-    binaryCompatibility {
-        enabled.set(false)
-    }
-}
-
 if (System.getenv("SONAR_TOKEN") != null) {
     tasks.configureEach { if (it.name == "testCodeCoverageReport") { enabled = false } }
 }

gradle.properties

@@ -2,7 +2,7 @@ projectVersion=1.0.0-SNAPSHOT
 projectGroup=io.micronaut.sourcegen
 
 title=Compilation time source code generators
-projectDesc=TODO
+projectDesc=Micronaut SourceGen exposes a language-neutral API for source code generation.
 projectUrl=https://micronaut.io
 githubSlug=micronaut-projects/micronaut-sourcegen
 developers=Denis Stepanov

gradle/libs.versions.toml

@@ -1,5 +1,5 @@
 [versions]
-micronaut = "4.2.0"
+micronaut = "4.2.2"
 micronaut-docs = "2.0.0"
 micronaut-test = "4.1.0"
 groovy = "4.0.15"

gradle/wrapper/gradle-wrapper.properties

@@ -1,6 +1,6 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.4-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.5-bin.zip
 networkTimeout=10000
 validateDistributionUrl=true
 zipStoreBase=GRADLE_USER_HOME

sourcegen-generator-java/src/main/java/io/micronaut/sourcegen/javapoet/TypeName.java

@@ -50,15 +50,15 @@
  * <p>Instances of this class are immutable value objects that implement {@code equals()} and {@code
  * hashCode()} properly.
  *
- * <h3>Referencing existing types</h3>
+ * <strong>Referencing existing types</strong>
  *
  * <p>Primitives and void are constants that you can reference directly: see {@link #INT}, {@link
  * #DOUBLE}, and {@link #VOID}.
  *
  * <p>In an annotation processor you can get a type name instance for a type mirror by calling
  * {@link #get(TypeMirror)}. In reflection code, you can use {@link #get(Type)}.
  *
- * <h3>Defining new types</h3>
+ * <strong>Defining new types</strong>
  *
  * <p>Create new reference types like {@code com.example.HelloWorld} with {@link
  * ClassName#get(String, String, String...)}. To build composite types like {@code char[]} and

src/main/docs/guide/annotations.adoc

@@ -0,0 +1,32 @@
+The module Micronaut SourceGen annotations ships with annotations which you can use in your projects:
+
+To use them, you need the following dependency:
+
+dependency:micronaut-sourcegen-annotations[groupId=io.micronaut.sourcegen]
+
+dependency:micronaut-sourcegen-annotations[groupId=io.micronaut.sourcegen,scope=annotationProcessor]
+
+[options="header"]
+|===
+| Annotation | Description
+
+| api:sourcegen.annotations.Builder[]
+| Create a builder of the annotated type.
+|===
+
+
+If you annotate a Java Record with `@Builder`, a `PersonBuilder` class is generated at compliation-time.
+
+[source,java]
+----
+include::test-suite-java/src/main/java/io/micronaut/sourcegen/example/Person.java[tags=clazz,indent=0]
+----
+
+You can use a https://blogs.oracle.com/javamagazine/post/exploring-joshua-blochs-builder-design-pattern-in-java[builder pattern] to create a `Person` instance:
+
+[source,java]
+----
+include::test-suite-java/src/test/java/io/micronaut/sourcegen/example/PersonBuilderTest.java[tags=test,indent=0]
+----
+
+NOTE: The https://github.com/micronaut-projects/micronaut-sourcegen/blob/master/sourcegen-generator/src/main/java/io/micronaut/sourcegen/generator/visitors/BuilderAnnotationVisitor.java[BuilderAnnotationVisitor] is an example of how to use the Micronaut SourceGen API.

src/main/docs/guide/introduction.adoc

@@ -1 +1 @@
-TODO
+Micronaut SourceGen exposes a language-neutral API for source code generation. It uses https://github.com/square/javapoet[JavaPoet] internally.

src/main/docs/guide/toc.yml

@@ -1,7 +1,6 @@
 introduction:
   title: Introduction
 releaseHistory: Release History
-quickStart:
-  title: Quick Start
+annotations: Annotations
 repository: Repository
 

test-suite-java/src/main/java/io/micronaut/sourcegen/example/Person.java

@@ -16,8 +16,10 @@
 package io.micronaut.sourcegen.example;
 
 
+//tag::clazz[]
 import io.micronaut.sourcegen.annotations.Builder;
 
 @Builder
 public record Person(Long id, String name) {
 }
+//end::clazz[]

test-suite-java/src/test/java/io/micronaut/sourcegen/example/PersonBuilderTest.java

@@ -20,6 +20,8 @@
 import static org.junit.jupiter.api.Assertions.assertEquals;
 
 class PersonBuilderTest {
+
+//tag::test[]
     @Test
     public void buildsPerson() {
         var person = PersonBuilder.builder()
@@ -29,4 +31,5 @@ public void buildsPerson() {
         assertEquals("Cédric", person.name());
         assertEquals(123L, person.id());
     }
+//end::test[]
 }