Find @Option annotations without example values

As came up in Slack: openrewrite/gh-automation#45 (comment)

rewrite-java-test/src/test/java/org/openrewrite/java/recipes/MissingOptionExampleTest.java

@@ -0,0 +1,103 @@
+/*
+ * Copyright 2024 the original author or authors.
+ * <p>
+ * Licensed 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
+ * <p>
+ * https://www.apache.org/licenses/LICENSE-2.0
+ * <p>
+ * 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.openrewrite.java.recipes;
+
+import org.junit.jupiter.api.Test;
+import org.openrewrite.DocumentExample;
+import org.openrewrite.java.JavaParser;
+import org.openrewrite.test.RecipeSpec;
+import org.openrewrite.test.RewriteTest;
+
+import static org.openrewrite.java.Assertions.java;
+
+class MissingOptionExampleTest implements RewriteTest {
+    @Override
+    public void defaults(RecipeSpec spec) {
+        spec.recipe(new MissingOptionExample())
+          .parser(JavaParser.fromJavaVersion().classpath(JavaParser.runtimeClasspath()));
+    }
+
+    @DocumentExample
+    @Test
+    void lacksExample() {
+        rewriteRun(
+          java(
+            """
+              import org.openrewrite.Option;
+              import org.openrewrite.Recipe;
+
+              class SomeRecipe extends Recipe {
+                  @Option(displayName = "Test", description = "Test")
+                  private boolean test = true;
+              
+                  @Override
+                  public String getDisplayName() {
+                      return "Find missing `@Option` `example` values";
+                  }
+                  @Override
+                  public String getDescription() {
+                      return "Find `@Option` annotations that are missing `example` values.";
+                  }
+              }
+              """,
+            """
+              import org.openrewrite.Option;
+              import org.openrewrite.Recipe;
+
+              class SomeRecipe extends Recipe {
+                  /*~~(Missing example value for documentation)~~>*/@Option(displayName = "Test", description = "Test")
+                  private boolean test = true;
+              
+                  @Override
+                  public String getDisplayName() {
+                      return "Find missing `@Option` `example` values";
+                  }
+                  @Override
+                  public String getDescription() {
+                      return "Find `@Option` annotations that are missing `example` values.";
+                  }
+              }
+              """
+          )
+        );
+    }
+
+    @Test
+    void hasExampleAlready() {
+        rewriteRun(
+          java(
+            """
+              import org.openrewrite.Option;
+              import org.openrewrite.Recipe;
+
+              class SomeRecipe extends Recipe {
+                  @Option(displayName = "Test", description = "Test", example = "true")
+                  private boolean test = true;
+              
+                  @Override
+                  public String getDisplayName() {
+                      return "Find missing `@Option` `example` values";
+                  }
+                  @Override
+                  public String getDescription() {
+                      return "Find `@Option` annotations that are missing `example` values.";
+                  }
+              }
+              """
+          )
+        );
+    }
+}

rewrite-java/src/main/java/org/openrewrite/java/recipes/MissingOptionExample.java

@@ -0,0 +1,63 @@
+/*
+ * Copyright 2024 the original author or authors.
+ * <p>
+ * Licensed 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
+ * <p>
+ * https://www.apache.org/licenses/LICENSE-2.0
+ * <p>
+ * 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.openrewrite.java.recipes;
+
+import org.openrewrite.ExecutionContext;
+import org.openrewrite.Preconditions;
+import org.openrewrite.Recipe;
+import org.openrewrite.TreeVisitor;
+import org.openrewrite.java.JavaIsoVisitor;
+import org.openrewrite.java.search.UsesType;
+import org.openrewrite.java.tree.Expression;
+import org.openrewrite.java.tree.J;
+import org.openrewrite.java.tree.TypeUtils;
+import org.openrewrite.marker.SearchResult;
+
+public class MissingOptionExample extends Recipe {
+    @Override
+    public String getDisplayName() {
+        return "Find missing `@Option` `example` values";
+    }
+
+    @Override
+    public String getDescription() {
+        return "Find `@Option` annotations that are missing `example` values for documentation.";
+    }
+
+    @Override
+    public TreeVisitor<?, ExecutionContext> getVisitor() {
+        return Preconditions.check(new UsesType<>("org.openrewrite.Option", false),
+                new JavaIsoVisitor<ExecutionContext>() {
+                    @Override
+                    public J.Annotation visitAnnotation(J.Annotation annotation, ExecutionContext executionContext) {
+                        J.Annotation an = super.visitAnnotation(annotation, executionContext);
+                        if (!TypeUtils.isOfClassType(annotation.getType(), "org.openrewrite.Option") || an.getArguments() == null) {
+                            return an;
+                        }
+                        boolean hasExample = an.getArguments().stream().anyMatch(exp -> {
+                            if (exp instanceof J.Assignment) {
+                                Expression variable = ((J.Assignment) exp).getVariable();
+                                if (variable instanceof J.Identifier) {
+                                    return "example".equals(((J.Identifier) variable).getSimpleName());
+                                }
+                            }
+                            return false;
+                        });
+                        return hasExample ? an : SearchResult.found(an, "Missing example value for documentation");
+                    }
+                });
+    }
+}