diff --git a/src/core/lombok/CheckReturnValue.java b/src/core/lombok/CheckReturnValue.java new file mode 100644 index 00000000..ef8f5c61 --- /dev/null +++ b/src/core/lombok/CheckReturnValue.java @@ -0,0 +1,44 @@ +/* + * Copyright (C) 2025 The Project Lombok Authors. + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + * THE SOFTWARE. + */ +package lombok; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * Lombok adds this annotation to generated methods where the return value should not be ignored. + *

+ * For example, {@code @With} methods return a new instance, so ignoring the return value is always a bug. + * Similarly, {@code @Builder}'s {@code build()} method produces the built object. + *

+ * Static analysis tools (Error Prone, IntelliJ, SpotBugs) recognize {@code @CheckReturnValue} + * by simple class name, regardless of package, and will warn when the return value is discarded. + *

+ * If you want to opt out, you can add {@code lombok.addCheckReturnValueAnnotation = false} to + * {@code lombok.config}. + */ +@Target({ElementType.METHOD}) +@Retention(RetentionPolicy.CLASS) +public @interface CheckReturnValue { +} diff --git a/src/core/lombok/ConfigurationKeys.java b/src/core/lombok/ConfigurationKeys.java index 997c550b..6c5c08f5 100644 --- a/src/core/lombok/ConfigurationKeys.java +++ b/src/core/lombok/ConfigurationKeys.java @@ -89,7 +89,15 @@ public class ConfigurationKeys { * If {@code true}, lombok generates {@code @lombok.Generated} on all fields, methods, and types that are generated. */ public static final ConfigurationKey ADD_LOMBOK_GENERATED_ANNOTATIONS = new ConfigurationKey("lombok.addLombokGeneratedAnnotation", "Generate @lombok.Generated on all generated code (default: true).") {}; - + + /** + * lombok configuration: {@code lombok.addCheckReturnValueAnnotation} = {@code true} | {@code false}. + * + * If {@code true}, lombok generates {@code @lombok.CheckReturnValue} on generated methods where the return value should not be ignored, + * such as {@code @With} methods and {@code @Builder}'s {@code build()} method. + */ + public static final ConfigurationKey ADD_CHECK_RETURN_VALUE_ANNOTATIONS = new ConfigurationKey("lombok.addCheckReturnValueAnnotation", "Generate @lombok.CheckReturnValue on generated methods where the return value should not be ignored (default: true).") {}; + /** * lombok configuration: {@code lombok.extern.findbugs.addSuppressFBWarnings} = {@code true} | {@code false}. * diff --git a/src/core/lombok/eclipse/handlers/EclipseHandlerUtil.java b/src/core/lombok/eclipse/handlers/EclipseHandlerUtil.java index 7eaaf7b6..a479356d 100644 --- a/src/core/lombok/eclipse/handlers/EclipseHandlerUtil.java +++ b/src/core/lombok/eclipse/handlers/EclipseHandlerUtil.java @@ -2096,6 +2096,7 @@ public class EclipseHandlerUtil { private static final char[][] JAKARTA_ANNOTATION_GENERATED = Eclipse.fromQualifiedName("jakarta.annotation.Generated"); private static final char[][] LOMBOK_GENERATED = Eclipse.fromQualifiedName("lombok.Generated"); private static final char[][] EDU_UMD_CS_FINDBUGS_ANNOTATIONS_SUPPRESSFBWARNINGS = Eclipse.fromQualifiedName("edu.umd.cs.findbugs.annotations.SuppressFBWarnings"); + private static final char[][] LOMBOK_CHECK_RETURN_VALUE = Eclipse.fromQualifiedName("lombok.CheckReturnValue"); public static Annotation[] addSuppressWarningsAll(EclipseNode node, ASTNode source, Annotation[] originalAnnotationArray) { Annotation[] anns = originalAnnotationArray; @@ -2126,6 +2127,11 @@ public class EclipseHandlerUtil { return result; } + public static Annotation[] addCheckReturnValue(EclipseNode node, ASTNode source, Annotation[] originalAnnotationArray) { + if (Boolean.FALSE.equals(node.getAst().readConfiguration(ConfigurationKeys.ADD_CHECK_RETURN_VALUE_ANNOTATIONS))) return originalAnnotationArray; + return addAnnotation(source, originalAnnotationArray, LOMBOK_CHECK_RETURN_VALUE); + } + static Annotation[] addAnnotation(ASTNode source, Annotation[] originalAnnotationArray, char[][] annotationTypeFqn) { return addAnnotation(source, originalAnnotationArray, annotationTypeFqn, (ASTNode[]) null); } diff --git a/src/core/lombok/eclipse/handlers/HandleBuilder.java b/src/core/lombok/eclipse/handlers/HandleBuilder.java index c39acdc7..d1e31617 100755 --- a/src/core/lombok/eclipse/handlers/HandleBuilder.java +++ b/src/core/lombok/eclipse/handlers/HandleBuilder.java @@ -889,11 +889,12 @@ public class HandleBuilder extends EclipseAnnotationHandler { out.annotations = new Annotation[] {generateNamedAnnotation(job.source, CheckerFrameworkVersion.NAME__SIDE_EFFECT_FREE)}; } out.receiver = generateBuildReceiver(job); + out.annotations = addCheckReturnValue(job.builderType, job.source, out.annotations); if (staticName == null) createRelevantNonNullAnnotation(job.builderType, out); out.traverse(new SetGeneratedByVisitor(job.source), (ClassScope) null); return out; } - + private TypeReference[] typeParameterNames(TypeParameter[] typeParameters) { if (typeParameters == null) return null; diff --git a/src/core/lombok/eclipse/handlers/HandleSuperBuilder.java b/src/core/lombok/eclipse/handlers/HandleSuperBuilder.java index 8ed1fa5a..8ced7e07 100644 --- a/src/core/lombok/eclipse/handlers/HandleSuperBuilder.java +++ b/src/core/lombok/eclipse/handlers/HandleSuperBuilder.java @@ -893,6 +893,7 @@ public class HandleSuperBuilder extends EclipseAnnotationHandler { statements.add(new ReturnStatement(allocationStatement, 0, 0)); out.statements = statements.isEmpty() ? null : statements.toArray(new Statement[0]); out.receiver = HandleBuilder.generateBuildReceiver(job); + out.annotations = addCheckReturnValue(job.builderType, job.source, out.annotations); createRelevantNonNullAnnotation(job.builderType, out); out.traverse(new SetGeneratedByVisitor(job.source), (ClassScope) null); return out; diff --git a/src/core/lombok/eclipse/handlers/HandleWith.java b/src/core/lombok/eclipse/handlers/HandleWith.java index 153f0c4a..b286e769 100644 --- a/src/core/lombok/eclipse/handlers/HandleWith.java +++ b/src/core/lombok/eclipse/handlers/HandleWith.java @@ -292,7 +292,8 @@ public class HandleWith extends EclipseAnnotationHandler { param.annotations = copyAnnotations(source, copyableAnnotations, onParam.toArray(new Annotation[0])); EclipseHandlerUtil.createRelevantNonNullAnnotation(fieldNode, method); - + method.annotations = EclipseHandlerUtil.addCheckReturnValue(fieldNode, source, method.annotations); + method.traverse(new SetGeneratedByVisitor(source), parent.scope); copyJavadoc(fieldNode, method, CopyJavadoc.WITH); return method; diff --git a/src/core/lombok/eclipse/handlers/HandleWithBy.java b/src/core/lombok/eclipse/handlers/HandleWithBy.java index bfba91d4..e25bb843 100644 --- a/src/core/lombok/eclipse/handlers/HandleWithBy.java +++ b/src/core/lombok/eclipse/handlers/HandleWithBy.java @@ -375,7 +375,8 @@ public class HandleWithBy extends EclipseAnnotationHandler { createRelevantNonNullAnnotation(sourceNode, param, method); createRelevantNonNullAnnotation(fieldNode, method); - + method.annotations = addCheckReturnValue(fieldNode, source, method.annotations); + method.traverse(new SetGeneratedByVisitor(source), parent.scope); copyJavadoc(fieldNode, method, CopyJavadoc.WITH_BY); return method; diff --git a/src/core/lombok/javac/handlers/HandleBuilder.java b/src/core/lombok/javac/handlers/HandleBuilder.java index 1e023f20..ea3392e2 100644 --- a/src/core/lombok/javac/handlers/HandleBuilder.java +++ b/src/core/lombok/javac/handlers/HandleBuilder.java @@ -801,10 +801,11 @@ public class HandleBuilder extends JavacAnnotationHandler { } else { methodDef = maker.MethodDef(maker.Modifiers(toJavacModifier(job.accessInners), annsOnMethod), job.toName(job.buildMethodName), returnTypeCopy, List.nil(), List.nil(), thrownExceptions, body, null); } + addCheckReturnValue(methodDef.mods, job.builderType, job.sourceNode); if (staticName == null) createRelevantNonNullAnnotation(job.builderType, methodDef); return methodDef; } - + public static JCMethodDecl generateDefaultProvider(Name methodName, JavacNode fieldNode, List params, BuilderJob job) { JavacTreeMaker maker = fieldNode.getTreeMaker(); JCVariableDecl field = (JCVariableDecl) fieldNode.get(); diff --git a/src/core/lombok/javac/handlers/HandleSuperBuilder.java b/src/core/lombok/javac/handlers/HandleSuperBuilder.java index c5a50508..a48225fa 100644 --- a/src/core/lombok/javac/handlers/HandleSuperBuilder.java +++ b/src/core/lombok/javac/handlers/HandleSuperBuilder.java @@ -869,10 +869,11 @@ public class HandleSuperBuilder extends JavacAnnotationHandler { } else { methodDef = maker.MethodDef(modifiers, job.toName(job.buildMethodName), cloneSelfType(job.parentType), List.nil(), List.nil(), thrownExceptions, body, null); } + addCheckReturnValue(methodDef.mods, job.builderType, job.sourceNode); createRelevantNonNullAnnotation(job.builderType, methodDef); return methodDef; } - + private JCMethodDecl generateCleanMethod(java.util.List builderFields, JavacNode type, JavacNode source) { JavacTreeMaker maker = type.getTreeMaker(); ListBuffer statements = new ListBuffer(); diff --git a/src/core/lombok/javac/handlers/HandleWith.java b/src/core/lombok/javac/handlers/HandleWith.java index 52f2c192..395cae65 100644 --- a/src/core/lombok/javac/handlers/HandleWith.java +++ b/src/core/lombok/javac/handlers/HandleWith.java @@ -281,15 +281,16 @@ public class HandleWith extends JavacAnnotationHandler { List annsOnMethod = copyAnnotations(onMethod, maker); CheckerFrameworkVersion checkerFramework = getCheckerFrameworkVersion(source); if (checkerFramework.generateSideEffectFree()) annsOnMethod = annsOnMethod.prepend(maker.Annotation(genTypeRef(source, CheckerFrameworkVersion.NAME__SIDE_EFFECT_FREE), List.nil())); - + if (isFieldDeprecated(field)) annsOnMethod = annsOnMethod.prepend(maker.Annotation(genJavaLangTypeRef(field, "Deprecated"), List.nil())); - + if (makeAbstract) access |= Flags.ABSTRACT; AnnotationValues accessors = JavacHandlerUtil.getAccessorsForField(field); boolean makeFinal = shouldMakeFinal(field, accessors); if (makeFinal) access |= Flags.FINAL; JCMethodDecl decl = recursiveSetGeneratedBy(maker.MethodDef(maker.Modifiers(access, annsOnMethod), methodName, returnType, methodGenericParams, parameters, throwsClauses, methodBody, annotationMethodDefaultValue), source); + addCheckReturnValue(decl.mods, field, source); copyJavadoc(field, decl, CopyJavadoc.WITH); return decl; } diff --git a/src/core/lombok/javac/handlers/HandleWithBy.java b/src/core/lombok/javac/handlers/HandleWithBy.java index 7978928f..aad502a0 100644 --- a/src/core/lombok/javac/handlers/HandleWithBy.java +++ b/src/core/lombok/javac/handlers/HandleWithBy.java @@ -334,6 +334,7 @@ public class HandleWithBy extends JavacAnnotationHandler { createRelevantNonNullAnnotation(source, param); JCMethodDecl decl = recursiveSetGeneratedBy(maker.MethodDef(maker.Modifiers(access, annsOnMethod), methodName, returnType, methodGenericParams, parameters, throwsClauses, methodBody, annotationMethodDefaultValue), source); + addCheckReturnValue(decl.mods, field, source); copyJavadoc(field, decl, CopyJavadoc.WITH_BY); createRelevantNonNullAnnotation(source, decl); return decl; diff --git a/src/core/lombok/javac/handlers/JavacHandlerUtil.java b/src/core/lombok/javac/handlers/JavacHandlerUtil.java index 0c075295..48a2c3fb 100644 --- a/src/core/lombok/javac/handlers/JavacHandlerUtil.java +++ b/src/core/lombok/javac/handlers/JavacHandlerUtil.java @@ -1554,6 +1554,11 @@ public class JavacHandlerUtil { } } + public static void addCheckReturnValue(JCModifiers mods, JavacNode node, JavacNode source) { + if (Boolean.FALSE.equals(node.getAst().readConfiguration(ConfigurationKeys.ADD_CHECK_RETURN_VALUE_ANNOTATIONS))) return; + addAnnotation(mods, node, source, "lombok.CheckReturnValue", null); + } + public static void addAnnotation(JCModifiers mods, JavacNode node, JavacNode source, String annotationTypeFqn, JCExpression arg) { boolean isJavaLangBased; String simpleName; { diff --git a/test/transform/resource/after-delombok/CheckReturnValueBuilder.java b/test/transform/resource/after-delombok/CheckReturnValueBuilder.java new file mode 100644 index 00000000..c8d84291 --- /dev/null +++ b/test/transform/resource/after-delombok/CheckReturnValueBuilder.java @@ -0,0 +1,59 @@ +class CheckReturnValueBuilder { + private final int x; + private final String name; + @java.lang.SuppressWarnings("all") + @lombok.Generated + CheckReturnValueBuilder(final int x, final String name) { + this.x = x; + this.name = name; + } + @java.lang.SuppressWarnings("all") + @lombok.Generated + public static class CheckReturnValueBuilderBuilder { + @java.lang.SuppressWarnings("all") + @lombok.Generated + private int x; + @java.lang.SuppressWarnings("all") + @lombok.Generated + private String name; + @java.lang.SuppressWarnings("all") + @lombok.Generated + CheckReturnValueBuilderBuilder() { + } + /** + * @return {@code this}. + */ + @java.lang.SuppressWarnings("all") + @lombok.Generated + public CheckReturnValueBuilder.CheckReturnValueBuilderBuilder x(final int x) { + this.x = x; + return this; + } + /** + * @return {@code this}. + */ + @java.lang.SuppressWarnings("all") + @lombok.Generated + public CheckReturnValueBuilder.CheckReturnValueBuilderBuilder name(final String name) { + this.name = name; + return this; + } + @lombok.CheckReturnValue + @java.lang.SuppressWarnings("all") + @lombok.Generated + public CheckReturnValueBuilder build() { + return new CheckReturnValueBuilder(this.x, this.name); + } + @java.lang.Override + @java.lang.SuppressWarnings("all") + @lombok.Generated + public java.lang.String toString() { + return "CheckReturnValueBuilder.CheckReturnValueBuilderBuilder(x=" + this.x + ", name=" + this.name + ")"; + } + } + @java.lang.SuppressWarnings("all") + @lombok.Generated + public static CheckReturnValueBuilder.CheckReturnValueBuilderBuilder builder() { + return new CheckReturnValueBuilder.CheckReturnValueBuilderBuilder(); + } +} diff --git a/test/transform/resource/after-delombok/CheckReturnValueOff.java b/test/transform/resource/after-delombok/CheckReturnValueOff.java new file mode 100644 index 00000000..ecffc92e --- /dev/null +++ b/test/transform/resource/after-delombok/CheckReturnValueOff.java @@ -0,0 +1,14 @@ +class CheckReturnValueOff { + final int x; + CheckReturnValueOff(int x) { + this.x = x; + } + /** + * @return a clone of this object, except with this updated property (returns {@code this} if an identical value is passed). + */ + @java.lang.SuppressWarnings("all") + @lombok.Generated + public CheckReturnValueOff withX(final int x) { + return this.x == x ? this : new CheckReturnValueOff(x); + } +} diff --git a/test/transform/resource/after-delombok/CheckReturnValueWith.java b/test/transform/resource/after-delombok/CheckReturnValueWith.java new file mode 100644 index 00000000..a679b4b2 --- /dev/null +++ b/test/transform/resource/after-delombok/CheckReturnValueWith.java @@ -0,0 +1,26 @@ +class CheckReturnValueWith { + final int x; + final String name; + CheckReturnValueWith(int x, String name) { + this.x = x; + this.name = name; + } + /** + * @return a clone of this object, except with this updated property (returns {@code this} if an identical value is passed). + */ + @lombok.CheckReturnValue + @java.lang.SuppressWarnings("all") + @lombok.Generated + public CheckReturnValueWith withX(final int x) { + return this.x == x ? this : new CheckReturnValueWith(x, this.name); + } + /** + * @return a clone of this object, except with this updated property (returns {@code this} if an identical value is passed). + */ + @lombok.CheckReturnValue + @java.lang.SuppressWarnings("all") + @lombok.Generated + public CheckReturnValueWith withName(final String name) { + return this.name == name ? this : new CheckReturnValueWith(this.x, name); + } +} diff --git a/test/transform/resource/after-ecj/CheckReturnValueBuilder.java b/test/transform/resource/after-ecj/CheckReturnValueBuilder.java new file mode 100644 index 00000000..d7da093d --- /dev/null +++ b/test/transform/resource/after-ecj/CheckReturnValueBuilder.java @@ -0,0 +1,39 @@ +@lombok.Builder class CheckReturnValueBuilder { + public static @java.lang.SuppressWarnings("all") @lombok.Generated class CheckReturnValueBuilderBuilder { + private @java.lang.SuppressWarnings("all") @lombok.Generated int x; + private @java.lang.SuppressWarnings("all") @lombok.Generated String name; + @java.lang.SuppressWarnings("all") @lombok.Generated CheckReturnValueBuilderBuilder() { + super(); + } + /** + * @return {@code this}. + */ + public @java.lang.SuppressWarnings("all") @lombok.Generated CheckReturnValueBuilder.CheckReturnValueBuilderBuilder x(final int x) { + this.x = x; + return this; + } + /** + * @return {@code this}. + */ + public @java.lang.SuppressWarnings("all") @lombok.Generated CheckReturnValueBuilder.CheckReturnValueBuilderBuilder name(final String name) { + this.name = name; + return this; + } + public @lombok.CheckReturnValue @java.lang.SuppressWarnings("all") @lombok.Generated CheckReturnValueBuilder build() { + return new CheckReturnValueBuilder(this.x, this.name); + } + public @java.lang.Override @java.lang.SuppressWarnings("all") @lombok.Generated java.lang.String toString() { + return (((("CheckReturnValueBuilder.CheckReturnValueBuilderBuilder(x=" + this.x) + ", name=") + this.name) + ")"); + } + } + private final int x; + private final String name; + @java.lang.SuppressWarnings("all") @lombok.Generated CheckReturnValueBuilder(final int x, final String name) { + super(); + this.x = x; + this.name = name; + } + public static @java.lang.SuppressWarnings("all") @lombok.Generated CheckReturnValueBuilder.CheckReturnValueBuilderBuilder builder() { + return new CheckReturnValueBuilder.CheckReturnValueBuilderBuilder(); + } +} diff --git a/test/transform/resource/after-ecj/CheckReturnValueOff.java b/test/transform/resource/after-ecj/CheckReturnValueOff.java new file mode 100644 index 00000000..b786cdbc --- /dev/null +++ b/test/transform/resource/after-ecj/CheckReturnValueOff.java @@ -0,0 +1,14 @@ +import lombok.With; +class CheckReturnValueOff { + final @With int x; + CheckReturnValueOff(int x) { + super(); + this.x = x; + } + /** + * @return a clone of this object, except with this updated property (returns {@code this} if an identical value is passed). + */ + public @java.lang.SuppressWarnings("all") @lombok.Generated CheckReturnValueOff withX(final int x) { + return ((this.x == x) ? this : new CheckReturnValueOff(x)); + } +} diff --git a/test/transform/resource/after-ecj/CheckReturnValueWith.java b/test/transform/resource/after-ecj/CheckReturnValueWith.java new file mode 100644 index 00000000..c798870a --- /dev/null +++ b/test/transform/resource/after-ecj/CheckReturnValueWith.java @@ -0,0 +1,22 @@ +import lombok.With; +class CheckReturnValueWith { + final @With int x; + final @With String name; + CheckReturnValueWith(int x, String name) { + super(); + this.x = x; + this.name = name; + } + /** + * @return a clone of this object, except with this updated property (returns {@code this} if an identical value is passed). + */ + public @lombok.CheckReturnValue @java.lang.SuppressWarnings("all") @lombok.Generated CheckReturnValueWith withX(final int x) { + return ((this.x == x) ? this : new CheckReturnValueWith(x, this.name)); + } + /** + * @return a clone of this object, except with this updated property (returns {@code this} if an identical value is passed). + */ + public @lombok.CheckReturnValue @java.lang.SuppressWarnings("all") @lombok.Generated CheckReturnValueWith withName(final String name) { + return ((this.name == name) ? this : new CheckReturnValueWith(this.x, name)); + } +} diff --git a/test/transform/resource/before/CheckReturnValueBuilder.java b/test/transform/resource/before/CheckReturnValueBuilder.java new file mode 100644 index 00000000..1c8cb7e2 --- /dev/null +++ b/test/transform/resource/before/CheckReturnValueBuilder.java @@ -0,0 +1,5 @@ +@lombok.Builder +class CheckReturnValueBuilder { + private final int x; + private final String name; +} diff --git a/test/transform/resource/before/CheckReturnValueOff.java b/test/transform/resource/before/CheckReturnValueOff.java new file mode 100644 index 00000000..3a4aebca --- /dev/null +++ b/test/transform/resource/before/CheckReturnValueOff.java @@ -0,0 +1,9 @@ +//CONF: lombok.addCheckReturnValueAnnotation = false +import lombok.With; +class CheckReturnValueOff { + @With final int x; + + CheckReturnValueOff(int x) { + this.x = x; + } +} diff --git a/test/transform/resource/before/CheckReturnValueWith.java b/test/transform/resource/before/CheckReturnValueWith.java new file mode 100644 index 00000000..187a96cb --- /dev/null +++ b/test/transform/resource/before/CheckReturnValueWith.java @@ -0,0 +1,10 @@ +import lombok.With; +class CheckReturnValueWith { + @With final int x; + @With final String name; + + CheckReturnValueWith(int x, String name) { + this.x = x; + this.name = name; + } +}