GROOVY-11896: Adjust Module import resolution

This better accommodates single-type > type-on-demand > module-import precedence of Java.
See [JLS 6.4.1](https://docs.oracle.com/javase/specs/jls/se25/html/jls-6.html#jls-6.4)

This also lays a little bit of groundwork for
https://issues.apache.org/jira/browse/GROOVY-11916 if/when we action
that.

Author: jonnybot0

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

@@ -410,14 +410,13 @@ public ImportNode visitImportDeclaration(final ImportDeclarationContext ctx) {
      * {@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>
+     * As per JLS 6.4.1, explicit single-type imports and type-on-demand (star)
+     * imports take priority over module-expanded imports. Ambiguous class names
+     * from multiple module imports produce a compile-time error (JLS 7.5.5).
+     * <p>
+     * Known difference from Java: Groovy's star imports (including module-expanded
+     * ones) can resolve package-private types, whereas Java only exposes public
+     * types from exported packages (see GROOVY-11916).
      */
     private ImportNode expandModuleImport(final String moduleName, final List<AnnotationNode> annotations, final ImportDeclarationContext ctx) {
         var finder = ModuleImportHelper.moduleFinder(sourceUnit);
@@ -430,18 +429,22 @@ private ImportNode expandModuleImport(final String moduleName, final List<Annota
         Set<String> skip = new HashSet<>(Arrays.asList(
                 org.codehaus.groovy.control.ResolveVisitor.DEFAULT_IMPORTS));
         moduleNode.getStarImports().stream().map(ImportNode::getPackageName).forEach(skip::add);
+        moduleNode.getModuleStarImports().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());
+                // Separate list so resolution can apply JLS 6.4.1 shadowing:
+                // a user-written `import foo.*` beats a module-expanded `foo.*`.
+                moduleNode.addModuleStarImport(packageName, annotations);
+                lastImport = last(moduleNode.getModuleStarImports());
                 skip.add(packageName);
             }
         }
         if (lastImport == null) {
             // All exported packages were already covered by existing imports
-            lastImport = last(moduleNode.getStarImports());
+            List<ImportNode> existing = moduleNode.getModuleStarImports();
+            lastImport = !existing.isEmpty() ? last(existing) : last(moduleNode.getStarImports());
         }
         return configureAST(lastImport, ctx);
     }

src/main/java/org/codehaus/groovy/ast/ModuleNode.java

@@ -70,6 +70,7 @@ public class ModuleNode extends ASTNode {
     private final List<MethodNode> methods = new ArrayList<>();
     private final List<ImportNode> imports = new ArrayList<>();
     private final List<ImportNode> starImports = new ArrayList<>();
+    private final List<ImportNode> moduleStarImports = new ArrayList<>();
     private final Map<String, ImportNode> staticImports = new LinkedHashMap<>();
     private final Map<String, ImportNode> staticStarImports = new LinkedHashMap<>();
     private CompileUnit unit;
@@ -183,6 +184,23 @@ public void addStarImport(final String packageName, final List<AnnotationNode> a
         storeLastAddedImportNode(importNode);
     }
 
+    /**
+     * @return star imports that originated from {@code import module M} declarations.
+     *         Separate from {@link #getStarImports()} so that resolution can apply
+     *         JLS 6.4.1 shadowing (type-import-on-demand shadows module-import).
+     */
+    public List<ImportNode> getModuleStarImports() {
+        return moduleStarImports;
+    }
+
+    public void addModuleStarImport(final String packageName, final List<AnnotationNode> annotations) {
+        ImportNode importNode = new ImportNode(packageName);
+        importNode.addAnnotations(annotations);
+        moduleStarImports.add(importNode);
+
+        storeLastAddedImportNode(importNode);
+    }
+
     public void addStaticImport(final ClassNode type, final String memberName, final String simpleName) {
         addStaticImport(type, memberName, simpleName, Collections.emptyList());
     }

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

@@ -768,6 +768,31 @@ protected boolean resolveFromModule(final ClassNode type, final boolean testModu
                     }
                 }
             }
+            // Module-expanded star imports — lowest precedence per JLS 6.4.1.
+            // Only consulted if nothing above resolved the type, and ambiguity
+            // between two module-expanded packages is a compile-time error
+            // (matching Java's behavior per JLS 7.5.5 Example 7.5.5-3).
+            ClassNode moduleMatch = null;
+            String moduleMatchPkg = null;
+            for (ImportNode importNode : module.getModuleStarImports()) {
+                ClassNode tmp = new ConstructedClassWithPackage(importNode.getPackageName(), name);
+                if (resolve(tmp, false, false, true)) {
+                    ClassNode resolved = tmp.redirect();
+                    if (moduleMatch != null && !moduleMatch.getName().equals(resolved.getName())) {
+                        addError("reference to " + name + " is ambiguous, both "
+                                + moduleMatch.getName() + " (from " + moduleMatchPkg + ")"
+                                + " and " + resolved.getName()
+                                + " (from " + importNode.getPackageName() + ") match", type);
+                        return true;
+                    }
+                    moduleMatch = resolved;
+                    moduleMatchPkg = importNode.getPackageName();
+                }
+            }
+            if (moduleMatch != null) {
+                type.setRedirect(moduleMatch);
+                return true;
+            }
         }
 
         return false;

src/test/groovy/groovy/ImportTest.groovy

@@ -272,4 +272,38 @@ final class ImportTest {
             assert module.toUpperCase() == 'HELLO'
         '''
     }
+
+    // GROOVY-11896: JLS 7.5.5 Example 7.5.5-3 — when a module import exposes
+    // two packages that both contain a public type with the same simple name,
+    // using that simple name must be a compile-time error, not a silent pick.
+    // Here, java.desktop exports both javax.swing.text (with Element interface)
+    // and javax.swing.text.html.parser (with Element class).
+    @Test
+    void testImportModuleAmbiguousSimpleName() {
+        def err = shouldFail '''
+            import module java.desktop
+            Element e = null
+        '''
+        assert err.message.contains('ambiguous'),
+                "expected ambiguity error, got: ${err.message}"
+    }
+
+    // GROOVY-11896: JLS 6.4.1 — a type-import-on-demand declaration shadows
+    // types imported by a single-module-import declaration. The `import module`
+    // is written FIRST so that without proper tier separation, the module-
+    // expanded java.awt.* would win by list ordering. With correct shadowing,
+    // the user's `import java.util.*` wins regardless of source order, and
+    // List resolves to java.util.List rather than java.awt.List.
+    @Test
+    void testImportModuleShadowedByStarImport() {
+        assertScript '''
+            import module java.desktop
+            assert List.name == 'java.awt.List'
+        '''
+        assertScript '''
+            import module java.desktop
+            import java.util.*
+            assert List.name == 'java.util.List'
+        '''
+    }
 }