feat: add autodocBom task to generate Autodoc manifests for BOMs (#282)

Author: paullatzelsperger

plugins/autodoc/autodoc-plugin/src/main/java/org/eclipse/edc/plugins/autodoc/AutodocPlugin.java

@@ -14,6 +14,7 @@
 
 package org.eclipse.edc.plugins.autodoc;
 
+import org.eclipse.edc.plugins.autodoc.tasks.AutodocBomTask;
 import org.eclipse.edc.plugins.autodoc.tasks.DownloadManifestTask;
 import org.eclipse.edc.plugins.autodoc.tasks.MarkdownRendererTask.ToHtml;
 import org.eclipse.edc.plugins.autodoc.tasks.MarkdownRendererTask.ToMarkdown;
@@ -47,6 +48,15 @@ public void apply(Project project) {
         project.getTasks().register(ToHtml.NAME, ToHtml.class, t -> t.setGroup(GROUP_NAME));
         project.getTasks().register(DownloadManifestTask.NAME, DownloadManifestTask.class, t -> t.setGroup(GROUP_NAME));
         // resolving manifests requires the Autodoc manifests of all dependencies to exist already
-        project.getTasks().register(ResolveManifestTask.NAME, ResolveManifestTask.class, t -> t.dependsOn(AUTODOC_TASK_NAME).setGroup(GROUP_NAME));
+        project.getTasks().register(ResolveManifestTask.NAME, ResolveManifestTask.class, t -> {
+            t.dependsOn(AUTODOC_TASK_NAME);
+            t.setGroup(GROUP_NAME);
+            t.setDescription(ResolveManifestTask.DESCRIPTION);
+        });
+        project.getTasks().register(AutodocBomTask.NAME, AutodocBomTask.class, t -> {
+            t.dependsOn(ResolveManifestTask.NAME);
+            t.setDescription(AutodocBomTask.DESCRIPTION);
+            t.setGroup(GROUP_NAME);
+        });
     }
 }

plugins/autodoc/autodoc-plugin/src/main/java/org/eclipse/edc/plugins/autodoc/tasks/AbstractManifestResolveTask.java

@@ -31,6 +31,7 @@
 import java.util.Set;
 
 import static java.util.Objects.requireNonNull;
+import static org.eclipse.edc.plugins.autodoc.tasks.Constants.DEFAULT_AUTODOC_FOLDER;
 
 /**
  * Abstract gradle task, that "resolves" an already-existing autodoc manifest from a URI and transfers (=copies, downloads,...)
@@ -45,7 +46,7 @@ public abstract class AbstractManifestResolveTask extends DefaultTask {
     private File outputDirectoryOverride;
 
     public AbstractManifestResolveTask() {
-        downloadDirectory = getProject().getLayout().getBuildDirectory().getAsFile().get().toPath().resolve("autodoc");
+        downloadDirectory = getProject().getLayout().getBuildDirectory().getAsFile().get().toPath().resolve(DEFAULT_AUTODOC_FOLDER);
     }
 
     @TaskAction
@@ -92,10 +93,12 @@ protected Set<String> getExclusions() {
     private void transferDependencyFile(DependencySource dependencySource, Path downloadDirectory) {
         var targetFilePath = downloadDirectory.resolve(dependencySource.filename());
         try (var inputStream = resolveManifest(dependencySource)) {
-            downloadDirectory.toFile().mkdirs();
-            getLogger().debug("Downloading {} into {}", dependencySource, downloadDirectory);
-            try (var fos = new FileOutputStream(targetFilePath.toFile())) {
-                inputStream.transferTo(fos);
+            if (inputStream != null) {
+                downloadDirectory.toFile().mkdirs();
+                getLogger().debug("Downloading {} into {}", dependencySource, downloadDirectory);
+                try (var fos = new FileOutputStream(targetFilePath.toFile())) {
+                    inputStream.transferTo(fos);
+                }
             }
         } catch (IOException e) {
             throw new RuntimeException(e);

plugins/autodoc/autodoc-plugin/src/main/java/org/eclipse/edc/plugins/autodoc/tasks/AutodocBomTask.java

@@ -0,0 +1,71 @@
+/*
+ *  Copyright (c) 2024 Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
+ *
+ *  This program and the accompanying materials are made available under the
+ *  terms of the Apache License, Version 2.0 which is available at
+ *  https://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  SPDX-License-Identifier: Apache-2.0
+ *
+ *  Contributors:
+ *       Bayerische Motoren Werke Aktiengesellschaft (BMW AG) - initial API and implementation
+ *
+ */
+
+package org.eclipse.edc.plugins.autodoc.tasks;
+
+import org.gradle.api.DefaultTask;
+import org.gradle.api.tasks.OutputFile;
+import org.gradle.api.tasks.TaskAction;
+import org.gradle.util.internal.GFileUtils;
+
+import java.io.File;
+
+public class AutodocBomTask extends DefaultTask {
+
+    public static final String NAME = "autodocBom";
+    public static final String DESCRIPTION = """
+            This task is intended for BOM modules. It resolves all autodoc manifests of modules that the BOM depends on
+            and generates a merged manifest file. By default, this merged file is stored at {project}/build/edc.json.
+            """;
+    private final JsonFileAppender appender;
+    private File outputFile;
+
+    public AutodocBomTask() {
+        appender = new JsonFileAppender(getLogger());
+        outputFile = getProject().getLayout().getBuildDirectory().file(outputFileName()).get().getAsFile();
+    }
+
+    @TaskAction
+    public void mergeManifests() {
+        if (!getProject().getName().endsWith("-bom")) {
+            getLogger().warn("Project name does not end with '-bom'. Is this really a BOM module?");
+        }
+
+        var inputDirectory = getProject().getLayout().getBuildDirectory().dir(Constants.DEFAULT_AUTODOC_FOLDER).get();
+        if (!inputDirectory.getAsFile().exists()) {
+            getLogger().info("Input directory does not exist: {}, Skipping", inputDirectory);
+            return;
+        }
+
+        var destinationFile = outputFile;
+
+        var files = GFileUtils.listFiles(inputDirectory.getAsFile(), new String[]{ "json" }, false);
+        getLogger().debug("Appending [{}] additional JSON files to the merged manifest", files.size());
+        files.forEach(f -> appender.append(destinationFile, f));
+
+    }
+
+    @OutputFile
+    public File getOutputFile() {
+        return outputFile;
+    }
+
+    public void setOutputFile(File outputFile) {
+        this.outputFile = outputFile;
+    }
+
+    private String outputFileName() {
+        return "edc.json";
+    }
+}

