Register a generated auto-configuration where it is generated

The class a beans closure compiles to is created during compilation and is not a
source file anyone can open, so listing it in AutoConfiguration.imports required
knowing both that it exists and what the compiler decided to call it. Not knowing
either produced a plugin whose beans were silently never registered, which is a
poor thing to ask an author to notice.

The name is settled in createAutoConfigurationSibling and nowhere else, so that is
where the entry is now written - into the compilation's target directory, beside
the grails-plugin.xml and grails.factories that are already generated there.

A module that keeps the file by hand keeps it, and nothing is generated beside it:
two copies of one resource cannot both go into the jar, and folding the hand
authored entries into a copy under the build directory would lose them as soon as
anyone deleted the file they were written in. Such a module is warned at compile
time when the generated class is missing from its file, so the silent case is gone
either way, and deleting the file is what opts in. Hand-authored entries have to
stay possible: a class from another jar, one annotated with a composed annotation,
or one carrying no annotation at all - the imports file being the registration and
@autoConfiguration only supplying ordering.

grails-databinding and the beans-dsl-plugin example no longer apply the
autoconfiguration-imports convention plugin, which generated the same entries a
second time. The beans-dsl example keeps it: what it registers is a standalone
@GrailsBeans class, which is a source file its author can see and so is left to be
registered by hand, as any other auto-configuration is.

Author: codeconsole

grails-beans-dsl/src/main/java/org/grails/compiler/beans/AutoConfigurationImportsWriter.java

