Ensure all packages declare package-info.java with null-safety annotations

sbrannen · sbrannen · commit 99e54fec3ac8 · 2023-03-10T17:33:52.000+01:00
This commit picks up where the two previous commits left off. Specifically, this commit: - Removes the "severity=warning" configuration to ensure that violations actually fail the build. - Fixes regular expressions for suppressions by matching forward slashes using `[\\/]` instead of `\/`. - Moves the configuration for newly introduced checks to locations in checkstyle.xml that align with the existing organization of that file. - Renames the IDs for RegexpSinglelineJava checks from javaDocPackageNonNullApiAnnotation/javaDocPackageNonNullFieldsAnnotation to packageLevelNonNullApiAnnotation/packageLevelNonNullFieldsAnnotation, respectively, since these checks are not related to Javadoc. - Simplifies the null-safety annotation checks to match against imported annotation types, which enforces consistency across package-info.java files for the annotation declarations. - Simplifies the RegEx for JavadocPackage suppressions to only exclude packages not under src/main/java (vs src/main) and those in the framework-docs module. - Consistently suppresses all checks for the `asm`, `cglib`, `objenesis`, and `javapoet` packages in spring-core. - Adds explicit suppressions for null-safety annotations for the `lang` package in spring-core. - Adds explicit suppressions for null-safety annotations for the `org.aopalliance` package in spring-aop. - Revises the RegEx for null-safety annotation suppressions to only exclude package-info.java files not under src/main/java and additionally to exclude package-info.java files in the framework-docs module as well as those in the spring-context-indexer, spring-instrument, and spring-jcl modules. - Adds all missing package-info.java files. - Adds null-safety annotations to package-info.java files where appropriate. Closes spring-projectsgh-30069
diff --git a/spring-aop/src/main/java/org/springframework/aop/target/dynamic/package-info.java b/spring-aop/src/main/java/org/springframework/aop/target/dynamic/package-info.java
@@ -0,0 +1,10 @@
+/**
+ * Support for dynamic, refreshable {@link org.springframework.aop.TargetSource}
+ * implementations for use with Spring AOP.
+ */
+@NonNullApi
+@NonNullFields
+package org.springframework.aop.target.dynamic;
+
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;
diff --git a/spring-aop/src/main/java/org/springframework/aop/target/package-info.java b/spring-aop/src/main/java/org/springframework/aop/target/package-info.java
@@ -0,0 +1,10 @@
+/**
+ * Various {@link org.springframework.aop.TargetSource} implementations for use
+ * with Spring AOP.
+ */
+@NonNullApi
+@NonNullFields
+package org.springframework.aop.target;
+
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;
diff --git a/spring-aspects/src/main/java/org/springframework/beans/factory/aspectj/package-info.java b/spring-aspects/src/main/java/org/springframework/beans/factory/aspectj/package-info.java
@@ -0,0 +1,9 @@
+/**
+ * AspectJ-based dependency injection support.
+ */
+@NonNullApi
+@NonNullFields
+package org.springframework.beans.factory.aspectj;
+
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;
diff --git a/spring-aspects/src/main/java/org/springframework/cache/aspectj/package-info.java b/spring-aspects/src/main/java/org/springframework/cache/aspectj/package-info.java
@@ -0,0 +1,9 @@
+/**
+ * AspectJ-based caching support.
+ */
+@NonNullApi
+@NonNullFields
+package org.springframework.cache.aspectj;
+
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;
diff --git a/spring-aspects/src/main/java/org/springframework/context/annotation/aspectj/package-info.java b/spring-aspects/src/main/java/org/springframework/context/annotation/aspectj/package-info.java
@@ -0,0 +1,11 @@
+/**
+ * AspectJ-based dependency injection support driven by the
+ * {@link org.springframework.beans.factory.annotation.Configurable @Configurable}
+ * annotation.
+ */
+@NonNullApi
+@NonNullFields
+package org.springframework.context.annotation.aspectj;
+
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;
diff --git a/spring-aspects/src/main/java/org/springframework/scheduling/aspectj/package-info.java b/spring-aspects/src/main/java/org/springframework/scheduling/aspectj/package-info.java
@@ -0,0 +1,9 @@
+/**
+ * AspectJ-based scheduling support.
+ */
+@NonNullApi
+@NonNullFields
+package org.springframework.scheduling.aspectj;
+
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;
diff --git a/spring-aspects/src/main/java/org/springframework/transaction/aspectj/package-info.java b/spring-aspects/src/main/java/org/springframework/transaction/aspectj/package-info.java
@@ -0,0 +1,9 @@
+/**
+ * AspectJ-based transaction management support.
+ */
+@NonNullApi
+@NonNullFields
+package org.springframework.transaction.aspectj;
+
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;
diff --git a/spring-beans/src/main/java/org/springframework/beans/factory/groovy/package-info.java b/spring-beans/src/main/java/org/springframework/beans/factory/groovy/package-info.java
@@ -1,4 +1,9 @@
 /**
  * Support package for Groovy-based bean definitions.
  */
