Introduce Plugin API for ChangeRecorder

pom.xml

@@ -96,10 +96,11 @@
   </contributors>
 
   <modules>
-    <module>versions-maven-plugin</module>
-    <module>model-ruleset</module>
     <module>model-report</module>
+    <module>model-ruleset</module>
+    <module>versions-api</module>
     <module>versions-common</module>
+    <module>versions-maven-plugin</module>
   </modules>
 
   <scm>
@@ -133,6 +134,7 @@
     <modelloNamespaceReportVersion>2.0.0</modelloNamespaceReportVersion>
     <scmpublish.content>${project.build.directory}/staging</scmpublish.content><!-- mono-module doesn't require site:stage for scm-publish -->
     <project.build.outputTimestamp>2022-10-23T15:41:47Z</project.build.outputTimestamp>
+    <sisu-maven-plugin-version>0.9.0.M1</sisu-maven-plugin-version>
   </properties>
 
   <dependencyManagement>
@@ -198,6 +200,26 @@
   </dependencyManagement>
 
   <build>
+
+    <pluginManagement>
+      <plugins>
+        <plugin>
+          <groupId>org.eclipse.sisu</groupId>
+          <artifactId>sisu-maven-plugin</artifactId>
+          <version>${sisu-maven-plugin-version}</version>
+          <executions>
+            <execution>
+              <id>generate-index</id>
+              <goals>
+                <goal>main-index</goal>
+                <goal>test-index</goal>
+              </goals>
+            </execution>
+          </executions>
+        </plugin>
+      </plugins>
+    </pluginManagement>
+
     <plugins>
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>

versions-api/pom.xml

@@ -0,0 +1,17 @@
+<?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 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <parent>
+    <groupId>org.codehaus.mojo.versions</groupId>
+    <artifactId>versions</artifactId>
+    <version>2.14.0-SNAPSHOT</version>
+  </parent>
+
+  <artifactId>versions-api</artifactId>
+  <name>Versions API</name>
+  <description>Extension API for Versions Plugin</description>
+
+</project>

versions-api/src/main/java/org/codehaus/mojo/versions/api/change/VersionChange.java

@@ -0,0 +1,52 @@
+package org.codehaus.mojo.versions.api.change;
+
+/*
+ * Copyright MojoHaus and Contributors
+ *
+ * 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.
+ *
+ */
+
+/**
+ * Represents a change of an item's version.
+ *
+ * @author Slawomir Jaranowski
+ * @since 2.14.0
+ */
+public interface VersionChange
+{
+    /**
+     * @return a groupId of changed item
+     * @since 2.14.0
+     */
+    String getGroupId();
+
+    /**
+     * @return an ArtifactId of change item
+     * @since 2.14.0
+     */
+    String getArtifactId();
+
+    /**
+     * @return an old version of changed item
+     * @since 2.14.0
+     */
+    String getOldVersion();
+
+    /**
+     * @return a new version of changed item
+     * @since 2.14.0
+     */
+    String getNewVersion();
+
+}

versions-api/src/main/java/org/codehaus/mojo/versions/api/recording/ChangeRecord.java

@@ -0,0 +1,66 @@
+package org.codehaus.mojo.versions.api.recording;
+
+/*
+ * Copyright MojoHaus and Contributors
+ *
+ * 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.codehaus.mojo.versions.api.change.VersionChange;
+
+/**
+ * Represents a change record of an item's version.
+ *
+ * @author Slawomir Jaranowski
+ * @since 2.14.0
+ */
+public interface ChangeRecord
+{
+    /**
+     * Describe where version item is updated.
+     */
+    enum ChangeKind
+    {
+        DEPENDENCY( "dependency-update" ),
+        DEPENDENCY_MANAGEMENT( "dependency-management-update" ),
+        PARENT( "parent-update" ),
+        PLUGIN( "plugin-update" ),
+        PLUGIN_MANAGEMENT( "plugin-management-update" ),
+        PROPERTY( "property-update" );
+
+        private final String label;
+
+        ChangeKind( String label )
+        {
+            this.label = label;
+        }
+
+        public String getLabel()
+        {
+            return label;
+        }
+    }
+
+    /**
+     * @return a version item change kind
+     * @since 2.14.0
+     */
+    ChangeKind getKind();
+
+    /**
+     * @return a details about changed item
+     * @since 2.14.0
+     */
+    VersionChange getVersionChange();
+}

