feat!: ✨ Immutable Collections Extension added

.github/semantic.yml

@@ -0,0 +1 @@
+titleAndCommits: true

README.md

@@ -2,47 +2,54 @@
 
 Java record newContext generator
 
-[![Maven Central version](https://img.shields.io/maven-central/v/pl.com.labaj/auto-record)](https://mvnrepository.com/artifact/pl.com.labaj/auto-record)
-[![javadoc](https://javadoc.io/badge2/pl.com.labaj/auto-record/javadoc.svg)](https://javadoc.io/doc/pl.com.labaj/auto-record)
+[![Maven Central version](https://img.shields.io/maven-central/v/pl.com.labaj.autorecord/auto-record)](https://mvnrepository.com/artifact/pl.com.labaj.autorecord/auto-record)
+[![javadoc](https://javadoc.io/badge2/pl.com.labaj.autorecord/auto-record-project/javadoc.svg)](https://javadoc.io/doc/pl.com.labaj.autorecord/auto-record-project)
 
 [![CI Verify Status](https://github.com/pawellabaj/auto-record/actions/workflows/verify.yml/badge.svg?branch=main)](https://github.com/pawellabaj/auto-record/actions/workflows/verify.yml)
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=pl.com.labaj%3Aauto-record-project&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=pl.com.labaj%3Aauto-record-project)
 [![Sonatype Lift Status](https://lift.sonatype.com/api/badge/github.com/pawellabaj/auto-record)](https://lift.sonatype.com/results/github.com/pawellabaj/auto-record)
-[![Reproducible Builds](https://img.shields.io/badge/Reproducible_Builds-ok-success?labelColor=1e5b96)](https://github.com/jvm-repo-rebuild/reproducible-central#pl.com.labaj:auto-record)
+[![Reproducible Builds](https://img.shields.io/badge/Reproducible_Builds-ok-success?labelColor=1e5b96)](https://github.com/jvm-repo-rebuild/reproducible-central#pl.com.labaj.autorecord:auto-record)
+[![OpenSSF Best Practices](https://bestpractices.coreinfrastructure.org/projects/7700/badge)](https://bestpractices.coreinfrastructure.org/projects/7700)
 [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](.github/CODE_OF_CONDUCT.md)
 
 ## What is AutoRecord
 
-AutoRecord is a code generator that helps you easily generate Java records. 
+AutoRecord is a code generator that helps you easily generate Java records.
 It provides an easy way to avoid writing repetitive boilerplate code. It generates the code with features such as:
+
 * [nullability](https://github.com/pawellabaj/auto-record/wiki/Nullability) checking
-* [builders](https://github.com/pawellabaj/auto-record/wiki/Record-Builder) - incorporating [Randgalt/record-builder](https://github.com/Randgalt/record-builder) library
+* [builders](https://github.com/pawellabaj/auto-record/wiki/Record-Builder) -
+  incorporating [Randgalt/record-builder](https://github.com/Randgalt/record-builder) library
 * [memoization](https://github.com/pawellabaj/auto-record/wiki/Memoization)
 * [ignoring fields](https://github.com/pawellabaj/auto-record/wiki/Ignored-components) in `hashCode()` and `equals()` methods
-* generated _common_ methods if the record has an [array component](https://github.com/pawellabaj/auto-record/wiki/Array-components)
+* generated _common_ methods if the record has an [array recordComponent](https://github.com/pawellabaj/auto-record/wiki/Array-components)
 * exclusion from [JaCoCo test coverage](https://github.com/pawellabaj/auto-record/wiki/JaCoCo-exclusion) analysis
 
 AutoRecord allows users to customize record generation process by:
+
 * specifying [options](https://github.com/pawellabaj/auto-record/wiki/Single-record-options)
 * using [custom annotation](https://github.com/pawellabaj/auto-record/wiki/Custom-annotations) templates
 * implementing [custom extensions](https://github.com/pawellabaj/auto-record/wiki/Extensions)
 
 ## Why AutoRecord was created
 
 Google [AutoValue](https://github.com/google/auto) has long been used as a way to work with _Value Classes_ in an easy way.
-However, when Java [records](https://docs.oracle.com/en/java/javase/17/language/records.html) were introduced, they lacked some features that AutoValue had, such as nullability checking, builders, and memoization.
+However, when Java [records](https://docs.oracle.com/en/java/javase/17/language/records.html) were introduced, they lacked some features that AutoValue had,
+such as nullability checking, builders, and memoization.
 This is why AutoRecord was created.
 
 ## How to use AutoRecord
 
-To use AutoRecord, simply annotate your interface with [@AutoRecord](https://github.com/pawellabaj/auto-record/blob/main/modules/auto-record/src/main/java/pl/com/labaj/autorecord/AutoRecord.java) annotation:
+To use AutoRecord, simply annotate your interface
+with [@AutoRecord](https://github.com/pawellabaj/auto-record/blob/main/modules/auto-record/src/main/java/pl/com/labaj/autorecord/AutoRecord.java) annotation:
 
 ```java
 import pl.com.labaj.autorecord.AutoRecord;
 
 @AutoRecord
 interface Person {
     String name();
+
     int age();
 }
 ```
@@ -51,7 +58,9 @@ AutoRecord will then generate a Java record class that implements your interface
 
 ```java
 import pl.com.labaj.autorecord.GeneratedWithAutoRecord;
+
 import javax.annotation.processing.Generated;
+
 import static java.util.Objects.requireNonNull;
 
 @Generated("pl.com.labaj.autorecord.AutoRecord")
@@ -71,17 +80,30 @@ record PersonRecord(String name, int age) implements Person {
 
 For more information on how to use AutoRecord and all its features, please visit the project's [Wiki](https://github.com/pawellabaj/auto-record/wiki).
 
+## Projects maintained in this repository
+
+| Project                                                                                                                    | Description                                                                                      |
+|:---------------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------|
+| [Auto Record API](https://github.com/pawellabaj/auto-record/tree/main/modules/auto-record-api)                             | Annotations to mark interfaces to be processed                                                   |
+| [Auto Record](https://github.com/pawellabaj/auto-record/tree/main/modules/auto-record)                                     | Annotation processor to generate records                                                         | 
+| [Auto Record Utilities](https://github.com/pawellabaj/auto-record/tree/main/modules/auto-record-utils)                     | Utility classes used by generated records                                                        | 
+| [ARICE API](https://github.com/pawellabaj/auto-record/tree/main/arice/api)                                                 | Annotations to mark interface methods, used by ARICE                                             |
+| [ARICE (Auto Record Immutable Collections Extension)](https://github.com/pawellabaj/auto-record/tree/main/arice/extension) | The extension for customizing a record generation process with support for immutable collections |
+| [ARICE Utilities](https://github.com/pawellabaj/auto-record/tree/main/arice/utils)                                         | Utility classes used by ARICE                                                                    | 
+
 ## Getting started
 
 ### Maven
 
 Add the following dependency to your `pom.xml` file:
 
 ```xml
+
 <dependency>
-    <groupId>pl.com.labaj</groupId>
+    <groupId>pl.com.labaj.autorecord</groupId>
     <artifactId>auto-record</artifactId>
     <version>${auto-record.version}</version>
+    <scope>provided</scope>
 </dependency>
 ```
 
@@ -91,7 +113,7 @@ Declare the following dependency in your `build.gradle` script:
 
 ```groovy
 dependencies {
-    annotationProcessor 'pl.com.labaj:auto-record:${autoRecordVersion}'
+    annotationProcessor 'pl.com.labaj.autorecord:auto-record:${autoRecordVersion}'
 }
 ```
 
@@ -100,7 +122,9 @@ dependencies {
 Depending on your IDE you are likely to need to enable Annotation Processing in your IDE settings.
 
 ## Contributing
-We welcome contributions from all developers! If you would like to contribute to AutoRecord, please refer to the [Contributing guide](.github/CONTRIBUTING.md) for more information on how to get started.
+
+We welcome contributions from all developers! If you would like to contribute to AutoRecord, please refer to the [Contributing guide](.github/CONTRIBUTING.md)
+for more information on how to get started.
 
 ## License
 

arice/api/README.md

@@ -0,0 +1,34 @@
+# ARICE API
+
+Annotations to mark methods in an interface, used during annotation processing with ARICE usage.
+
+Please, see [WIKI](https://github.com/pawellabaj/auto-record/wiki/ARICE) for information.
+
+## Usage
+
+If you use annotation processing in your project, the library will be provided as a dependency of [ARICE](https://github.com/pawellabaj/auto-record/tree/main/arice/extension).
+
+If you just want to mark your sources (ieg. annotations are being processed in other project or build step),
+use `arice-api` directly.
+
+### Maven
+
+Add the following dependency to your `pom.xml` file:
+
+```xml
+
+<dependency>
+    <groupId>pl.com.labaj.autorecord</groupId>
+    <artifactId>arice-api</artifactId>
+    <version>${arice.version}</version>
+</dependency>
+```
+
+### Gradle
+
+Declare the following dependency in your `build.gradle` script:
+
+```groovy
+dependencies {
+    annotationProcessor 'pl.com.labaj.autorecord:arice-api:${ariceVersion}'
+}

arice/api/pom.xml

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>pl.com.labaj.autorecord</groupId>
+        <artifactId>arice-project</artifactId>
+        <version>1.0.0-SNAPSHOT</version>
+        <relativePath>../project/pom.xml</relativePath>
+    </parent>
+
+    <name>ARICE API</name>
+
+    <artifactId>arice-api</artifactId>
+</project>

arice/api/src/main/java/pl/com/labaj/autorecord/extension/arice/Mutable.java

@@ -0,0 +1,41 @@
+package pl.com.labaj.autorecord.extension.arice;
+
+/*-
+ * Copyright © 2023 Auto Record
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import org.apiguardian.api.API;
+
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.ElementType.PARAMETER;
+import static java.lang.annotation.ElementType.TYPE_PARAMETER;
+import static java.lang.annotation.RetentionPolicy.SOURCE;
+import static org.apiguardian.api.API.Status.STABLE;
+
+/**
+ * Annotates methods in @AutoRecord annotated interface for which the corresponding components in generated record are not relevant
+ * for copying to immutable collection.
+ *
+ * @see <a href="https://github.com/pawellabaj/auto-record/wiki/ARICE">ARICE Wiki</a>
+ */
+@Retention(SOURCE)
+@Target({METHOD, TYPE_PARAMETER, PARAMETER})
+@Inherited
+@API(status = STABLE)
+public @interface Mutable {}

modules/auto-record/src/main/java/pl/com/labaj/autorecord/extension/package-info.java → arice/api/src/main/java/pl/com/labaj/autorecord/extension/arice/package-info.java

@@ -14,19 +14,9 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-
 /**
- * Provides annotations and interfaces needed to process extensions.
- *
- * <p>{@link pl.com.labaj.autorecord.extension.AutoRecordExtension} interface has to be implemented by all extensions.
+ * Provides annotations used to annotate interfaces or methods that are used by <a href="https://github.com/pawellabaj/auto-record/blob/main/arice/extension/src/main/java/pl/com/labaj/autorecord/extension/arice/ImmutableCollectionsExtension.java">ImmutableCollectionsExtension</a>.
  *
- * @see <a href="https://github.com/pawellabaj/auto-record/wiki/Extensions">Extensions Wiki</a>
- * @since 2.1.0
+ * @see <a href="https://github.com/pawellabaj/auto-record/wiki/ARICE/">Wiki</a>
  */
-
-@API(status = STABLE, since = "2.1.0")
-package pl.com.labaj.autorecord.extension;
-
-import org.apiguardian.api.API;
-
-import static org.apiguardian.api.API.Status.STABLE;
+package pl.com.labaj.autorecord.extension.arice;

arice/extension/README.md

@@ -0,0 +1,43 @@
+# ARICE (Auto Record Immutable Collections Extension)
+
+An implementations of the link AutoRecord extension for customizing a record generation process with support for immutable collections.
+
+## Documentation
+
+For more information on how to use ARICE and all its features, please visit the project's [Wiki](https://github.com/pawellabaj/auto-record/wiki/ARICE).
+
+## Getting started
+
+### Maven
+
+Add the following dependency to your `pom.xml` file:
+
+```xml
+<dependency>
+    <groupId>pl.com.labaj.autorecord</groupId>
+    <artifactId>auto-record</artifactId>
+    <version>${auto-record.version}</version>
+    <scope>provided</scope>
+</dependency>
+<dependency>
+    <groupId>pl.com.labaj.autorecord</groupId>
+    <artifactId>arice</artifactId>
+    <version>${arice.version}</version>
+    <scope>provided</scope>
+</dependency>
+```
+
+### Gradle
+
+Declare the following dependency in your `build.gradle` script:
+
+```groovy
+dependencies {
+    annotationProcessor 'pl.com.labaj.autorecord:auto-record:${autoRecordVersion}',
+    implementation 'pl.com.labaj.autorecord:arice:${ariceVersion}'
+}
+```
+
+### IDE
+
+Depending on your IDE you are likely to need to enable Annotation Processing in your IDE settings.

arice/extension/pom.xml

@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>pl.com.labaj.autorecord</groupId>
+        <artifactId>arice-project</artifactId>
+        <version>1.0.0-SNAPSHOT</version>
+        <relativePath>../project/pom.xml</relativePath>
+    </parent>
+
+    <name>ARICE</name>
+    <description>Auto Record Immutable Collections Extension</description>
+    <artifactId>arice-extension</artifactId>
+
+    <properties>
+        <license-maven-plugin.header>${project.basedir}/../../.build/lic-header.txt</license-maven-plugin.header>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>pl.com.labaj.autorecord</groupId>
+            <artifactId>auto-record</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>pl.com.labaj.autorecord</groupId>
+            <artifactId>arice-api</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>pl.com.labaj.autorecord</groupId>
+            <artifactId>arice-utils</artifactId>
+        </dependency>
+    </dependencies>
+</project>

arice/extension/src/main/java/pl/com/labaj/autorecord/extension/arice/ARICEUtilities.java

@@ -0,0 +1,54 @@
+package pl.com.labaj.autorecord.extension.arice;
+
+/*-
+ * Copyright © 2023 Auto Record
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import org.apiguardian.api.API;
+
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+import static java.lang.annotation.ElementType.TYPE;
+import static java.lang.annotation.RetentionPolicy.SOURCE;
+import static org.apiguardian.api.API.Status.MAINTAINED;
+
+/**
+ * This annotation is used to mark the generated record, so the ARICE (AutoRecord Immutable Collections Extension)
+ * knows what utility class it should generate.
+ *
+ * @since 3.0.0
+ */
+@Retention(SOURCE)
+@Target(TYPE)
+@Inherited
+@API(status = MAINTAINED)
+public @interface ARICEUtilities {
+    /**
+     * Specifies the fully qualified name of the utility class that provides additional methods and functionality
+     * to support the ARICE extension.
+     *
+     * @return the fully qualified name of the utility class.
+     */
+    String className();
+
+    /**
+     * Specifies an array of fully qualified names of immutable types. These types will be used in conjunction with the ARICE extension
+     *
+     * @return an array of fully qualified names of immutable types.
+     */
+    String[] immutableTypes() default {};
+}