+@NonNullApi
+@NonNullFields
 package org.springframework.beans.factory.groovy;
+
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;
diff --git a/spring-context-indexer/src/main/java/org/springframework/context/index/processor/package-info.java b/spring-context-indexer/src/main/java/org/springframework/context/index/processor/package-info.java
@@ -0,0 +1,4 @@
+/**
+ * Core package for Spring Framework's scanned component index.
+ */
+package org.springframework.context.index.processor;
diff --git a/spring-instrument/src/main/java/org/springframework/instrument/package-info.java b/spring-instrument/src/main/java/org/springframework/instrument/package-info.java
@@ -0,0 +1,4 @@
+/**
+ * Core package for byte code instrumentation.
+ */
+package org.springframework.instrument;
diff --git a/spring-jdbc/src/main/java/org/springframework/jdbc/support/incrementer/package-info.java b/spring-jdbc/src/main/java/org/springframework/jdbc/support/incrementer/package-info.java
@@ -4,4 +4,9 @@
  *
  * <p>Can be used independently, for example in custom JDBC access code.
  */
+@NonNullApi
+@NonNullFields
 package org.springframework.jdbc.support.incrementer;
+
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;
diff --git a/spring-r2dbc/src/main/java/org/springframework/r2dbc/connection/init/package-info.java b/spring-r2dbc/src/main/java/org/springframework/r2dbc/connection/init/package-info.java
@@ -1,6 +1,9 @@
 /**
  * Provides extensible support for initializing databases through scripts.
  */
-@org.springframework.lang.NonNullApi
-@org.springframework.lang.NonNullFields
+@NonNullApi
+@NonNullFields
 package org.springframework.r2dbc.connection.init;
+
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;
diff --git a/spring-r2dbc/src/main/java/org/springframework/r2dbc/core/package-info.java b/spring-r2dbc/src/main/java/org/springframework/r2dbc/core/package-info.java
@@ -1,6 +1,9 @@
 /**
  * Core domain types around DatabaseClient.
  */
-@org.springframework.lang.NonNullApi
-@org.springframework.lang.NonNullFields
+@NonNullApi
+@NonNullFields
 package org.springframework.r2dbc.core;
+
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;
diff --git a/spring-test/src/main/java/org/springframework/test/context/event/annotation/package-info.java b/spring-test/src/main/java/org/springframework/test/context/event/annotation/package-info.java
@@ -1,4 +1,9 @@
 /**
  * Test execution event annotations for the <em>Spring TestContext Framework</em>.
  */
+@NonNullApi
+@NonNullFields
 package org.springframework.test.context.event.annotation;
+
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;
diff --git a/spring-test/src/main/java/org/springframework/test/context/event/package-info.java b/spring-test/src/main/java/org/springframework/test/context/event/package-info.java
@@ -1,4 +1,9 @@
 /**
  * Test event support classes for the <em>Spring TestContext Framework</em>.
  */
+@NonNullApi
+@NonNullFields
 package org.springframework.test.context.event;
+
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;
diff --git a/spring-test/src/main/java/org/springframework/test/package-info.java b/spring-test/src/main/java/org/springframework/test/package-info.java
diff --git a/spring-test/src/main/java/org/springframework/test/web/package-info.java b/spring-test/src/main/java/org/springframework/test/web/package-info.java
@@ -1,4 +1,9 @@
 /**
  * Helper classes for unit tests based on Spring's web support.
  */
