Use the Comments trait instead of hand-built comments (K5 of #1330) (#1355)

* Add `ThreadStopUnsupported` comment through the `Comments` trait

* Add `CommentJava24KotlinCap` comment through the `Comments` trait

`Placement.FIRST_CHILD` replaces the hand-built `Xml.Comment`. The
prefix-based `hasCapComment`/`removeCapComment` stay, as the trait only
matches exact comment text and removes comments preceding an element,
not a tag's own children.

* Leave a persisted `TODO` comment where `AddInputStreamBulkReadMethod` cannot delegate

The `SearchResult` marker for complex `read()` bodies is transient and
dropped from committed code, so the hint to add a bulk read method by
hand was lost. The `Comments` trait adds a real block comment instead,
on its own line above a class declaration and inline before an
anonymous `new InputStream() {...}`. An equivalent existing comment,
including a `// TODO` line comment, is left as is.

Author: timtebeek

src/main/java/org/openrewrite/java/migrate/CommentJava24KotlinCap.java

@@ -18,15 +18,15 @@
 import lombok.EqualsAndHashCode;
 import lombok.Value;
 import org.jspecify.annotations.Nullable;
+import org.openrewrite.Cursor;
 import org.openrewrite.ExecutionContext;
 import org.openrewrite.Recipe;
-import org.openrewrite.Tree;
 import org.openrewrite.TreeVisitor;
 import org.openrewrite.internal.ListUtils;
-import org.openrewrite.marker.Markers;
 import org.openrewrite.maven.MavenIsoVisitor;
 import org.openrewrite.maven.tree.ResolvedDependency;
 import org.openrewrite.semver.LatestRelease;
+import org.openrewrite.trait.Comments;
 import org.openrewrite.xml.tree.Content;
 import org.openrewrite.xml.tree.Xml;
 
@@ -73,7 +73,8 @@ public Xml.Tag visitTag(Xml.Tag tag, ExecutionContext ctx) {
                     String kotlinStdlibVersion = capsJavaAt24(t) ? findKotlinStdlibVersionBefore23() : null;
                     if (kotlinStdlibVersion != null) {
                         if (!hasCapComment(t)) {
-                            return addCommentAsFirstChild(t, comment(kotlinStdlibVersion));
+                            return Comments.of(new Cursor(getCursor().getParentOrThrow(), t))
+                                    .comment(comment(kotlinStdlibVersion), Comments.Placement.FIRST_CHILD);
                         }
                     } else if (hasCapComment(t)) {
                         return removeCapComment(t);
@@ -132,13 +133,6 @@ private boolean hasCapComment(Xml.Tag tag) {
                 return false;
             }
 
-            private Xml.Tag addCommentAsFirstChild(Xml.Tag tag, String text) {
-                List<Content> content = (List<Content>) tag.getContent();
-                String prefix = content == null || content.isEmpty() ? "" : content.get(0).getPrefix();
-                Xml.Comment comment = new Xml.Comment(Tree.randomId(), prefix, Markers.EMPTY, text);
-                return tag.withContent(ListUtils.concat(comment, content));
-            }
-
             @SuppressWarnings("unchecked")
             private Xml.Tag removeCapComment(Xml.Tag tag) {
                 return tag.withContent(ListUtils.filter((List<Content>) tag.getContent(), c ->

src/main/java/org/openrewrite/java/migrate/io/AddInputStreamBulkReadMethod.java

@@ -24,7 +24,7 @@
 import org.openrewrite.java.JavaTemplate;
 import org.openrewrite.java.search.DeclaresType;
 import org.openrewrite.java.tree.*;
-import org.openrewrite.marker.SearchResult;
+import org.openrewrite.trait.Comments;
 
 import java.util.Arrays;
 import java.util.HashSet;
@@ -37,7 +37,7 @@
 @EqualsAndHashCode(callSuper = false)
 public class AddInputStreamBulkReadMethod extends Recipe {
 
-    private static final String MARKER_MESSAGE = "Missing bulk read method may cause significant performance degradation";
+    private static final String TODO_COMMENT = " TODO: Missing bulk read method may cause significant performance degradation ";
     private static final String JAVA_IO_INPUT_STREAM = "java.io.InputStream";
 
     String displayName = "Add bulk read method to `InputStream` implementations";
@@ -46,7 +46,9 @@ public class AddInputStreamBulkReadMethod extends Recipe {
                 "`read()` method. Java's default `InputStream.read(byte[], int, int)` implementation calls the " +
                 "single-byte `read()` method in a loop, which can cause severe performance degradation (up to 350x " +
                 "slower) for bulk reads. This recipe detects `InputStream` implementations that delegate to another " +
-                "stream and adds the missing bulk read method to delegate bulk reads as well.";
+                "stream and adds the missing bulk read method to delegate bulk reads as well. Implementations whose " +
+                "`read()` body is too complex to delegate safely get a `TODO` comment instead, to implement the bulk " +
+                "read method by hand.";
 
     @Override
     public TreeVisitor<?, ExecutionContext> getVisitor() {
@@ -97,9 +99,10 @@ private <T extends J> T processInputStreamClass(T tree, J.Block body) {
                     return tree;
                 }
 
-                // No delegate found or complex body - add marker for manual implementation
+                // No delegate found or complex body - add a TODO comment for manual implementation
                 if (result.getDelegate() == null || result.isComplex()) {
-                    return SearchResult.found(tree, MARKER_MESSAGE);
+                    return Comments.of(new Cursor(getCursor().getParentOrThrow(), tree))
+                            .multilineComment(TODO_COMMENT, Comments.Placement.BEFORE, lineBreakBefore(tree));
                 }
 
                 // Simple delegation - add bulk read method right after the single-byte read method
@@ -116,6 +119,12 @@ private <T extends J> T processInputStreamClass(T tree, J.Block body) {
                 return tree;
             }
 
+            private @Nullable String lineBreakBefore(J tree) {
+                String whitespace = tree.getPrefix().getWhitespace();
+                int lastNewline = whitespace.lastIndexOf('\n');
+                return lastNewline < 0 ? null : whitespace.substring(lastNewline);
+            }
+
             private @Nullable AnalysisResult analyzeClass(List<Statement> statements) {
                 J.MethodDeclaration readMethod = null;
                 boolean hasBulkRead = false;

src/main/java/org/openrewrite/java/migrate/lang/ThreadStopUnsupported.java

@@ -16,6 +16,7 @@
 package org.openrewrite.java.migrate.lang;
 
 import lombok.Getter;
+import org.openrewrite.Cursor;
 import org.openrewrite.ExecutionContext;
 import org.openrewrite.Preconditions;
 import org.openrewrite.Recipe;
@@ -27,10 +28,7 @@
 import org.openrewrite.java.search.UsesMethod;
 import org.openrewrite.java.tree.J;
 import org.openrewrite.java.tree.JavaSourceFile;
-import org.openrewrite.java.tree.TextComment;
-import org.openrewrite.marker.Markers;
-
-import static java.util.Collections.singletonList;
+import org.openrewrite.trait.Comments;
 
 public class ThreadStopUnsupported extends Recipe {
     private static final MethodMatcher THREAD_STOP_MATCHER = new MethodMatcher("java.lang.Thread stop()");
@@ -78,7 +76,7 @@ private J getWithComment(J j, String methodName) {
                                 prefixWhitespace + " * For detailed migration instructions see the migration guide available at" +
                                 prefixWhitespace + " * https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/doc-files/threadPrimitiveDeprecation.html" +
                                 prefixWhitespace + " ";
-                return j.withComments(singletonList(new TextComment(true, commentText, prefixWhitespace, Markers.EMPTY)));
+                return Comments.of(new Cursor(getCursor().getParentOrThrow(), j)).multilineComment(commentText);
             }
         });
     }

src/main/resources/META-INF/rewrite/recipes.csv

@@ -228,7 +228,7 @@ maven,org.openrewrite.recipe:rewrite-migrate-java,org.openrewrite.java.migrate.g
 maven,org.openrewrite.recipe:rewrite-migrate-java,org.openrewrite.java.migrate.guava.PreferMathMultiplyExact,Prefer `Math#multiplyExact`,Prefer `java.lang.Math#multiplyExact` instead of using `com.google.common.math.IntMath#checkedMultiply`.,3,,Guava,Modernize,Java,,Recipes for migrating from [Google Guava](https://github.com/google/guava) to Java standard library.,Modernize your code to best use the project's current JDK version. Take advantage of newly available APIs and reduce the dependency of your code on third party dependencies where there is equivalent functionality in the Java standard library.,Basic building blocks for transforming Java code.,,
 maven,org.openrewrite.recipe:rewrite-migrate-java,org.openrewrite.java.migrate.guava.PreferMathSubtractExact,Prefer `Math#subtractExact`,Prefer `java.lang.Math#subtractExact` instead of using `com.google.common.math.IntMath#checkedSubtract`.,3,,Guava,Modernize,Java,,Recipes for migrating from [Google Guava](https://github.com/google/guava) to Java standard library.,Modernize your code to best use the project's current JDK version. Take advantage of newly available APIs and reduce the dependency of your code on third party dependencies where there is equivalent functionality in the Java standard library.,Basic building blocks for transforming Java code.,,
 maven,org.openrewrite.recipe:rewrite-migrate-java,org.openrewrite.java.migrate.guava.PreferShortCompare,Prefer `Short#compare`,Prefer `java.lang.Short#compare` instead of using `com.google.common.primitives.Shorts#compare`.,2,,Guava,Modernize,Java,,Recipes for migrating from [Google Guava](https://github.com/google/guava) to Java standard library.,Modernize your code to best use the project's current JDK version. Take advantage of newly available APIs and reduce the dependency of your code on third party dependencies where there is equivalent functionality in the Java standard library.,Basic building blocks for transforming Java code.,,
-maven,org.openrewrite.recipe:rewrite-migrate-java,org.openrewrite.java.migrate.io.AddInputStreamBulkReadMethod,Add bulk read method to `InputStream` implementations,"Adds a `read(byte[], int, int)` method to `InputStream` subclasses that only override the single-byte `read()` method. Java's default `InputStream.read(byte[], int, int)` implementation calls the single-byte `read()` method in a loop, which can cause severe performance degradation (up to 350x slower) for bulk reads. This recipe detects `InputStream` implementations that delegate to another stream and adds the missing bulk read method to delegate bulk reads as well.",1,,`java.io` APIs,Modernize,Java,,,Modernize your code to best use the project's current JDK version. Take advantage of newly available APIs and reduce the dependency of your code on third party dependencies where there is equivalent functionality in the Java standard library.,Basic building blocks for transforming Java code.,,
+maven,org.openrewrite.recipe:rewrite-migrate-java,org.openrewrite.java.migrate.io.AddInputStreamBulkReadMethod,Add bulk read method to `InputStream` implementations,"Adds a `read(byte[], int, int)` method to `InputStream` subclasses that only override the single-byte `read()` method. Java's default `InputStream.read(byte[], int, int)` implementation calls the single-byte `read()` method in a loop, which can cause severe performance degradation (up to 350x slower) for bulk reads. This recipe detects `InputStream` implementations that delegate to another stream and adds the missing bulk read method to delegate bulk reads as well. Implementations whose `read()` body is too complex to delegate safely get a `TODO` comment instead, to implement the bulk read method by hand.",1,,`java.io` APIs,Modernize,Java,,,Modernize your code to best use the project's current JDK version. Take advantage of newly available APIs and reduce the dependency of your code on third party dependencies where there is equivalent functionality in the Java standard library.,Basic building blocks for transforming Java code.,,
 maven,org.openrewrite.recipe:rewrite-migrate-java,org.openrewrite.java.migrate.io.ReplaceFileInOrOutputStreamFinalizeWithClose,Replace invocations of `finalize()` on `FileInputStream` and `FileOutputStream` with `close()`,Replace invocations of the deprecated `finalize()` method on `FileInputStream` and `FileOutputStream` with `close()`.,1,,`java.io` APIs,Modernize,Java,,,Modernize your code to best use the project's current JDK version. Take advantage of newly available APIs and reduce the dependency of your code on third party dependencies where there is equivalent functionality in the Java standard library.,Basic building blocks for transforming Java code.,,
 maven,org.openrewrite.recipe:rewrite-migrate-java,org.openrewrite.java.migrate.io.ReplaceSystemOutWithIOPrint,Migrate `System.out.print` to Java 25 IO utility class,"Replace `System.out.print()`, `System.out.println()` with `IO.print()` and `IO.println()`. Migrates to the new IO utility class introduced in Java 25.",1,,`java.io` APIs,Modernize,Java,,,Modernize your code to best use the project's current JDK version. Take advantage of newly available APIs and reduce the dependency of your code on third party dependencies where there is equivalent functionality in the Java standard library.,Basic building blocks for transforming Java code.,,
 maven,org.openrewrite.recipe:rewrite-migrate-java,org.openrewrite.java.migrate.jacoco.UpgradeJaCoCo,Upgrade JaCoCo,"This recipe will upgrade JaCoCo to the latest patch version, which traditionally advertises full backwards compatibility for older Java versions.",3,,JaCoCo,Modernize,Java,,,Modernize your code to best use the project's current JDK version. Take advantage of newly available APIs and reduce the dependency of your code on third party dependencies where there is equivalent functionality in the Java standard library.,Basic building blocks for transforming Java code.,,"[{""name"":""org.openrewrite.maven.table.MavenMetadataFailures"",""displayName"":""Maven metadata failures"",""instanceName"":""Maven metadata failures"",""description"":""Attempts to resolve maven metadata that failed."",""columns"":[{""name"":""group"",""type"":""String"",""displayName"":""Group id"",""description"":""The groupId of the artifact for which the metadata download failed.""},{""name"":""artifactId"",""type"":""String"",""displayName"":""Artifact id"",""description"":""The artifactId of the artifact for which the metadata download failed.""},{""name"":""version"",""type"":""String"",""displayName"":""Version"",""description"":""The version of the artifact for which the metadata download failed.""},{""name"":""mavenRepositoryUri"",""type"":""String"",""displayName"":""Maven repository"",""description"":""The URL of the Maven repository that the metadata download failed on.""},{""name"":""snapshots"",""type"":""String"",""displayName"":""Snapshots"",""description"":""Does the repository support snapshots.""},{""name"":""releases"",""type"":""String"",""displayName"":""Releases"",""description"":""Does the repository support releases.""},{""name"":""failure"",""type"":""String"",""displayName"":""Failure"",""description"":""The reason the metadata download failed.""}]}]"