@@ -0,0 +1,164 @@
+/*
+ *  Licensed to the Apache Software Foundation (ASF) under one
+ *  or more contributor license agreements.  See the NOTICE file
+ *  distributed with this work for additional information
+ *  regarding copyright ownership.  The ASF licenses this file
+ *  to you 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
+ *
+ *    https://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.
+ */
+package org.grails.compiler.beans;
+
+import java.io.File;
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.util.Set;
+import java.util.TreeSet;
+
+import org.codehaus.groovy.control.SourceUnit;
+import org.codehaus.groovy.control.messages.WarningMessage;
+
+/**
+ * Registers a generated auto-configuration in
+ * {@code META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports}.
+ *
+ * <p>The class a {@code beans} closure compiles to is created during compilation and is not a source
+ * file anyone can open. Leaving its registration to be written by hand made a plugin whose beans are
+ * silently never registered the ordinary consequence of not knowing the class exists - and the name
+ * to write is one only the compiler knows, since it follows from the descriptor's name and package.
+ * Writing it where the class is created is the only point at which that name is known for certain.
+ *
+ * <p>A module that keeps the file by hand keeps it: generating a second copy would put the same
+ * resource at the same path twice, and folding its entries into a copy under the build directory
+ * would lose them the moment anyone deleted the file that was, until then, where they were written
+ * down. Such a module is warned when the generated class is missing from it and is otherwise left
+ * alone, so nothing that builds today builds differently - deleting the hand-authored file is what
+ * opts in, and is safe once it holds nothing but what is generated.
+ *
+ * <p>Hand-authored entries have to remain possible: a module may register a class from another jar,
+ * one annotated with a composed annotation, or one carrying no annotation at all, the imports file
+ * being the registration and {@code @AutoConfiguration} only supplying ordering.
+ *
+ * @since 8.0
+ */
+final class AutoConfigurationImportsWriter {
+
+    static final String IMPORTS_LOCATION =
+            "META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports";
+
+    static final String SOURCE_IMPORTS_LOCATION = "src/main/resources/" + IMPORTS_LOCATION;
+
+    /** Set by the Grails Gradle plugin on the compiler's fork options; see GrailsAppBaseDirProvider. */
+    private static final String BASE_DIR_PROPERTY = "base.dir";
+
+    private static final String COMMENT_START = "#";
+
+    private AutoConfigurationImportsWriter() {
+    }
+
+    /**
+     * Adds {@code className} to the generated imports file under {@code targetDirectory}, together
+     * with anything an earlier source unit of the same compilation registered there. A module that
+     * keeps the file by hand is warned instead, and its file is left as the only one.
+     *
+     * @param className the generated auto-configuration's binary name
+     * @param targetDirectory the compilation output directory, or {@code null} when the compiler did
+     *                        not supply one - in which case there is nowhere to write and the class
+     *                        stays registerable by hand
+     * @return {@code true} when the file was written
+     */
+    static boolean register(String className, File targetDirectory, SourceUnit source) {
+        if (className == null || className.isEmpty() || targetDirectory == null) {
+            return false;
+        }
+
+        File sourceDirectory = findSourceDirectory(targetDirectory);
+        File handAuthored = sourceDirectory == null ? null : new File(sourceDirectory, SOURCE_IMPORTS_LOCATION);
+        if (handAuthored != null && handAuthored.isFile()) {
+            Set<String> handAuthoredEntries = new TreeSet<>();
+            readEntries(handAuthored, handAuthoredEntries);
+            if (!handAuthoredEntries.contains(className)) {
+                warn(source, className + " is generated from a beans closure but is not listed in " +
+                        SOURCE_IMPORTS_LOCATION + ", so Spring Boot will not read it. Add it there, or delete " +
+                        "that file once it holds nothing that is not generated and it will be written for you.");
+            }
+            return false;
+        }
+
+        File importsFile = new File(targetDirectory, IMPORTS_LOCATION);
+        Set<String> entries = new TreeSet<>();
+        // Entries an earlier source unit of the same compilation already registered
+        readEntries(importsFile, entries);
+        if (!entries.add(className) && importsFile.isFile()) {
+            return false;
+        }
+
+        try {
+            Files.createDirectories(importsFile.toPath().getParent());
+            // Sorted and newline-terminated, so recompiling the same sources rewrites the same bytes.
+            Files.write(importsFile.toPath(), (String.join("\n", entries) + "\n")
+                    .getBytes(StandardCharsets.UTF_8));
+            return true;
+        }
+        catch (IOException notWritable) {
+            // The class is still generated and still registerable by hand, so failing compilation
+            // over the convenience of not having to would be the worse trade.
+            return false;
+        }
+    }
+
+    private static void warn(SourceUnit source, String message) {
+        if (source != null) {
+            source.getErrorCollector().addWarning(WarningMessage.LIKELY_ERRORS, message, null, source);
+        }
+    }
+
+    /**
+     * The module's base directory, so a hand-authored imports file can be found. Mirrors
+     * {@code FactoriesFileWriter.findSourceDirectory}: the build tool's own answer if it supplied
+     * one, otherwise the directory above the output root.
+     */
+    private static File findSourceDirectory(File targetDirectory) {
+        String baseDir = System.getProperty(BASE_DIR_PROPERTY);
+        if (baseDir != null && !baseDir.isEmpty()) {
+            File candidate = new File(baseDir);
+            if (candidate.isDirectory()) {
+                return candidate;
+            }
+        }
+        File directory = targetDirectory;
+        while (directory != null && !("build".equals(directory.getName()) || "target".equals(directory.getName()))) {
+            directory = directory.getParentFile();
+        }
+        return directory == null ? null : directory.getParentFile();
+    }
+
+    /** Adds the names in {@code file}, skipping blanks and the {@code #} comments Spring Boot skips. */
+    private static void readEntries(File file, Set<String> entries) {
+        if (file == null || !file.isFile()) {
+            return;
+        }
+        try {
+            for (String line : Files.readAllLines(file.toPath(), StandardCharsets.UTF_8)) {
+                String entry = line.trim();
+                if (!entry.isEmpty() && !entry.startsWith(COMMENT_START)) {
+                    entries.add(entry);
+                }
+            }
+        }
+        catch (IOException unreadable) {
+            // Nothing to merge that can be read; the generated entry is still written below.
+        }
+    }
+
+}

grails-beans-dsl/src/main/java/org/grails/compiler/beans/GrailsBeansASTTransformation.java

@@ -19,6 +19,7 @@
 package org.grails.compiler.beans;
 
 import java.beans.Introspector;
+import java.io.File;
 import java.lang.reflect.Modifier;
 import java.util.ArrayList;
 import java.util.HashSet;
@@ -63,6 +64,7 @@
 import org.codehaus.groovy.ast.stmt.Statement;
 import org.codehaus.groovy.control.CompilationUnit;
 import org.codehaus.groovy.control.CompilePhase;
+import org.codehaus.groovy.control.CompilerConfiguration;
 import org.codehaus.groovy.control.SourceUnit;
 import org.codehaus.groovy.syntax.SyntaxException;
 import org.codehaus.groovy.syntax.Types;
@@ -324,9 +326,18 @@ private ClassNode createAutoConfigurationSibling(ClassNode pluginClass, Annotati
         sibling.addAnnotations(siblingAnnotations);
         pluginClass.getAnnotations().removeAll(siblingAnnotations);
 
+        // The name is settled here and nowhere else, so this is where it can be registered.
+        AutoConfigurationImportsWriter.register(siblingName, targetDirectory(source), source);
+
         return sibling;
     }
 