+@NonNullApi
+@NonNullFields
 package org.springframework.test.web;
+
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;
diff --git a/spring-web/src/main/java/org/springframework/http/codec/cbor/package-info.java b/spring-web/src/main/java/org/springframework/http/codec/cbor/package-info.java
@@ -0,0 +1,9 @@
+/**
+ * CBOR encoder and decoder support.
+ */
+@NonNullApi
+@NonNullFields
+package org.springframework.http.codec.cbor;
+
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;
diff --git a/spring-web/src/main/java/org/springframework/web/context/request/async/package-info.java b/spring-web/src/main/java/org/springframework/web/context/request/async/package-info.java
@@ -1,4 +1,9 @@
 /**
  * Support for asynchronous request processing.
  */
+@NonNullApi
+@NonNullFields
 package org.springframework.web.context.request.async;
+
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;
diff --git a/spring-webflux/src/main/java/org/springframework/web/reactive/result/condition/package-info.java b/spring-webflux/src/main/java/org/springframework/web/reactive/result/condition/package-info.java
@@ -2,4 +2,9 @@
  * {@link org.springframework.web.reactive.result.condition.RequestCondition}
  * and implementations for matching requests based on different criteria.
  */
+@NonNullApi
+@NonNullFields
 package org.springframework.web.reactive.result.condition;
+
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;
diff --git a/src/checkstyle/checkstyle-suppressions.xml b/src/checkstyle/checkstyle-suppressions.xml
@@ -2,12 +2,18 @@
 <!DOCTYPE suppressions PUBLIC "-//Checkstyle//DTD SuppressionFilter Configuration 1.2//EN" "https://checkstyle.org/dtds/suppressions_1_2.dtd">
 <suppressions>
 
-	<!-- global -->
+	<!-- Global: generated sources -->
+	<suppress files="[\\/]build[\\/]generated[\\/]sources[\\/]" checks=".*"/>
+
+	<!-- Global: package-info.java -->
+	<suppress files="(^(?!.+[\\/]src[\\/]main[\\/]java[\\/]).*)|(.*framework-docs.*)" checks="JavadocPackage" />
+	<suppress files="(^(?!.+[\\/]src[\\/]main[\\/]java[\\/].*package-info\.java))|(.*framework-docs.*)|(.*spring-(context-indexer|instrument|jcl).*)" checks="RegexpSinglelineJava" id="packageLevelNonNullApiAnnotation" />
+	<suppress files="(^(?!.+[\\/]src[\\/]main[\\/]java[\\/].*package-info\.java))|(.*framework-docs.*)|(.*spring-(context-indexer|instrument|jcl).*)" checks="RegexpSinglelineJava" id="packageLevelNonNullFieldsAnnotation" />
+
+	<!-- Global: tests and test fixtures -->
 	<suppress files="[\\/]src[\\/](test|testFixtures)[\\/]java[\\/]" checks="AnnotationLocation|AnnotationUseStyle|AtclauseOrder|AvoidNestedBlocks|FinalClass|HideUtilityClassConstructor|InnerTypeLast|JavadocStyle|JavadocType|JavadocVariable|LeftCurly|MultipleVariableDeclarations|NeedBraces|OneTopLevelClass|OuterTypeFilename|RequireThis|SpringCatch|SpringJavadoc|SpringNoThis"/>
 	<suppress files="[\\/]src[\\/](test|testFixtures)[\\/]java[\\/]org[\\/]springframework[\\/].+(Tests|Suite)" checks="IllegalImport" id="bannedJUnitJupiterImports"/>
 	<suppress files="[\\/]src[\\/](test|testFixtures)[\\/]java[\\/]" checks="SpringJUnit5" message="should not be public"/>
-	<!-- generated sources -->
-	<suppress files="[\\/]build[\\/]generated[\\/]sources[\\/]" checks=".*"/>
 
 	<!-- JMH benchmarks -->
 	<suppress files="[\\/]src[\\/]jmh[\\/]java[\\/]org[\\/]springframework[\\/]" checks="JavadocVariable|JavadocStyle|InnerTypeLast"/>