plugins/autodoc/autodoc-plugin/src/main/java/org/eclipse/edc/plugins/autodoc/tasks/Constants.java

@@ -0,0 +1,19 @@
+/*
+ *  Copyright (c) 2024 Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
+ *
+ *  This program and the accompanying materials are made available under the
+ *  terms of the Apache License, Version 2.0 which is available at
+ *  https://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  SPDX-License-Identifier: Apache-2.0
+ *
+ *  Contributors:
+ *       Bayerische Motoren Werke Aktiengesellschaft (BMW AG) - initial API and implementation
+ *
+ */
+
+package org.eclipse.edc.plugins.autodoc.tasks;
+
+public interface Constants {
+    String DEFAULT_AUTODOC_FOLDER = "autodoc";
+}

plugins/autodoc/autodoc-plugin/src/main/java/org/eclipse/edc/plugins/autodoc/tasks/DownloadManifestTask.java

@@ -53,7 +53,7 @@ protected InputStream resolveManifest(DependencySource autodocManifest) {
         }
         if (response.statusCode() != 200) {
             getLogger().warn("Could not download {}, HTTP response: {}", autodocManifest.dependency(), response);
-            return InputStream.nullInputStream();
+            return null;
         }
         return response.body();
     }

plugins/autodoc/autodoc-plugin/src/main/java/org/eclipse/edc/plugins/autodoc/tasks/MergeManifestsTask.java

@@ -26,6 +26,8 @@
 import java.nio.file.Path;
 import java.util.Objects;
 
+import static org.eclipse.edc.plugins.autodoc.tasks.Constants.DEFAULT_AUTODOC_FOLDER;
+
 /**
  * Task that takes an input file (JSON) and appends its contents to a destination file. This task is intended to be called per-project.
  */
@@ -43,7 +45,7 @@ public MergeManifestsTask() {
         appender = new JsonFileAppender(getProject().getLogger());
         projectBuildDirectory = getProject().getLayout().getBuildDirectory().getAsFile().get();
         destinationFile = getProject().getRootProject().getLayout().getBuildDirectory().get().getAsFile().toPath().resolve(MERGED_MANIFEST_FILENAME).toFile();
-        inputDirectory = projectBuildDirectory.toPath().resolve("autodoc").toFile();
+        inputDirectory = projectBuildDirectory.toPath().resolve(DEFAULT_AUTODOC_FOLDER).toFile();
     }
 
     /**

plugins/autodoc/autodoc-plugin/src/main/java/org/eclipse/edc/plugins/autodoc/tasks/ResolveManifestTask.java

@@ -23,12 +23,10 @@
 import java.io.InputStream;
 import java.util.Optional;
 
-import static java.io.InputStream.nullInputStream;
-
 public class ResolveManifestTask extends AbstractManifestResolveTask {
 
     public static final String NAME = "resolveManifests";
-
+    public static final String DESCRIPTION = "This task is intended for BOM modules and resolves the autodoc manifests of all modules that the project depends on. By default, all manifests are stored in {project}/build/autodoc.";
 
     @Override
     protected InputStream resolveManifest(DependencySource autodocManifest) {
@@ -40,7 +38,7 @@ protected InputStream resolveManifest(DependencySource autodocManifest) {
             }
 
             getLogger().info("File {} does not exist", file);
-            return nullInputStream();
+            return null;
         } catch (FileNotFoundException e) {
             throw new RuntimeException(e);
         }
@@ -62,5 +60,4 @@ protected Optional<DependencySource> createSource(Dependency dependency) {
 
         return Optional.empty();
     }
-
 }