versions-api/src/main/java/org/codehaus/mojo/versions/api/recording/ChangeRecorder.java

@@ -0,0 +1,52 @@
+package org.codehaus.mojo.versions.api.recording;
+
+/*
+ * Copyright MojoHaus and Contributors
+ *
+ * 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 java.io.IOException;
+import java.nio.file.Path;
+
+/**
+ * Interface for implement a recorder of version changes.
+ *
+ * @author Slawomir Jaranowski
+ * @since 2.14.0
+ */
+public interface ChangeRecorder
+{
+    /**
+     * Record that a dependency was updated.
+     *
+     * @param changeRecord a record described change
+     * @since 2.14.0
+     */
+    void recordChange( ChangeRecord changeRecord );
+
+    /**
+     * Write the current set of changes to the given output path.
+     * <p>
+     * Implementation is responsible for creating all missing directories.
+     * <p>
+     * Output should not be created for empty record sets.
+     *
+     * @param outputPath The output path, can be null, provided by <code>changeRecorderOutputFile</code>
+     *                   plugin parameters
+     * @throws IOException On write and/or I/O errors
+     * @since 2.14.0
+     */
+    void writeReport( Path outputPath ) throws IOException;
+}

versions-api/src/site/markdown/change-recorder.md.vm

@@ -0,0 +1,88 @@
+title: Writing a own ChangeRecorder
+author: Slawomir Jaranowski
+date: 2022-11-20
+
+Writing an own ChangeRecorder
+============================
+
+In order to create an own ChangeRecorder you must implement [ChangeRecorder](apidocs/org/codehaus/mojo/versions/api/recording/ChangeRecorder.html) interface.
+
+Write code
+----------
+
+```java
+import javax.inject.Named;
+
+import java.nio.file.Path;
+
+import org.codehaus.mojo.versions.api.recording.ChangeRecord;
+import org.codehaus.mojo.versions.api.recording.ChangeRecorder;
+
+@Named( "my-recorder" )
+public class MyChangeRecorder implements ChangeRecorder
+{
+    @Override
+    public final void recordChange( ChangeRecord changeRecord )
+    {
+        // your code
+    }
+
+    @Override
+    public final void writeReport( Path outputPath )
+    {
+        // your code
+    }
+}
+```
+
+`Changerecoder` is stateful component, so you must not add `Singleton` annotation to it.
+
+Using extension
+---------------
+
+Plugin configuration:
+
+```xml
+<?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 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <groupId>your.group</groupId>
+  <artifactId>your-project</artifactId>
+
+  <build>
+    <pluginManagement>
+      <plugins>
+        <plugin>
+          <groupId>org.codehaus.mojo</groupId>
+          <artifactId>versions-maven-plugin</artifactId>
+          <version>${project.version}</version>
+          <configuration>
+            <!-- your component name -->
+            <changeRecorderFormat>my-recorder</changeRecorderFormat>
+            <changeRecorderOutputFile>\${project.build.directory}/my-versions-changes.txt</changeRecorderOutputFile>
+          </configuration>
+          <dependencies>
+            <dependency>
+              <!-- add your extension as plugin dependency -->
+              <groupId>your.group</groupId>
+              <artifactId>your-extension</artifactId>
+              <version>ext.version</version>
+            </dependency>
+          </dependencies>
+        </plugin>
+      </plugins>
+    </pluginManagement>
+  </build>
+</project>
+```
+
+Now execution like:
+
+```
+mvn versions:update-properties
+```
+
+will generate your custom report.