@@ -17,6 +23,8 @@
 
 	<!-- spring-aop -->
 	<suppress files="[\\/]src[\\/]main[\\/]java[\\/]org[\\/]aopalliance[\\/]" checks="IllegalImport" id="bannedImports" message="javax"/>
+	<suppress files="[\\/]src[\\/]main[\\/]java[\\/]org[\\/]aopalliance[\\/]" checks="RegexpSinglelineJava" id="packageLevelNonNullApiAnnotation"/>
+	<suppress files="[\\/]src[\\/]main[\\/]java[\\/]org[\\/]aopalliance[\\/]" checks="RegexpSinglelineJava" id="packageLevelNonNullFieldsAnnotation"/>
 
 	<!-- spring-beans -->
 	<suppress files="TypeMismatchException" checks="MutableException"/>
@@ -31,9 +39,10 @@
 	<suppress files="SpringAtInjectTckTests" checks="IllegalImportCheck" id="bannedJUnit3Imports"/>
 
 	<!-- spring-core -->
-	<suppress files="[\\/]src[\\/]main[\\/]java[\\/]org[\\/]springframework[\\/]asm[\\/]" checks=".*"/>
-	<suppress files="[\\/]src[\\/]main[\\/]java[\\/]org[\\/]springframework[\\/]cglib[\\/]" checks=".*"/>
+	<suppress files="[\\/]src[\\/]main[\\/]java[\\/]org[\\/]springframework[\\/](asm|cglib|objenesis|javapoet)[\\/]" checks=".*"/>
 	<suppress files="[\\/]src[\\/]main[\\/]java[\\/]org[\\/]springframework[\\/]lang[\\/]" checks="IllegalImport" id="bannedImports" message="javax"/>
+	<suppress files="[\\/]src[\\/]main[\\/]java[\\/]org[\\/]springframework[\\/]lang[\\/]" checks="RegexpSinglelineJava" id="packageLevelNonNullApiAnnotation" />
+	<suppress files="[\\/]src[\\/]main[\\/]java[\\/]org[\\/]springframework[\\/]lang[\\/]" checks="RegexpSinglelineJava" id="packageLevelNonNullFieldsAnnotation" />
 	<suppress files="[\\/]src[\\/]main[\\/]java[\\/]org[\\/]springframework[\\/]core[\\/]annotation[\\/]" checks="IllegalImport" id="bannedImports" message="javax"/>
 	<suppress files="[\\/]src[\\/]test[\\/]java[\\/]org[\\/]springframework[\\/]core[\\/]annotation[\\/]" checks="IllegalImport" id="bannedImports" message="javax"/>
 	<suppress files="ByteArrayEncoder" checks="SpringLambda"/>
@@ -130,15 +139,4 @@
 	<suppress files="sockjs[\\/]transport[\\/]TransportType" checks="JavadocVariable"/>
 	<suppress files="src[\\/]test[\\/]java[\\/]org[\\/]springframework[\\/]web[\\/]reactive[\\/]protobuf[\\/].*" checks=".*"/>
 
-	<!-- Suppress JavadocPackage checks and package null safety annotations on packages outside of src/main-->
-	<!-- And outside 'framework-docs' module-->
-	<!-- And outside 'spring-core/src/main/java/org/springframework/asm' package-->
-	<!-- And outside 'spring-core/src/main/java/org/springframework/cglib' package-->
-	<!-- And outside 'spring-core/src/main/java/org/springframework/objenesis' package-->
-	<!-- And outside 'spring-core/src/main/java/org/springframework/javapoet' package-->
-	<!-- And outside 'spring-core/src/main/java/org/springframework/lang' package-->
-	<suppress checks="JavadocPackage" files="(^(?!.*src[\\/]main[\\/]).*)|(.*framework-docs.*)|(.*spring-core\/src\/main\/java\/org\/springframework\/asm.*)|(.*spring-core\/src\/main\/java\/org\/springframework\/cglib.*)|(.*spring-core\/src\/main\/java\/org\/springframework\/objenesis.*)|(.*spring-core\/src\/main\/java\/org\/springframework\/javapoet.*)|(.*spring-core\/src\/main\/java\/org\/springframework\/lang.*)"/>
-	<suppress checks="RegexpSinglelineJava" files="^(?!.*(package-info.java))" id="javaDocPackageNonNullFieldsAnnotation"/>
-	<suppress checks="RegexpSinglelineJava" files="^(?!.*(package-info.java))" id="javaDocPackageNonNullApiAnnotation"/>
-
 </suppressions>
