GROOVY-11896: Support module import declarations

Author: paulk-asert

src/antlr/GroovyLexer.g4

@@ -457,6 +457,7 @@ INT           : 'int';
 fragment
 LONG          : 'long';
 
+MODULE        : 'module';
 NATIVE        : 'native';
 NEW           : 'new';
 NON_SEALED    : 'non-sealed';

src/antlr/GroovyParser.g4

@@ -119,6 +119,7 @@ packageDeclaration
 
 importDeclaration
     :   annotationsOpt IMPORT STATIC? qualifiedName (DOT MUL | AS alias=identifier)?
+    |   annotationsOpt IMPORT MODULE qualifiedName
     ;
 
 
@@ -1243,6 +1244,7 @@ identifier
     |   AWAIT
     |   DEFER
     |   IN
+    |   MODULE
     |   PERMITS
     |   RECORD
     |   SEALED

src/main/java/org/apache/groovy/parser/antlr4/AstBuilder.java

@@ -124,6 +124,7 @@
 import org.codehaus.groovy.classgen.Verifier;
 import org.codehaus.groovy.control.CompilationFailedException;
 import org.codehaus.groovy.control.CompilePhase;
+import org.codehaus.groovy.control.ModuleImportHelper;
 import org.codehaus.groovy.control.SourceUnit;
 import org.codehaus.groovy.control.messages.SyntaxErrorMessage;
 import org.codehaus.groovy.transform.AsyncTransformHelper;
@@ -140,15 +141,18 @@
 import java.util.ArrayDeque;
 import java.util.ArrayList;
 import java.util.Arrays;
+import java.util.Collection;
 import java.util.Collections;
 import java.util.Deque;
+import java.util.HashSet;
 import java.util.Iterator;
 import java.util.LinkedHashMap;
 import java.util.LinkedList;
 import java.util.List;
 import java.util.Map;
 import java.util.Objects;
 import java.util.Optional;
+import java.util.Set;
 import java.util.function.Function;
 import java.util.stream.Collectors;
 
