GROOVY-11909: Add a @Modifies annotation to groovy-contracts

subprojects/groovy-contracts/src/main/java/groovy/contracts/Modifies.java

@@ -0,0 +1,72 @@
+/*
+ *  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.contracts;
+
+import org.apache.groovy.lang.annotation.Incubating;
+import org.codehaus.groovy.transform.GroovyASTTransformationClass;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Repeatable;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Declares the <b>frame condition</b> for a method: the set of fields and parameters
+ * that the method is allowed to modify. All other state is implicitly declared unchanged.
+ * <p>
+ * The closure value lists the modifiable targets as field references ({@code this.fieldName})
+ * or parameter references ({@code paramName}). Multiple targets can be specified using a list:
+ * <pre>
+ *   &#064;Modifies({ this.items })
+ *   void addItem(Item item) { ... }
+ *
+ *   &#064;Modifies({ [this.items, this.count] })
+ *   void addAndCount(Item item) { ... }
+ * </pre>
+ * <p>
+ * Multiple {@code @Modifies} annotations can also be used (via {@link Repeatable}):
+ * <pre>
+ *   &#064;Modifies({ this.items })
+ *   &#064;Modifies({ this.count })
+ *   void addAndCount(Item item) { ... }
+ * </pre>
+ * <p>
+ * When both {@code @Modifies} and {@link Ensures} are present on a method,
+ * the {@code old} variable in the postcondition may only reference fields
+ * declared in {@code @Modifies}. A compile error is reported otherwise.
+ * <p>
+ * {@code @Modifies} does not generate runtime assertion code. It serves as
+ * a specification for humans and tools (including AI) to reason about method behavior.
+ *
+ * @since 6.0.0
+ * @see Ensures
+ * @see Requires
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.CONSTRUCTOR, ElementType.METHOD})
+@Incubating
+@Repeatable(ModifiesConditions.class)
+@GroovyASTTransformationClass({
+        "org.apache.groovy.contracts.ast.ModifiesASTTransformation",
+        "org.apache.groovy.contracts.ast.ModifiesEnsuresValidationTransformation"
+})
+public @interface Modifies {
+    Class value();
+}

subprojects/groovy-contracts/src/main/java/groovy/contracts/ModifiesConditions.java

@@ -0,0 +1,39 @@
+/*
+ *  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.contracts;
+
+import org.apache.groovy.lang.annotation.Incubating;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Container for multiple {@link Modifies} annotations on the same method.
+ *
+ * @since 6.0.0
+ * @see Modifies
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.CONSTRUCTOR, ElementType.METHOD})
+@Incubating
+public @interface ModifiesConditions {
+    Modifies[] value();
+}

subprojects/groovy-contracts/src/main/java/org/apache/groovy/contracts/ast/ModifiesASTTransformation.java

@@ -0,0 +1,155 @@
+/*
+ *  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.apache.groovy.contracts.ast;
+
+import org.codehaus.groovy.ast.ASTNode;
+import org.codehaus.groovy.ast.AnnotationNode;
+import org.codehaus.groovy.ast.ClassNode;
+import org.codehaus.groovy.ast.MethodNode;
+import org.codehaus.groovy.ast.Parameter;
+import org.codehaus.groovy.ast.expr.ClosureExpression;
+import org.codehaus.groovy.ast.expr.Expression;
+import org.codehaus.groovy.ast.expr.ListExpression;
+import org.codehaus.groovy.ast.expr.PropertyExpression;
+import org.codehaus.groovy.ast.expr.VariableExpression;
+import org.codehaus.groovy.ast.stmt.BlockStatement;
+import org.codehaus.groovy.ast.stmt.ExpressionStatement;
+import org.codehaus.groovy.ast.stmt.Statement;
+import org.codehaus.groovy.control.CompilePhase;
+import org.codehaus.groovy.control.SourceUnit;
+import org.codehaus.groovy.syntax.SyntaxException;
+import org.codehaus.groovy.transform.ASTTransformation;
+import org.codehaus.groovy.transform.GroovyASTTransformation;
+
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Set;
+
+/**
+ * Handles {@link groovy.contracts.Modifies} annotations placed on methods.
+ * Extracts the declared modification targets (fields and parameters) from
+ * the annotation closure and stores them as node metadata on the {@link MethodNode}.
+ * <p>
+ * The metadata key is {@value #MODIFIES_FIELDS_KEY} and the value is a
+ * {@code Set<String>} of field/parameter names. Downstream processors
+ * (such as {@code @Ensures} validation) can read this metadata.
+ *
+ * @since 6.0.0
+ * @see groovy.contracts.Modifies
+ */
+@GroovyASTTransformation(phase = CompilePhase.SEMANTIC_ANALYSIS)
+public class ModifiesASTTransformation implements ASTTransformation {
+
+    /** Node metadata key for the set of modifiable field/parameter names. */
+    public static final String MODIFIES_FIELDS_KEY = "groovy.contracts.modifiesFields";
+
+    @Override
+    @SuppressWarnings("unchecked")
+    public void visit(final ASTNode[] nodes, final SourceUnit source) {
+        if (nodes.length != 2) return;
+        if (!(nodes[0] instanceof AnnotationNode annotation)) return;
+        if (!(nodes[1] instanceof MethodNode methodNode)) return;
+
+        // For @Repeatable, each annotation triggers this transform separately,
+        // so merge with any existing metadata from prior invocations.
+        Set<String> modifiesSet = (Set<String>) methodNode.getNodeMetaData(MODIFIES_FIELDS_KEY);
+        if (modifiesSet == null) {
+            modifiesSet = new LinkedHashSet<>();
+        }
+
+        extractFromAnnotation(annotation, methodNode, modifiesSet, source);
+
+        if (!modifiesSet.isEmpty()) {
+            methodNode.putNodeMetaData(MODIFIES_FIELDS_KEY, modifiesSet);
+        }
+    }
+
+    private static void extractFromAnnotation(AnnotationNode annotation, MethodNode methodNode, Set<String> modifiesSet, SourceUnit source) {
+        Expression value = annotation.getMember("value");
+        if (!(value instanceof ClosureExpression closureExpr)) return;
+
+        Expression expr = extractExpression(closureExpr);
+        if (expr == null) {
+            source.addError(new SyntaxException(
+                    "@Modifies closure must contain a field reference, parameter reference, or list of references",
+                    annotation.getLineNumber(), annotation.getColumnNumber()));
+            return;
+        }
+
+        if (expr instanceof ListExpression listExpr) {
+            for (Expression element : listExpr.getExpressions()) {
+                addValidatedName(element, methodNode, modifiesSet, source);
+            }
+        } else {
+            addValidatedName(expr, methodNode, modifiesSet, source);
+        }
+    }
+
+    private static void addValidatedName(Expression expr, MethodNode methodNode, Set<String> modifiesSet, SourceUnit source) {
+        if (expr instanceof PropertyExpression propExpr) {
+            Expression objExpr = propExpr.getObjectExpression();
+            if (objExpr instanceof VariableExpression varExpr && "this".equals(varExpr.getName())) {
+                String fieldName = propExpr.getPropertyAsString();
+                ClassNode declaringClass = methodNode.getDeclaringClass();
+                if (declaringClass != null && declaringClass.getField(fieldName) == null) {
+                    source.addError(new SyntaxException(
+                            "@Modifies references field '" + fieldName + "' which does not exist in " + declaringClass.getName(),
+                            expr.getLineNumber(), expr.getColumnNumber()));
+                } else {
+                    modifiesSet.add(fieldName);
+                }
+                return;
+            }
+        }
+        if (expr instanceof VariableExpression varExpr) {
+            String name = varExpr.getName();
+            if (!"this".equals(name)) {
+                boolean isParam = false;
+                for (Parameter param : methodNode.getParameters()) {
+                    if (param.getName().equals(name)) {
+                        isParam = true;
+                        break;
+                    }
+                }
+                if (!isParam) {
+                    source.addError(new SyntaxException(
+                            "@Modifies references '" + name + "' which is not a parameter of " + methodNode.getName() + "()",
+                            expr.getLineNumber(), expr.getColumnNumber()));
+                } else {
+                    modifiesSet.add(name);
+                }
+                return;
+            }
+        }
+        source.addError(new SyntaxException(
+                "@Modifies elements must be field references (this.field) or parameter references",
+                expr.getLineNumber(), expr.getColumnNumber()));
+    }
+
+    private static Expression extractExpression(ClosureExpression closureExpression) {
+        BlockStatement block = (BlockStatement) closureExpression.getCode();
+        List<Statement> statements = block.getStatements();
+        if (statements.size() != 1) return null;
+        Statement stmt = statements.get(0);
+        if (stmt instanceof ExpressionStatement exprStmt) {
+            return exprStmt.getExpression();
+        }
+        return null;
+    }
+}

