GROOVY-12093: Static method override on trait implementer ignored when called via this in trait body (cont'd)

Backport to GROOVY_5_0_X. Preserves existing 5.x-vs-master differences in
the trait transforms (the createHelperClasses refactor, javadoc and pattern-
matching differences are master-only and left untouched). The
TraitStaticDispatchMatrix test remains master-only for now; Groovy12093's
comment is adjusted accordingly and @Anchored is marked @SInCE 5.0.7.

Author: paulk-asert

src/main/java/groovy/transform/Anchored.java

@@ -0,0 +1,70 @@
+/*
+ *  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 groovy.transform;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Marks a trait method as <em>anchored to the trait</em> — dispatch is fixed
+ * to the trait's own definition rather than routed through the implementing
+ * class.
+ *
+ * <p>Applied to a trait <code>static</code> method, this opts out of the
+ * default per-implementer override dispatch (the Groovy distinctive that the
+ * Grails <code>Validateable.defaultNullable()</code> pattern depends on) and
+ * substitutes the JVM interface-static dispatch model: the implementer's
+ * same-signature static is an independent method, not an override; the trait
+ * body always calls the trait's own copy.
+ *
+ * <p>By default the marker also promotes the annotated method onto the
+ * generated trait interface as a JVM-native public static. That makes
+ * external <code>Trait.m()</code> calls and from-trait <code>T.m()</code>
+ * calls both resolve at the JVM level rather than throwing
+ * <code>MissingMethodException</code>. The {@link #inInterface()} attribute
+ * is provided as an opt-out for the narrow case where dispatch should be
+ * trait-anchored but the method should <em>not</em> be published on the
+ * interface (e.g. a soft-deprecated trait-internal helper that needs to
+ * remain publicly callable for backward compatibility but should not gain a
+ * fresh Java-visible API surface).
+ *
+ * <p>Use this marker for trait statics that are part of the trait's published
+ * contract — guaranteed-invariant utilities the trait author does not want
+ * implementers to redefine. Continue to use plain <code>static</code> when
+ * the trait offers a default that implementers may legitimately override.
+ *
+ * @since 5.0.7
+ */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.METHOD)
+public @interface Anchored {
+    /**
+     * Whether the annotated method should also be promoted onto the generated
+     * trait interface. Default <code>true</code>: the marker bundles
+     * declarer-bound dispatch with external interface visibility (the
+     * coherent JVM interface-static model). Set to <code>false</code> for the
+     * narrow opt-out described above — dispatch stays trait-anchored but the
+     * method is not exposed on the interface.
+     */
+    boolean inInterface() default true;
+}

src/main/java/org/codehaus/groovy/transform/trait/TraitASTTransformation.java

@@ -27,6 +27,7 @@
 import org.codehaus.groovy.ast.AnnotatedNode;
 import org.codehaus.groovy.ast.AnnotationNode;
 import org.codehaus.groovy.ast.ClassCodeExpressionTransformer;
+import org.codehaus.groovy.ast.ClassHelper;
 import org.codehaus.groovy.ast.ClassNode;
 import org.codehaus.groovy.ast.FieldNode;
 import org.codehaus.groovy.ast.GenericsType;
@@ -36,6 +37,7 @@
 import org.codehaus.groovy.ast.Parameter;
 import org.codehaus.groovy.ast.PropertyNode;
 import org.codehaus.groovy.ast.expr.BinaryExpression;
+import org.codehaus.groovy.ast.expr.ConstantExpression;
 import org.codehaus.groovy.ast.expr.Expression;
 import org.codehaus.groovy.ast.expr.MethodCallExpression;
 import org.codehaus.groovy.ast.expr.SpreadExpression;