+    /** The compiler's output directory, which is where generated metadata belongs. */
+    private static File targetDirectory(SourceUnit source) {
+        CompilerConfiguration configuration = source == null ? null : source.getConfiguration();
+        return configuration == null ? null : configuration.getTargetDirectory();
+    }
+
     private Set<String> parseMoveAnnotations(AnnotationNode grailsBeansAnnotation, SourceUnit source) {
         Expression member = grailsBeansAnnotation.getMember(MOVE_ANNOTATIONS_MEMBER);
         if (member == null) {

grails-beans-dsl/src/test/groovy/org/grails/compiler/beans/AutoConfigurationImportsWriterSpec.groovy

@@ -0,0 +1,163 @@
+/*
+ *  Licensed to the Apache Software Foundation (ASF) under one
+ *  or more contributor license agreements.  See the NOTICE file
+ *  distributed with this work for additional information
+ *  regarding copyright ownership.  The ASF licenses this file
+ *  to you 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
+ *
+ *    https://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.
+ */
+package org.grails.compiler.beans
+
+import org.codehaus.groovy.control.CompilationUnit
+import org.codehaus.groovy.control.CompilerConfiguration
+import org.codehaus.groovy.control.Phases
+import spock.lang.Specification
+import spock.lang.TempDir
+
+/**
+ * The class a {@code beans} closure compiles to is generated rather than written, so nobody can
+ * list it in {@code AutoConfiguration.imports} without first knowing it exists. These drive a real
+ * compilation with a target directory, which is the only thing that makes the file observable.
+ */
+class AutoConfigurationImportsWriterSpec extends Specification {
+
+    private static final String IMPORTS =
+            'META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports'
+
+    @TempDir
+    File projectDir
+
+    private File targetDir
+    private String previousBaseDir
+
+    void setup() {
+        targetDir = new File(projectDir, 'build/classes/groovy/main')
+        targetDir.mkdirs()
+        previousBaseDir = System.setProperty('base.dir', projectDir.absolutePath)
+    }
+
+    void cleanup() {
+        if (previousBaseDir == null) {
+            System.clearProperty('base.dir')
+        }
+        else {
+            System.setProperty('base.dir', previousBaseDir)
+        }
+    }
+
+    void 'the generated sibling registers itself'() {
+        when:
+        compile(plugin('Greeting'))
+
+        then: 'the name only the compiler knows is written where Spring Boot reads it'
+        importsEntries() == ['com.example.GreetingAutoConfiguration']
+    }
+
+    void 'autoConfigurationName registers under the name it asks for'() {
+        when:
+        compile(plugin('Renamed', "autoConfigurationName = 'LegacyAutoConfiguration'"))
+
+        then: 'what is registered is the name the class is actually generated under'
+        importsEntries() == ['com.example.LegacyAutoConfiguration']
+    }
+
+    void 'siblings from separate source units accumulate rather than replacing one another'() {
+        when: 'two descriptors compile separately, as they do in a real build'
+        compile(plugin('First'))
+        compile(plugin('Second'))
+
+        then:
+        importsEntries() == ['com.example.FirstAutoConfiguration', 'com.example.SecondAutoConfiguration']
+    }
+
+    void 'a module that keeps the file by hand keeps it'() {
+        given: 'a hand-authored file, which may hold entries no compilation can discover'
+        File handAuthored = new File(projectDir, "src/main/resources/${IMPORTS}")
+        handAuthored.parentFile.mkdirs()
+        handAuthored.text = 'com.example.GreetingAutoConfiguration\ncom.elsewhere.FromAnotherJar\n'
+
+        when:
+        compile(plugin('Greeting'))
+
+        then: 'nothing is generated beside it, which would put the same resource at the same path twice'
+        !new File(targetDir, IMPORTS).exists()
+
+        and: 'and the entries it alone knows about are untouched'
+        handAuthored.readLines().contains('com.elsewhere.FromAnotherJar')
+    }
+
+    void 'a hand-authored file missing the generated class is warned about'() {
+        given:
+        File handAuthored = new File(projectDir, "src/main/resources/${IMPORTS}")
+        handAuthored.parentFile.mkdirs()
+        handAuthored.text = 'com.elsewhere.FromAnotherJar\n'
+
+        when:
+        compile(plugin('Greeting'))
+
+        then: 'silently registering nothing is the failure this exists to prevent'
+        warnings().any {
+            it.contains('com.example.GreetingAutoConfiguration') && it.contains(IMPORTS)
+        }
+    }
+
+    private List<String> collectedWarnings = []
+
+    private List<String> warnings() {
+        collectedWarnings
+    }
+
+    private List<String> importsEntries() {
+        File file = new File(targetDir, IMPORTS)
+        file.exists() ? file.readLines().findAll { it.trim() && !it.startsWith('#') } : []
+    }
+
+    private static String plugin(String name, String grailsBeansMembers = '') {
+        """
+            package com.example
+
+            import grails.compiler.beans.GrailsBeans
+            import grails.plugins.Plugin
+            import org.springframework.boot.autoconfigure.AutoConfiguration
+
+            @GrailsBeans(${grailsBeansMembers})
+            @AutoConfiguration
+            class ${name}GrailsPlugin extends Plugin {
+                def beans = {
+                    bean('${name.uncapitalize()}Greeting', String) { 'hello' }
+                }
+            }
+        """
+    }
+
+    /** A real compilation, since only a target directory makes the generated file observable. */
+    private CompilerConfiguration compile(String source) {
+        CompilerConfiguration configuration = new CompilerConfiguration()
+        configuration.targetDirectory = targetDir
+        CompilationUnit unit = new CompilationUnit(configuration, null,
+                new GroovyClassLoader(getClass().classLoader, configuration))
+        unit.addSource("Source${System.identityHashCode(source)}.groovy", source)
+        try {
+            unit.compile(Phases.CLASS_GENERATION)
+        }
+        catch (Exception ignored) {
+            // the generated file is what is under test, not the class
+        }
+        List warningMessages = unit.errorCollector.warnings
+        if (warningMessages) {
+            collectedWarnings.addAll(warningMessages.collect { it.message?.toString() ?: it.toString() })
+        }
+        configuration
+    }
+
+}

grails-databinding/build.gradle

@@ -23,7 +23,6 @@ plugins {
     id 'project-report'
     id 'org.apache.grails.buildsrc.properties'
     id 'org.apache.grails.buildsrc.dependency-validator'
-    id 'org.apache.grails.buildsrc.autoconfiguration-imports'
     id 'org.apache.grails.buildsrc.compile'
     id 'org.apache.grails.buildsrc.publish'
     id 'org.apache.grails.buildsrc.sbom'

grails-doc/src/en/guide/plugins/hookingIntoRuntimeConfiguration.adoc

@@ -193,7 +193,11 @@ bean('greeting', Greeting) {
 }
 ----
 
-Because the result is an ordinary `AutoConfiguration` class, it must be registered the same way any Spring Boot auto-configuration is: listed in `META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports`. Modules built as part of this project can apply the `org.apache.grails.buildsrc.autoconfiguration-imports` Gradle convention plugin to generate that file automatically, by scanning the module's own compiled classes for `@AutoConfiguration` at build time. Projects outside this build register the class the same way any hand-written `AutoConfiguration` is registered — by listing it in that file directly.
+Because the result is an ordinary `AutoConfiguration` class, it must be registered the same way any Spring Boot auto-configuration is: listed in `META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports`. **The compiler writes that entry for you.** The class is generated rather than written, so its name is one only the compiler knows — leaving the registration to be typed by hand made a plugin whose beans are silently never registered the ordinary consequence of not knowing the class exists.
+
+A module that keeps the imports file by hand keeps it, and nothing is generated beside it: two copies of the same resource cannot both go into the jar, and folding the hand-authored entries into a copy under the build directory would lose them as soon as anyone deleted the file they were written in. Such a module is warned at compile time when the generated class is missing from its file. Deleting that file is what opts in, and is safe once it lists nothing that is not generated — a module may still need it for entries no compilation can discover, such as a class from another jar, one annotated with a composed annotation, or one carrying no annotation at all, the imports file being the registration and `@AutoConfiguration` only supplying ordering.
+
+A standalone `@GrailsBeans` class — one that is neither a plugin descriptor nor an `Application` — is a source file you can see, so it is registered by hand like any other auto-configuration.
 
 NOTE: `@GrailsBeans` does not require extending `Plugin` at all — it produces a plain Spring Boot `AutoConfiguration`, so it can be used by any Spring Boot module, not just a Grails plugin descriptor. Applications can use it too, including directly on the `Application` class — where no imports-file registration is needed, since Spring Boot processes the application class itself — see link:spring.html#springdslAdditional[Configuring Additional Beans]. Within a plugin, reach for it specifically when a bean's registration needs to be ordered against a particular other auto-configuration; otherwise `beanRegistrar()` remains the recommended way to register beans from a `Plugin`.