@@ -338,6 +342,11 @@ public PackageNode visitPackageDeclaration(final PackageDeclarationContext ctx)
     public ImportNode visitImportDeclaration(final ImportDeclarationContext ctx) {
         List<AnnotationNode> annotations = this.visitAnnotationsOpt(ctx.annotationsOpt());
 
+        if (asBoolean(ctx.MODULE())) {
+            String moduleName = this.visitQualifiedName(ctx.qualifiedName());
+            return expandModuleImport(moduleName, annotations, ctx);
+        }
+
         boolean hasStatic = asBoolean(ctx.STATIC());
         boolean hasStar   = asBoolean(ctx.MUL());
         boolean hasAlias  = asBoolean(ctx.alias);
@@ -388,6 +397,55 @@ public ImportNode visitImportDeclaration(final ImportDeclarationContext ctx) {
         return configureAST(importNode, ctx);
     }
 
+    /**
+     * Expands {@code import module java.base} into star imports for all
+     * packages exported (unqualified) by the named module and, recursively,
+     * by any modules it {@code requires transitive} (per JEP 476).
+     * Packages already covered by Groovy's default imports or existing
+     * star imports are skipped to avoid redundant resolution work.
+     * <p>
+     * Modules are located from system modules (JDK) first, then from
+     * modular JARs on the compilation classpath. Automatic modules
+     * (JARs with an {@code Automatic-Module-Name} manifest entry but no
+     * {@code module-info.class}) are supported — all packages in the JAR
+     * are imported since automatic modules have no explicit exports.
+     * <p>
+     * Known differences from Java's module import behavior:
+     * <ul>
+     * <li>Ambiguous class names from multiple module imports silently resolve
+     *     to the last match, consistent with Groovy's existing star import
+     *     semantics. Java reports a compile-time error for such ambiguities.</li>
+     * <li>Explicit single-type imports take priority over module-expanded
+     *     star imports (same as Java).</li>
+     * </ul>
+     */
+    private ImportNode expandModuleImport(final String moduleName, final List<AnnotationNode> annotations, final ImportDeclarationContext ctx) {
+        var finder = ModuleImportHelper.moduleFinder(sourceUnit);
+        List<String> packageNames;
+        try {
+            packageNames = ModuleImportHelper.resolveModulePackages(moduleName, finder);
+        } catch (IllegalArgumentException e) {
+            throw createParsingFailedException(e.getMessage(), ctx);
+        }
+        Set<String> skip = new HashSet<>(Arrays.asList(
+                org.codehaus.groovy.control.ResolveVisitor.DEFAULT_IMPORTS));
+        moduleNode.getStarImports().stream().map(ImportNode::getPackageName).forEach(skip::add);
+        ImportNode lastImport = null;
+        for (String pkg : packageNames) {
+            String packageName = pkg + DOT_STR;
+            if (!skip.contains(packageName)) {
+                moduleNode.addStarImport(packageName, annotations);
+                lastImport = last(moduleNode.getStarImports());
+                skip.add(packageName);
+            }
+        }
+        if (lastImport == null) {
+            // All exported packages were already covered by existing imports
+            lastImport = last(moduleNode.getStarImports());
+        }
+        return configureAST(lastImport, ctx);
+    }
+
     private static AnnotationNode makeAnnotationNode(final Class<? extends Annotation> type) {
         AnnotationNode node = new AnnotationNode(ClassHelper.make(type));
         // TODO: source offsets

src/main/java/org/codehaus/groovy/control/ModuleImportHelper.java

@@ -0,0 +1,145 @@
+/*
+ *  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
+ *
+ *    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.
+ */
+package org.codehaus.groovy.control;
+
+import java.lang.module.FindException;
+import java.lang.module.ModuleDescriptor;
+import java.lang.module.ModuleFinder;
+import java.lang.module.ModuleReference;
+import java.net.URISyntaxException;
+import java.net.URL;
+import java.net.URLClassLoader;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.HashSet;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Set;
+
+/**
+ * Shared utilities for expanding JPMS module imports into package-level
+ * star imports. Used by both the parser ({@code AstBuilder}) and the
+ * {@link org.codehaus.groovy.control.customizers.ImportCustomizer}.
+ *
+ * @since 6.0.0
+ */
+public final class ModuleImportHelper {
+
+    private ModuleImportHelper() { }
+
+    /**
+     * Builds a {@link ModuleFinder} that combines the system module finder
+     * with one scanning the compilation classpath for modular JARs.
+     *
+     * @param source the source unit providing classpath and classloader
+     * @return a composite module finder
+     */
+    public static ModuleFinder moduleFinder(final SourceUnit source) {
+        return ModuleFinder.compose(ModuleFinder.ofSystem(), classpathModuleFinder(source));
+    }
+
+    /**
+     * Collects the exported package names from the given module and,
+     * recursively, from any modules it {@code requires transitive}.
+     * This implements the transitive readability semantics specified
+     * by JEP 476.
+     *
+     * @param moduleRef the module to inspect
+     * @param finder    the finder used to resolve transitive dependencies
+     * @param packageNames accumulator for discovered package names
+     * @param visited   set of already-visited module names (to avoid cycles)
+     */
+    public static void collectModuleExports(final ModuleReference moduleRef, final ModuleFinder finder,
+                                            final List<String> packageNames, final Set<String> visited) {
+        ModuleDescriptor descriptor = moduleRef.descriptor();
+        if (!visited.add(descriptor.name())) return;
+        // Automatic modules have no exports — use packages() instead
+        if (descriptor.isAutomatic()) {
+            packageNames.addAll(descriptor.packages());
+        } else {
+            descriptor.exports().stream()
+                    .filter(e -> !e.isQualified())
+                    .map(ModuleDescriptor.Exports::source)
+                    .forEach(packageNames::add);
+        }
+        // Recursively process transitive dependencies (JEP 476)
+        for (ModuleDescriptor.Requires req : descriptor.requires()) {
+            if (req.modifiers().contains(ModuleDescriptor.Requires.Modifier.TRANSITIVE)) {
+                finder.find(req.name()).ifPresent(ref ->
+                        collectModuleExports(ref, finder, packageNames, visited));
+            }
+        }
+    }
+
+    /**
+     * Resolves a module by name and collects its exported packages
+     * (including transitive dependencies).
+     *
+     * @param moduleName the JPMS module name
+     * @param finder     the module finder to use
+     * @return the list of exported package names
+     * @throws IllegalArgumentException if the module is not found
+     */
+    public static List<String> resolveModulePackages(final String moduleName, final ModuleFinder finder) {
+        ModuleReference moduleRef = finder.find(moduleName).orElse(null);
+        if (moduleRef == null) {
+            throw new IllegalArgumentException("Unknown module: " + moduleName);
+        }
+        List<String> packageNames = new ArrayList<>();
+        collectModuleExports(moduleRef, finder, packageNames, new HashSet<>());
+        return packageNames;
+    }
+
+    /**
+     * Builds a {@link ModuleFinder} that scans the compilation classpath
+     * for modular JARs (those containing {@code module-info.class}).
+     * Collects paths from both the compiler configuration classpath and
+     * any URLClassLoaders in the classloader hierarchy.
+     */
+    private static ModuleFinder classpathModuleFinder(final SourceUnit source) {
+        Set<Path> paths = new LinkedHashSet<>();
+        for (String entry : source.getConfiguration().getClasspath()) {
+            Path p = Path.of(entry);
+            if (Files.exists(p)) {
+                paths.add(p);
+            }
+        }
+        ClassLoader cl = source.getClassLoader();
+        while (cl != null) {
+            if (cl instanceof URLClassLoader) {
+                for (URL url : ((URLClassLoader) cl).getURLs()) {
+                    try {
+                        Path p = Path.of(url.toURI());
+                        if (Files.exists(p)) {
+                            paths.add(p);
+                        }
+                    } catch (URISyntaxException ignore) {
+                    }
+                }
+            }
+            cl = cl.getParent();
+        }
+        try {
+            return ModuleFinder.of(paths.toArray(Path[]::new));
+        } catch (FindException e) {
+            return ModuleFinder.of();
+        }
+    }
+}

src/main/java/org/codehaus/groovy/control/customizers/ImportCustomizer.java

@@ -20,13 +20,21 @@
 
 import org.codehaus.groovy.ast.ClassHelper;
 import org.codehaus.groovy.ast.ClassNode;
+import org.codehaus.groovy.ast.ImportNode;
 import org.codehaus.groovy.ast.ModuleNode;
 import org.codehaus.groovy.classgen.GeneratorContext;
 import org.codehaus.groovy.control.CompilePhase;
+import org.codehaus.groovy.control.ModuleImportHelper;
+import org.codehaus.groovy.control.ResolveVisitor;
 import org.codehaus.groovy.control.SourceUnit;
 
+import java.lang.module.ModuleFinder;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.HashSet;
 import java.util.LinkedList;
 import java.util.List;
+import java.util.Set;
 
 /**
  * This compilation customizer allows adding various types of imports to the compilation unit. Supports adding:
@@ -35,6 +43,7 @@
  *     <li>star imports via {@link #addStarImports(String...)}</li>
  *     <li>static imports via {@link #addStaticImport(String, String)} or {@link #addStaticImport(String, String, String)}</li>
  *     <li>static star imports via {@link #addStaticStars(String...)}</li>
+ *     <li>module imports via {@link #addModuleImports(String...)}</li>
  * </ul>
  *
  * @since 1.8.0
@@ -68,6 +77,24 @@ public void call(final SourceUnit source, final GeneratorContext context, final
                 case star:
                     ast.addStarImport(anImport.star);
                     break;
+                case moduleImport:
+                    expandModuleImport(source, ast, anImport.star);
+                    break;
+            }
+        }
+    }
+
+    private static void expandModuleImport(final SourceUnit source, final ModuleNode ast, final String moduleName) {
+        ModuleFinder finder = ModuleImportHelper.moduleFinder(source);
+        List<String> packageNames = ModuleImportHelper.resolveModulePackages(moduleName, finder);
+        Set<String> skip = new HashSet<>(Arrays.asList(ResolveVisitor.DEFAULT_IMPORTS));
+        ast.getStarImports().stream().map(ImportNode::getPackageName).forEach(skip::add);
+        ast.getModuleStarImports().stream().map(ImportNode::getPackageName).forEach(skip::add);
+        for (String pkg : packageNames) {
+            String packageName = pkg + ".";
+            if (!skip.contains(packageName)) {
+                ast.addModuleStarImport(packageName, Collections.emptyList());
+                skip.add(packageName);
             }
         }
     }
@@ -108,6 +135,21 @@ public ImportCustomizer addStaticStars(final String... classNames) {
         return this;
     }
 
+    /**
+     * Adds module imports. Each module name (e.g. {@code "java.sql"}) is expanded
+     * at compilation time into star imports for all packages exported by that module,
+     * including packages from transitively required modules (per JEP 476).
+     *
+     * @param moduleNames the JPMS module names to import
+     * @since 6.0.0
+     */
+    public ImportCustomizer addModuleImports(final String... moduleNames) {
+        for (String moduleName : moduleNames) {
+            imports.add(new Import(ImportType.moduleImport, moduleName));
+        }
+        return this;
+    }
+
     //
 
     private void addImport(final String className) {
@@ -164,6 +206,7 @@ private enum ImportType {
         regular,
         staticImport,
         staticStar,
-        star
+        star,
+        moduleImport
     }
 }

src/main/java/org/codehaus/groovy/control/customizers/builder/ImportCustomizerFactory.java

@@ -36,6 +36,7 @@
  *     <li><i>staticStar</i> for "static star" imports</li>
  *     <li><i>alias</i> for imports with alias</li>
  *     <li><i>staticMember</i> for static imports of individual members</li>
+ *     <li><i>module</i> for module imports (JEP 476)</li>
  * </ul>
  *
  * For example:
@@ -130,6 +131,10 @@ protected void staticMember(String alias, String name, String field) {
             customizer.addStaticImport(alias, name, field);
         }
 
+        protected void module(String... moduleNames) {
+            customizer.addModuleImports(moduleNames);
+        }
+
     }
 
 }