Re-implement Mavenizer invocation as a task (#996)

- Add the first documentation page
  - All documentation pages will be moved to MinecraftForge/Documentation OR its own repo if necessary when the time comes
- Create the ForgeGradle Magic plugin
  - Currently does nothing, but lays the groundwork for what it will need to do later on.
- Re-implement Mavenizer invocation

Author: Jonathing

docs/Overview.md

@@ -0,0 +1,54 @@
+# ForgeGradle
+
+[![Plugin Portal](https://img.shields.io/gradle-plugin-portal/v/net.minecraftforge.gradle)](https://plugins.gradle.org/plugin/net.minecraftforge.gradle)
+
+Welcome to ForgeGradle, Minecraft Forge's Gradle plugin. It is a small, simple,
+and effective plugin with the primary purpose of bootstrapping Minecraft Forge's
+toolchain to aid in the development of mods targeting Minecraft Forge.
+
+## Basic Usage
+
+### Applying the Plugin
+
+ForgeGradle 7 can be applied to projects or settings by using the following:
+
+```groovy
+plugins {
+    id 'net.minecraftforge.gradle' version '<version>'
+}
+```
+
+ForgeGradle 7 and later can now be found on the
+[Gradle Plugin Portal][Gradle Plugin Portal]. Adding the Forge maven to the
+plugin management repositories is no longer necessary.
+
+### Depending on Minecraft
+
+```groovy
+dependencies {
+    implementation minecraft.dependency('net.minecraftforge:forge:1.21.10-60.0.0')
+}
+```
+
+## API Design
+
+ForgeGradle 7, the latest iteration of ForgeGradle, has a completely different
+approach to API design. If you plan on interfacing with the plugin in
+unconventional ways, there are a few things to keep in mind.
+
+- ForgeGradle is **stateless by default.**
+  - This means that if nothing is asked of it, it will not do anything.
+  - The only exception to this rule is ForgeGradle Magic, which is covered in
+    its own documentation entry.
+- ForgeGradle's **implementation and internal code is inaccessible.**
+  - All implementations are package-private, so they cannot be accessed by other
+    plugins or extended from. Everything that is public API has been
+    deliberately made so.
+- ForgeGradle is **not the toolchain.**
+  - Unlike ForgeGradle 6 and its predecessors, ForgeGradle 7 does not include
+    the toolchain. It instead acts as the configuring interface and invocation
+    of the toolchain. If you are interested in contributing to the toolchain,
+    please see the [Minecraft Mavenizer][Mavenizer].
+
+[Gradle Plugin Portal]: https://plugins.gradle.org
+[Mavenizer]: https://github.com/MinecraftForge/MinecraftMavenizer

settings.gradle

@@ -20,7 +20,7 @@ gradle.beforeProject { Project project ->
 
 //@formatter:off
 dependencyResolutionManagement.versionCatalogs.register('libs') {
-    version 'gradleutils', '3.3.18'
+    version 'gradleutils', '3.3.20'
 
     plugin 'licenser',       'net.minecraftforge.licenser'    version '1.2.0' // https://plugins.gradle.org/plugin/net.minecraftforge.licenser
     plugin 'gradleutils',    'net.minecraftforge.gradleutils' versionRef 'gradleutils'
@@ -43,7 +43,7 @@ dependencyResolutionManagement.versionCatalogs.register('libs') {
 
     // AccessTransformers Gradle Plugin
     // https://plugins.gradle.org/plugin/net.minecraftforge.accesstransformers
-    library 'accesstransformers-gradle', 'net.minecraftforge.accesstransformers', 'net.minecraftforge.accesstransformers.gradle.plugin' version '5.0.0-beta.8'
+    library 'accesstransformers-gradle', 'net.minecraftforge.accesstransformers', 'net.minecraftforge.accesstransformers.gradle.plugin' version '5.0.1'
 
     library 'utils-data',     'net.minecraftforge', 'json-data-utils' version '0.3.0'  // https://files.minecraftforge.net/net/minecraftforge/json-data-utils/index.html
     library 'utils-hash',     'net.minecraftforge', 'hash-utils'      version '0.1.10' // https://files.minecraftforge.net/net/minecraftforge/hash-utils/index.html

src/main/java/net/minecraftforge/gradle/Constants.java

@@ -18,7 +18,7 @@ final class Constants {
     static final String SLIMELAUNCHER_MAIN = "net.minecraftforge.launcher.Main";
 
     static final String MAVENIZER_NAME = "mavenizer";
-    static final String MAVENIZER_VERSION = "0.3.17";
+    static final String MAVENIZER_VERSION = "0.3.25";
     static final String MAVENIZER_DL_URL = "https://maven.minecraftforge.net/net/minecraftforge/minecraft-mavenizer/" + MAVENIZER_VERSION + "/minecraft-mavenizer-" + MAVENIZER_VERSION + ".jar";
     static final int MAVENIZER_JAVA_VERSION = 21;
     static final String MAVENIZER_MAIN = "net.minecraftforge.mcmaven.cli.Main";
@@ -58,5 +58,19 @@ If you are on an older version (1.20.4 and older), you will need the
             {}
             
             For more details on this release, see https://docs.minecraftforge.net/en/fg-7.0/""";
+
+        static final String MAGIC = """
+            This build is using ForgeGradle Magic. ForgeGradle Magic employs automatic
+            behavior that is hidden from buildscript authors in order to implement and
+            account for convenience features.
+            
+            Magic is enabled by default. It can be disabled by using the following
+            Gradle property:
+            net.minecraftforge.gradle.magic=false
+            
+            This message will not display again unless the below file is deleted:
+            {}
+            
+            For more information, see https://docs.minecraftforge.net/en/fg-7.0/magic/""";
     }
 }

src/main/java/net/minecraftforge/gradle/ForgeGradleFlowAction.java

@@ -63,6 +63,46 @@ protected void run(Parameters parameters) throws IOException {
         }
     }
 
+    static abstract class MagicMessage extends ForgeGradleFlowAction<MagicMessage.Parameters> {
+        enum DisplayOption {
+            ONCE, NEVER, ALWAYS
+        }
+
+        static abstract class Parameters extends ForgeGradleFlowAction.Parameters {
+            final DirectoryProperty messagesDir;
+            final Property<DisplayOption> displayOption;
+
+            protected abstract @Inject ProviderFactory getProviders();
+
+            @Inject
+            public Parameters() {
+                this.messagesDir = this.getObjects().directoryProperty();
+                this.displayOption = this.getObjects().property(DisplayOption.class).convention(DisplayOption.ONCE).value(
+                    this.getProviders().gradleProperty("net.minecraftforge.gradle.messages.magic")
+                        .orElse(this.getProviders().systemProperty("net.minecraftforge.gradle.messages.magic"))
+                        .map(it -> DisplayOption.valueOf(it.toUpperCase(Locale.ROOT)))
+                );
+            }
+        }
+
+        @Inject
+        public MagicMessage() { }
+
+        @Override
+        protected void run(Parameters parameters) throws IOException {
+            // if build failed, don't bother
+            if (parameters.getFailure().isPresent()) return;
+
+            // check for marker file
+            var markerFile = parameters.messagesDir.file("7_0_BETA_MAGIC_1").get().getAsFile();
+            if (markerFile.exists()) return;
+            Files.createDirectories(markerFile.toPath().getParent());
+            Files.createFile(markerFile.toPath());
+
+            LOGGER.lifecycle(Constants.Messages.MAGIC, markerFile.getAbsolutePath());
+        }
+    }
+
     static abstract class AccessTransformersMissing extends ForgeGradleFlowAction<AccessTransformersMissing.Parameters> {
         static abstract class Parameters extends ForgeGradleFlowAction.Parameters {
             final Property<Boolean> appliedPlugin = this.getObjects().property(Boolean.class).convention(false);

src/main/java/net/minecraftforge/gradle/ForgeGradleMagicPlugin.java

@@ -0,0 +1,29 @@
+/*
+ * Copyright (c) Forge Development LLC and contributors
+ * SPDX-License-Identifier: LGPL-2.1-only
+ */
+package net.minecraftforge.gradle;
+
+import net.minecraftforge.gradleutils.shared.EnhancedPlugin;
+import org.gradle.api.Project;
+import org.gradle.api.logging.Logger;
+import org.gradle.api.logging.Logging;
+
+import javax.inject.Inject;
+
+abstract class ForgeGradleMagicPlugin extends EnhancedPlugin<Project> {
+    static final String NAME = "forgegradle-magic";
+    static final String DISPLAY_NAME = "ForgeGradle Magic";
+
+    static final Logger LOGGER = Logging.getLogger(ForgeGradleMagicPlugin.class);
+
+    @Inject
+    public ForgeGradleMagicPlugin() {
+        super(NAME, DISPLAY_NAME);
+    }
+
+    @Override
+    public void setup(Project project) {
+
+    }
+}

src/main/java/net/minecraftforge/gradle/ForgeGradlePlugin.java

@@ -5,6 +5,7 @@
 package net.minecraftforge.gradle;
 
 import net.minecraftforge.gradleutils.shared.EnhancedPlugin;
+import org.gradle.api.Project;
 import org.gradle.api.logging.Logger;
 import org.gradle.api.logging.Logging;
 import org.gradle.api.plugins.ExtensionAware;
@@ -17,13 +18,24 @@ abstract class ForgeGradlePlugin extends EnhancedPlugin<ExtensionAware> {
 
     static final Logger LOGGER = Logging.getLogger(ForgeGradlePlugin.class);
 
+    private final ForgeGradleProblems problems = this.getObjects().newInstance(ForgeGradleProblems.class);
+
+    static {
+        LOGGER.lifecycle("ForgeGradle 7 is an incubating plugin.");
+    }
+
     @Inject
     public ForgeGradlePlugin() {
         super(NAME, DISPLAY_NAME, "fgtools");
     }
 
     @Override
     public void setup(ExtensionAware target) {
+        if (target instanceof Project project && !problems.testFalse("net.minecraftforge.gradle.magic")) {
+            LOGGER.info("Applying ForgeGradle Magic to {}", project);
+            project.getPluginManager().apply(ForgeGradleMagicPlugin.class);
+        }
+
         ForgeGradleExtensionImpl.register(this, target);
         MinecraftExtensionImpl.register(this, target);
     }

src/main/java/net/minecraftforge/gradle/ForgeGradleProblems.java

@@ -124,6 +124,21 @@ RuntimeException changingMinecraftDependency(Dependency dependency) {
     //endregion
 
     //region Minecraft Maven
+    RuntimeException mavenizerOutOfDateCompile(Dependency dependency) {
+        return this.throwing(new IllegalStateException(), "mavenizer-out-of-date", "Minecraft Mavenizer is out-of-date", spec -> spec
+            .details("""
+                Gradle cannot compile your sources because the Minecraft Mavenizer is out-of-date.
+                The Mavenizer must be re-run in order for the changes made to the Minecraft dependency to take effect.
+                Affected dependency: '%s'"""
+                .formatted(dependency))
+            .severity(Severity.ERROR)
+            .solution("Re-import your project in your IDE, as this will automatically synchronize the Mavenizer.")
+            .solution("Run `gradlew` with no arguments, as this will automatically synchronize the Mavenizer.")
+            .solution("Manually run the `syncMavenizer` task, located in the 'Build Setup' group.")
+            .solution("Temporary revert any edits to the Minecraft dependency until the Mavenizer is re-run.")
+            .solution(HELP_MESSAGE));
+    }
+
     void reportMcMavenNotDeclared() {
         if (!this.test("net.minecraftforge.gradle.warnings.repository.missing.mavenizer")) return;