Proper error if javadoc links is applied too early

Author: Jonathing

src/main/groovy/net/minecraftforge/gradleutils/GradleUtilsExtensionImpl.groovy

@@ -6,12 +6,13 @@ package net.minecraftforge.gradleutils
 
 import groovy.transform.CompileStatic
 import groovy.transform.PackageScope
-import net.minecraftforge.gradleutils.shared.SharedUtil
 import org.gradle.api.Action
 import org.gradle.api.Project
 import org.gradle.api.artifacts.repositories.MavenArtifactRepository
 import org.gradle.api.file.Directory
 import org.gradle.api.file.DirectoryProperty
+import org.gradle.api.flow.FlowProviders
+import org.gradle.api.flow.FlowScope
 import org.gradle.api.model.ObjectFactory
 import org.gradle.api.plugins.ExtensionAware
 import org.gradle.api.provider.Property
@@ -26,10 +27,6 @@ import static net.minecraftforge.gradleutils.GradleUtilsPlugin.LOGGER
 
 @CompileStatic
 @PackageScope abstract class GradleUtilsExtensionImpl implements GradleUtilsExtensionInternal {
-    protected abstract @Inject ObjectFactory getObjects()
-    protected abstract @Inject BuildLayout getBuildLayout()
-    protected abstract @Inject ProviderFactory getProviders()
-
     private final DirectoryProperty rootDirectory
 
     private final Property<String> mavenUser
@@ -38,16 +35,29 @@ import static net.minecraftforge.gradleutils.GradleUtilsPlugin.LOGGER
 
     final PomUtils pom
 
+    protected abstract @Inject ObjectFactory getObjects()
+    protected abstract @Inject BuildLayout getBuildLayout()
+    protected abstract @Inject ProviderFactory getProviders()
+
+    protected abstract @Inject FlowScope getFlowScope()
+    protected abstract @Inject FlowProviders getFlowProviders()
+
     @Inject
     GradleUtilsExtensionImpl(ExtensionAware target) {
         this.rootDirectory = this.objects.directoryProperty().fileValue(this.buildLayout.rootDirectory)
 
-        this.mavenUser = this.objects.property(String).value(this.providers.environmentVariable('MAVEN_USER')).tap(SharedUtil.finalizeProperty())
-        this.mavenPassword = this.objects.property(String).value(this.providers.environmentVariable('MAVEN_PASSWORD')).tap(SharedUtil.finalizeProperty())
-        this.mavenUrl = this.objects.property(String).value(this.providers.environmentVariable('MAVEN_URL').orElse(this.providers.environmentVariable('MAVEN_URL_RELEASE'))).tap(SharedUtil.finalizeProperty())
+        this.mavenUser = this.objects.property(String).value(this.providers.environmentVariable('MAVEN_USER')).tap(Util.finalizeProperty())
+        this.mavenPassword = this.objects.property(String).value(this.providers.environmentVariable('MAVEN_PASSWORD')).tap(Util.finalizeProperty())
+        this.mavenUrl = this.objects.property(String).value(this.providers.environmentVariable('MAVEN_URL').orElse(this.providers.environmentVariable('MAVEN_URL_RELEASE'))).tap(Util.finalizeProperty())
 
         this.pom = this.objects.newInstance(PomUtilsImpl, target)
 
+        this.flowScope.always(GradleUtilsFlowAction.JavadocLinksClassCheck) {
+            it.parameters { parameters ->
+                parameters.failure.set(this.flowProviders.buildWorkResult.map { it.failure.orElse(null) })
+            }
+        }
+
         if (target instanceof Project) {
             target.tasks.register(GenerateActionsWorkflow.NAME, GenerateActionsWorkflowImpl)
         }

src/main/groovy/net/minecraftforge/gradleutils/GradleUtilsFlowAction.java

@@ -0,0 +1,31 @@
+package net.minecraftforge.gradleutils;
+
+import net.minecraftforge.gradleutils.shared.EnhancedFlowAction;
+import org.jetbrains.annotations.Nullable;
+
+import javax.inject.Inject;
+
+abstract class GradleUtilsFlowAction<P extends GradleUtilsFlowAction.Parameters> extends EnhancedFlowAction<P> {
+    static abstract class Parameters extends EnhancedFlowAction.EnhancedFlowParameters<GradleUtilsProblems> {
+        Parameters() {
+            super(GradleUtilsProblems.class);
+        }
+    }
+
+    static abstract class JavadocLinksClassCheck extends GradleUtilsFlowAction<JavadocLinksClassCheck.Parameters> {
+        static abstract class Parameters extends GradleUtilsFlowAction.Parameters {
+            @Inject
+            public Parameters() { }
+        }
+
+        @Inject
+        public JavadocLinksClassCheck() { }
+
+        @Override
+        protected void run(Parameters parameters) {
+            @Nullable var e = parameters.getFailure().getOrNull();
+            if (e != null && contains(e, "io/freefair/gradle/plugins/maven/javadoc/JavadocLinkProvider"))
+                parameters.problems().reportJavadocLinksNotOnClasspath(e);
+        }
+    }
+}

src/main/groovy/net/minecraftforge/gradleutils/GradleUtilsProblems.java

@@ -49,7 +49,24 @@ void reportPomUtilsForgeProjWithoutForgeOrg() {
                 This project was autodetected as a MinecraftForge project, but `gradleutils.pom.addForgeDetails` was not used.""")
             .severity(Severity.ADVICE)
             .stackLocation()
-            .solution("Consider using `gradleutils.pom.addForgeDetails`"));
+            .solution("Consider using `gradleutils.pom.addForgeDetails`."));
+    }
+    //endregion
+
+    //region JavaDoc Links
+    void reportJavadocLinksNotOnClasspath(Throwable e) {
+        this.getReporter().report(id("javadoc-links-plugin-not-found", "JavaDoc Links plugin not in classpath"), spec -> spec
+            .details("""
+                This project is using `resolveJavadocLinks` from FreeFair's JavaDoc Links plugin, but it was not loaded in the classpath!
+                The javadoc links plugin must be loaded in the classpath before GradleUtils, even if it is not applied (i.e. in `settings.gradle`).
+                
+                This can be done by declaring it as so (in Groovy DSL):
+                `id 'io.freefair.javadoc-links' version '8.14' apply false`""")
+            .withException(e)
+            .severity(Severity.ERROR)
+            .stackLocation()
+            .solution("Add the JavaDoc Links plugin before GradleUtils (use `apply(false)` if necessary).")
+            .solution(HELP_MESSAGE));
     }
     //endregion
 }

src/main/groovy/net/minecraftforge/gradleutils/Util.java

@@ -0,0 +1,9 @@
+/*
+ * Copyright (c) Forge Development LLC and contributors
+ * SPDX-License-Identifier: LGPL-2.1-only
+ */
+package net.minecraftforge.gradleutils;
+
+import net.minecraftforge.gradleutils.shared.SharedUtil;
+
+final class Util extends SharedUtil { }

src/main/groovy/net/minecraftforge/gradleutils/services/GradleUtilsJavadocLinkProvider.groovy

@@ -0,0 +1,21 @@
+/*
+ * Copyright (c) Forge Development LLC and contributors
+ * SPDX-License-Identifier: LGPL-2.1-only
+ */
+package net.minecraftforge.gradleutils.services
+
+import io.freefair.gradle.plugins.maven.javadoc.JavadocLinkProvider
+import io.freefair.gradle.plugins.maven.javadoc.JavadocLinkUtil
+import org.gradle.util.GradleVersion
+import org.jetbrains.annotations.Nullable
+
+class GradleUtilsJavadocLinkProvider implements JavadocLinkProvider {
+    GradleUtilsJavadocLinkProvider() { }
+
+    @Override
+    @Nullable String getJavadocLink(String group, String artifact, String version) {
+        // Allow Nokee and Remal's redistributions of Gradle API to link to Gradle's JavaDocs
+        if ('gradle-api' == artifact && ('dev.gradleplugins' == group || 'name.remal.gradle-api' == group))
+            JavadocLinkUtil.getGradleApiLink(GradleVersion.version(version))
+    }
+}