subprojects/groovy-contracts/src/main/java/org/apache/groovy/contracts/ast/ModifiesEnsuresValidationTransformation.java

@@ -0,0 +1,71 @@
+/*
+ *  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.apache.groovy.contracts.ast;
+
+import org.apache.groovy.contracts.ast.visitor.AnnotationClosureVisitor;
+import org.codehaus.groovy.ast.ASTNode;
+import org.codehaus.groovy.ast.AnnotationNode;
+import org.codehaus.groovy.ast.MethodNode;
+import org.codehaus.groovy.control.CompilePhase;
+import org.codehaus.groovy.control.SourceUnit;
+import org.codehaus.groovy.syntax.SyntaxException;
+import org.codehaus.groovy.transform.ASTTransformation;
+import org.codehaus.groovy.transform.GroovyASTTransformation;
+
+import java.util.Set;
+
+/**
+ * Validates that {@code @Ensures} postconditions on a method only reference
+ * fields via {@code old.xxx} that are declared as modifiable by {@code @Modifies}.
+ * <p>
+ * Runs at {@link CompilePhase#INSTRUCTION_SELECTION} after both:
+ * <ul>
+ *   <li>{@link ModifiesASTTransformation} has stored the modification set, and</li>
+ *   <li>{@link AnnotationClosureVisitor} has recorded the {@code old} references</li>
+ * </ul>
+ * Then simply compares the two metadata sets.
+ *
+ * @since 6.0.0
+ * @see groovy.contracts.Modifies
+ */
+@GroovyASTTransformation(phase = CompilePhase.INSTRUCTION_SELECTION)
+public class ModifiesEnsuresValidationTransformation implements ASTTransformation {
+
+    @Override
+    @SuppressWarnings("unchecked")
+    public void visit(final ASTNode[] nodes, final SourceUnit source) {
+        if (nodes.length != 2) return;
+        if (!(nodes[0] instanceof AnnotationNode annotation)) return;
+        if (!(nodes[1] instanceof MethodNode methodNode)) return;
+
+        Set<String> modifiesSet = (Set<String>) methodNode.getNodeMetaData(ModifiesASTTransformation.MODIFIES_FIELDS_KEY);
+        if (modifiesSet == null || modifiesSet.isEmpty()) return;
+
+        Set<String> oldRefs = (Set<String>) methodNode.getNodeMetaData(AnnotationClosureVisitor.OLD_REFERENCES_KEY);
+        if (oldRefs == null || oldRefs.isEmpty()) return;
+
+        for (String ref : oldRefs) {
+            if (!modifiesSet.contains(ref)) {
+                source.addError(new SyntaxException(
+                        "@Ensures references old." + ref + " but @Modifies does not declare '" + ref + "' as modifiable",
+                        annotation.getLineNumber(), annotation.getColumnNumber()));
+            }
+        }
+    }
+}