diff --git a/src/checkstyle/checkstyle.xml b/src/checkstyle/checkstyle.xml
@@ -1,6 +1,7 @@
 <?xml version="1.0"?>
 <!DOCTYPE module PUBLIC "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN" "https://checkstyle.org/dtds/configuration_1_3.dtd">
 <module name="com.puppycrawl.tools.checkstyle.Checker">
+
 	<!-- Suppressions -->
 	<module name="SuppressionFilter">
 		<property name="file" value="${config_loc}/checkstyle-suppressions.xml"/>
@@ -14,9 +15,29 @@
 		<property name="packageInfoHeaderType" value="none"/>
 	</module>
 	<module name="com.puppycrawl.tools.checkstyle.checks.NewlineAtEndOfFileCheck"/>
+	<module name="JavadocPackage" /><!-- package-info.java -->
 
 	<!-- TreeWalker Checks -->
 	<module name="com.puppycrawl.tools.checkstyle.TreeWalker">
+
+		<!-- Package-level null-safety annotations -->
+		<module name="RegexpSinglelineJavaCheck">
+			<property name="id" value="packageLevelNonNullApiAnnotation"/>
+			<property name="format" value="@NonNullApi"/>
+			<property name="minimum" value="1"/>
+			<property  name="maximum" value="1"/>
+			<property name="message" value="package-info.java is missing required null-safety annotation @NonNullApi."/>
+			<property name="ignoreComments" value="true"/>
+		</module>
+		<module name="RegexpSinglelineJavaCheck">
+			<property name="id" value="packageLevelNonNullFieldsAnnotation"/>
+			<property name="format" value="@NonNullFields"/>
+			<property name="minimum" value="1"/>
+			<property  name="maximum" value="1"/>
+			<property name="message" value="package-info.java is missing required null-safety annotation @NonNullFields."/>
+			<property name="ignoreComments" value="true"/>
+		</module>
+
 		<!-- Annotations -->
 		<module name="com.puppycrawl.tools.checkstyle.checks.annotation.AnnotationUseStyleCheck">
 			<property name="elementStyle" value="compact"/>
@@ -239,30 +260,7 @@
 		<module name="io.spring.javaformat.checkstyle.check.SpringCatchCheck"/>
 		<module name="io.spring.javaformat.checkstyle.check.SpringJavadocCheck"/>
 		<module name="io.spring.javaformat.checkstyle.check.SpringJUnit5Check"/>
-		<!--package-info should contain null-safety annotations-->
-		<!--These two modules will fail to detect multiline annotations-->
-		<module name="RegexpSinglelineJavaCheck">
-			<property name="id" value="javaDocPackageNonNullFieldsAnnotation"/>
-			<property name="format" value="(@NonNullFields|@org\.springframework\.lang\.NonNullFields)"/>
-			<property name="minimum" value="1"/>
-			<property  name="maximum" value="1"/>
-			<property name="severity" value="warning"/>
-			<property name="message" value="package-info.java is missing required null-safety annotation @NonNullFields."/>
-			<property name="ignoreComments" value="true"/>
-		</module>
-		<module name="RegexpSinglelineJavaCheck">
-			<property name="id" value="javaDocPackageNonNullApiAnnotation"/>
-			<property name="format" value="(@NonNullApi|@org\.springframework\.lang\.NonNullApi)"/>
-			<property name="minimum" value="1"/>
-			<property  name="maximum" value="1"/>
-			<property name="severity" value="warning"/>
-			<property name="message" value="package-info.java is missing required null-safety annotation @NonNullApi."/>
-			<property name="ignoreComments" value="true"/>
-		</module>
- 	</module>
 
-	<!--package-info checker -->
-	<module name="JavadocPackage">
-		<property name="severity" value="warning"/>
 	</module>
+
 </module>

-Original file line number
+Diff line change
@@ @@ -0,0 +1,4 @@ @@
 +/**
 + * Core package for Spring Framework's scanned component index.
 + */
 +package org.springframework.context.index.processor;