Avoid duplicate Truth migration comments

[martinfrancois]

Suggested review order: 26 of 52 (Score: 5)
Review first: #1096

What's changed?

TruthAssertToAssertThat and TruthCustomSubjectsToAssertJ now add a normal block comment through the Comments trait. The trait recognizes an equivalent existing comment, so later recipe cycles leave the warning unchanged.

Each focused test runs its recipe for two cycles and requires exactly one changing cycle. This verifies both the first-run warning and idempotence without a recipe-specific comment parser.

What's your motivation?

Recipes: TruthAssertToAssertThat and TruthCustomSubjectsToAssertJ.

I confirmed the released behavior by running org.openrewrite.java.testing.truth.TruthAssertToAssertThat from rewrite-testing-frameworks:3.44.0 on Glide at 36a7b2ec. The affected file is library/test/src/test/java/com/bumptech/glide/tests/KeyTester.java.

After the first run, the recipe correctly flags the unsupported Truth assertion:

/*~~(Truth's assert_() requires manual review for migration to AssertJ)~~>*/assert_().withMessage(...).fail();

Before

assert_().fail();

Actual after the recipe

/*~~(Truth's assert_() requires manual review for migration to AssertJ)~~>*//*~~(Truth's assert_() requires manual review for migration to AssertJ)~~>*/assert_().fail();

Expected after the recipe

/* Truth's assert_() requires manual review for migration to AssertJ */assert_().fail();

The same defect affects TruthCustomSubjectsToAssertJ and its assertAbout(...) warning. Every later run adds another identical comment. A recipe run over its own persisted warning MUST leave that warning unchanged.

Confirmed real-world execution

• Project: Glide (35,025 stars on 2026-08-16).
• Location: KeyTester.java at 36a7b2ec.
• Recipe release: org.openrewrite.recipe:rewrite-testing-frameworks:3.44.0.

The first execution adds the manual-migration warning. The second execution adds the same warning again instead of leaving the persisted result unchanged.

Anything in particular you'd like reviewers to focus on?

Please review the use of the shared Comments trait and the decision to emit a normal block comment instead of a rendered search marker. An equivalent warning on the matching invocation MUST suppress another insertion; unrelated comments MUST NOT.

Have you considered any alternatives or workarounds?

Removing duplicate comments after every migration run hides the non-idempotent behavior and creates repeated cleanup work. A recipe-specific parser for rendered search-marker text also duplicates the shared comment service's equivalence behavior.

Any additional context

Pre-existing tests changed: None.

• Verified release: org.openrewrite.recipe:rewrite-testing-frameworks:3.44.0
• Fork branch: martinfrancois/rewrite-testing-frameworks:repro/truth-flagging-idempotence
• Focused tests: TruthAssertToAssertThatTest and TruthCustomSubjectsToAssertJTest; each contains one two-cycle test
• Verification: ./gradlew build

This change was prepared with AI assistance. I reviewed the real-project execution evidence, implementation, tests, generated output, and contribution text.

Checklist

• I've added unit tests to cover both positive and negative cases
• I've read and applied the recipe conventions and best practices
• I've run ./gradlew build locally, and committed any resulting changes to recipes.csv
• I've formatted the lines I changed, without reformatting code I didn't touch