refactor: adopt jspecify (#5384)

pom.xml

@@ -99,6 +99,11 @@
       <artifactId>commons-compress</artifactId>
       <version>1.23.0</version>
 	</dependency>
+    <dependency>
+      <groupId>org.jspecify</groupId>
+      <artifactId>jspecify</artifactId>
+      <version>0.3.0</version>
+    </dependency>
     <dependency>
       <!-- to reproduce JTD error with nullable annotation -->
       <groupId>com.google.guava</groupId>

qodana.yaml

@@ -11,7 +11,8 @@ include:
   - name: DoubleBraceInitialization
   - name: EqualsAndHashcode
   - name: JavaLangImport
-  - name: MissortedModifiers
+  # Disabled for annotations applied to type
+  #- name: MissortedModifiers
   - name: NestedAssignment
   - name: NonShortCircuitBoolean
   - name: RedundantFieldInitialization

src/main/java/spoon/OutputType.java

@@ -9,6 +9,8 @@
 
 import java.util.Locale;
 
+import org.jspecify.annotations.Nullable;
+
 /**
  * Types of output.
  */
@@ -42,7 +44,7 @@ public String toString() {
 	 *
 	 * @see Launcher#printUsage()
 	 */
-	public static OutputType fromString(String string) {
+	public static @Nullable OutputType fromString(String string) {
 		for (OutputType outputType : OutputType.values()) {
 			if (outputType.toString().equals(string)) {
 				return outputType;

src/main/java/spoon/compiler/Environment.java

@@ -27,6 +27,8 @@
 import java.nio.charset.Charset;
 import java.util.function.Supplier;
 
+import org.jspecify.annotations.Nullable;
+
 /**
  * This interface represents the environment in which Spoon is launched -
  * accessible through {@link spoon.reflect.factory.Factory#getEnvironment()}. Its
@@ -103,7 +105,7 @@ public interface Environment {
 	 * @param processorName fully qualified name of a processor
 	 * @return properties for the processor, or {@code null} if there is no processor by that name
 	 */
-	ProcessorProperties getProcessorProperties(String processorName);
+	@Nullable ProcessorProperties getProcessorProperties(String processorName);
 
 	/**
 	 * Sets the properties for a given processor.

src/main/java/spoon/metamodel/Metamodel.java

@@ -18,6 +18,9 @@
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
+
+import org.jspecify.annotations.Nullable;
+
 import spoon.Launcher;
 import spoon.SpoonException;
 import spoon.reflect.annotations.PropertyGetter;
@@ -346,7 +349,7 @@ private static String getConceptName(String simpleName) {
 	 * @param iface the interface of spoon model element
 	 * @return {@link CtClass} of Spoon model which implements the spoon model interface. null if there is no implementation.
 	 */
-	public static CtClass<?> getImplementationOfInterface(CtInterface<?> iface) {
+	public static @Nullable CtClass<?> getImplementationOfInterface(CtInterface<?> iface) {
 		String impl = replaceApiToImplPackage(iface.getQualifiedName()) + CLASS_SUFFIX;
 		return (CtClass<?>) getType(impl, iface);
 	}
@@ -355,7 +358,7 @@ public static CtClass<?> getImplementationOfInterface(CtInterface<?> iface) {
 	 * @param impl the implementation class of a Spoon element
 	 * @return {@link CtInterface} of Spoon model which represents API of the spoon model class. null if there is no implementation.
 	 */
-	public static CtInterface<?> getInterfaceOfImplementation(CtClass<?> impl) {
+	public static @Nullable CtInterface<?> getInterfaceOfImplementation(CtClass<?> impl) {
 		String iface = impl.getQualifiedName();
 		if (!iface.endsWith(CLASS_SUFFIX) || !iface.startsWith("spoon.support.reflect.")) {
 			throw new SpoonException("Unexpected spoon model implementation class: " + impl.getQualifiedName());

src/main/java/spoon/metamodel/MetamodelProperty.java

@@ -21,6 +21,8 @@
 import java.util.Map;
 import java.util.Set;
 
+import org.jspecify.annotations.Nullable;
+
 import spoon.SpoonException;
 import spoon.reflect.declaration.CtField;
 import spoon.reflect.declaration.CtMethod;
@@ -435,7 +437,7 @@ private enum MatchLevel {
 	 * @param realType
 	 * @return new expectedType or null if it is not matching
 	 */
-	private MatchLevel getMatchLevel(CtTypeReference<?> expectedType, CtTypeReference<?> realType) {
+	private @Nullable MatchLevel getMatchLevel(CtTypeReference<?> expectedType, CtTypeReference<?> realType) {
 		if (expectedType.equals(realType)) {
 			return MatchLevel.EQUALS;
 		}

src/main/java/spoon/pattern/internal/DefaultGenerator.java

@@ -34,6 +34,8 @@
 import java.util.List;
 import java.util.Map;
 
+import org.jspecify.annotations.Nullable;
+
 /**
  * Drives generation process
  */
@@ -55,7 +57,7 @@ public DefaultGenerator(Factory factory, ListOfNodes nodes) {
 	 *
 	 * @return a generate value or null
 	 */
-	public <T> T generateSingleTarget(RootNode node, ImmutableMap parameters, Class<T> expectedType) {
+	public <T> @Nullable T generateSingleTarget(RootNode node, ImmutableMap parameters, Class<T> expectedType) {
 		ResultHolder.Single<T> result = new ResultHolder.Single<>(expectedType);
 		generateTargets(node, result, parameters);
 		return result.getResult();

src/main/java/spoon/pattern/internal/matcher/TobeMatched.java

@@ -16,6 +16,9 @@
 import java.util.Objects;
 import java.util.Set;
 import java.util.function.BiFunction;
+
+import org.jspecify.annotations.Nullable;
+
 import spoon.SpoonException;
 import spoon.reflect.meta.ContainerKind;
 import spoon.support.util.ImmutableMap;
@@ -173,7 +176,7 @@ public TobeMatched copyAndSetParams(ImmutableMap newParams) {
 	 * @param matcher a matching algorithm
 	 * @return {@link TobeMatched} with List of remaining (to be matched) targets or null if there is no match
 	 */
-	public TobeMatched matchNext(BiFunction<Object, ImmutableMap, ImmutableMap> matcher) {
+	public @Nullable TobeMatched matchNext(BiFunction<Object, ImmutableMap, ImmutableMap> matcher) {
 		if (targets.isEmpty()) {
 			//no target -> no match
 			return null;
@@ -205,7 +208,7 @@ public TobeMatched matchNext(BiFunction<Object, ImmutableMap, ImmutableMap> matc
 	 * @param remainingMatch the {@link TobeMatched} whose parameters has to be returned
 	 * @return parameters from `remainingMatch`, if it exists. Else returns null
 	 */
-	public static ImmutableMap getMatchedParameters(TobeMatched remainingMatch) {
+	public static @Nullable ImmutableMap getMatchedParameters(TobeMatched remainingMatch) {
 		return remainingMatch == null ? null : remainingMatch.getParameters();
 	}
 	/**

src/main/java/spoon/pattern/internal/node/ElementNode.java

@@ -33,6 +33,8 @@
 import java.util.function.BiConsumer;
 import java.util.stream.Collectors;
 
+import org.jspecify.annotations.Nullable;
+
 import static spoon.pattern.internal.matcher.TobeMatched.getMatchedParameters;
 
 /**
@@ -225,7 +227,7 @@ public RootNode getOrCreateNodeOfRole(CtRole role, Map<CtElement, RootNode> patt
 	 * @param type required type of returned value
 	 * @return value of {@link ConstantNode} on the `role` attribute of this {@link ElementNode} or null if there is none or has different type
 	 */
-	public <T> T getValueOfRole(CtRole role, Class<T> type) {
+	public <T> @Nullable T getValueOfRole(CtRole role, Class<T> type) {
 		RootNode node = getNodeOfRole(role);
 		if (node instanceof ConstantNode) {
 //			FIX it delivers value of StringNode too ... generated by must be added into produced elements

src/main/java/spoon/pattern/internal/parameter/ParameterInfo.java

@@ -7,6 +7,8 @@
  */
 package spoon.pattern.internal.parameter;
 
+import org.jspecify.annotations.Nullable;
+
 import spoon.pattern.Pattern;
 import spoon.pattern.Quantifier;
 import spoon.pattern.internal.ResultHolder;
@@ -35,7 +37,7 @@ public interface ParameterInfo {
 	 * @param value the new, to be stored value
 	 * @return copy of `parameters` with new value or existing `parameters` if value is already there or null if value doesn't fit into these parameters
 	 */
-	ImmutableMap addValueAs(ImmutableMap parameters, Object value);
+	@Nullable ImmutableMap addValueAs(ImmutableMap parameters, Object value);
 
 	/**
 	 * Takes the value of parameter identified by this {@link ParameterInfo} from the `parameters`