@@ -115,6 +117,9 @@
 @GroovyASTTransformation(phase = CompilePhase.SEMANTIC_ANALYSIS)
 public class TraitASTTransformation extends AbstractASTTransformation implements CompilationUnitAware {
 
+    /** Marker annotation type for {@code @Anchored} trait static methods. */
+    private static final ClassNode ANCHORED_TYPE = ClassHelper.make(groovy.transform.Anchored.class);
+
     public static final String DO_DYNAMIC = TraitReceiverTransformer.class + ".doDynamic";
     public static final String POST_TYPECHECKING_REPLACEMENT = TraitReceiverTransformer.class + ".replacement";
 
@@ -246,6 +251,19 @@ private ClassNode createHelperClass(final ClassNode cNode) {
             processField(field, initializer, staticInitializer, fieldHelper, helper, staticFieldHelper, cNode, fieldNames);
         }
 
+        // Reject misapplied @Anchored markers before we waste effort
+        // processing them. Errors are registered against the source unit but
+        // processing continues so that multiple violations can be reported
+        // in a single compilation.
+        validateAnchoredAnnotations(cNode);
+
+        // Identify @Anchored public statics whose bodies the main loop will
+        // emit on the helper. Captured up front so the main loop carries no
+        // @Anchored-specific branching and so the interface forwarders can be
+        // installed in a single post-processing step after the originals are
+        // removed from the trait interface.
+        List<MethodNode> anchoredOnInterface = collectAnchoredOnInterface(cNode);
+
         // add methods
         List<MethodNode> nonPublicAPIMethods = new ArrayList<>();
         List<Statement> staticInitStatements = null;
@@ -274,6 +292,15 @@ private ClassNode createHelperClass(final ClassNode cNode) {
             cNode.removeMethod(privateMethod);
         }
 
+        // Install a public-static method on the trait interface for each
+        // @Anchored callee identified above. The forwarder delegates to the
+        // helper so external `Trait.m()` and from-trait `T.m()` calls resolve
+        // at the JVM level. Done after the removal step so the original
+        // static method is no longer on cNode when the forwarder is added.
+        for (MethodNode anchored : anchoredOnInterface) {
+            cNode.addMethod(createAnchoredInterfaceForwarder(cNode, helper, anchored));
+        }
+
         // copy statements from static and instance init blocks
         if (staticInitStatements != null) {
             BlockStatement toBlock = getBlockStatement(staticInitializer, staticInitializer.getCode());
@@ -617,6 +644,106 @@ private void processField(final FieldNode field, final MethodNode initializer, f
         fieldHelper.addField(dummyField);
     }
 
+    /**
+     * Reports a compile error for any {@code @Anchored} annotation that is
+     * applied to something other than a public static non-abstract trait
+     * method. Without this check the misapplied annotation would be silently
+     * ignored, leaving the user with no signal that the marker had no effect.
+     */
+    private void validateAnchoredAnnotations(final ClassNode traitClass) {
+        for (MethodNode methodNode : traitClass.getMethods()) {
+            List<AnnotationNode> annotations = methodNode.getAnnotations(ANCHORED_TYPE);
+            if (annotations.isEmpty()) continue;
+            String issue;
+            if (!methodNode.isStatic()) {
+                issue = "is not static";
+            } else if (methodNode.isPrivate()) {
+                issue = "is private";
+            } else if (methodNode.isAbstract()) {
+                issue = "is abstract";
+            } else {
+                continue; // valid
+            }
+            AnnotationNode anchored = annotations.get(0);
+            sourceUnit.addError(new SyntaxException(
+                    "@Anchored can only be applied to public static trait methods; "
+                            + traitClass.getName() + "#" + methodNode.getTypeDescriptor() + " " + issue,
+                    anchored.getLineNumber(), anchored.getColumnNumber()));
+        }
+    }
+
+    /**
+     * Returns the public {@code static} trait methods whose {@code @Anchored}
+     * marker requests interface promotion (i.e. {@code inInterface=true}, the
+     * default). The returned list snapshots the trait's method set so the
+     * caller can iterate the methods without being affected by later
+     * mutations to {@code traitClass.getMethods()}.
+     */
+    private static List<MethodNode> collectAnchoredOnInterface(final ClassNode traitClass) {
+        List<MethodNode> result = new ArrayList<>();
+        for (MethodNode methodNode : traitClass.getMethods()) {
+            if (methodNode.isStatic() && !methodNode.isPrivate() && !methodNode.isAbstract()
+                    && isAnchoredOnInterface(methodNode)) {
+                result.add(methodNode);
+            }
+        }
+        return result;
+    }
+
+    /**
+     * Returns {@code true} if the method is annotated with {@code @Anchored}
+     * and the {@code inInterface} attribute is true (the default).
+     */
+    private static boolean isAnchoredOnInterface(final MethodNode methodNode) {
+        List<AnnotationNode> anns = methodNode.getAnnotations(ANCHORED_TYPE);
+        if (anns.isEmpty()) return false;
+        Expression member = anns.get(0).getMember("inInterface");
+        if (member instanceof ConstantExpression
+                && Boolean.FALSE.equals(((ConstantExpression) member).getValue())) {
+            return false;
+        }
+        return true;
+    }
+
+    /**
+     * Builds a public-static method on the trait interface that delegates to
+     * the corresponding helper method.
+     *
+     * <p>Emits {@code public static R m(args) { return T$Trait$Helper.m(T.class, args); }},
+     * preserving generics, exceptions and parameter list of the original
+     * trait static. The trait class itself is passed as the synthetic
+     * {@code $self} receiver expected by the helper, consistent with the
+     * declarer-bound dispatch model that {@code @Anchored} selects.
+     */
+    private static MethodNode createAnchoredInterfaceForwarder(final ClassNode traitClass, final ClassNode helper, final MethodNode original) {
+        Parameter[] params = original.getParameters();
+        Expression[] callArgs = new Expression[params.length + 1];
+        callArgs[0] = classX(traitClass);
+        for (int i = 0; i < params.length; i++) {
+            callArgs[i + 1] = varX(params[i]);
+        }
+        MethodCallExpression call = callX(classX(helper), original.getName(), args(callArgs));
+        Statement body = VOID_TYPE.equals(original.getReturnType()) ? stmt(call) : returnS(call);
+        MethodNode forwarder = new MethodNode(
+                original.getName(),
+                ACC_PUBLIC | ACC_STATIC,
+                original.getReturnType(),
+                params,
+                original.getExceptions(),
+                body);
+        forwarder.setGenericsTypes(original.getGenericsTypes());
+        forwarder.setSynthetic(true);
+        forwarder.setSourcePosition(original);
+        // Carry over the trait method's RUNTIME/CLASS-retention annotations (e.g.
+        // @Deprecated) so the promoted interface static behaves like the original,
+        // consistent with the forwarders generated by TraitComposer. The helper
+        // filters out SOURCE-retention/transform markers and closure-member ones.
+        List<AnnotationNode> copied = new ArrayList<>(), notCopied = new ArrayList<>();
+        GeneralUtils.copyAnnotatedNodeAnnotations(original, copied, notCopied);
+        forwarder.addAnnotations(copied);
+        return forwarder;
+    }
+
     private MethodNode processMethod(final ClassNode traitClass, final ClassNode traitHelperClass, final MethodNode methodNode, final ClassNode fieldHelper, final Collection<String> knownFields) {
         boolean isAbstractMethod = methodNode.isAbstract();
         boolean isPrivateMethod = methodNode.isPrivate();

src/main/java/org/codehaus/groovy/transform/trait/TraitReceiverTransformer.java

@@ -66,6 +66,8 @@
  */
 class TraitReceiverTransformer extends ClassCodeExpressionTransformer {
 
+    private static final ClassNode ANCHORED_TYPE = ClassHelper.make(groovy.transform.Anchored.class);
+
     private final VariableExpression weaved;
     private final SourceUnit unit;
     private final ClassNode traitClass;
@@ -278,16 +280,23 @@ private Expression transformMethodCallOnThis(final MethodCallExpression call) {
             MethodNode methodNode = findConcreteMethod(traitClass, call.getMethodAsString());
             if (methodNode != null) {
                 MethodCallExpression newCall;
-                if (methodNode.isStatic() && !methodNode.isPrivate() && !inClosure) {
+                boolean anchored = !methodNode.getAnnotations(ANCHORED_TYPE).isEmpty();
+                if (methodNode.isStatic() && !methodNode.isPrivate() && !anchored && !inClosure) {
                     // GROOVY-11985: dispatch unqualified/this-qualified calls to
-                    // public trait statics through the implementing class so an
-                    // override declared on the implementer is visible from trait code.
+                    // public, non-@Anchored trait statics through the
+                    // implementing class so an override declared on the
+                    // implementer is visible from trait code. Annotating the
+                    // trait static with @Anchored opts out of this override
+                    // path and keeps dispatch declarer-bound through the trait
+                    // helper (Java/interface-static flavour); the matching
+                    // interface promotion is performed in TraitASTTransformation.
                     Expression implClass = ClassHelper.isClassType(weaved.getOriginType()) ? varX(weaved) : castX(ClassHelper.CLASS_Type.getPlainNodeReference(), callX(varX(weaved), "getClass"));
                     newCall = callX(implClass, method, transform(arguments));
                     newCall.setImplicitThis(false);
                     newCall.putNodeMetaData(TraitASTTransformation.DO_DYNAMIC, methodNode.getReturnType());
                 } else {
                     // this.m(x) --> (this or T$Trait$Helper).m($self or $static$self or (Class)$self.getClass(), x)
+                    // Reached for: private static, @Anchored static, instance method, or any call inside a closure.
                     Expression selfClassOrObject = methodNode.isStatic() && !ClassHelper.isClassType(weaved.getOriginType()) ? castX(ClassHelper.CLASS_Type.getPlainNodeReference(), callX(weaved, "getClass")) : weaved;
                     newCall = callX(!inClosure ? thisExpr : classX(traitHelper), method, createArgumentList(selfClassOrObject, arguments));
                 }