Merge pull request #46 from diffblue/pcrane/feature/intestsusellm-experimental-annotation

Add an `@InTestsUseLLM` experimental annotation

Author: pcrane

README.md

@@ -24,7 +24,7 @@ For installation into a Maven project the `provided` scope is recommended so tha
     <dependency>
         <groupId>com.diffblue.cover</groupId>
         <artifactId>cover-annotations</artifactId>
-        <version>1.7.0</version>
+        <version>1.8.0</version>
         <scope>provided</scope>
     </dependency>
 </dependencies>
@@ -36,9 +36,9 @@ For installation into a Gradle project the `compileOnly` and `testImplementation
 
 ```
 dependencies {
-    compileOnly("com.diffblue.cover:cover-annotations:1.7.0")
+    compileOnly("com.diffblue.cover:cover-annotations:1.8.0")
 
-    testImplementation("com.diffblue.cover:cover-annotations:1.7.0")    
+    testImplementation("com.diffblue.cover:cover-annotations:1.8.0")    
 }
 ```
 
@@ -343,3 +343,17 @@ public class CarPainter {
 }
 ```
 
+### Experimental Annotations
+
+Experimental annotations should not be used in a production setting, but are
+included to allow Diffblue to perform experiments with new features.
+
+> [!NOTE]
+> The annotations in the `experimental` package can change at any time.
+>
+> Do not rely on them in production code!
+
+#### Using `@InTestsUseLLM`
+
+Indicates that LLMs can be used in this context.
+

pom.xml

@@ -16,7 +16,7 @@
   <modelVersion>4.0.0</modelVersion>
   <groupId>com.diffblue.cover</groupId>
   <artifactId>cover-annotations</artifactId>
-  <version>1.7.0</version>
+  <version>1.8.0</version>
   <packaging>jar</packaging>
 
   <name>Cover Annotations</name>

src/main/java/com/diffblue/cover/annotations/experimental/InTestsUseLLM.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2025 Diffblue Limited.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * or in the "license" file accompanying this file. This file 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 com.diffblue.cover.annotations.experimental;
+
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.ElementType.PACKAGE;
+import static java.lang.annotation.ElementType.PARAMETER;
+import static java.lang.annotation.ElementType.TYPE;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+/**
+ * Indicates the annotated element can request assistance from LLMs.
+ *
+ * <p>The specific assistance will depend on: the element, what features Diffblue Cover has
+ * implemented, and any number of other things.
+ *
+ * <p><em>Note:</em> this annotation may change in the future without further warning.
+ *
+ * @deprecated This annotation is experimental and may change or be removed in future releases. Its
+ *     use is discouraged except for internal experimental purposes.
+ */
+@Retention(RUNTIME)
+@Target({PACKAGE, TYPE, METHOD, PARAMETER})
+@Deprecated
+public @interface InTestsUseLLM {}