subprojects/groovy-contracts/src/main/java/org/apache/groovy/contracts/ast/visitor/AnnotationClosureVisitor.java

@@ -459,6 +459,9 @@ protected SourceUnit getSourceUnit() {
         }
     }
 
+    /** Node metadata key for the set of field names referenced via {@code old.xxx} in postconditions. */
+    public static final String OLD_REFERENCES_KEY = "groovy.contracts.oldReferences";
+
     private static class OldPropertyExpressionTransformer extends ClassCodeExpressionTransformer {
         private final MethodNode methodNode;
         private CastExpression currentCast;
@@ -472,6 +475,7 @@ protected SourceUnit getSourceUnit() {
             return null;
         }
 
+        @SuppressWarnings("unchecked")
         @Override
         public Expression transform(Expression expr) {
             if (expr instanceof CastExpression) {
@@ -488,6 +492,13 @@ public Expression transform(Expression expr) {
                 if (objExpr instanceof VariableExpression varExpr) {
                     if ("old".equals(varExpr.getName())) {
                         String propName = propExpr.getPropertyAsString();
+                        // Record the old reference for @Modifies validation
+                        java.util.Set<String> oldRefs = (java.util.Set<String>) methodNode.getNodeMetaData(OLD_REFERENCES_KEY);
+                        if (oldRefs == null) {
+                            oldRefs = new java.util.LinkedHashSet<>();
+                            methodNode.putNodeMetaData(OLD_REFERENCES_KEY, oldRefs);
+                        }
+                        oldRefs.add(propName);
                         ClassNode declaringClass = methodNode.getDeclaringClass();
                         if (declaringClass != null && declaringClass.getField(propName) != null) {
                             CastExpression adjusted = new CastExpression(declaringClass.getField(propName).getType(), expr);