Move new rule collection

This is a squash commit of the following previous commits:

---

Introduce `documentation-support` module to extract website data from source code

By adding a compilation `TaskListener` that extracts data from the Bug pattern
and Refaster rule collection (test) classes and writing to JSON output files
in the target directory. This extraction happens as part of the Maven build
using the `docgen` profile.

---

Improve website styling

Co-authored-by: japborst <japborst@gmail.com>
Co-authored-by: Gijs de Jong <berichtaangijs@gmail.com>

---

Generate Markdown files from existing content for the website

---

Upgrade dependencies to the latest versions

---

Compile and install project jars before docgen

---

Run validation in build and exclude self-url

---

Reintroduce `htmlproofer`, improve templates, cleanup setup and dependencies

---

Delete directory if it exists

---

Add SCSS for GitHub button and fix bug pattern sample rendering

---

Fix bug pattern GitHub link

---

Small styling tweaks (incl. for dark theme)

---

Use single mvn command

---

Move mustache templates

---

Hardcode anchors for headings

---

Add supression to bugpatterns

---

Remove self ignore for html-proofer

---

Add refaster supressions and use callouts

---

Use v0.4.1-SNAPSHOT

---

Revert "Use single mvn command"

This reverts commit 594471d1ed23a1c19d7fe88d925d1b7f828716cd.

---

Extract Refaster samples from source code instead of AST

---

Skip verification, for now

---

Add notes on disabling bugpatterns

---

Set default layout and image

---

Fix mobile navigation

---

Revert "Set default layout and image"

This reverts commit 67a4aa7b5b4d14c0f2b783f345f53affe6ef3ec5.

---

Add supression for refaster rules

---

Post-rebase fixes

---

Fix the tests

---

Doh

---

Version bump

---

Exclude ThirdPartyLibraryTest from Bug Pattern test output

---

Remove only last occurence of 'Test' in Bug Pattern tests doc generation

---

Move `MapRulesTest` resources

---

Add exclusion for docgen of `SourceCodeTest`

---

Bump version

---

Extra fixes after rebase

---

Delete custom nav footer and `assets/images/favicon.ico`

---

Post rebase fixes with version bump to `0.8.1-SNAPSHOT`

---

Use new BugPatternTest extraction method

.github/ISSUE_TEMPLATE/bug_report.md

@@ -42,9 +42,9 @@ Please replace this sentence with log output, if applicable.
 <!-- Please complete the following information: -->
 
 - Operating system (e.g. MacOS Monterey).
-- Java version (i.e. `java --version`, e.g. `17.0.3`).
-- Error Prone version (e.g. `2.15.0`).
-- Error Prone Support version (e.g. `0.3.0`).
+- Java version (i.e. `java --version`, e.g. `17.0.6`).
+- Error Prone version (e.g. `2.18.0`).
+- Error Prone Support version (e.g. `0.8.0`).
 
 ### Additional context
 

.github/ISSUE_TEMPLATE/feature_request.md

@@ -17,23 +17,24 @@ you'd like to be solved through Error Prone Support. -->
 
 - [ ] Support a stylistic preference.
 - [ ] Avoid a common gotcha, or potential problem.
+- [ ] Improve performance.
 
 <!--
 Here, provide a clear and concise description of the desired change.
 
 If possible, provide a simple and minimal example using the following format:
-
-  I would like to rewrite the following code:
-  ```java
-  // XXX: Write the code to match here.
-  ```
-
-  to:
-  ```java
-  // XXX: Write the desired code here.
-  ```
 -->
 
+I would like to rewrite the following code:
+```java
+// XXX: Write the code to match here.
+```
+
+to:
+```java
+// XXX: Write the desired code here.
+```
+
 ### Considerations
 
 <!--

.github/release.yml

@@ -3,7 +3,7 @@ changelog:
     labels:
       - "ignore-changelog"
   categories:
-    - title: ":rocket: New Error Prone checks and Refaster templates"
+    - title: ":rocket: New Error Prone checks and Refaster rules"
       labels:
         - "new feature"
     - title: ":sparkles: Improvements"

.github/workflows/build.yaml

@@ -2,15 +2,32 @@ name: Build and verify
 on:
   pull_request:
   push:
-    branches: [$default-branch]
+    branches: [ master ]
 permissions:
   contents: read
 jobs:
   build:
-    runs-on: ubuntu-22.04
     strategy:
       matrix:
-        jdk: [ 11.0.16, 17.0.4 ]
+        os: [ ubuntu-22.04 ]
+        jdk: [ 11.0.18, 17.0.6, 19.0.2 ]
+        distribution: [ temurin ]
+        experimental: [ false ]
+        include:
+          - os: macos-12
+            jdk: 17.0.6
+            distribution: temurin
+            experimental: false
+          - os: windows-2022
+            jdk: 17.0.6
+            distribution: temurin
+            experimental: false
+          - os: ubuntu-22.04
+            jdk: 20-ea
+            distribution: zulu
+            experimental: true
+    runs-on: ${{ matrix.os }}
+    continue-on-error: ${{ matrix.experimental }}
     steps:
         # We run the build twice for each supported JDK: once against the
         # original Error Prone release, using only Error Prone checks available
@@ -18,12 +35,12 @@ jobs:
         # additionally enabling all checks defined in this project and any
         # Error Prone checks available only from other artifact repositories.
       - name: Check out code
-        uses: actions/checkout@v3.0.2
+        uses: actions/checkout@v3.1.0
       - name: Set up JDK
-        uses: actions/setup-java@v3.5.1
+        uses: actions/setup-java@v3.8.0
         with:
           java-version: ${{ matrix.jdk }}
-          distribution: temurin
+          distribution: ${{ matrix.distribution }}
           cache: maven
       - name: Display build environment details
         run: mvn --version

.github/workflows/deploy-website.yaml

@@ -2,39 +2,48 @@ name: Update `error-prone.picnic.tech` website content
 on:
   pull_request:
   push:
-    branches: [$default-branch]
-permissions:
-  contents: read
-  id-token: write
-  pages: write
+    branches: [ master, website ]
 concurrency:
-  group: pages
-  cancel-in-progress: true
+  group: ${{ github.workflow }}-${{ github.ref }}
 jobs:
   build:
+    permissions:
+      contents: read
     runs-on: ubuntu-22.04
     steps:
       - name: Check out code
-        uses: actions/checkout@v3.0.2
+        uses: actions/checkout@v3.1.0
+      - uses: ruby/setup-ruby@v1.126.0
+        with:
+          working-directory: ./website
+          bundler-cache: true
       - name: Configure Github Pages
-        uses: actions/configure-pages@v2.1.1
+        uses: actions/configure-pages@v2.1.3
+      - name: Set up JDK
+        uses: actions/setup-java@v3.5.1
+        with:
+          java-version: 17.0.4
+          distribution: temurin
+          cache: maven
+      - name: Compile project and extract data
+        # XXX: Remove `-Dverification.{skip|warn}` and update `website/README.md`
+        # once module `docgen` has no errors.
+        run: |
+          mvn -T1C clean install -DskipTests -Dverification.warn
+          mvn -T1C clean install -DskipTests -Dverification.skip -Pdocgen
       - name: Generate documentation
-        run: ./generate-docs.sh
-      - name: Build website with Jekyll
-        uses: actions/jekyll-build-pages@v1.0.5
-        with:
-          source: website/
-          destination: ./_site
-      - name: Validate HTML output
-        uses: anishathalye/proof-html@v1.4.1
-        with:
-          directory: ./_site
-          check_external_hash: false
+        working-directory: ./website
+        run: bundle exec ruby generate-docs.rb
       - name: Upload website as artifact
-        uses: actions/upload-pages-artifact@v1.0.4
+        uses: actions/upload-pages-artifact@v1.0.5
+        with:
+          path: ./website/_site
   deploy:
-    if: github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
+    if: github.ref == 'refs/heads/website'
     needs: build
+    permissions:
+      id-token: write
+      pages: write
     runs-on: ubuntu-22.04
     environment:
       name: github-pages
@@ -42,4 +51,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v1.2.1
+        uses: actions/deploy-pages@v1.2.3

.github/workflows/pitest-analyze-pr.yml

@@ -0,0 +1,37 @@
+# Performs mutation testing analysis on the files changed by a pull request and
+# uploads the results. The associated PR is subsequently updated by the
+# `pitest-update-pr.yml` workflow. See https://blog.pitest.org/oss-pitest-pr/
+# for details.
+name: "Mutation testing"
+on:
+  pull_request:
+permissions:
+  contents: read
+jobs:
+  analyze-pr:
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v3.1.0
+        with:
+          fetch-depth: 2
+      - name: Set up JDK
+        uses: actions/setup-java@v3.8.0
+        with:
+          java-version: 17.0.6
+          distribution: temurin
+          cache: maven
+      - name: Run Pitest
+        # By running with features `+GIT(from[HEAD~1]), +gitci`, Pitest only
+        # analyzes lines changed in the associated pull request, as GitHub
+        # exposes the changes unique to the PR as a single commit on top of the
+        # target branch. See https://blog.pitest.org/pitest-pr-setup for
+        # details.
+        run: mvn test pitest:mutationCoverage -DargLine.xmx=2048m -Dverification.skip -Dfeatures="+GIT(from[HEAD~1]), +gitci"
+      - name: Aggregate Pitest reports
+        run: mvn pitest-git:aggregate -DkilledEmoji=":tada:" -DmutantEmoji=":zombie:" -DtrailingText="Mutation testing report by [Pitest](https://pitest.org/). Review any surviving mutants by inspecting the line comments under [_Files changed_](${{ github.event.number }}/files)."
+      - name: Upload Pitest reports as artifact
+        uses: actions/upload-artifact@v3.1.1
+        with:
+          name: pitest-reports
+          path: ./target/pit-reports-ci

.github/workflows/pitest-update-pr.yml

@@ -0,0 +1,35 @@
+# Updates a pull request based on the corresponding mutation testing analysis
+# performed by the `pitest-analyze-pr.yml` workflow. See
+# https://blog.pitest.org/oss-pitest-pr/ for details.
+name: "Mutation testing: post results"
+on:
+  workflow_run:
+    workflows: ["Mutation testing"]
+    types:
+      - completed
+permissions:
+  actions: read
+  checks: write
+  contents: read
+  pull-requests: write
+jobs:
+  update-pr:
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v3.1.0
+      - name: Set up JDK
+        uses: actions/setup-java@v3.8.0
+        with:
+          java-version: 17.0.6
+          distribution: temurin
+          cache: maven
+      - name: Download Pitest analysis artifact
+        uses: dawidd6/action-download-artifact@v2.24.2
+        with:
+          workflow: ${{ github.event.workflow_run.workflow_id }}
+          name: pitest-reports
+          path: ./target/pit-reports-ci
+      - name: Update PR
+        run: mvn -DrepoToken="${{ secrets.GITHUB_TOKEN }}" pitest-github:updatePR

.mvn/maven.config

@@ -1 +1,3 @@
---batch-mode --errors --strict-checksums
+--batch-mode
+--errors
+--strict-checksums

.renovaterc.json

@@ -10,7 +10,7 @@
     },
     {
       "matchPackagePatterns": [
-        "^com\\.palantir\\.baseline:baseline-error-prone$"
+        "^ruby\\/setup-ruby$"
       ],
       "schedule": "* * 1 * *"
     }

LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2017-2022 Picnic Technologies BV
+Copyright (c) 2017-2023 Picnic Technologies BV
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -15,7 +15,12 @@ focussing on maintainability, consistency and avoidance of common pitfalls.
 > Error Prone is a static analysis tool for Java that catches common
 > programming mistakes at compile-time.
 
+Read more on how Picnic uses Error Prone (Support) in the blog post [_Picnic
+loves Error Prone: producing high-quality and consistent Java
+code_][picnic-blog-ep-post].
+
 [![Maven Central][maven-central-badge]][maven-central-search]
+[![Reproducible Builds][reproducible-builds-badge]][reproducible-builds-report]
 [![GitHub Actions][github-actions-build-badge]][github-actions-build-master]
 [![License][license-badge]][license]
 [![PRs Welcome][pr-badge]][contributing]
@@ -31,7 +36,9 @@ focussing on maintainability, consistency and avoidance of common pitfalls.
 ### Installation
 
 This library is built on top of [Error Prone][error-prone-orig-repo]. To use
-it:
+it, read the installation guide for Maven or Gradle below.
+
+#### Maven
 
 1. First, follow Error Prone's [installation
    guide][error-prone-installation-guide].
@@ -59,7 +66,7 @@ it:
                                <artifactId>error-prone-contrib</artifactId>
                                <version>${error-prone-support.version}</version>
                            </path>
-                           <!-- Error Prone Support's Refaster templates. -->
+                           <!-- Error Prone Support's Refaster rules. -->
                            <path>
                                <groupId>tech.picnic.error-prone-support</groupId>
                                <artifactId>refaster-runner</artifactId>
@@ -89,6 +96,31 @@ it:
 Prone Support. Alternatively reference this project's `self-check` profile
 definition. -->
 
+#### Gradle
+
+1. First, follow the [installation guide]
+   [error-prone-gradle-installation-guide] of the `gradle-errorprone-plugin`.
+2. Next, edit your `build.gradle` file to add one or more Error Prone Support
+   modules:
+
+   ```groovy
+   dependencies {
+       // Error Prone itself.
+       errorprone("com.google.errorprone:error_prone_core:${errorProneVersion}")
+       // Error Prone Support's additional bug checkers.
+       errorprone("tech.picnic.error-prone-support:error-prone-contrib:${errorProneSupportVersion}")
+       // Error Prone Support's Refaster rules.
+       errorprone("tech.picnic.error-prone-support:refaster-runner:${errorProneSupportVersion}")
+   }
+
+   tasks.withType(JavaCompile).configureEach {
+       options.errorprone.disableWarningsInGeneratedCode = true
+       // Add other Error Prone flags here. See:
+       // - https://github.com/tbroyer/gradle-errorprone-plugin#configuration
+       // - https://errorprone.info/docs/flags
+   }
+   ```
+
 ### Seeing it in action
 
 Consider the following example code:
@@ -115,16 +147,13 @@ code with Maven should yield two compiler warnings:
 ```sh
 $ mvn clean install
 ...
-[INFO] -------------------------------------------------------------
-[WARNING] COMPILATION WARNING :
-[INFO] -------------------------------------------------------------
-[WARNING] Example.java:[9,34] [tech.picnic.errorprone.refastertemplates.BigDecimalTemplates.BigDecimalZero]
+[INFO] Example.java:[9,34] [Refaster Rule] BigDecimalRules.BigDecimalZero: Refactoring opportunity
+    (see https://error-prone.picnic.tech/refasterrules/BigDecimalRules#BigDecimalZero)
   Did you mean 'return BigDecimal.ZERO;'?
+...
 [WARNING] Example.java:[13,35] [IdentityConversion] This method invocation appears redundant; remove it or suppress this warning and add a comment explaining its purpose
     (see https://error-prone.picnic.tech/bugpatterns/IdentityConversion)
   Did you mean 'return set;' or '@SuppressWarnings("IdentityConversion") public ImmutableSet<Integer> getSet() {'?
-[INFO] 2 warnings
-[INFO] -------------------------------------------------------------
 ...
 ```
 
@@ -132,12 +161,12 @@ Two things are kicking in here:
 
 1. An Error Prone [`BugChecker`][error-prone-bugchecker] that flags unnecessary
    [identity conversions][bug-checks-identity-conversion].
-2. A [Refaster][refaster] template capable of
-   [rewriting][refaster-templates-bigdecimal] expressions of the form
+2. A [Refaster][refaster] rule capable of
+   [rewriting][refaster-rules-bigdecimal] expressions of the form
    `BigDecimal.valueOf(0)` and `new BigDecimal(0)` to `BigDecimal.ZERO`.
 
 Be sure to check out all [bug checks][bug-checks] and [refaster
-templates][refaster-templates].
+rules][refaster-rules].
 
 ## 👷 Developing Error Prone Support
 
@@ -164,7 +193,7 @@ Some other commands one may find relevant:
 
 - `mvn fmt:format` formats the code using
   [`google-java-format`][google-java-format].
-- `./run-mutation-tests.sh` runs mutation tests using [PIT][pitest]. The
+- `./run-mutation-tests.sh` runs mutation tests using [Pitest][pitest]. The
   results can be reviewed by opening the respective
   `target/pit-reports/index.html` files. For more information check the [PIT
   Maven plugin][pitest-maven].
@@ -205,6 +234,7 @@ guidelines][contributing].
 [error-prone-bugchecker]: https://github.com/google/error-prone/blob/master/check_api/src/main/java/com/google/errorprone/bugpatterns/BugChecker.java
 [error-prone-fork-jitpack]: https://jitpack.io/#PicnicSupermarket/error-prone
 [error-prone-fork-repo]: https://github.com/PicnicSupermarket/error-prone
+[error-prone-gradle-installation-guide]: https://github.com/tbroyer/gradle-errorprone-plugin
 [error-prone-installation-guide]: https://errorprone.info/docs/installation#maven
 [error-prone-orig-repo]: https://github.com/google/error-prone
 [error-prone-pull-3301]: https://github.com/google/error-prone/pull/3301
@@ -218,9 +248,12 @@ guidelines][contributing].
 [maven-central-search]: https://search.maven.org/artifact/tech.picnic.error-prone-support/error-prone-support
 [maven]: https://maven.apache.org
 [picnic-blog]: https://blog.picnic.nl
+[picnic-blog-ep-post]: https://blog.picnic.nl/picnic-loves-error-prone-producing-high-quality-and-consistent-java-code-b8a566be6886
 [pitest]: https://pitest.org
 [pitest-maven]: https://pitest.org/quickstart/maven
 [pr-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg
 [refaster]: https://errorprone.info/docs/refaster
-[refaster-templates-bigdecimal]: https://github.com/PicnicSupermarket/error-prone-support/blob/master/error-prone-contrib/src/main/java/tech/picnic/errorprone/refastertemplates/BigDecimalTemplates.java
-[refaster-templates]: https://github.com/PicnicSupermarket/error-prone-support/blob/master/error-prone-contrib/src/main/java/tech/picnic/errorprone/refastertemplates/
+[refaster-rules-bigdecimal]: https://github.com/PicnicSupermarket/error-prone-support/blob/master/error-prone-contrib/src/main/java/tech/picnic/errorprone/refasterrules/BigDecimalRules.java
+[refaster-rules]: https://github.com/PicnicSupermarket/error-prone-support/blob/master/error-prone-contrib/src/main/java/tech/picnic/errorprone/refasterrules/
+[reproducible-builds-badge]: https://img.shields.io/badge/Reproducible_Builds-ok-success?labelColor=1e5b96
+[reproducible-builds-report]: https://github.com/jvm-repo-rebuild/reproducible-central/blob/master/content/tech/picnic/error-prone-support/error-prone-support/README.md

apply-error-prone-suggestions.sh

@@ -9,13 +9,14 @@
 set -e -u -o pipefail
 
 if [ "${#}" -gt 1 ]; then
-  echo "Usage: ./$(basename "${0}") [PatchChecks]"
+  echo "Usage: ${0} [PatchChecks]"
   exit 1
 fi
 
 patchChecks=${1:-}
 
 mvn clean test-compile fmt:format \
+  -s "$(dirname "${0}")/settings.xml" \
   -T 1.0C \
   -Perror-prone \
   -Perror-prone-fork \

cdg-pitest-licence.txt

@@ -0,0 +1,7 @@
+# Arcmutate license for Error Prone Support, requested by sending an email to
+# support@arcmutate.com.
+expires=07/11/2023
+keyVersion=1
+signature=MhZxMbnO6UovNfllM0JuVWkZyvRT3/G5o/uT0Mm36c7200VpZNVu03gTAGivnl9W5RzvZhfpIHccuQ5ctjQkrqhsFSrl4fyqPqu3y5V2fsHIdFXP/G72EGj6Kay9ndLpaEHalqE0bEwxdnHMzEYq5y3O9vUPv8MhUl57xk+rvBo\=
+packages=tech.picnic.errorprone.*
+type=OSSS

docgen/pom.xml

@@ -1,53 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
-    <modelVersion>4.0.0</modelVersion>
-
-    <parent>
-        <groupId>tech.picnic.error-prone-support</groupId>
-        <artifactId>error-prone-support</artifactId>
-        <version>0.3.1-SNAPSHOT</version>
-    </parent>
-
-    <artifactId>docgen</artifactId>
-
-    <name>Picnic :: Error Prone Support :: Docgen</name>
-    <description>Docgen.</description>
-
-    <dependencies>
-        <dependency>
-            <groupId>${groupId.error-prone}</groupId>
-            <artifactId>error_prone_annotations</artifactId>
-            <scope>provided</scope>
-        </dependency>
-        <dependency>
-            <groupId>${groupId.error-prone}</groupId>
-            <artifactId>error_prone_check_api</artifactId>
-        </dependency>
-        <dependency>
-            <groupId>${groupId.error-prone}</groupId>
-            <artifactId>error_prone_core</artifactId>
-        </dependency>
-        <dependency>
-            <groupId>com.fasterxml.jackson.core</groupId>
-            <artifactId>jackson-databind</artifactId>
-        </dependency>
-        <dependency>
-            <groupId>com.google.auto.service</groupId>
-            <artifactId>auto-service-annotations</artifactId>
-            <scope>provided</scope>
-        </dependency>
-        <dependency>
-            <groupId>com.google.auto.value</groupId>
-            <artifactId>auto-value-annotations</artifactId>
-        </dependency>
-        <dependency>
-            <groupId>com.google.code.findbugs</groupId>
-            <artifactId>jsr305</artifactId>
-            <scope>provided</scope>
-        </dependency>
-        <dependency>
-            <groupId>com.google.guava</groupId>
-            <artifactId>guava</artifactId>
-        </dependency>
-    </dependencies>
-</project>

docgen/src/main/java/tech/picnic/errorprone/plugin/BugPatternExtractor.java

@@ -1,15 +0,0 @@
-package tech.picnic.errorprone.plugin;
-
-import com.google.errorprone.BugPattern;
-import com.google.errorprone.VisitorState;
-import com.sun.source.tree.ClassTree;
-import com.sun.source.util.TaskEvent;
-import tech.picnic.errorprone.plugin.objects.BugPatternData;
-
-public final class BugPatternExtractor implements DocExtractor<BugPatternData> {
-  @Override
-  public BugPatternData extractData(ClassTree tree, TaskEvent taskEvent, VisitorState state) {
-    BugPattern annotation = taskEvent.getTypeElement().getAnnotation(BugPattern.class);
-    return BugPatternData.create(annotation, taskEvent.getTypeElement().getSimpleName().toString());
-  }
-}

docgen/src/main/java/tech/picnic/errorprone/plugin/BugPatternTestsExtractor.java

@@ -1,113 +0,0 @@
-package tech.picnic.errorprone.plugin;
-
-import static com.google.errorprone.matchers.Matchers.allOf;
-import static com.google.errorprone.matchers.Matchers.anyOf;
-import static com.google.errorprone.matchers.Matchers.hasAnnotation;
-import static com.google.errorprone.matchers.Matchers.instanceMethod;
-import static com.google.errorprone.matchers.Matchers.methodIsNamed;
-
-import com.google.errorprone.VisitorState;
-import com.google.errorprone.matchers.Matcher;
-import com.google.errorprone.util.ASTHelpers;
-import com.sun.source.tree.ClassTree;
-import com.sun.source.tree.ExpressionTree;
-import com.sun.source.tree.MethodInvocationTree;
-import com.sun.source.tree.MethodTree;
-import com.sun.source.util.TaskEvent;
-import com.sun.source.util.TreeScanner;
-import java.util.List;
-import javax.annotation.Nullable;
-import tech.picnic.errorprone.plugin.objects.BugPatternTestData;
-
-public final class BugPatternTestsExtractor implements DocExtractor<BugPatternTestData> {
-  private static final Matcher<MethodTree> BUG_PATTERN_TEST =
-      allOf(
-          hasAnnotation("org.junit.jupiter.api.Test"),
-          anyOf(methodIsNamed("replacement"), methodIsNamed("identification")));
-  private static final Matcher<ExpressionTree> IDENTIFICATION_SOURCE_LINES =
-      instanceMethod()
-          .onDescendantOf("com.google.errorprone.CompilationTestHelper")
-          .named("addSourceLines");
-  private static final Matcher<ExpressionTree> REPLACEMENT_INPUT =
-      instanceMethod()
-          .onDescendantOf("com.google.errorprone.BugCheckerRefactoringTestHelper")
-          .named("addInputLines");
-  private static final Matcher<ExpressionTree> REPLACEMENT_OUTPUT =
-      instanceMethod()
-          .onDescendantOf("com.google.errorprone.BugCheckerRefactoringTestHelper.ExpectOutput")
-          .named("addOutputLines");
-
-  @Override
-  public BugPatternTestData extractData(ClassTree tree, TaskEvent taskEvent, VisitorState state) {
-    String name = tree.getSimpleName().toString().replace("Test", "");
-    ScanBugCheckerTestData scanner = new ScanBugCheckerTestData(state);
-
-    tree.getMembers().stream()
-        .filter(MethodTree.class::isInstance)
-        .map(MethodTree.class::cast)
-        .filter(m -> BUG_PATTERN_TEST.matches(m, state))
-        .forEach(m -> scanner.scan(m, null));
-
-    return BugPatternTestData.create(
-        name, scanner.getIdentification(), scanner.getInput(), scanner.getOutput());
-  }
-
-  private static final class ScanBugCheckerTestData extends TreeScanner<Void, Void> {
-    private final VisitorState state;
-
-    private String identification;
-    private String input;
-    private String output;
-
-    ScanBugCheckerTestData(VisitorState state) {
-      this.state = state;
-    }
-
-    public String getIdentification() {
-      return identification;
-    }
-
-    public String getInput() {
-      return input;
-    }
-
-    public String getOutput() {
-      return output;
-    }
-
-    @Nullable
-    @Override
-    public Void visitMethodInvocation(MethodInvocationTree node, Void unused) {
-      if (IDENTIFICATION_SOURCE_LINES.matches(node, state)) {
-        identification = getSourceLines(node);
-      } else if (REPLACEMENT_INPUT.matches(node, state)) {
-        input = getSourceLines(node);
-      } else if (REPLACEMENT_OUTPUT.matches(node, state)) {
-        output = getSourceLines(node);
-      }
-      return super.visitMethodInvocation(node, unused);
-    }
-
-    private String getSourceLines(MethodInvocationTree tree) {
-      List<? extends ExpressionTree> sourceLines =
-          tree.getArguments().subList(1, tree.getArguments().size());
-
-      return getConstantSourceCode(sourceLines);
-    }
-
-    private String getConstantSourceCode(List<? extends ExpressionTree> sourceLines) {
-      StringBuilder source = new StringBuilder();
-
-      for (ExpressionTree sourceLine : sourceLines) {
-        Object value = ASTHelpers.constValue(sourceLine);
-        if (value == null) {
-          return "";
-        }
-
-        source.append(value).append('\n');
-      }
-
-      return source.toString();
-    }
-  }
-}

docgen/src/main/java/tech/picnic/errorprone/plugin/DocExtractor.java

@@ -1,9 +0,0 @@
-package tech.picnic.errorprone.plugin;
-
-import com.google.errorprone.VisitorState;
-import com.sun.source.tree.ClassTree;
-import com.sun.source.util.TaskEvent;
-
-public interface DocExtractor<T> {
-  T extractData(ClassTree tree, TaskEvent taskEvent, VisitorState state);
-}

docgen/src/main/java/tech/picnic/errorprone/plugin/Docgen.java

@@ -1,25 +0,0 @@
-package tech.picnic.errorprone.plugin;
-
-import com.google.auto.service.AutoService;
-import com.sun.source.util.JavacTask;
-import com.sun.source.util.Plugin;
-import com.sun.tools.javac.api.BasicJavacTask;
-
-/**
- * A variant of {@code com.google.errorprone.refaster.RefasterRuleCompiler} that outputs a {@code
- * fully/qualified/Class.refaster} file for each compiled {@code fully.qualified.Class} that
- * contains a Refaster template.
- */
-@AutoService(Plugin.class)
-public final class Docgen implements Plugin {
-  @Override
-  public String getName() {
-    return getClass().getSimpleName();
-  }
-
-  @Override
-  public void init(JavacTask javacTask, String... args) {
-    javacTask.addTaskListener(
-        new DocgenTaskListener(((BasicJavacTask) javacTask).getContext(), args[0]));
-  }
-}

docgen/src/main/java/tech/picnic/errorprone/plugin/DocgenPart.java

@@ -1,24 +0,0 @@
-package tech.picnic.errorprone.plugin;
-
-public enum DocgenPart {
-  BUGPATTERN("bug-pattern-test-data.jsonl", new BugPatternExtractor()),
-  BUGPATTERN_TEST("bug-pattern-data.jsonl", new BugPatternTestsExtractor()),
-  REFASTER_TEMPLATE_TEST_INPUT("refaster-test-input-data.jsonl", new RefasterTestExtractor()),
-  REFASTER_TEMPLATE_TEST_OUTPUT("refaster-test-output-data.jsonl", new RefasterTestExtractor());
-
-  private final String dataFileName;
-  private final DocExtractor<?> extractor;
-
-  DocgenPart(String dataFileName, DocExtractor<?> extractor) {
-    this.dataFileName = dataFileName;
-    this.extractor = extractor;
-  }
-
-  public DocExtractor<?> getExtractor() {
-    return extractor;
-  }
-
-  public String getDataFileName() {
-    return dataFileName;
-  }
-}

docgen/src/main/java/tech/picnic/errorprone/plugin/DocgenTaskListener.java

@@ -1,95 +0,0 @@
-package tech.picnic.errorprone.plugin;
-
-import com.fasterxml.jackson.core.JsonGenerator;
-import com.fasterxml.jackson.databind.ObjectMapper;
-import com.fasterxml.jackson.databind.SerializationFeature;
-import com.google.errorprone.BugPattern;
-import com.google.errorprone.VisitorState;
-import com.google.errorprone.util.ASTHelpers;
-import com.sun.source.tree.ClassTree;
-import com.sun.source.tree.VariableTree;
-import com.sun.source.util.TaskEvent;
-import com.sun.source.util.TaskListener;
-import com.sun.tools.javac.api.JavacTrees;
-import com.sun.tools.javac.util.Context;
-import java.io.File;
-import java.io.FileWriter;
-import java.io.IOException;
-import java.util.Optional;
-import javax.tools.JavaFileObject;
-
-/** XXX: Write this. */
-final class DocgenTaskListener implements TaskListener {
-  private final Context context;
-
-  private final String basePath;
-
-  private final VisitorState state;
-
-  private final ObjectMapper mapper =
-      new ObjectMapper()
-          .configure(SerializationFeature.FAIL_ON_EMPTY_BEANS, false)
-          .configure(JsonGenerator.Feature.AUTO_CLOSE_TARGET, false);
-
-  DocgenTaskListener(Context context, String path) {
-    this.context = context;
-    this.basePath = path.substring(path.indexOf('=') + 1);
-    this.state = VisitorState.createForUtilityPurposes(context);
-  }
-
-  @Override
-  @SuppressWarnings("SystemOut")
-  public void finished(TaskEvent taskEvent) {
-    ClassTree tree = JavacTrees.instance(context).getTree(taskEvent.getTypeElement());
-    if (tree == null || taskEvent.getSourceFile() == null) {
-      return;
-    }
-
-    getDocgenPart(tree, taskEvent)
-        .ifPresent(
-            docgenPart ->
-                writeToFile(
-                    docgenPart.getExtractor().extractData(tree, taskEvent, state),
-                    docgenPart.getDataFileName()));
-  }
-
-  private static Optional<DocgenPart> getDocgenPart(ClassTree tree, TaskEvent taskEvent) {
-    JavaFileObject sourceFile = taskEvent.getSourceFile();
-
-    if (isBugPatternTest(tree)) {
-      return Optional.of(DocgenPart.BUGPATTERN_TEST);
-    } else if (isBugPattern(tree)) {
-      return Optional.of(DocgenPart.BUGPATTERN);
-    } else if (sourceFile.getName().contains("TestInput")) {
-      return Optional.of(DocgenPart.REFASTER_TEMPLATE_TEST_INPUT);
-    } else if (sourceFile.getName().contains("TestOutput")) {
-      return Optional.of(DocgenPart.REFASTER_TEMPLATE_TEST_OUTPUT);
-    } else {
-      return Optional.empty();
-    }
-  }
-
-  private <T> void writeToFile(T data, String fileName) {
-    File file = new File(basePath + "/" + fileName);
-
-    try (FileWriter fileWriter = new FileWriter(file, true)) {
-      mapper.writeValue(fileWriter, data);
-      fileWriter.write("\n");
-    } catch (IOException e) {
-      e.printStackTrace();
-    }
-  }
-
-  private static boolean isBugPattern(ClassTree tree) {
-    return ASTHelpers.hasDirectAnnotationWithSimpleName(tree, BugPattern.class.getSimpleName());
-  }
-
-  private static boolean isBugPatternTest(ClassTree tree) {
-    return tree.getSimpleName().toString().endsWith("Test")
-        && tree.getMembers().stream()
-            .filter(VariableTree.class::isInstance)
-            .map(VariableTree.class::cast)
-            .anyMatch(
-                member -> member.getType().toString().equals("BugCheckerRefactoringTestHelper"));
-  }
-}

docgen/src/main/java/tech/picnic/errorprone/plugin/RefasterTestExtractor.java

@@ -1,32 +0,0 @@
-package tech.picnic.errorprone.plugin;
-
-import static com.google.common.collect.ImmutableList.toImmutableList;
-
-import com.google.common.collect.ImmutableList;
-import com.google.errorprone.VisitorState;
-import com.sun.source.tree.ClassTree;
-import com.sun.source.tree.MethodTree;
-import com.sun.source.util.TaskEvent;
-import tech.picnic.errorprone.plugin.objects.RefasterTemplateTestData;
-
-public class RefasterTestExtractor
-    implements DocExtractor<ImmutableList<RefasterTemplateTestData>> {
-  @Override
-  public ImmutableList<RefasterTemplateTestData> extractData(
-      ClassTree tree, TaskEvent taskEvent, VisitorState state) {
-
-    String templateCollectionName = tree.getSimpleName().toString().replace("Test", "");
-
-    return tree.getMembers().stream()
-        .filter(MethodTree.class::isInstance)
-        .map(MethodTree.class::cast)
-        .filter(m -> m.getName().toString().startsWith("test"))
-        .map(
-            m ->
-                RefasterTemplateTestData.create(
-                    templateCollectionName,
-                    m.getName().toString().replace("test", ""),
-                    m.toString()))
-        .collect(toImmutableList());
-  }
-}

docgen/src/main/java/tech/picnic/errorprone/plugin/objects/BugPatternData.java

@@ -1,56 +0,0 @@
-package tech.picnic.errorprone.plugin.objects;
-
-import com.fasterxml.jackson.annotation.JsonProperty;
-import com.google.auto.value.AutoValue;
-import com.google.errorprone.BugPattern;
-import com.google.errorprone.BugPattern.LinkType;
-import com.google.errorprone.BugPattern.SeverityLevel;
-import java.util.Arrays;
-
-@AutoValue
-public abstract class BugPatternData {
-  public static BugPatternData create(BugPattern annotation, String name) {
-    return new AutoValue_BugPatternData(
-        name,
-        Arrays.toString(annotation.altNames()),
-        annotation.linkType(),
-        annotation.link(),
-        Arrays.toString(annotation.tags()),
-        annotation.summary(),
-        annotation.explanation(),
-        annotation.severity(),
-        annotation.disableable());
-  }
-
-  @JsonProperty
-  abstract String name();
-
-  // Should be String[]
-  @JsonProperty
-  abstract String altNames();
-
-  @JsonProperty
-  abstract LinkType linkType();
-
-  @JsonProperty
-  abstract String link();
-
-  @JsonProperty
-  // Should be String[]
-  abstract String tags();
-
-  @JsonProperty
-  abstract String summary();
-
-  @JsonProperty
-  abstract String explanation();
-
-  @JsonProperty
-  abstract SeverityLevel severityLevel();
-
-  @JsonProperty
-  abstract boolean disableable();
-
-  // SuppressionAnnotations?
-  // DocumentSuppression?
-}

docgen/src/main/java/tech/picnic/errorprone/plugin/objects/BugPatternTestData.java

@@ -1,28 +0,0 @@
-package tech.picnic.errorprone.plugin.objects;
-
-import com.fasterxml.jackson.annotation.JsonProperty;
-import com.google.auto.value.AutoValue;
-import javax.annotation.Nullable;
-
-@AutoValue
-public abstract class BugPatternTestData {
-  public static BugPatternTestData create(
-      String name, String identificationLines, String inputLines, String outputLines) {
-    return new AutoValue_BugPatternTestData(name, identificationLines, inputLines, outputLines);
-  }
-
-  @JsonProperty
-  abstract String name();
-
-  @Nullable
-  @JsonProperty
-  abstract String identificationLines();
-
-  @Nullable
-  @JsonProperty
-  abstract String inputLines();
-
-  @Nullable
-  @JsonProperty
-  abstract String outputLines();
-}

docgen/src/main/java/tech/picnic/errorprone/plugin/objects/RefasterTemplateTestData.java

@@ -1,22 +0,0 @@
-package tech.picnic.errorprone.plugin.objects;
-
-import com.fasterxml.jackson.annotation.JsonProperty;
-import com.google.auto.value.AutoValue;
-
-@AutoValue
-public abstract class RefasterTemplateTestData {
-  public static RefasterTemplateTestData create(
-      String templateCollection, String templateName, String templateTestContent) {
-    return new AutoValue_RefasterTemplateTestData(
-        templateCollection, templateName, templateTestContent);
-  }
-
-  @JsonProperty
-  abstract String templateCollection();
-
-  @JsonProperty
-  abstract String templateName();
-
-  @JsonProperty
-  abstract String templateTestContent();
-}

docgen/src/main/java/tech/picnic/errorprone/plugin/package-info.java

@@ -1,4 +0,0 @@
-/** A Java compiler plugin that XXX: fill in. */
-@com.google.errorprone.annotations.CheckReturnValue
-@javax.annotation.ParametersAreNonnullByDefault
-package tech.picnic.errorprone.plugin;

documentation-support/pom.xml

@@ -0,0 +1,91 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>tech.picnic.error-prone-support</groupId>
+        <artifactId>error-prone-support</artifactId>
+        <version>0.9.1-SNAPSHOT</version>
+    </parent>
+
+    <artifactId>documentation-support</artifactId>
+
+    <name>Picnic :: Error Prone Support :: Documentation Support</name>
+    <description>Data extraction support for the purpose of documentation generation.</description>
+
+    <dependencies>
+        <dependency>
+            <groupId>${groupId.error-prone}</groupId>
+            <artifactId>error_prone_annotation</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>${groupId.error-prone}</groupId>
+            <artifactId>error_prone_annotations</artifactId>
+            <scope>provided</scope>
+        </dependency>
+        <dependency>
+            <groupId>${groupId.error-prone}</groupId>
+            <artifactId>error_prone_check_api</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>${groupId.error-prone}</groupId>
+            <artifactId>error_prone_core</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>${groupId.error-prone}</groupId>
+            <artifactId>error_prone_test_helpers</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>com.fasterxml.jackson.core</groupId>
+            <artifactId>jackson-annotations</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>com.fasterxml.jackson.core</groupId>
+            <artifactId>jackson-databind</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>com.google.auto</groupId>
+            <artifactId>auto-common</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>com.google.auto.service</groupId>
+            <artifactId>auto-service-annotations</artifactId>
+            <scope>provided</scope>
+        </dependency>
+        <dependency>
+            <groupId>com.google.auto.value</groupId>
+            <artifactId>auto-value-annotations</artifactId>
+            <scope>provided</scope>
+        </dependency>
+        <dependency>
+            <groupId>com.google.guava</groupId>
+            <artifactId>guava</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.assertj</groupId>
+            <artifactId>assertj-core</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.jspecify</groupId>
+            <artifactId>jspecify</artifactId>
+            <scope>provided</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-api</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-engine</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-params</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+</project>

documentation-support/src/main/java/tech/picnic/errorprone/documentation/BugPatternExtractor.java

@@ -0,0 +1,114 @@
+package tech.picnic.errorprone.documentation;
+
+import static com.google.common.base.Verify.verify;
+import static com.google.common.collect.ImmutableList.toImmutableList;
+import static java.util.Objects.requireNonNull;
+
+import com.google.auto.common.AnnotationMirrors;
+import com.google.auto.service.AutoService;
+import com.google.auto.value.AutoValue;
+import com.google.common.collect.ImmutableList;
+import com.google.errorprone.BugPattern;
+import com.google.errorprone.BugPattern.SeverityLevel;
+import com.google.errorprone.VisitorState;
+import com.google.errorprone.annotations.Immutable;
+import com.google.errorprone.util.ASTHelpers;
+import com.sun.source.tree.AnnotationTree;
+import com.sun.source.tree.ClassTree;
+import com.sun.tools.javac.code.Attribute;
+import com.sun.tools.javac.code.Symbol.ClassSymbol;
+import java.util.Optional;
+import javax.lang.model.element.AnnotationValue;
+import tech.picnic.errorprone.documentation.BugPatternExtractor.BugPatternDocumentation;
+
+/**
+ * An {@link Extractor} that describes how to extract data from a {@code @BugPattern} annotation.
+ */
+@Immutable
+@AutoService(Extractor.class)
+public final class BugPatternExtractor implements Extractor<BugPatternDocumentation> {
+  /** Instantiates a new {@link BugPatternExtractor} instance. */
+  public BugPatternExtractor() {}
+
+  @Override
+  public String identifier() {
+    return "bugpattern";
+  }
+
+  @Override
+  public Optional<BugPatternDocumentation> tryExtract(ClassTree tree, VisitorState state) {
+    ClassSymbol symbol = ASTHelpers.getSymbol(tree);
+    BugPattern annotation = symbol.getAnnotation(BugPattern.class);
+    if (annotation == null) {
+      return Optional.empty();
+    }
+
+    return Optional.of(
+        new AutoValue_BugPatternExtractor_BugPatternDocumentation(
+            symbol.getQualifiedName().toString(),
+            annotation.name().isEmpty() ? tree.getSimpleName().toString() : annotation.name(),
+            ImmutableList.copyOf(annotation.altNames()),
+            annotation.link(),
+            ImmutableList.copyOf(annotation.tags()),
+            annotation.summary(),
+            annotation.explanation(),
+            annotation.severity(),
+            annotation.disableable(),
+            annotation.documentSuppression()
+                ? getSuppressionAnnotations(tree)
+                : ImmutableList.of()));
+  }
+
+  /**
+   * Returns the fully-qualified class names of suppression annotations specified by the {@link
+   * BugPattern} annotation located on the given tree.
+   *
+   * @implNote This method cannot simply invoke {@link BugPattern#suppressionAnnotations()}, as that
+   *     will yield an "Attempt to access Class objects for TypeMirrors" exception.
+   */
+  private static ImmutableList<String> getSuppressionAnnotations(ClassTree tree) {
+    AnnotationTree annotationTree =
+        ASTHelpers.getAnnotationWithSimpleName(
+            ASTHelpers.getAnnotations(tree), BugPattern.class.getSimpleName());
+    requireNonNull(annotationTree, "BugPattern annotation must be present");
+
+    Attribute.Array types =
+        doCast(
+            AnnotationMirrors.getAnnotationValue(
+                ASTHelpers.getAnnotationMirror(annotationTree), "suppressionAnnotations"),
+            Attribute.Array.class);
+
+    return types.getValue().stream()
+        .map(v -> doCast(v, Attribute.Class.class).classType.toString())
+        .collect(toImmutableList());
+  }
+
+  @SuppressWarnings("unchecked")
+  private static <T extends AnnotationValue> T doCast(AnnotationValue value, Class<T> target) {
+    verify(target.isInstance(value), "Value '%s' is not of type '%s'", value, target);
+    return (T) value;
+  }
+
+  @AutoValue
+  abstract static class BugPatternDocumentation {
+    abstract String fullyQualifiedName();
+
+    abstract String name();
+
+    abstract ImmutableList<String> altNames();
+
+    abstract String link();
+
+    abstract ImmutableList<String> tags();
+
+    abstract String summary();
+
+    abstract String explanation();
+
+    abstract SeverityLevel severityLevel();
+
+    abstract boolean canDisable();
+
+    abstract ImmutableList<String> suppressionAnnotations();
+  }
+}

documentation-support/src/main/java/tech/picnic/errorprone/documentation/BugPatternTestExtractor.java

@@ -0,0 +1,200 @@
+package tech.picnic.errorprone.documentation;
+
+import static com.google.errorprone.matchers.Matchers.allOf;
+import static com.google.errorprone.matchers.Matchers.anything;
+import static com.google.errorprone.matchers.Matchers.argument;
+import static com.google.errorprone.matchers.Matchers.classLiteral;
+import static com.google.errorprone.matchers.Matchers.hasAnnotation;
+import static com.google.errorprone.matchers.Matchers.instanceMethod;
+import static com.google.errorprone.matchers.Matchers.toType;
+import static com.google.errorprone.matchers.method.MethodMatchers.staticMethod;
+
+import com.google.auto.service.AutoService;
+import com.google.auto.value.AutoValue;
+import com.google.common.collect.ImmutableList;
+import com.google.errorprone.VisitorState;
+import com.google.errorprone.annotations.Immutable;
+import com.google.errorprone.matchers.Matcher;
+import com.google.errorprone.util.ASTHelpers;
+import com.sun.source.tree.ClassTree;
+import com.sun.source.tree.ExpressionTree;
+import com.sun.source.tree.MemberSelectTree;
+import com.sun.source.tree.MethodInvocationTree;
+import com.sun.source.tree.MethodTree;
+import com.sun.source.tree.Tree;
+import com.sun.source.util.TreeScanner;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Optional;
+import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.regex.Pattern;
+import org.jspecify.annotations.Nullable;
+import tech.picnic.errorprone.documentation.BugPatternTestExtractor.BugPatternTestDocumentation;
+
+/**
+ * An {@link Extractor} that describes how to extract data from classes that test a {@code
+ * BugChecker}.
+ */
+@Immutable
+@AutoService(Extractor.class)
+public final class BugPatternTestExtractor implements Extractor<BugPatternTestDocumentation> {
+  private static final Pattern TEST_CLASS_NAME_PATTERN = Pattern.compile("(.*)Test");
+  private static final Matcher<Tree> JUNIT_TEST_METHOD =
+      toType(MethodTree.class, hasAnnotation("org.junit.jupiter.api.Test"));
+  private static final Matcher<MethodInvocationTree> BUG_PATTERN_TEST_METHOD =
+      allOf(
+          staticMethod()
+              .onDescendantOfAny(
+                  "com.google.errorprone.CompilationTestHelper",
+                  "com.google.errorprone.BugCheckerRefactoringTestHelper")
+              .named("newInstance"),
+          argument(0, classLiteral(anything())));
+
+  /** Instantiates a new {@link BugPatternTestExtractor} instance. */
+  public BugPatternTestExtractor() {}
+
+  @Override
+  public String identifier() {
+    return "bugpattern-test";
+  }
+
+  // XXX: Improve support for correctly extracting multiple sources from a single
+  // `{BugCheckerRefactoring,Compilation}TestHelper` test.
+  @Override
+  public Optional<BugPatternTestDocumentation> tryExtract(ClassTree tree, VisitorState state) {
+    return getClassUnderTest(tree)
+        .filter(bugPatternName -> testsBugPattern(bugPatternName, tree, state))
+        .map(
+            bugPatternName -> {
+              CollectBugPatternTests scanner = new CollectBugPatternTests();
+
+              for (Tree m : tree.getMembers()) {
+                if (JUNIT_TEST_METHOD.matches(m, state)) {
+                  scanner.scan(m, state);
+                }
+              }
+
+              return new AutoValue_BugPatternTestExtractor_BugPatternTestDocumentation(
+                  bugPatternName, scanner.getIdentificationTests(), scanner.getReplacementTests());
+            });
+  }
+
+  private static boolean testsBugPattern(
+      String bugPatternName, ClassTree tree, VisitorState state) {
+    AtomicBoolean result = new AtomicBoolean(false);
+
+    new TreeScanner<@Nullable Void, @Nullable Void>() {
+      @Override
+      public @Nullable Void visitMethodInvocation(MethodInvocationTree node, @Nullable Void v) {
+        if (BUG_PATTERN_TEST_METHOD.matches(node, state)) {
+          MemberSelectTree firstArgumentTree = (MemberSelectTree) node.getArguments().get(0);
+          result.compareAndSet(
+              /* expectedValue= */ false,
+              bugPatternName.equals(firstArgumentTree.getExpression().toString()));
+        }
+
+        return super.visitMethodInvocation(node, v);
+      }
+    }.scan(tree, null);
+
+    return result.get();
+  }
+
+  private static Optional<String> getClassUnderTest(ClassTree tree) {
+    return Optional.of(TEST_CLASS_NAME_PATTERN.matcher(tree.getSimpleName().toString()))
+        .filter(java.util.regex.Matcher::matches)
+        .map(m -> m.group(1));
+  }
+
+  private static final class CollectBugPatternTests
+      extends TreeScanner<@Nullable Void, VisitorState> {
+    private static final Matcher<ExpressionTree> IDENTIFICATION_SOURCE_LINES =
+        instanceMethod()
+            .onDescendantOf("com.google.errorprone.CompilationTestHelper")
+            .named("addSourceLines");
+    private static final Matcher<ExpressionTree> REPLACEMENT_INPUT =
+        instanceMethod()
+            .onDescendantOf("com.google.errorprone.BugCheckerRefactoringTestHelper")
+            .named("addInputLines");
+    private static final Matcher<ExpressionTree> REPLACEMENT_OUTPUT =
+        instanceMethod()
+            .onDescendantOf("com.google.errorprone.BugCheckerRefactoringTestHelper.ExpectOutput")
+            .named("addOutputLines");
+
+    private final List<String> identificationTests = new ArrayList<>();
+    private final List<BugPatternReplacementTestDocumentation> replacementTests = new ArrayList<>();
+
+    public ImmutableList<String> getIdentificationTests() {
+      return ImmutableList.copyOf(identificationTests);
+    }
+
+    public ImmutableList<BugPatternReplacementTestDocumentation> getReplacementTests() {
+      return ImmutableList.copyOf(replacementTests);
+    }
+
+    // XXX: Consider:
+    // - Whether to omit or handle differently identification tests without `// BUG: Diagnostic
+    //   (contains|matches)` markers.
+    // - Whether to omit or handle differently replacement tests with identical input and output.
+    //   (Though arguably we should have a separate checker which replaces such cases with
+    //   `.expectUnchanged()`.)
+    // - Whether to track `.expectUnchanged()` test cases.
+    @Override
+    public @Nullable Void visitMethodInvocation(MethodInvocationTree node, VisitorState state) {
+      if (IDENTIFICATION_SOURCE_LINES.matches(node, state)) {
+        getSourceCode(node).ifPresent(identificationTests::add);
+      } else if (REPLACEMENT_OUTPUT.matches(node, state)) {
+        ExpressionTree receiver = ASTHelpers.getReceiver(node);
+        // XXX: Make this code nicer.
+        if (REPLACEMENT_INPUT.matches(receiver, state)) {
+          getSourceCode(node)
+              .ifPresent(
+                  output ->
+                      getSourceCode((MethodInvocationTree) receiver)
+                          .ifPresent(
+                              input ->
+                                  replacementTests.add(
+                                      new AutoValue_BugPatternTestExtractor_BugPatternReplacementTestDocumentation(
+                                          input, output))));
+        }
+      }
+
+      return super.visitMethodInvocation(node, state);
+    }
+
+    // XXX: Duplicated from `ErrorProneTestSourceFormat`. Can we do better?
+    private static Optional<String> getSourceCode(MethodInvocationTree tree) {
+      List<? extends ExpressionTree> sourceLines =
+          tree.getArguments().subList(1, tree.getArguments().size());
+      StringBuilder source = new StringBuilder();
+
+      for (ExpressionTree sourceLine : sourceLines) {
+        String value = ASTHelpers.constValue(sourceLine, String.class);
+        if (value == null) {
+          return Optional.empty();
+        }
+        source.append(value).append('\n');
+      }
+
+      return Optional.of(source.toString());
+    }
+  }
+
+  // XXX: Rename?
+  @AutoValue
+  abstract static class BugPatternTestDocumentation {
+    abstract String name();
+
+    abstract ImmutableList<String> identificationTests();
+
+    abstract ImmutableList<BugPatternReplacementTestDocumentation> replacementTests();
+  }
+
+  // XXX: Rename?
+  @AutoValue
+  abstract static class BugPatternReplacementTestDocumentation {
+    abstract String inputLines();
+
+    abstract String outputLines();
+  }
+}

documentation-support/src/main/java/tech/picnic/errorprone/documentation/DocumentationGenerator.java

@@ -0,0 +1,56 @@
+package tech.picnic.errorprone.documentation;
+
+import static com.google.common.base.Preconditions.checkArgument;
+
+import com.google.auto.service.AutoService;
+import com.google.common.annotations.VisibleForTesting;
+import com.sun.source.util.JavacTask;
+import com.sun.source.util.Plugin;
+import com.sun.tools.javac.api.BasicJavacTask;
+import java.nio.file.InvalidPathException;
+import java.nio.file.Path;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+/**
+ * A compiler {@link Plugin} that analyzes and extracts relevant information for documentation
+ * purposes from processed files.
+ */
+// XXX: Find a better name for this class; it doesn't generate documentation per se.
+@AutoService(Plugin.class)
+public final class DocumentationGenerator implements Plugin {
+  @VisibleForTesting static final String OUTPUT_DIRECTORY_FLAG = "-XoutputDirectory";
+  private static final Pattern OUTPUT_DIRECTORY_FLAG_PATTERN =
+      Pattern.compile(Pattern.quote(OUTPUT_DIRECTORY_FLAG) + "=(.*)");
+
+  /** Instantiates a new {@link DocumentationGenerator} instance. */
+  public DocumentationGenerator() {}
+
+  @Override
+  public String getName() {
+    return getClass().getSimpleName();
+  }
+
+  @Override
+  public void init(JavacTask javacTask, String... args) {
+    checkArgument(args.length == 1, "Precisely one path must be provided");
+
+    javacTask.addTaskListener(
+        new DocumentationGeneratorTaskListener(
+            ((BasicJavacTask) javacTask).getContext(), getOutputPath(args[0])));
+  }
+
+  @VisibleForTesting
+  static Path getOutputPath(String pathArg) {
+    Matcher matcher = OUTPUT_DIRECTORY_FLAG_PATTERN.matcher(pathArg);
+    checkArgument(
+        matcher.matches(), "'%s' must be of the form '%s=<value>'", pathArg, OUTPUT_DIRECTORY_FLAG);
+
+    String path = matcher.group(1);
+    try {
+      return Path.of(path);
+    } catch (InvalidPathException e) {
+      throw new IllegalArgumentException(String.format("Invalid path '%s'", path), e);
+    }
+  }
+}

documentation-support/src/main/java/tech/picnic/errorprone/documentation/DocumentationGeneratorTaskListener.java

@@ -0,0 +1,109 @@
+package tech.picnic.errorprone.documentation;
+
+import static java.nio.charset.StandardCharsets.UTF_8;
+
+import com.fasterxml.jackson.annotation.JsonAutoDetect.Visibility;
+import com.fasterxml.jackson.annotation.PropertyAccessor;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.google.common.collect.ImmutableList;
+import com.google.errorprone.VisitorState;
+import com.sun.source.tree.ClassTree;
+import com.sun.source.tree.CompilationUnitTree;
+import com.sun.source.util.TaskEvent;
+import com.sun.source.util.TaskEvent.Kind;
+import com.sun.source.util.TaskListener;
+import com.sun.source.util.TreePath;
+import com.sun.tools.javac.api.JavacTrees;
+import com.sun.tools.javac.util.Context;
+import java.io.File;
+import java.io.FileWriter;
+import java.io.IOException;
+import java.io.UncheckedIOException;
+import java.net.URI;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import java.util.ServiceLoader;
+import javax.tools.JavaFileObject;
+
+/**
+ * A {@link TaskListener} that identifies and extracts relevant content for documentation generation
+ * and writes it to disk.
+ */
+// XXX: Find a better name for this class; it doesn't generate documentation per se.
+final class DocumentationGeneratorTaskListener implements TaskListener {
+  @SuppressWarnings({"rawtypes", "unchecked"})
+  private static final ImmutableList<Extractor<?>> EXTRACTORS =
+      (ImmutableList)
+          ImmutableList.copyOf(
+              ServiceLoader.load(
+                  Extractor.class, DocumentationGeneratorTaskListener.class.getClassLoader()));
+
+  private static final ObjectMapper OBJECT_MAPPER =
+      new ObjectMapper().setVisibility(PropertyAccessor.FIELD, Visibility.ANY);
+
+  private final Context context;
+  private final Path docsPath;
+
+  DocumentationGeneratorTaskListener(Context context, Path path) {
+    this.context = context;
+    this.docsPath = path;
+  }
+
+  @Override
+  public void started(TaskEvent taskEvent) {
+    if (taskEvent.getKind() == Kind.ANALYZE) {
+      createDocsDirectory();
+    }
+  }
+
+  @Override
+  public void finished(TaskEvent taskEvent) {
+    if (taskEvent.getKind() != Kind.ANALYZE) {
+      return;
+    }
+
+    JavaFileObject sourceFile = taskEvent.getSourceFile();
+    CompilationUnitTree compilationUnit = taskEvent.getCompilationUnit();
+    ClassTree classTree = JavacTrees.instance(context).getTree(taskEvent.getTypeElement());
+    if (sourceFile == null || compilationUnit == null || classTree == null) {
+      return;
+    }
+
+    VisitorState state =
+        VisitorState.createForUtilityPurposes(context)
+            .withPath(new TreePath(new TreePath(compilationUnit), classTree));
+
+    for (Extractor<?> extractor : EXTRACTORS) {
+      extractor
+          .tryExtract(classTree, state)
+          .ifPresent(
+              data ->
+                  writeToFile(
+                      extractor.identifier(), getSimpleClassName(sourceFile.toUri()), data));
+    }
+  }
+
+  private void createDocsDirectory() {
+    try {
+      Files.createDirectories(docsPath);
+    } catch (IOException e) {
+      throw new IllegalStateException(
+          String.format("Error while creating directory with path '%s'", docsPath), e);
+    }
+  }
+
+  private <T> void writeToFile(String identifier, String className, T data) {
+    File file = docsPath.resolve(String.format("%s-%s.json", identifier, className)).toFile();
+
+    try (FileWriter fileWriter = new FileWriter(file, UTF_8)) {
+      OBJECT_MAPPER.writeValue(fileWriter, data);
+    } catch (IOException e) {
+      throw new UncheckedIOException(String.format("Cannot write to file '%s'", file.getPath()), e);
+    }
+  }
+
+  private static String getSimpleClassName(URI path) {
+    return Paths.get(path).getFileName().toString().replace(".java", "");
+  }
+}

documentation-support/src/main/java/tech/picnic/errorprone/documentation/Extractor.java

@@ -0,0 +1,33 @@
+package tech.picnic.errorprone.documentation;
+
+import com.google.errorprone.VisitorState;
+import com.google.errorprone.annotations.Immutable;
+import com.sun.source.tree.ClassTree;
+import java.util.Optional;
+
+/**
+ * Interface implemented by classes that define how to extract data of some type {@link T} from a
+ * given {@link ClassTree}.
+ *
+ * @param <T> The type of data that is extracted.
+ */
+@Immutable
+interface Extractor<T> {
+  /**
+   * Returns the unique identifier of this extractor.
+   *
+   * @return A non-{@code null} string.
+   */
+  String identifier();
+
+  /**
+   * Attempts to extract an instance of type {@link T} using the provided arguments.
+   *
+   * @param tree The {@link ClassTree} to analyze and from which to extract an instance of type
+   *     {@link T}.
+   * @param state A {@link VisitorState} describing the context in which the given {@link ClassTree}
+   *     is found.
+   * @return An instance of type {@link T}, if possible.
+   */
+  Optional<T> tryExtract(ClassTree tree, VisitorState state);
+}

documentation-support/src/main/java/tech/picnic/errorprone/documentation/RefasterTestInputExtractor.java

@@ -0,0 +1,61 @@
+package tech.picnic.errorprone.documentation;
+
+import static com.google.common.collect.ImmutableList.toImmutableList;
+
+import com.google.auto.service.AutoService;
+import com.google.common.collect.ImmutableList;
+import com.google.errorprone.VisitorState;
+import com.google.errorprone.annotations.Immutable;
+import com.sun.source.tree.ClassTree;
+import com.sun.source.tree.MethodTree;
+import java.util.Optional;
+import java.util.regex.Pattern;
+import tech.picnic.errorprone.documentation.models.RefasterTemplateCollectionTestData;
+import tech.picnic.errorprone.documentation.models.RefasterTemplateTestData;
+
+@Immutable
+@AutoService(Extractor.class)
+public final class RefasterTestInputExtractor
+    implements Extractor<RefasterTemplateCollectionTestData> {
+  private static final Pattern TEST_INPUT_CLASS_NAME_PATTERN = Pattern.compile("(.*)TestInput");
+
+  @Override
+  public String identifier() {
+    return "refaster-test-input";
+  }
+
+  @Override
+  public Optional<RefasterTemplateCollectionTestData> tryExtract(
+      ClassTree tree, VisitorState state) {
+    Optional<String> className = getClassUnderTest(tree);
+    if (className.isEmpty()) {
+      return Optional.empty();
+    }
+
+    ImmutableList<RefasterTemplateTestData> templateTests =
+        tree.getMembers().stream()
+            .filter(m -> m instanceof MethodTree)
+            .map(MethodTree.class::cast)
+            .filter(m -> m.getName().toString().startsWith("test"))
+            .map(
+                m ->
+                    RefasterTemplateTestData.create(
+                        m.getName().toString().replace("test", ""), getSourceCode(m, state)))
+            .collect(toImmutableList());
+
+    return Optional.of(
+        RefasterTemplateCollectionTestData.create(className.orElseThrow(), true, templateTests));
+  }
+
+  private static Optional<String> getClassUnderTest(ClassTree tree) {
+    return Optional.of(TEST_INPUT_CLASS_NAME_PATTERN.matcher(tree.getSimpleName().toString()))
+        .filter(java.util.regex.Matcher::matches)
+        .map(m -> m.group(1));
+  }
+
+  // XXX: Duplicated from `SourceCode`. Can we do better?
+  private String getSourceCode(MethodTree tree, VisitorState state) {
+    String src = state.getSourceForNode(tree);
+    return src != null ? src : tree.toString();
+  }
+}

documentation-support/src/main/java/tech/picnic/errorprone/documentation/RefasterTestOutputExtractor.java

@@ -0,0 +1,61 @@
+package tech.picnic.errorprone.documentation;
+
+import static com.google.common.collect.ImmutableList.toImmutableList;
+
+import com.google.auto.service.AutoService;
+import com.google.common.collect.ImmutableList;
+import com.google.errorprone.VisitorState;
+import com.google.errorprone.annotations.Immutable;
+import com.sun.source.tree.ClassTree;
+import com.sun.source.tree.MethodTree;
+import java.util.Optional;
+import java.util.regex.Pattern;
+import tech.picnic.errorprone.documentation.models.RefasterTemplateCollectionTestData;
+import tech.picnic.errorprone.documentation.models.RefasterTemplateTestData;
+
+@Immutable
+@AutoService(Extractor.class)
+public final class RefasterTestOutputExtractor
+    implements Extractor<RefasterTemplateCollectionTestData> {
+  private static final Pattern TEST_INPUT_CLASS_NAME_PATTERN = Pattern.compile("(.*)TestOutput");
+
+  @Override
+  public String identifier() {
+    return "refaster-test-output";
+  }
+
+  @Override
+  public Optional<RefasterTemplateCollectionTestData> tryExtract(
+      ClassTree tree, VisitorState state) {
+    Optional<String> className = getClassUnderTest(tree);
+    if (className.isEmpty()) {
+      return Optional.empty();
+    }
+
+    ImmutableList<RefasterTemplateTestData> templateTests =
+        tree.getMembers().stream()
+            .filter(m -> m instanceof MethodTree)
+            .map(MethodTree.class::cast)
+            .filter(m -> m.getName().toString().startsWith("test"))
+            .map(
+                m ->
+                    RefasterTemplateTestData.create(
+                        m.getName().toString().replace("test", ""), getSourceCode(m, state)))
+            .collect(toImmutableList());
+
+    return Optional.of(
+        RefasterTemplateCollectionTestData.create(className.orElseThrow(), true, templateTests));
+  }
+
+  private static Optional<String> getClassUnderTest(ClassTree tree) {
+    return Optional.of(TEST_INPUT_CLASS_NAME_PATTERN.matcher(tree.getSimpleName().toString()))
+        .filter(java.util.regex.Matcher::matches)
+        .map(m -> m.group(1));
+  }
+
+  // XXX: Duplicated from `SourceCode`. Can we do better?
+  private String getSourceCode(MethodTree tree, VisitorState state) {
+    String src = state.getSourceForNode(tree);
+    return src != null ? src : tree.toString();
+  }
+}

documentation-support/src/main/java/tech/picnic/errorprone/documentation/models/RefasterTemplateCollectionData.java

@@ -0,0 +1,25 @@
+package tech.picnic.errorprone.documentation.models;
+
+import com.google.auto.value.AutoValue;
+import java.util.List;
+import tech.picnic.errorprone.documentation.models.AutoValue_RefasterTemplateCollectionData;
+
+/**
+ * Object containing all data related to a Refaster template collection. This is solely used for
+ * serialization.
+ */
+@AutoValue
+public abstract class RefasterTemplateCollectionData {
+  public static RefasterTemplateCollectionData create(
+      String name, String description, String link, List<RefasterTemplateData> templates) {
+    return new AutoValue_RefasterTemplateCollectionData(name, description, link, templates);
+  }
+
+  abstract String name();
+
+  abstract String description();
+
+  abstract String link();
+
+  abstract List<RefasterTemplateData> templates();
+}

documentation-support/src/main/java/tech/picnic/errorprone/documentation/models/RefasterTemplateCollectionTestData.java

@@ -0,0 +1,20 @@
+package tech.picnic.errorprone.documentation.models;
+
+import com.google.auto.value.AutoValue;
+import java.util.List;
+import tech.picnic.errorprone.documentation.models.AutoValue_RefasterTemplateCollectionTestData;
+
+@AutoValue
+public abstract class RefasterTemplateCollectionTestData {
+  public static RefasterTemplateCollectionTestData create(
+      String templateCollection, boolean isInput, List<RefasterTemplateTestData> templatesTests) {
+    return new AutoValue_RefasterTemplateCollectionTestData(
+        templateCollection, isInput, templatesTests);
+  }
+
+  abstract String templateCollection();
+
+  abstract boolean isInput();
+
+  abstract List<RefasterTemplateTestData> templateTests();
+}

documentation-support/src/main/java/tech/picnic/errorprone/documentation/models/RefasterTemplateData.java

@@ -1,8 +1,8 @@
-package tech.picnic.errorprone.plugin.objects;
+package tech.picnic.errorprone.documentation.models;
 
-import com.fasterxml.jackson.annotation.JsonProperty;
 import com.google.auto.value.AutoValue;
 import com.google.errorprone.BugPattern.SeverityLevel;
+import tech.picnic.errorprone.documentation.models.AutoValue_RefasterTemplateData;
 
 @AutoValue
 public abstract class RefasterTemplateData {
@@ -11,15 +11,11 @@ public abstract class RefasterTemplateData {
     return new AutoValue_RefasterTemplateData(name, description, link, severityLevel);
   }
 
-  @JsonProperty
   abstract String name();
 
-  @JsonProperty
   abstract String description();
 
-  @JsonProperty
   abstract String link();
 
-  @JsonProperty
   abstract SeverityLevel severityLevel();
 }

documentation-support/src/main/java/tech/picnic/errorprone/documentation/models/RefasterTemplateTestData.java

@@ -0,0 +1,15 @@
+package tech.picnic.errorprone.documentation.models;
+
+import com.google.auto.value.AutoValue;
+import tech.picnic.errorprone.documentation.models.AutoValue_RefasterTemplateTestData;
+
+@AutoValue
+public abstract class RefasterTemplateTestData {
+  public static RefasterTemplateTestData create(String templateName, String templateTestContent) {
+    return new AutoValue_RefasterTemplateTestData(templateName, templateTestContent);
+  }
+
+  abstract String templateName();
+
+  abstract String templateTestContent();
+}

documentation-support/src/main/java/tech/picnic/errorprone/documentation/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * A Java compiler plugin that extracts data from compiled classes, in support of the Error Prone
+ * Support documentation.
+ */
+@com.google.errorprone.annotations.CheckReturnValue
+@org.jspecify.annotations.NullMarked
+package tech.picnic.errorprone.documentation;

documentation-support/src/test/java/tech/picnic/errorprone/documentation/BugPatternExtractorTest.java

@@ -0,0 +1,148 @@
+package tech.picnic.errorprone.documentation;
+
+import static com.google.errorprone.BugPattern.SeverityLevel.ERROR;
+import static java.nio.charset.StandardCharsets.UTF_8;
+import static org.assertj.core.api.Assertions.assertThat;
+
+import com.google.common.io.Resources;
+import com.google.errorprone.BugPattern;
+import com.google.errorprone.CompilationTestHelper;
+import com.google.errorprone.VisitorState;
+import com.google.errorprone.bugpatterns.BugChecker;
+import com.google.errorprone.bugpatterns.BugChecker.ClassTreeMatcher;
+import com.google.errorprone.matchers.Description;
+import com.sun.source.tree.ClassTree;
+import java.io.IOException;
+import java.nio.file.Path;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+final class BugPatternExtractorTest {
+  @Test
+  void noBugPattern(@TempDir Path outputDirectory) {
+    Compilation.compileWithDocumentationGenerator(
+        outputDirectory,
+        "TestCheckerWithoutAnnotation.java",
+        "import com.google.errorprone.bugpatterns.BugChecker;",
+        "",
+        "public final class TestCheckerWithoutAnnotation extends BugChecker {}");
+
+    assertThat(outputDirectory.toAbsolutePath()).isEmptyDirectory();
+  }
+
+  @Test
+  void minimalBugPattern(@TempDir Path outputDirectory) throws IOException {
+    Compilation.compileWithDocumentationGenerator(
+        outputDirectory,
+        "MinimalBugChecker.java",
+        "package pkg;",
+        "",
+        "import com.google.errorprone.BugPattern;",
+        "import com.google.errorprone.BugPattern.SeverityLevel;",
+        "import com.google.errorprone.bugpatterns.BugChecker;",
+        "",
+        "@BugPattern(summary = \"MinimalBugChecker summary\", severity = SeverityLevel.ERROR)",
+        "public final class MinimalBugChecker extends BugChecker {}");
+
+    verifyFileMatchesResource(
+        outputDirectory,
+        "bugpattern-MinimalBugChecker.json",
+        "bugpattern-documentation-minimal.json");
+  }
+
+  @Test
+  void completeBugPattern(@TempDir Path outputDirectory) throws IOException {
+    Compilation.compileWithDocumentationGenerator(
+        outputDirectory,
+        "CompleteBugChecker.java",
+        "package pkg;",
+        "",
+        "import com.google.errorprone.BugPattern;",
+        "import com.google.errorprone.BugPattern.SeverityLevel;",
+        "import com.google.errorprone.bugpatterns.BugChecker;",
+        "import org.junit.jupiter.api.Test;",
+        "",
+        "@BugPattern(",
+        "    name = \"OtherName\",",
+        "    summary = \"CompleteBugChecker summary\",",
+        "    linkType = BugPattern.LinkType.CUSTOM,",
+        "    link = \"https://error-prone.picnic.tech\",",
+        "    explanation = \"Example explanation\",",
+        "    severity = SeverityLevel.SUGGESTION,",
+        "    altNames = \"Check\",",
+        "    tags = BugPattern.StandardTags.SIMPLIFICATION,",
+        "    disableable = false,",
+        "    suppressionAnnotations = {BugPattern.class, Test.class})",
+        "public final class CompleteBugChecker extends BugChecker {}");
+
+    verifyFileMatchesResource(
+        outputDirectory,
+        "bugpattern-CompleteBugChecker.json",
+        "bugpattern-documentation-complete.json");
+  }
+
+  @Test
+  void undocumentedSuppressionBugPattern(@TempDir Path outputDirectory) throws IOException {
+    Compilation.compileWithDocumentationGenerator(
+        outputDirectory,
+        "UndocumentedSuppressionBugPattern.java",
+        "package pkg;",
+        "",
+        "import com.google.errorprone.BugPattern;",
+        "import com.google.errorprone.BugPattern.SeverityLevel;",
+        "import com.google.errorprone.bugpatterns.BugChecker;",
+        "",
+        "@BugPattern(",
+        "    summary = \"UndocumentedSuppressionBugPattern summary\",",
+        "    severity = SeverityLevel.WARNING,",
+        "    documentSuppression = false)",
+        "public final class UndocumentedSuppressionBugPattern extends BugChecker {}");
+
+    verifyFileMatchesResource(
+        outputDirectory,
+        "bugpattern-UndocumentedSuppressionBugPattern.json",
+        "bugpattern-documentation-undocumented-suppression.json");
+  }
+
+  @Test
+  void bugPatternAnnotationIsAbsent() {
+    CompilationTestHelper.newInstance(TestChecker.class, getClass())
+        .addSourceLines(
+            "TestChecker.java",
+            "import com.google.errorprone.bugpatterns.BugChecker;",
+            "",
+            "// BUG: Diagnostic contains: Can extract: false",
+            "public final class TestChecker extends BugChecker {}")
+        .doTest();
+  }
+
+  private static void verifyFileMatchesResource(
+      Path outputDirectory, String fileName, String resourceName) throws IOException {
+    assertThat(outputDirectory.resolve(fileName))
+        .content(UTF_8)
+        .isEqualToIgnoringWhitespace(getResource(resourceName));
+  }
+
+  // XXX: Once we support only JDK 15+, drop this method in favour of including the resources as
+  // text blocks in this class. (This also requires renaming the `verifyFileMatchesResource`
+  // method.)
+  private static String getResource(String resourceName) throws IOException {
+    return Resources.toString(
+        Resources.getResource(BugPatternExtractorTest.class, resourceName), UTF_8);
+  }
+
+  /** A {@link BugChecker} that validates the {@link BugPatternExtractor}. */
+  @BugPattern(summary = "Validates `BugPatternExtractor` extraction", severity = ERROR)
+  public static final class TestChecker extends BugChecker implements ClassTreeMatcher {
+    private static final long serialVersionUID = 1L;
+
+    @Override
+    public Description matchClass(ClassTree tree, VisitorState state) {
+      return buildDescription(tree)
+          .setMessage(
+              String.format(
+                  "Can extract: %s", new BugPatternExtractor().tryExtract(tree, state).isPresent()))
+          .build();
+    }
+  }
+}

documentation-support/src/test/java/tech/picnic/errorprone/documentation/BugPatternTestExtractorTest.java

@@ -0,0 +1,352 @@
+package tech.picnic.errorprone.documentation;
+
+import static java.nio.charset.StandardCharsets.UTF_8;
+import static org.assertj.core.api.Assertions.assertThat;
+
+import com.google.common.io.Resources;
+import java.io.IOException;
+import java.nio.file.Path;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+final class BugPatternTestExtractorTest {
+  @Test
+  void noBugPatternTest(@TempDir Path outputDirectory) {
+    Compilation.compileWithDocumentationGenerator(
+        outputDirectory,
+        "TestCheckerWithoutAnnotation.java",
+        "import com.google.errorprone.bugpatterns.BugChecker;",
+        "",
+        "public final class TestCheckerWithoutAnnotation extends BugChecker {}");
+
+    assertThat(outputDirectory.toAbsolutePath()).isEmptyDirectory();
+  }
+
+  @Test
+  void bugPatternTestFileWithoutTestSuffix(@TempDir Path outputDirectory) {
+    Compilation.compileWithDocumentationGenerator(
+        outputDirectory,
+        "TestCheckerWithWrongSuffix.java",
+        "import com.google.errorprone.bugpatterns.BugChecker;",
+        "import com.google.errorprone.CompilationTestHelper;",
+        "",
+        "final class TestCheckerWithoutTestSuffix {",
+        "  private static class TestCheckerWithout extends BugChecker {}",
+        "",
+        "  CompilationTestHelper compilationTestHelper = CompilationTestHelper.newInstance(TestCheckerWithout.class, getClass());",
+        "}");
+
+    assertThat(outputDirectory.toAbsolutePath()).isEmptyDirectory();
+  }
+
+  @Test
+  void minimalBugPatternTest(@TempDir Path outputDirectory) throws IOException {
+    Compilation.compileWithDocumentationGenerator(
+        outputDirectory,
+        "TestCheckerTest.java",
+        "import com.google.errorprone.bugpatterns.BugChecker;",
+        "import com.google.errorprone.CompilationTestHelper;",
+        "",
+        "final class TestCheckerTest {",
+        "  private static class TestChecker extends BugChecker {}",
+        "",
+        "  CompilationTestHelper compilationTestHelper = CompilationTestHelper.newInstance(TestChecker.class, getClass());",
+        "}");
+
+    verifyFileMatchesResource(
+        outputDirectory,
+        "bugpattern-test-TestCheckerTest.json",
+        "bugpattern-test-documentation-minimal.json");
+  }
+
+  @Test
+  void differentBugPatternAsClassVariableTest(@TempDir Path outputDirectory) {
+    Compilation.compileWithDocumentationGenerator(
+        outputDirectory,
+        "TestCheckerTest.java",
+        "import com.google.errorprone.bugpatterns.BugChecker;",
+        "import com.google.errorprone.CompilationTestHelper;",
+        "",
+        "final class TestCheckerTest {",
+        "  private static class DifferentChecker extends BugChecker {}",
+        "",
+        "  CompilationTestHelper compilationTestHelper = CompilationTestHelper.newInstance(DifferentChecker.class, getClass());",
+        "}");
+
+    assertThat(outputDirectory.toAbsolutePath()).isEmptyDirectory();
+  }
+
+  @Test
+  void differentBugPatternAsLocalVariable(@TempDir Path outputDirectory) {
+    Compilation.compileWithDocumentationGenerator(
+        outputDirectory,
+        "TestCheckerTest.java",
+        "import com.google.errorprone.bugpatterns.BugChecker;",
+        "import com.google.errorprone.CompilationTestHelper;",
+        "import org.junit.jupiter.api.Test;",
+        "",
+        "final class TestCheckerTest {",
+        "  private static class DifferentChecker extends BugChecker {}",
+        "",
+        "  @Test",
+        "  void identification() {",
+        "    CompilationTestHelper.newInstance(DifferentChecker.class, getClass())",
+        "        .addSourceLines(\"A.java\", \"class A {}\")",
+        "        .doTest();",
+        "  }",
+        "}");
+
+    assertThat(outputDirectory.toAbsolutePath()).isEmptyDirectory();
+  }
+
+  @Test
+  void bugPatternTestSingleIdentification(@TempDir Path outputDirectory) throws IOException {
+    Compilation.compileWithDocumentationGenerator(
+        outputDirectory,
+        "TestCheckerTest.java",
+        "import com.google.errorprone.bugpatterns.BugChecker;",
+        "import com.google.errorprone.CompilationTestHelper;",
+        "import org.junit.jupiter.api.Test;",
+        "",
+        "final class TestCheckerTest {",
+        "  private static class TestChecker extends BugChecker {}",
+        "",
+        "  @Test",
+        "  void identification() {",
+        "    CompilationTestHelper.newInstance(TestChecker.class, getClass())",
+        "        .addSourceLines(\"A.java\", \"class A {}\")",
+        "        .doTest();",
+        "  }",
+        "}");
+
+    verifyFileMatchesResource(
+        outputDirectory,
+        "bugpattern-test-TestCheckerTest.json",
+        "bugpattern-test-documentation-identification.json");
+  }
+
+  @Test
+  void bugPatternTestIdentificationMultipleSourceLines(@TempDir Path outputDirectory)
+      throws IOException {
+    Compilation.compileWithDocumentationGenerator(
+        outputDirectory,
+        "TestCheckerTest.java",
+        "package pkg;",
+        "",
+        "import com.google.errorprone.bugpatterns.BugChecker;",
+        "import com.google.errorprone.CompilationTestHelper;",
+        "import org.junit.jupiter.api.Test;",
+        "",
+        "final class TestCheckerTest {",
+        "  private static class TestChecker extends BugChecker {}",
+        "",
+        "  @Test",
+        "  void identification() {",
+        "    CompilationTestHelper.newInstance(TestChecker.class, getClass())",
+        "        .addSourceLines(\"A.java\", \"class A {}\")",
+        "        .addSourceLines(\"B.java\", \"class B {}\")",
+        "        .doTest();",
+        "  }",
+        "}");
+
+    verifyFileMatchesResource(
+        outputDirectory,
+        "bugpattern-test-TestCheckerTest.json",
+        "bugpattern-test-documentation-identification-two-sources.json");
+  }
+
+  @Test
+  void bugPatternTestSingleReplacement(@TempDir Path outputDirectory) throws IOException {
+    Compilation.compileWithDocumentationGenerator(
+        outputDirectory,
+        "TestCheckerTest.java",
+        "import com.google.errorprone.BugCheckerRefactoringTestHelper;",
+        "import com.google.errorprone.BugCheckerRefactoringTestHelper.TestMode;",
+        "import com.google.errorprone.bugpatterns.BugChecker;",
+        "import org.junit.jupiter.api.Test;",
+        "",
+        "final class TestCheckerTest {",
+        "  private static class TestChecker extends BugChecker {}",
+        "",
+        "  @Test",
+        "  void replacement() {",
+        "    BugCheckerRefactoringTestHelper.newInstance(TestChecker.class, getClass())",
+        "        .addInputLines(\"A.java\", \"class A {}\")",
+        "        .addOutputLines(\"A.java\", \"class A {}\")",
+        "        .doTest(TestMode.TEXT_MATCH);",
+        "  }",
+        "}");
+
+    verifyFileMatchesResource(
+        outputDirectory,
+        "bugpattern-test-TestCheckerTest.json",
+        "bugpattern-test-documentation-replacement.json");
+  }
+
+  @Test
+  void bugPatternTestMultipleReplacementSources(@TempDir Path outputDirectory) throws IOException {
+    Compilation.compileWithDocumentationGenerator(
+        outputDirectory,
+        "TestCheckerTest.java",
+        "import com.google.errorprone.BugCheckerRefactoringTestHelper;",
+        "import com.google.errorprone.BugCheckerRefactoringTestHelper.TestMode;",
+        "import com.google.errorprone.bugpatterns.BugChecker;",
+        "import org.junit.jupiter.api.Test;",
+        "",
+        "final class TestCheckerTest {",
+        "  private static class TestChecker extends BugChecker {}",
+        "",
+        "  @Test",
+        "  void replacement() {",
+        "    BugCheckerRefactoringTestHelper.newInstance(TestChecker.class, getClass())",
+        "        .addInputLines(\"A.java\", \"class A {}\")",
+        "        .addOutputLines(\"A.java\", \"class A {}\")",
+        "        .addInputLines(\"B.java\", \"class B {}\")",
+        "        .addOutputLines(\"B.java\", \"class B {}\")",
+        "        .doTest(TestMode.TEXT_MATCH);",
+        "  }",
+        "}");
+
+    verifyFileMatchesResource(
+        outputDirectory,
+        "bugpattern-test-TestCheckerTest.json",
+        "bugpattern-test-documentation-replacement-two-sources.json");
+  }
+
+  @Test
+  void bugPatternReplacementExpectUnchanged(@TempDir Path outputDirectory) throws IOException {
+    Compilation.compileWithDocumentationGenerator(
+        outputDirectory,
+        "TestCheckerTest.java",
+        "import com.google.errorprone.BugCheckerRefactoringTestHelper;",
+        "import com.google.errorprone.BugCheckerRefactoringTestHelper.TestMode;",
+        "import com.google.errorprone.bugpatterns.BugChecker;",
+        "import org.junit.jupiter.api.Test;",
+        "",
+        "final class TestCheckerTest {",
+        "  private static class TestChecker extends BugChecker {}",
+        "",
+        "  @Test",
+        "  void replacement() {",
+        "    BugCheckerRefactoringTestHelper.newInstance(TestChecker.class, getClass())",
+        "        .addInputLines(\"A.java\", \"class A {}\")",
+        "        .expectUnchanged()",
+        "        .doTest(TestMode.TEXT_MATCH);",
+        "  }",
+        "}");
+
+    verifyFileMatchesResource(
+        outputDirectory,
+        "bugpattern-test-TestCheckerTest.json",
+        "bugpattern-test-documentation-replacement-expect-unchanged.json");
+  }
+
+  @Test
+  void bugPatternTestIdentificationAndReplacement(@TempDir Path outputDirectory)
+      throws IOException {
+    Compilation.compileWithDocumentationGenerator(
+        outputDirectory,
+        "TestCheckerTest.java",
+        "import com.google.errorprone.BugCheckerRefactoringTestHelper;",
+        "import com.google.errorprone.BugCheckerRefactoringTestHelper.TestMode;",
+        "import com.google.errorprone.bugpatterns.BugChecker;",
+        "import com.google.errorprone.CompilationTestHelper;",
+        "import org.junit.jupiter.api.Test;",
+        "",
+        "final class TestCheckerTest {",
+        "  private static class TestChecker extends BugChecker {}",
+        "",
+        "  @Test",
+        "  void identification() {",
+        "    CompilationTestHelper.newInstance(TestChecker.class, getClass())",
+        "        .addSourceLines(\"A.java\", \"class A {}\")",
+        "        .doTest();",
+        "  }",
+        "",
+        "  @Test",
+        "  void replacement() {",
+        "    BugCheckerRefactoringTestHelper.newInstance(TestChecker.class, getClass())",
+        "        .addInputLines(\"A.java\", \"class A {}\")",
+        "        .addOutputLines(\"A.java\", \"class A {}\")",
+        "        .doTest(TestMode.TEXT_MATCH);",
+        "  }",
+        "}");
+
+    verifyFileMatchesResource(
+        outputDirectory,
+        "bugpattern-test-TestCheckerTest.json",
+        "bugpattern-test-documentation-identification-and-replacement.json");
+  }
+
+  @Test
+  void bugPatternTestMultipleIdentificationAndReplacement(@TempDir Path outputDirectory)
+      throws IOException {
+    Compilation.compileWithDocumentationGenerator(
+        outputDirectory,
+        "TestCheckerTest.java",
+        "package pkg;",
+        "",
+        "import static com.google.errorprone.BugCheckerRefactoringTestHelper.FixChoosers.SECOND;",
+        "",
+        "import com.google.errorprone.BugCheckerRefactoringTestHelper;",
+        "import com.google.errorprone.BugCheckerRefactoringTestHelper.TestMode;",
+        "import com.google.errorprone.bugpatterns.BugChecker;",
+        "import com.google.errorprone.CompilationTestHelper;",
+        "import org.junit.jupiter.api.Test;",
+        "",
+        "final class TestCheckerTest {",
+        "  private static class TestChecker extends BugChecker {}",
+        "",
+        "  @Test",
+        "  void identification() {",
+        "    CompilationTestHelper.newInstance(TestChecker.class, getClass())",
+        "        .addSourceLines(\"A.java\", \"class A {}\")",
+        "        .doTest();",
+        "  }",
+        "",
+        "  @Test",
+        "  void identification2() {",
+        "    CompilationTestHelper.newInstance(TestChecker.class, getClass())",
+        "        .addSourceLines(\"B.java\", \"class B {}\")",
+        "        .doTest();",
+        "  }",
+        "",
+        "  @Test",
+        "  void replacementFirstSuggestedFix() {",
+        "    BugCheckerRefactoringTestHelper.newInstance(TestChecker.class, getClass())",
+        "        .addInputLines(\"A.java\", \"class A {}\")",
+        "        .addOutputLines(\"A.java\", \"class A {}\")",
+        "        .doTest(TestMode.TEXT_MATCH);",
+        "  }",
+        "",
+        "  @Test",
+        "  void replacementSecondSuggestedFix() {",
+        "    BugCheckerRefactoringTestHelper.newInstance(TestChecker.class, getClass())",
+        "        .setFixChooser(SECOND)",
+        "        .addInputLines(\"B.java\", \"class B {}\")",
+        "        .addOutputLines(\"B.java\", \"class B {}\")",
+        "        .doTest(TestMode.TEXT_MATCH);",
+        "  }",
+        "}");
+
+    verifyFileMatchesResource(
+        outputDirectory,
+        "bugpattern-test-TestCheckerTest.json",
+        "bugpattern-test-documentation-multiple-identification-and-replacement.json");
+  }
+
+  private static void verifyFileMatchesResource(
+      Path outputDirectory, String fileName, String resourceName) throws IOException {
+    assertThat(outputDirectory.resolve(fileName))
+        .content(UTF_8)
+        .isEqualToIgnoringWhitespace(getResource(resourceName));
+  }
+
+  // XXX: Once we support only JDK 15+, drop this method in favour of including the resources as
+  // text blocks in this class. (This also requires renaming the `verifyFileMatchesResource`
+  // method.)
+  private static String getResource(String resourceName) throws IOException {
+    return Resources.toString(
+        Resources.getResource(BugPatternTestExtractorTest.class, resourceName), UTF_8);
+  }
+}

documentation-support/src/test/java/tech/picnic/errorprone/documentation/Compilation.java

@@ -0,0 +1,45 @@
+package tech.picnic.errorprone.documentation;
+
+import com.google.common.collect.ImmutableList;
+import com.google.errorprone.FileManagers;
+import com.google.errorprone.FileObjects;
+import com.sun.tools.javac.api.JavacTaskImpl;
+import com.sun.tools.javac.api.JavacTool;
+import com.sun.tools.javac.file.JavacFileManager;
+import java.nio.file.Path;
+import javax.tools.JavaCompiler;
+import javax.tools.JavaFileObject;
+
+// XXX: Generalize and move this class so that it can also be used by `refaster-compiler`.
+// XXX: Add support for this class to the `ErrorProneTestHelperSourceFormat` check.
+public final class Compilation {
+  private Compilation() {}
+
+  public static void compileWithDocumentationGenerator(
+      Path outputDirectory, String fileName, String... lines) {
+    compileWithDocumentationGenerator(outputDirectory.toAbsolutePath().toString(), fileName, lines);
+  }
+
+  public static void compileWithDocumentationGenerator(
+      String outputDirectory, String fileName, String... lines) {
+    compile(
+        ImmutableList.of("-Xplugin:DocumentationGenerator -XoutputDirectory=" + outputDirectory),
+        FileObjects.forSourceLines(fileName, lines));
+  }
+
+  private static void compile(ImmutableList<String> options, JavaFileObject javaFileObject) {
+    JavacFileManager javacFileManager = FileManagers.testFileManager();
+    JavaCompiler compiler = JavacTool.create();
+    JavacTaskImpl task =
+        (JavacTaskImpl)
+            compiler.getTask(
+                null,
+                javacFileManager,
+                null,
+                options,
+                ImmutableList.of(),
+                ImmutableList.of(javaFileObject));
+
+    task.call();
+  }
+}

documentation-support/src/test/java/tech/picnic/errorprone/documentation/DocumentationGeneratorTaskListenerTest.java

@@ -0,0 +1,138 @@
+package tech.picnic.errorprone.documentation;
+
+import static com.google.common.collect.ImmutableList.toImmutableList;
+import static java.nio.charset.StandardCharsets.UTF_8;
+import static java.nio.file.attribute.AclEntryPermission.ADD_SUBDIRECTORY;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.junit.jupiter.api.condition.OS.WINDOWS;
+
+import com.google.auto.service.AutoService;
+import com.google.auto.value.AutoValue;
+import com.google.common.collect.ImmutableList;
+import com.google.common.collect.ImmutableSet;
+import com.google.common.collect.Sets;
+import com.google.common.collect.Streams;
+import com.google.errorprone.VisitorState;
+import com.google.errorprone.annotations.Immutable;
+import com.sun.source.tree.ClassTree;
+import com.sun.source.tree.Tree;
+import java.io.IOException;
+import java.nio.file.FileSystemException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.attribute.AclEntry;
+import java.nio.file.attribute.AclFileAttributeView;
+import java.util.Optional;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.condition.DisabledOnOs;
+import org.junit.jupiter.api.condition.EnabledOnOs;
+import org.junit.jupiter.api.io.TempDir;
+
+final class DocumentationGeneratorTaskListenerTest {
+  @EnabledOnOs(WINDOWS)
+  @Test
+  void readOnlyFileSystemWindows(@TempDir Path outputDirectory) throws IOException {
+    AclFileAttributeView view =
+        Files.getFileAttributeView(outputDirectory, AclFileAttributeView.class);
+    view.setAcl(
+        view.getAcl().stream()
+            .map(
+                entry ->
+                    AclEntry.newBuilder(entry)
+                        .setPermissions(
+                            Sets.difference(entry.permissions(), ImmutableSet.of(ADD_SUBDIRECTORY)))
+                        .build())
+            .collect(toImmutableList()));
+
+    readOnlyFileSystemFailsToWrite(outputDirectory.resolve("nonexistent"));
+  }
+
+  @DisabledOnOs(WINDOWS)
+  @Test
+  void readOnlyFileSystemNonWindows(@TempDir Path outputDirectory) {
+    assertThat(outputDirectory.toFile().setWritable(false))
+        .describedAs("Failed to make test directory unwritable")
+        .isTrue();
+
+    readOnlyFileSystemFailsToWrite(outputDirectory.resolve("nonexistent"));
+  }
+
+  private static void readOnlyFileSystemFailsToWrite(Path outputDirectory) {
+    assertThatThrownBy(
+            () ->
+                Compilation.compileWithDocumentationGenerator(
+                    outputDirectory, "A.java", "class A {}"))
+        .hasRootCauseInstanceOf(FileSystemException.class)
+        .hasCauseInstanceOf(IllegalStateException.class)
+        .hasMessageEndingWith("Error while creating directory with path '%s'", outputDirectory);
+  }
+
+  @Test
+  void noClassNoOutput(@TempDir Path outputDirectory) {
+    Compilation.compileWithDocumentationGenerator(outputDirectory, "A.java", "package pkg;");
+
+    assertThat(outputDirectory).isEmptyDirectory();
+  }
+
+  @Test
+  void excessArguments(@TempDir Path outputDirectory) {
+    assertThatThrownBy(
+            () ->
+                Compilation.compileWithDocumentationGenerator(
+                    outputDirectory.toAbsolutePath() + " extra-arg", "A.java", "package pkg;"))
+        .isInstanceOf(IllegalArgumentException.class)
+        .hasMessage("Precisely one path must be provided");
+  }
+
+  @Test
+  void extraction(@TempDir Path outputDirectory) {
+    Compilation.compileWithDocumentationGenerator(
+        outputDirectory,
+        "DocumentationGeneratorTaskListenerTestClass.java",
+        "class DocumentationGeneratorTaskListenerTestClass {}");
+
+    // XXX: Once we support only JDK 15+, use a text block for the `expected` string.
+    assertThat(
+            outputDirectory.resolve(
+                "documentation-generator-task-listener-test-DocumentationGeneratorTaskListenerTestClass.json"))
+        .content(UTF_8)
+        .isEqualToIgnoringWhitespace(
+            "{\"className\":\"DocumentationGeneratorTaskListenerTestClass\",\"path\":[\"CLASS: DocumentationGeneratorTaskListenerTestClass\",\"COMPILATION_UNIT\"]}");
+  }
+
+  @Immutable
+  @AutoService(Extractor.class)
+  public static final class TestExtractor implements Extractor<ExtractionParameters> {
+    @Override
+    public String identifier() {
+      return "documentation-generator-task-listener-test";
+    }
+
+    @Override
+    public Optional<ExtractionParameters> tryExtract(ClassTree tree, VisitorState state) {
+      return Optional.of(tree.getSimpleName().toString())
+          .filter(n -> n.contains(DocumentationGeneratorTaskListenerTest.class.getSimpleName()))
+          .map(
+              className ->
+                  new AutoValue_DocumentationGeneratorTaskListenerTest_ExtractionParameters(
+                      className,
+                      Streams.stream(state.getPath())
+                          .map(TestExtractor::describeTree)
+                          .collect(toImmutableList())));
+    }
+
+    private static String describeTree(Tree tree) {
+      return (tree instanceof ClassTree)
+          ? String.join(": ", String.valueOf(tree.getKind()), ((ClassTree) tree).getSimpleName())
+          : tree.getKind().toString();
+    }
+  }
+
+  @AutoValue
+  abstract static class ExtractionParameters {
+    abstract String className();
+
+    abstract ImmutableList<String> path();
+  }
+}

documentation-support/src/test/java/tech/picnic/errorprone/documentation/DocumentationGeneratorTest.java

@@ -0,0 +1,38 @@
+package tech.picnic.errorprone.documentation;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static tech.picnic.errorprone.documentation.DocumentationGenerator.OUTPUT_DIRECTORY_FLAG;
+
+import java.nio.file.InvalidPathException;
+import java.nio.file.Path;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
+
+final class DocumentationGeneratorTest {
+  @ParameterizedTest
+  @ValueSource(strings = {"bar", "foo"})
+  void getOutputPath(String path) {
+    assertThat(DocumentationGenerator.getOutputPath(OUTPUT_DIRECTORY_FLAG + '=' + path))
+        .isEqualTo(Path.of(path));
+  }
+
+  @ParameterizedTest
+  @ValueSource(strings = {"", "-XoutputDirectory", "invalidOption=Test", "nothing"})
+  void getOutputPathWithInvalidArgument(String pathArg) {
+    assertThatThrownBy(() -> DocumentationGenerator.getOutputPath(pathArg))
+        .isInstanceOf(IllegalArgumentException.class)
+        .hasMessage("'%s' must be of the form '%s=<value>'", pathArg, OUTPUT_DIRECTORY_FLAG);
+  }
+
+  @Test
+  void getOutputPathWithInvalidPath() {
+    String basePath = "path-with-null-char-\0";
+    assertThatThrownBy(
+            () -> DocumentationGenerator.getOutputPath(OUTPUT_DIRECTORY_FLAG + '=' + basePath))
+        .isInstanceOf(IllegalArgumentException.class)
+        .hasCauseInstanceOf(InvalidPathException.class)
+        .hasMessageEndingWith("Invalid path '%s'", basePath);
+  }
+}

documentation-support/src/test/resources/tech/picnic/errorprone/documentation/bugpattern-documentation-complete.json

@@ -0,0 +1,19 @@
+{
+  "fullyQualifiedName": "pkg.CompleteBugChecker",
+  "name": "OtherName",
+  "altNames": [
+    "Check"
+  ],
+  "link": "https://error-prone.picnic.tech",
+  "tags": [
+    "Simplification"
+  ],
+  "summary": "CompleteBugChecker summary",
+  "explanation": "Example explanation",
+  "severityLevel": "SUGGESTION",
+  "canDisable": false,
+  "suppressionAnnotations": [
+    "com.google.errorprone.BugPattern",
+    "org.junit.jupiter.api.Test"
+  ]
+}

documentation-support/src/test/resources/tech/picnic/errorprone/documentation/bugpattern-documentation-minimal.json

@@ -0,0 +1,14 @@
+{
+  "fullyQualifiedName": "pkg.MinimalBugChecker",
+  "name": "MinimalBugChecker",
+  "altNames": [],
+  "link": "",
+  "tags": [],
+  "summary": "MinimalBugChecker summary",
+  "explanation": "",
+  "severityLevel": "ERROR",
+  "canDisable": true,
+  "suppressionAnnotations": [
+    "java.lang.SuppressWarnings"
+  ]
+}

documentation-support/src/test/resources/tech/picnic/errorprone/documentation/bugpattern-documentation-undocumented-suppression.json

@@ -0,0 +1,12 @@
+{
+  "fullyQualifiedName": "pkg.UndocumentedSuppressionBugPattern",
+  "name": "UndocumentedSuppressionBugPattern",
+  "altNames": [],
+  "link": "",
+  "tags": [],
+  "summary": "UndocumentedSuppressionBugPattern summary",
+  "explanation": "",
+  "severityLevel": "WARNING",
+  "canDisable": true,
+  "suppressionAnnotations": []
+}

documentation-support/src/test/resources/tech/picnic/errorprone/documentation/bugpattern-test-documentation-identification-and-replacement.json

@@ -0,0 +1,12 @@
+{
+  "name": "TestChecker",
+  "identificationTests": [
+    "class A {}\n"
+  ],
+  "replacementTests": [
+    {
+      "inputLines": "class A {}\n",
+      "outputLines": "class A {}\n"
+    }
+  ]
+}

documentation-support/src/test/resources/tech/picnic/errorprone/documentation/bugpattern-test-documentation-identification-two-sources.json

@@ -0,0 +1,8 @@
+{
+  "name": "TestChecker",
+  "identificationTests": [
+    "class B {}\n",
+    "class A {}\n"
+  ],
+  "replacementTests": []
+}

documentation-support/src/test/resources/tech/picnic/errorprone/documentation/bugpattern-test-documentation-identification.json

@@ -0,0 +1,7 @@
+{
+  "name": "TestChecker",
+  "identificationTests": [
+    "class A {}\n"
+  ],
+  "replacementTests": []
+}

documentation-support/src/test/resources/tech/picnic/errorprone/documentation/bugpattern-test-documentation-minimal.json

@@ -0,0 +1,5 @@
+{
+  "name": "TestChecker",
+  "identificationTests": [],
+  "replacementTests": []
+}

documentation-support/src/test/resources/tech/picnic/errorprone/documentation/bugpattern-test-documentation-multiple-identification-and-replacement.json

@@ -0,0 +1,17 @@
+{
+  "name": "TestChecker",
+  "identificationTests": [
+    "class A {}\n",
+    "class B {}\n"
+  ],
+  "replacementTests": [
+    {
+      "inputLines": "class A {}\n",
+      "outputLines": "class A {}\n"
+    },
+    {
+      "inputLines": "class B {}\n",
+      "outputLines": "class B {}\n"
+    }
+  ]
+}

documentation-support/src/test/resources/tech/picnic/errorprone/documentation/bugpattern-test-documentation-replacement-expect-unchanged.json

@@ -0,0 +1,5 @@
+{
+  "name": "TestChecker",
+  "identificationTests": [],
+  "replacementTests": []
+}

documentation-support/src/test/resources/tech/picnic/errorprone/documentation/bugpattern-test-documentation-replacement-two-sources.json

@@ -0,0 +1,14 @@
+{
+  "name": "TestChecker",
+  "identificationTests": [],
+  "replacementTests": [
+    {
+      "inputLines": "class B {}\n",
+      "outputLines": "class B {}\n"
+    },
+    {
+      "inputLines": "class A {}\n",
+      "outputLines": "class A {}\n"
+    }
+  ]
+}

documentation-support/src/test/resources/tech/picnic/errorprone/documentation/bugpattern-test-documentation-replacement.json

@@ -0,0 +1,10 @@
+{
+  "name": "TestChecker",
+  "identificationTests": [],
+  "replacementTests": [
+    {
+      "inputLines": "class A {}\n",
+      "outputLines": "class A {}\n"
+    }
+  ]
+}

error-prone-contrib/README.md

@@ -267,7 +267,7 @@ Refaster's expressiveness:
   motivating example, see the two subtly different loop definitions in
   `CollectionRemoveAllFromCollectionExpression`.
 - Figure out why Refaster sometimes doesn't match the correct generic overload.
-  See the `AssertThatIterableHasOneComparableElementEqualTo` template for an
+  See the `AssertThatIterableHasOneComparableElementEqualTo` rule for an
   example.
 
 [autorefactor]: https://autorefactor.org

error-prone-contrib/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <groupId>tech.picnic.error-prone-support</groupId>
         <artifactId>error-prone-support</artifactId>
-        <version>0.3.1-SNAPSHOT</version>
+        <version>0.9.1-SNAPSHOT</version>
     </parent>
 
     <artifactId>error-prone-contrib</artifactId>
@@ -37,7 +37,15 @@
         <dependency>
             <groupId>${groupId.error-prone}</groupId>
             <artifactId>error_prone_test_helpers</artifactId>
-            <scope>test</scope>
+            <scope>provided</scope>
+        </dependency>
+        <dependency>
+            <groupId>${project.groupId}</groupId>
+            <artifactId>documentation-support</artifactId>
+            <!-- This dependency is declared only as a hint to Maven that
+            compilation depends on it; see the `maven-compiler-plugin`'s
+            `annotationProcessorPaths` configuration below. -->
+            <scope>provided</scope>
         </dependency>
         <dependency>
             <groupId>${project.groupId}</groupId>
@@ -64,11 +72,6 @@
             <artifactId>auto-service-annotations</artifactId>
             <scope>provided</scope>
         </dependency>
-        <dependency>
-            <groupId>com.google.code.findbugs</groupId>
-            <artifactId>jsr305</artifactId>
-            <scope>provided</scope>
-        </dependency>
         <dependency>
             <groupId>com.google.googlejavaformat</groupId>
             <artifactId>google-java-format</artifactId>
@@ -98,6 +101,11 @@
             <artifactId>reactor-adapter</artifactId>
             <scope>provided</scope>
         </dependency>
+        <dependency>
+            <groupId>io.projectreactor.addons</groupId>
+            <artifactId>reactor-extra</artifactId>
+            <scope>provided</scope>
+        </dependency>
         <dependency>
             <groupId>io.reactivex.rxjava2</groupId>
             <artifactId>rxjava</artifactId>
@@ -146,7 +154,7 @@
         <dependency>
             <groupId>org.junit.jupiter</groupId>
             <artifactId>junit-jupiter-api</artifactId>
-            <scope>test</scope>
+            <scope>provided</scope>
         </dependency>
         <dependency>
             <groupId>org.junit.jupiter</groupId>
@@ -173,6 +181,11 @@
             <artifactId>slf4j-api</artifactId>
             <scope>test</scope>
         </dependency>
+        <dependency>
+            <groupId>org.springframework</groupId>
+            <artifactId>spring-context</artifactId>
+            <scope>test</scope>
+        </dependency>
         <dependency>
             <groupId>org.springframework</groupId>
             <artifactId>spring-test</artifactId>
@@ -208,6 +221,11 @@
                     <artifactId>maven-compiler-plugin</artifactId>
                     <configuration>
                         <annotationProcessorPaths combine.children="append">
+                            <path>
+                                <groupId>${project.groupId}</groupId>
+                                <artifactId>documentation-support</artifactId>
+                                <version>${project.version}</version>
+                            </path>
                             <path>
                                 <groupId>${project.groupId}</groupId>
                                 <artifactId>refaster-compiler</artifactId>
@@ -221,6 +239,7 @@
                         </annotationProcessorPaths>
                         <compilerArgs combine.children="append">
                             <arg>-Xplugin:RefasterRuleCompiler</arg>
+                            <arg>-Xplugin:DocumentationGenerator -XoutputDirectory=${project.build.directory}/docs</arg>
                         </compilerArgs>
                     </configuration>
                 </plugin>

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/AmbiguousJsonCreator.java

@@ -36,6 +36,9 @@ public final class AmbiguousJsonCreator extends BugChecker implements Annotation
   private static final Matcher<AnnotationTree> IS_JSON_CREATOR_ANNOTATION =
       isType("com.fasterxml.jackson.annotation.JsonCreator");
 
+  /** Instantiates a new {@link AmbiguousJsonCreator} instance. */
+  public AmbiguousJsonCreator() {}
+
   @Override
   public Description matchAnnotation(AnnotationTree tree, VisitorState state) {
     if (!IS_JSON_CREATOR_ANNOTATION.matches(tree, state)) {

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/AssertJIsNull.java

@@ -24,7 +24,7 @@ import com.sun.source.tree.MethodInvocationTree;
 /**
  * A {@link BugChecker} that flags AssertJ {@code isEqualTo(null)} checks for simplification.
  *
- * <p>This bug checker cannot be replaced with a simple Refaster template, as the Refaster approach
+ * <p>This bug checker cannot be replaced with a simple Refaster rule, as the Refaster approach
  * would require that all overloads of {@link org.assertj.core.api.Assert#isEqualTo(Object)} (such
  * as {@link org.assertj.core.api.AbstractStringAssert#isEqualTo(String)}) are explicitly
  * enumerated. This bug checker generically matches all such current and future overloads.
@@ -44,6 +44,9 @@ public final class AssertJIsNull extends BugChecker implements MethodInvocationT
           argumentCount(1),
           argument(0, nullLiteral()));
 
+  /** Instantiates a new {@link AssertJIsNull} instance. */
+  public AssertJIsNull() {}
+
   @Override
   public Description matchMethodInvocation(MethodInvocationTree tree, VisitorState state) {
     if (!ASSERT_IS_EQUAL_TO_NULL.matches(tree, state)) {

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/AutowiredConstructor.java

@@ -15,7 +15,6 @@ import com.google.errorprone.BugPattern;
 import com.google.errorprone.VisitorState;
 import com.google.errorprone.bugpatterns.BugChecker;
 import com.google.errorprone.bugpatterns.BugChecker.ClassTreeMatcher;
-import com.google.errorprone.fixes.SuggestedFix;
 import com.google.errorprone.matchers.Description;
 import com.google.errorprone.matchers.MultiMatcher;
 import com.google.errorprone.util.ASTHelpers;
@@ -24,6 +23,7 @@ import com.sun.source.tree.ClassTree;
 import com.sun.source.tree.MethodTree;
 import com.sun.source.tree.Tree;
 import java.util.List;
+import tech.picnic.errorprone.bugpatterns.util.SourceCode;
 
 /** A {@link BugChecker} that flags redundant {@code @Autowired} constructor annotations. */
 @AutoService(BugChecker.class)
@@ -38,6 +38,9 @@ public final class AutowiredConstructor extends BugChecker implements ClassTreeM
   private static final MultiMatcher<Tree, AnnotationTree> AUTOWIRED_ANNOTATION =
       annotations(AT_LEAST_ONE, isType("org.springframework.beans.factory.annotation.Autowired"));
 
+  /** Instantiates a new {@link AutowiredConstructor} instance. */
+  public AutowiredConstructor() {}
+
   @Override
   public Description matchClass(ClassTree tree, VisitorState state) {
     List<MethodTree> constructors = ASTHelpers.getConstructors(tree);
@@ -59,6 +62,6 @@ public final class AutowiredConstructor extends BugChecker implements ClassTreeM
      * leave flagging the unused import to Error Prone's `RemoveUnusedImports` check.
      */
     AnnotationTree annotation = Iterables.getOnlyElement(annotations);
-    return describeMatch(annotation, SuggestedFix.delete(annotation));
+    return describeMatch(annotation, SourceCode.deleteWithTrailingWhitespace(annotation, state));
   }
 }

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/CanonicalAnnotationSyntax.java

@@ -46,6 +46,9 @@ public final class CanonicalAnnotationSyntax extends BugChecker implements Annot
               CanonicalAnnotationSyntax::dropRedundantValueAttribute,
               CanonicalAnnotationSyntax::dropRedundantCurlies);
 
+  /** Instantiates a new {@link CanonicalAnnotationSyntax} instance. */
+  public CanonicalAnnotationSyntax() {}
+
   @Override
   public Description matchAnnotation(AnnotationTree tree, VisitorState state) {
     return FIX_FACTORIES.stream()

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/CollectorMutability.java

@@ -18,6 +18,7 @@ import com.google.errorprone.matchers.Matcher;
 import com.sun.source.tree.ExpressionTree;
 import com.sun.source.tree.MethodInvocationTree;
 import java.util.stream.Collector;
+import tech.picnic.errorprone.bugpatterns.util.ThirdPartyLibrary;
 
 /**
  * A {@link BugChecker} that flags {@link Collector Collectors} that don't clearly express
@@ -45,9 +46,13 @@ public final class CollectorMutability extends BugChecker implements MethodInvoc
   private static final Matcher<ExpressionTree> SET_COLLECTOR =
       staticMethod().anyClass().named("toSet");
 
+  /** Instantiates a new {@link CollectorMutability} instance. */
+  public CollectorMutability() {}
+
   @Override
   public Description matchMethodInvocation(MethodInvocationTree tree, VisitorState state) {
-    if (!COLLECTOR_METHOD.matches(tree, state)) {
+    if (!ThirdPartyLibrary.GUAVA.isIntroductionAllowed(state)
+        || !COLLECTOR_METHOD.matches(tree, state)) {
       return Description.NO_MATCH;
     }
 

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/DirectReturn.java

@@ -0,0 +1,131 @@
+package tech.picnic.errorprone.bugpatterns;
+
+import static com.google.errorprone.BugPattern.LinkType.CUSTOM;
+import static com.google.errorprone.BugPattern.SeverityLevel.SUGGESTION;
+import static com.google.errorprone.BugPattern.StandardTags.SIMPLIFICATION;
+import static com.google.errorprone.matchers.Matchers.allOf;
+import static com.google.errorprone.matchers.Matchers.argument;
+import static com.google.errorprone.matchers.Matchers.isSameType;
+import static com.google.errorprone.matchers.Matchers.isVariable;
+import static com.google.errorprone.matchers.Matchers.not;
+import static com.google.errorprone.matchers.Matchers.returnStatement;
+import static com.google.errorprone.matchers.Matchers.staticMethod;
+import static com.google.errorprone.matchers.Matchers.toType;
+import static tech.picnic.errorprone.bugpatterns.util.Documentation.BUG_PATTERNS_BASE_URL;
+
+import com.google.auto.service.AutoService;
+import com.google.errorprone.BugPattern;
+import com.google.errorprone.VisitorState;
+import com.google.errorprone.bugpatterns.BugChecker;
+import com.google.errorprone.bugpatterns.BugChecker.BlockTreeMatcher;
+import com.google.errorprone.fixes.SuggestedFix;
+import com.google.errorprone.matchers.Description;
+import com.google.errorprone.matchers.Matcher;
+import com.google.errorprone.util.ASTHelpers;
+import com.sun.source.tree.AssignmentTree;
+import com.sun.source.tree.BlockTree;
+import com.sun.source.tree.ExpressionStatementTree;
+import com.sun.source.tree.ExpressionTree;
+import com.sun.source.tree.MethodInvocationTree;
+import com.sun.source.tree.ReturnTree;
+import com.sun.source.tree.StatementTree;
+import com.sun.source.tree.Tree;
+import com.sun.source.tree.VariableTree;
+import com.sun.tools.javac.code.Symbol;
+import java.util.List;
+import java.util.Optional;
+import tech.picnic.errorprone.bugpatterns.util.MoreASTHelpers;
+import tech.picnic.errorprone.bugpatterns.util.SourceCode;
+
+/**
+ * A {@link BugChecker} that flags unnecessary local variable assignments preceding a return
+ * statement.
+ */
+@AutoService(BugChecker.class)
+@BugPattern(
+    summary = "Variable assignment is redundant; value can be returned directly",
+    link = BUG_PATTERNS_BASE_URL + "DirectReturn",
+    linkType = CUSTOM,
+    severity = SUGGESTION,
+    tags = SIMPLIFICATION)
+public final class DirectReturn extends BugChecker implements BlockTreeMatcher {
+  private static final long serialVersionUID = 1L;
+  private static final Matcher<StatementTree> VARIABLE_RETURN = returnStatement(isVariable());
+  private static final Matcher<ExpressionTree> MOCKITO_MOCK_OR_SPY_WITH_IMPLICIT_TYPE =
+      allOf(
+          not(toType(MethodInvocationTree.class, argument(0, isSameType(Class.class.getName())))),
+          staticMethod().onClass("org.mockito.Mockito").namedAnyOf("mock", "spy"));
+
+  /** Instantiates a new {@link DirectReturn} instance. */
+  public DirectReturn() {}
+
+  @Override
+  public Description matchBlock(BlockTree tree, VisitorState state) {
+    List<? extends StatementTree> statements = tree.getStatements();
+    if (statements.size() < 2) {
+      return Description.NO_MATCH;
+    }
+
+    StatementTree finalStatement = statements.get(statements.size() - 1);
+    if (!VARIABLE_RETURN.matches(finalStatement, state)) {
+      return Description.NO_MATCH;
+    }
+
+    Symbol variableSymbol = ASTHelpers.getSymbol(((ReturnTree) finalStatement).getExpression());
+    StatementTree precedingStatement = statements.get(statements.size() - 2);
+
+    return tryMatchAssignment(variableSymbol, precedingStatement)
+        .filter(resultExpr -> canInlineToReturnStatement(resultExpr, state))
+        .map(
+            resultExpr ->
+                describeMatch(
+                    precedingStatement,
+                    SuggestedFix.builder()
+                        .replace(
+                            precedingStatement,
+                            String.format("return %s;", SourceCode.treeToString(resultExpr, state)))
+                        .delete(finalStatement)
+                        .build()))
+        .orElse(Description.NO_MATCH);
+  }
+
+  private static Optional<ExpressionTree> tryMatchAssignment(Symbol targetSymbol, Tree tree) {
+    if (tree instanceof ExpressionStatementTree) {
+      return tryMatchAssignment(targetSymbol, ((ExpressionStatementTree) tree).getExpression());
+    }
+
+    if (tree instanceof AssignmentTree) {
+      AssignmentTree assignment = (AssignmentTree) tree;
+      return targetSymbol.equals(ASTHelpers.getSymbol(assignment.getVariable()))
+          ? Optional.of(assignment.getExpression())
+          : Optional.empty();
+    }
+
+    if (tree instanceof VariableTree) {
+      VariableTree declaration = (VariableTree) tree;
+      return declaration.getModifiers().getAnnotations().isEmpty()
+              && targetSymbol.equals(ASTHelpers.getSymbol(declaration))
+          ? Optional.ofNullable(declaration.getInitializer())
+          : Optional.empty();
+    }
+
+    return Optional.empty();
+  }
+
+  /**
+   * Tells whether inlining the given expression to the associated return statement can be done
+   * safely.
+   *
+   * <p>Inlining is generally safe, but in rare cases the operation may have a functional impact.
+   * The sole case considered here is the inlining of a Mockito mock or spy construction without an
+   * explicit type. In such a case the type created depends on context, such as the method's return
+   * type.
+   */
+  private static boolean canInlineToReturnStatement(
+      ExpressionTree expressionTree, VisitorState state) {
+    return !MOCKITO_MOCK_OR_SPY_WITH_IMPLICIT_TYPE.matches(expressionTree, state)
+        || MoreASTHelpers.findMethodExitedOnReturn(state)
+            .filter(m -> MoreASTHelpers.areSameType(expressionTree, m.getReturnType(), state))
+            .isPresent();
+  }
+}

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/EmptyMethod.java

@@ -14,7 +14,6 @@ import com.google.errorprone.BugPattern;
 import com.google.errorprone.VisitorState;
 import com.google.errorprone.bugpatterns.BugChecker;
 import com.google.errorprone.bugpatterns.BugChecker.MethodTreeMatcher;
-import com.google.errorprone.fixes.SuggestedFix;
 import com.google.errorprone.matchers.Description;
 import com.google.errorprone.matchers.Matcher;
 import com.google.errorprone.util.ASTHelpers;
@@ -22,6 +21,7 @@ import com.sun.source.tree.ClassTree;
 import com.sun.source.tree.MethodTree;
 import com.sun.source.tree.Tree;
 import java.util.Optional;
+import tech.picnic.errorprone.bugpatterns.util.SourceCode;
 
 /** A {@link BugChecker} that flags empty methods that seemingly can simply be deleted. */
 @AutoService(BugChecker.class)
@@ -38,6 +38,9 @@ public final class EmptyMethod extends BugChecker implements MethodTreeMatcher {
           AT_LEAST_ONE,
           anyOf(isType("java.lang.Override"), isType("org.aspectj.lang.annotation.Pointcut")));
 
+  /** Instantiates a new {@link EmptyMethod} instance. */
+  public EmptyMethod() {}
+
   @Override
   public Description matchMethod(MethodTree tree, VisitorState state) {
     if (tree.getBody() == null
@@ -52,7 +55,7 @@ public final class EmptyMethod extends BugChecker implements MethodTreeMatcher {
       return Description.NO_MATCH;
     }
 
-    return describeMatch(tree, SuggestedFix.delete(tree));
+    return describeMatch(tree, SourceCode.deleteWithTrailingWhitespace(tree, state));
   }
 
   private static boolean isInPossibleTestHelperClass(VisitorState state) {

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/ErrorProneTestHelperSourceFormat.java

@@ -72,6 +72,9 @@ public final class ErrorProneTestHelperSourceFormat extends BugChecker
           .onDescendantOf("com.google.errorprone.BugCheckerRefactoringTestHelper.ExpectOutput")
           .named("addOutputLines");
 
+  /** Instantiates a new {@link ErrorProneTestHelperSourceFormat} instance. */
+  public ErrorProneTestHelperSourceFormat() {}
+
   @Override
   public Description matchMethodInvocation(MethodInvocationTree tree, VisitorState state) {
     boolean isOutputSource = OUTPUT_SOURCE_ACCEPTING_METHOD.matches(tree, state);
@@ -149,7 +152,7 @@ public final class ErrorProneTestHelperSourceFormat extends BugChecker
     StringBuilder source = new StringBuilder();
 
     for (ExpressionTree sourceLine : sourceLines) {
-      Object value = ASTHelpers.constValue(sourceLine);
+      String value = ASTHelpers.constValue(sourceLine, String.class);
       if (value == null) {
         return Optional.empty();
       }

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/ExplicitEnumOrdering.java

@@ -46,6 +46,9 @@ public final class ExplicitEnumOrdering extends BugChecker implements MethodInvo
   private static final Matcher<ExpressionTree> EXPLICIT_ORDERING =
       staticMethod().onClass(Ordering.class.getName()).named("explicit");
 
+  /** Instantiates a new {@link ExplicitEnumOrdering} instance. */
+  public ExplicitEnumOrdering() {}
+
   @Override
   public Description matchMethodInvocation(MethodInvocationTree tree, VisitorState state) {
     if (!EXPLICIT_ORDERING.matches(tree, state)) {
@@ -86,6 +89,6 @@ public final class ExplicitEnumOrdering extends BugChecker implements MethodInvo
   private static Stream<String> getMissingEnumValues(Type enumType, Set<String> values) {
     Symbol.TypeSymbol typeSymbol = enumType.asElement();
     return Sets.difference(ASTHelpers.enumValues(typeSymbol), values).stream()
-        .map(v -> String.format("%s.%s", typeSymbol.getSimpleName(), v));
+        .map(v -> String.join(".", typeSymbol.getSimpleName(), v));
   }
 }

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/FluxFlatMapUsage.java

@@ -5,6 +5,10 @@ import static com.google.errorprone.BugPattern.SeverityLevel.ERROR;
 import static com.google.errorprone.BugPattern.StandardTags.LIKELY_ERROR;
 import static com.google.errorprone.matchers.method.MethodMatchers.instanceMethod;
 import static tech.picnic.errorprone.bugpatterns.util.Documentation.BUG_PATTERNS_BASE_URL;
+import static tech.picnic.errorprone.bugpatterns.util.MoreTypes.generic;
+import static tech.picnic.errorprone.bugpatterns.util.MoreTypes.subOf;
+import static tech.picnic.errorprone.bugpatterns.util.MoreTypes.type;
+import static tech.picnic.errorprone.bugpatterns.util.MoreTypes.unbound;
 
 import com.google.auto.service.AutoService;
 import com.google.common.collect.Iterables;
@@ -17,11 +21,14 @@ import com.google.errorprone.fixes.SuggestedFix;
 import com.google.errorprone.fixes.SuggestedFixes;
 import com.google.errorprone.matchers.Description;
 import com.google.errorprone.matchers.Matcher;
+import com.google.errorprone.suppliers.Supplier;
+import com.google.errorprone.suppliers.Suppliers;
+import com.google.errorprone.util.ASTHelpers;
 import com.sun.source.tree.ExpressionTree;
 import com.sun.source.tree.MemberReferenceTree;
 import com.sun.source.tree.MethodInvocationTree;
+import com.sun.tools.javac.code.Type;
 import java.util.function.Function;
-import java.util.function.Supplier;
 import reactor.core.publisher.Flux;
 
 /**
@@ -33,11 +40,12 @@ import reactor.core.publisher.Flux;
  * former interleaves values as they are emitted, yielding nondeterministic results. In most cases
  * {@link Flux#concatMap(Function)} should be preferred, as it produces consistent results and
  * avoids potentially saturating the thread pool on which subscription happens. If {@code
- * concatMap}'s single-subscription semantics are undesirable one should invoke a {@code flatMap} or
- * {@code flatMapSequential} overload with an explicit concurrency level.
+ * concatMap}'s sequential-subscription semantics are undesirable one should invoke a {@code
+ * flatMap} or {@code flatMapSequential} overload with an explicit concurrency level.
  *
- * <p>NB: The rarely-used overload {@link Flux#flatMap(Function, Function, Supplier)} is not flagged
- * by this check because there is no clear alternative to point to.
+ * <p>NB: The rarely-used overload {@link Flux#flatMap(Function, Function,
+ * java.util.function.Supplier)} is not flagged by this check because there is no clear alternative
+ * to point to.
  */
 @AutoService(BugChecker.class)
 @BugPattern(
@@ -52,11 +60,19 @@ public final class FluxFlatMapUsage extends BugChecker
     implements MethodInvocationTreeMatcher, MemberReferenceTreeMatcher {
   private static final long serialVersionUID = 1L;
   private static final String MAX_CONCURRENCY_ARG_NAME = "MAX_CONCURRENCY";
+  private static final Supplier<Type> FLUX =
+      Suppliers.typeFromString("reactor.core.publisher.Flux");
   private static final Matcher<ExpressionTree> FLUX_FLATMAP =
       instanceMethod()
-          .onDescendantOf("reactor.core.publisher.Flux")
+          .onDescendantOf(FLUX)
           .namedAnyOf("flatMap", "flatMapSequential")
           .withParameters(Function.class.getName());
+  private static final Supplier<Type> FLUX_OF_PUBLISHERS =
+      VisitorState.memoize(
+          generic(FLUX, subOf(generic(type("org.reactivestreams.Publisher"), unbound()))));
+
+  /** Instantiates a new {@link FluxFlatMapUsage} instance. */
+  public FluxFlatMapUsage() {}
 
   @Override
   public Description matchMethodInvocation(MethodInvocationTree tree, VisitorState state) {
@@ -64,14 +80,27 @@ public final class FluxFlatMapUsage extends BugChecker
       return Description.NO_MATCH;
     }
 
-    return buildDescription(tree)
-        .addFix(SuggestedFixes.renameMethodInvocation(tree, "concatMap", state))
-        .addFix(
-            SuggestedFix.builder()
-                .postfixWith(
-                    Iterables.getOnlyElement(tree.getArguments()), ", " + MAX_CONCURRENCY_ARG_NAME)
-                .build())
-        .build();
+    SuggestedFix serializationFix = SuggestedFixes.renameMethodInvocation(tree, "concatMap", state);
+    SuggestedFix concurrencyCapFix =
+        SuggestedFix.builder()
+            .postfixWith(
+                Iterables.getOnlyElement(tree.getArguments()), ", " + MAX_CONCURRENCY_ARG_NAME)
+            .build();
+
+    Description.Builder description = buildDescription(tree);
+
+    if (state.getTypes().isSubtype(ASTHelpers.getType(tree), FLUX_OF_PUBLISHERS.get(state))) {
+      /*
+       * Nested publishers may need to be subscribed to eagerly in order to avoid a deadlock, e.g.
+       * if they are produced by `Flux#groupBy`. In this case we suggest specifying an explicit
+       * concurrently bound, in favour of sequential subscriptions using `Flux#concatMap`.
+       */
+      description.addFix(concurrencyCapFix).addFix(serializationFix);
+    } else {
+      description.addFix(serializationFix).addFix(concurrencyCapFix);
+    }
+
+    return description.build();
   }
 
   @Override

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/FluxImplicitBlock.java

@@ -0,0 +1,100 @@
+package tech.picnic.errorprone.bugpatterns;
+
+import static com.google.common.base.Preconditions.checkState;
+import static com.google.errorprone.BugPattern.LinkType.CUSTOM;
+import static com.google.errorprone.BugPattern.SeverityLevel.WARNING;
+import static com.google.errorprone.BugPattern.StandardTags.CONCURRENCY;
+import static com.google.errorprone.BugPattern.StandardTags.PERFORMANCE;
+import static com.google.errorprone.matchers.method.MethodMatchers.instanceMethod;
+import static tech.picnic.errorprone.bugpatterns.util.Documentation.BUG_PATTERNS_BASE_URL;
+
+import com.google.auto.service.AutoService;
+import com.google.errorprone.BugPattern;
+import com.google.errorprone.VisitorState;
+import com.google.errorprone.bugpatterns.BugChecker;
+import com.google.errorprone.bugpatterns.BugChecker.MethodInvocationTreeMatcher;
+import com.google.errorprone.fixes.SuggestedFix;
+import com.google.errorprone.fixes.SuggestedFixes;
+import com.google.errorprone.matchers.Description;
+import com.google.errorprone.matchers.Matcher;
+import com.google.errorprone.suppliers.Supplier;
+import com.google.errorprone.suppliers.Suppliers;
+import com.google.errorprone.util.ASTHelpers;
+import com.sun.source.tree.ExpressionTree;
+import com.sun.source.tree.MethodInvocationTree;
+import com.sun.tools.javac.code.Type;
+import com.sun.tools.javac.util.Position;
+import java.util.stream.Stream;
+import tech.picnic.errorprone.bugpatterns.util.ThirdPartyLibrary;
+
+/**
+ * A {@link BugChecker} that flags {@link reactor.core.publisher.Flux} operator usages that may
+ * implicitly cause the calling thread to be blocked.
+ *
+ * <p>Note that the methods flagged here are not themselves blocking, but iterating over the
+ * resulting {@link Iterable} or {@link Stream} may be.
+ */
+@AutoService(BugChecker.class)
+@BugPattern(
+    summary = "Avoid iterating over `Flux`es in an implicitly blocking manner",
+    link = BUG_PATTERNS_BASE_URL + "FluxImplicitBlock",
+    linkType = CUSTOM,
+    severity = WARNING,
+    tags = {CONCURRENCY, PERFORMANCE})
+public final class FluxImplicitBlock extends BugChecker implements MethodInvocationTreeMatcher {
+  private static final long serialVersionUID = 1L;
+  private static final Matcher<ExpressionTree> FLUX_WITH_IMPLICIT_BLOCK =
+      instanceMethod()
+          .onDescendantOf("reactor.core.publisher.Flux")
+          .namedAnyOf("toIterable", "toStream")
+          .withNoParameters();
+  private static final Supplier<Type> STREAM = Suppliers.typeFromString(Stream.class.getName());
+
+  /** Instantiates a new {@link FluxImplicitBlock} instance. */
+  public FluxImplicitBlock() {}
+
+  @Override
+  public Description matchMethodInvocation(MethodInvocationTree tree, VisitorState state) {
+    if (!FLUX_WITH_IMPLICIT_BLOCK.matches(tree, state)) {
+      return Description.NO_MATCH;
+    }
+
+    Description.Builder description =
+        buildDescription(tree).addFix(SuggestedFixes.addSuppressWarnings(state, canonicalName()));
+    if (ThirdPartyLibrary.GUAVA.isIntroductionAllowed(state)) {
+      description.addFix(
+          suggestBlockingElementCollection(
+              tree, "com.google.common.collect.ImmutableList.toImmutableList", state));
+    }
+    description.addFix(
+        suggestBlockingElementCollection(tree, "java.util.stream.Collectors.toList", state));
+
+    return description.build();
+  }
+
+  private static SuggestedFix suggestBlockingElementCollection(
+      MethodInvocationTree tree, String fullyQualifiedCollectorMethod, VisitorState state) {
+    SuggestedFix.Builder importSuggestion = SuggestedFix.builder();
+    String replacementMethodInvocation =
+        SuggestedFixes.qualifyStaticImport(fullyQualifiedCollectorMethod, importSuggestion, state);
+
+    boolean isStream =
+        ASTHelpers.isSubtype(ASTHelpers.getResultType(tree), STREAM.get(state), state);
+    String replacement =
+        String.format(
+            ".collect(%s()).block()%s", replacementMethodInvocation, isStream ? ".stream()" : "");
+    return importSuggestion.merge(replaceMethodInvocation(tree, replacement, state)).build();
+  }
+
+  private static SuggestedFix.Builder replaceMethodInvocation(
+      MethodInvocationTree tree, String replacement, VisitorState state) {
+    int startPosition = state.getEndPosition(ASTHelpers.getReceiver(tree));
+    int endPosition = state.getEndPosition(tree);
+
+    checkState(
+        startPosition != Position.NOPOS && endPosition != Position.NOPOS,
+        "Cannot locate method to be replaced in source code");
+
+    return SuggestedFix.builder().replace(startPosition, endPosition, replacement);
+  }
+}

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/FormatStringConcatenation.java

@@ -32,7 +32,7 @@ import com.sun.source.util.SimpleTreeVisitor;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Optional;
-import javax.annotation.Nullable;
+import org.jspecify.annotations.Nullable;
 import tech.picnic.errorprone.bugpatterns.util.SourceCode;
 
 /**
@@ -48,7 +48,7 @@ import tech.picnic.errorprone.bugpatterns.util.SourceCode;
 // `Formattable#toString` invocation with a `Formattable#formatTo` invocation. But likely that
 // should be considered a bug fix, too.
 // XXX: Introduce a separate check that adds/removes the `Locale` parameter to `String.format`
-// invocations, as necessary.
+// invocations, as necessary. See also a comment in the `StringJoin` check.
 @AutoService(BugChecker.class)
 @BugPattern(
     summary = "Defer string concatenation to the invoked method",
@@ -129,6 +129,9 @@ public final class FormatStringConcatenation extends BugChecker
           .onDescendantOf("org.slf4j.Logger")
           .namedAnyOf("debug", "error", "info", "trace", "warn");
 
+  /** Instantiates a new {@link FormatStringConcatenation} instance. */
+  public FormatStringConcatenation() {}
+
   @Override
   public Description matchMethodInvocation(MethodInvocationTree tree, VisitorState state) {
     if (hasNonConstantStringConcatenationArgument(tree, 0, state)) {
@@ -204,7 +207,7 @@ public final class FormatStringConcatenation extends BugChecker
   }
 
   private static class ReplacementArgumentsConstructor
-      extends SimpleTreeVisitor<Void, VisitorState> {
+      extends SimpleTreeVisitor<@Nullable Void, VisitorState> {
     private final StringBuilder formatString = new StringBuilder();
     private final List<Tree> formatArguments = new ArrayList<>();
     private final String formatSpecifier;
@@ -213,9 +216,8 @@ public final class FormatStringConcatenation extends BugChecker
       this.formatSpecifier = formatSpecifier;
     }
 
-    @Nullable
     @Override
-    public Void visitBinary(BinaryTree tree, VisitorState state) {
+    public @Nullable Void visitBinary(BinaryTree tree, VisitorState state) {
       if (tree.getKind() == Kind.PLUS && isStringTyped(tree, state)) {
         tree.getLeftOperand().accept(this, state);
         tree.getRightOperand().accept(this, state);
@@ -226,15 +228,13 @@ public final class FormatStringConcatenation extends BugChecker
       return null;
     }
 
-    @Nullable
     @Override
-    public Void visitParenthesized(ParenthesizedTree tree, VisitorState state) {
+    public @Nullable Void visitParenthesized(ParenthesizedTree tree, VisitorState state) {
       return tree.getExpression().accept(this, state);
     }
 
-    @Nullable
     @Override
-    protected Void defaultAction(Tree tree, VisitorState state) {
+    protected @Nullable Void defaultAction(Tree tree, VisitorState state) {
       appendExpression(tree);
       return null;
     }

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/IdentityConversion.java

@@ -23,6 +23,7 @@ import com.google.errorprone.matchers.Matcher;
 import com.google.errorprone.util.ASTHelpers;
 import com.google.errorprone.util.ASTHelpers.TargetType;
 import com.sun.source.tree.ExpressionTree;
+import com.sun.source.tree.MemberSelectTree;
 import com.sun.source.tree.MethodInvocationTree;
 import com.sun.tools.javac.code.Type;
 import com.sun.tools.javac.code.Types;
@@ -32,7 +33,7 @@ import tech.picnic.errorprone.bugpatterns.util.SourceCode;
 
 /** A {@link BugChecker} that flags redundant identity conversions. */
 // XXX: Consider detecting cases where a flagged expression is passed to a method, and where removal
-// of the identify conversion would cause a different method overload to be selected. Depending on
+// of the identity conversion would cause a different method overload to be selected. Depending on
 // the target method such a modification may change the code's semantics or performance.
 @AutoService(BugChecker.class)
 @BugPattern(
@@ -45,6 +46,13 @@ public final class IdentityConversion extends BugChecker implements MethodInvoca
   private static final long serialVersionUID = 1L;
   private static final Matcher<ExpressionTree> IS_CONVERSION_METHOD =
       anyOf(
+          staticMethod()
+              .onClassAny(
+                  Primitives.allWrapperTypes().stream()
+                      .map(Class::getName)
+                      .collect(toImmutableSet()))
+              .named("valueOf"),
+          staticMethod().onClass(String.class.getName()).named("valueOf"),
           staticMethod()
               .onClassAny(
                   "com.google.common.collect.ImmutableBiMap",
@@ -60,18 +68,17 @@ public final class IdentityConversion extends BugChecker implements MethodInvoca
                   "com.google.common.collect.ImmutableTable")
               .named("copyOf"),
           staticMethod()
-              .onClassAny(
-                  Primitives.allWrapperTypes().stream()
-                      .map(Class::getName)
-                      .collect(toImmutableSet()))
-              .named("valueOf"),
-          staticMethod().onClass(String.class.getName()).named("valueOf"),
+              .onClass("com.google.errorprone.matchers.Matchers")
+              .namedAnyOf("allOf", "anyOf"),
           staticMethod().onClass("reactor.adapter.rxjava.RxJava2Adapter"),
           staticMethod()
               .onClass("reactor.core.publisher.Flux")
               .namedAnyOf("concat", "firstWithSignal", "from", "merge"),
           staticMethod().onClass("reactor.core.publisher.Mono").namedAnyOf("from", "fromDirect"));
 
+  /** Instantiates a new {@link IdentityConversion} instance. */
+  public IdentityConversion() {}
+
   @Override
   public Description matchMethodInvocation(MethodInvocationTree tree, VisitorState state) {
     List<? extends ExpressionTree> arguments = tree.getArguments();
@@ -92,6 +99,15 @@ public final class IdentityConversion extends BugChecker implements MethodInvoca
       return Description.NO_MATCH;
     }
 
+    if (sourceType.isPrimitive()
+        && state.getPath().getParentPath().getLeaf() instanceof MemberSelectTree) {
+      /*
+       * The result of the conversion method is dereferenced, while the source type is a primitive:
+       * dropping the conversion would yield uncompilable code.
+       */
+      return Description.NO_MATCH;
+    }
+
     return buildDescription(tree)
         .setMessage(
             "This method invocation appears redundant; remove it or suppress this warning and "

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/ImmutablesSortedSetComparator.java

@@ -67,6 +67,9 @@ public final class ImmutablesSortedSetComparator extends BugChecker implements M
                   hasAnnotation("org.immutables.value.Value.NaturalOrder"),
                   hasAnnotation("org.immutables.value.Value.ReverseOrder"))));
 
+  /** Instantiates a new {@link ImmutablesSortedSetComparator} instance. */
+  public ImmutablesSortedSetComparator() {}
+
   @Override
   public Description matchMethod(MethodTree tree, VisitorState state) {
     if (!METHOD_LACKS_ANNOTATION.matches(tree, state)) {

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/IsInstanceLambdaUsage.java

@@ -0,0 +1,60 @@
+package tech.picnic.errorprone.bugpatterns;
+
+import static com.google.errorprone.BugPattern.LinkType.CUSTOM;
+import static com.google.errorprone.BugPattern.SeverityLevel.SUGGESTION;
+import static com.google.errorprone.BugPattern.StandardTags.SIMPLIFICATION;
+import static tech.picnic.errorprone.bugpatterns.util.Documentation.BUG_PATTERNS_BASE_URL;
+
+import com.google.auto.service.AutoService;
+import com.google.common.collect.Iterables;
+import com.google.errorprone.BugPattern;
+import com.google.errorprone.VisitorState;
+import com.google.errorprone.bugpatterns.BugChecker;
+import com.google.errorprone.bugpatterns.BugChecker.LambdaExpressionTreeMatcher;
+import com.google.errorprone.fixes.SuggestedFix;
+import com.google.errorprone.matchers.Description;
+import com.google.errorprone.util.ASTHelpers;
+import com.sun.source.tree.InstanceOfTree;
+import com.sun.source.tree.LambdaExpressionTree;
+import com.sun.source.tree.Tree.Kind;
+import com.sun.source.tree.VariableTree;
+import tech.picnic.errorprone.bugpatterns.util.SourceCode;
+
+/**
+ * A {@link BugChecker} that flags lambda expressions that can be replaced with a method reference
+ * of the form {@code T.class::isInstance}.
+ *
+ * @see MethodReferenceUsage
+ */
+// XXX: Consider folding this logic into the `MethodReferenceUsage` check.
+@AutoService(BugChecker.class)
+@BugPattern(
+    summary = "Prefer `Class::isInstance` method reference over equivalent lambda expression",
+    link = BUG_PATTERNS_BASE_URL + "IsInstanceLambdaUsage",
+    linkType = CUSTOM,
+    severity = SUGGESTION,
+    tags = SIMPLIFICATION)
+public final class IsInstanceLambdaUsage extends BugChecker implements LambdaExpressionTreeMatcher {
+  private static final long serialVersionUID = 1L;
+
+  /** Instantiates a new {@link IsInstanceLambdaUsage} instance. */
+  public IsInstanceLambdaUsage() {}
+
+  @Override
+  public Description matchLambdaExpression(LambdaExpressionTree tree, VisitorState state) {
+    if (tree.getParameters().size() != 1 || tree.getBody().getKind() != Kind.INSTANCE_OF) {
+      return Description.NO_MATCH;
+    }
+
+    VariableTree param = Iterables.getOnlyElement(tree.getParameters());
+    InstanceOfTree instanceOf = (InstanceOfTree) tree.getBody();
+    if (!ASTHelpers.getSymbol(param).equals(ASTHelpers.getSymbol(instanceOf.getExpression()))) {
+      return Description.NO_MATCH;
+    }
+
+    return describeMatch(
+        tree,
+        SuggestedFix.replace(
+            tree, SourceCode.treeToString(instanceOf.getType(), state) + ".class::isInstance"));
+  }
+}

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/JUnitClassModifiers.java

@@ -0,0 +1,82 @@
+package tech.picnic.errorprone.bugpatterns;
+
+import static com.google.errorprone.BugPattern.LinkType.CUSTOM;
+import static com.google.errorprone.BugPattern.SeverityLevel.SUGGESTION;
+import static com.google.errorprone.BugPattern.StandardTags.STYLE;
+import static com.google.errorprone.matchers.ChildMultiMatcher.MatchType.AT_LEAST_ONE;
+import static com.google.errorprone.matchers.Matchers.allOf;
+import static com.google.errorprone.matchers.Matchers.annotations;
+import static com.google.errorprone.matchers.Matchers.anyOf;
+import static com.google.errorprone.matchers.Matchers.hasMethod;
+import static com.google.errorprone.matchers.Matchers.hasModifier;
+import static com.google.errorprone.matchers.Matchers.isType;
+import static com.google.errorprone.matchers.Matchers.not;
+import static tech.picnic.errorprone.bugpatterns.util.Documentation.BUG_PATTERNS_BASE_URL;
+import static tech.picnic.errorprone.bugpatterns.util.MoreJUnitMatchers.TEST_METHOD;
+import static tech.picnic.errorprone.bugpatterns.util.MoreMatchers.hasMetaAnnotation;
+
+import com.google.auto.service.AutoService;
+import com.google.common.collect.ImmutableSet;
+import com.google.errorprone.BugPattern;
+import com.google.errorprone.VisitorState;
+import com.google.errorprone.bugpatterns.BugChecker;
+import com.google.errorprone.bugpatterns.BugChecker.ClassTreeMatcher;
+import com.google.errorprone.fixes.SuggestedFix;
+import com.google.errorprone.fixes.SuggestedFixes;
+import com.google.errorprone.matchers.Description;
+import com.google.errorprone.matchers.Matcher;
+import com.sun.source.tree.ClassTree;
+import javax.lang.model.element.Modifier;
+
+/**
+ * A {@link BugChecker} that flags non-final and non package-private JUnit test class declarations,
+ * unless abstract.
+ */
+@AutoService(BugChecker.class)
+@BugPattern(
+    summary = "Non-abstract JUnit test classes should be declared package-private and final",
+    linkType = CUSTOM,
+    link = BUG_PATTERNS_BASE_URL + "JUnitClassModifiers",
+    severity = SUGGESTION,
+    tags = STYLE)
+public final class JUnitClassModifiers extends BugChecker implements ClassTreeMatcher {
+  private static final long serialVersionUID = 1L;
+  private static final Matcher<ClassTree> HAS_SPRING_CONFIGURATION_ANNOTATION =
+      annotations(
+          AT_LEAST_ONE,
+          anyOf(
+              isType("org.springframework.context.annotation.Configuration"),
+              hasMetaAnnotation("org.springframework.context.annotation.Configuration")));
+  private static final Matcher<ClassTree> TEST_CLASS_WITH_INCORRECT_MODIFIERS =
+      allOf(
+          hasMethod(TEST_METHOD),
+          not(hasModifier(Modifier.ABSTRACT)),
+          anyOf(
+              hasModifier(Modifier.PRIVATE),
+              hasModifier(Modifier.PROTECTED),
+              hasModifier(Modifier.PUBLIC),
+              allOf(not(hasModifier(Modifier.FINAL)), not(HAS_SPRING_CONFIGURATION_ANNOTATION))));
+
+  /** Instantiates a new {@link JUnitClassModifiers} instance. */
+  public JUnitClassModifiers() {}
+
+  @Override
+  public Description matchClass(ClassTree tree, VisitorState state) {
+    if (!TEST_CLASS_WITH_INCORRECT_MODIFIERS.matches(tree, state)) {
+      return Description.NO_MATCH;
+    }
+
+    SuggestedFix.Builder fixBuilder = SuggestedFix.builder();
+    SuggestedFixes.removeModifiers(
+            tree.getModifiers(),
+            state,
+            ImmutableSet.of(Modifier.PRIVATE, Modifier.PROTECTED, Modifier.PUBLIC))
+        .ifPresent(fixBuilder::merge);
+
+    if (!HAS_SPRING_CONFIGURATION_ANNOTATION.matches(tree, state)) {
+      SuggestedFixes.addModifiers(tree, state, Modifier.FINAL).ifPresent(fixBuilder::merge);
+    }
+
+    return describeMatch(tree, fixBuilder.build());
+  }
+}

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/JUnitMethodDeclaration.java

@@ -3,19 +3,18 @@ package tech.picnic.errorprone.bugpatterns;
 import static com.google.errorprone.BugPattern.LinkType.CUSTOM;
 import static com.google.errorprone.BugPattern.SeverityLevel.SUGGESTION;
 import static com.google.errorprone.BugPattern.StandardTags.SIMPLIFICATION;
-import static com.google.errorprone.matchers.ChildMultiMatcher.MatchType.AT_LEAST_ONE;
 import static com.google.errorprone.matchers.Matchers.allOf;
-import static com.google.errorprone.matchers.Matchers.annotations;
-import static com.google.errorprone.matchers.Matchers.anyOf;
 import static com.google.errorprone.matchers.Matchers.enclosingClass;
 import static com.google.errorprone.matchers.Matchers.hasModifier;
-import static com.google.errorprone.matchers.Matchers.isType;
+import static com.google.errorprone.matchers.Matchers.not;
 import static java.util.function.Predicate.not;
 import static tech.picnic.errorprone.bugpatterns.util.Documentation.BUG_PATTERNS_BASE_URL;
-import static tech.picnic.errorprone.bugpatterns.util.JavaKeywords.isReservedKeyword;
+import static tech.picnic.errorprone.bugpatterns.util.MoreJUnitMatchers.SETUP_OR_TEARDOWN_METHOD;
+import static tech.picnic.errorprone.bugpatterns.util.MoreJUnitMatchers.TEST_METHOD;
 
 import com.google.auto.service.AutoService;
 import com.google.common.collect.ImmutableSet;
+import com.google.common.collect.Sets;
 import com.google.errorprone.BugPattern;
 import com.google.errorprone.VisitorState;
 import com.google.errorprone.bugpatterns.BugChecker;
@@ -24,20 +23,12 @@ import com.google.errorprone.fixes.SuggestedFix;
 import com.google.errorprone.fixes.SuggestedFixes;
 import com.google.errorprone.matchers.Description;
 import com.google.errorprone.matchers.Matcher;
-import com.google.errorprone.matchers.Matchers;
-import com.google.errorprone.matchers.MultiMatcher;
-import com.google.errorprone.predicates.TypePredicate;
 import com.google.errorprone.util.ASTHelpers;
-import com.sun.source.tree.AnnotationTree;
-import com.sun.source.tree.ClassTree;
-import com.sun.source.tree.ImportTree;
 import com.sun.source.tree.MethodTree;
-import com.sun.source.tree.Tree;
-import com.sun.tools.javac.code.Symbol;
+import com.sun.tools.javac.code.Symbol.MethodSymbol;
 import java.util.Optional;
 import javax.lang.model.element.Modifier;
-import javax.lang.model.element.Name;
-import tech.picnic.errorprone.bugpatterns.util.SourceCode;
+import tech.picnic.errorprone.bugpatterns.util.ConflictDetection;
 
 /** A {@link BugChecker} that flags non-canonical JUnit method declarations. */
 // XXX: Consider introducing a class-level check that enforces that test classes:
@@ -56,32 +47,19 @@ public final class JUnitMethodDeclaration extends BugChecker implements MethodTr
   private static final long serialVersionUID = 1L;
   private static final String TEST_PREFIX = "test";
   private static final ImmutableSet<Modifier> ILLEGAL_MODIFIERS =
-      ImmutableSet.of(Modifier.PRIVATE, Modifier.PROTECTED, Modifier.PUBLIC);
-  private static final Matcher<MethodTree> HAS_UNMODIFIABLE_SIGNATURE =
-      anyOf(
-          annotations(AT_LEAST_ONE, isType("java.lang.Override")),
-          allOf(
-              Matchers.not(hasModifier(Modifier.FINAL)),
-              Matchers.not(hasModifier(Modifier.PRIVATE)),
-              enclosingClass(hasModifier(Modifier.ABSTRACT))));
-  private static final MultiMatcher<MethodTree, AnnotationTree> TEST_METHOD =
-      annotations(
-          AT_LEAST_ONE,
-          anyOf(
-              isType("org.junit.jupiter.api.Test"),
-              hasMetaAnnotation("org.junit.jupiter.api.TestTemplate")));
-  private static final MultiMatcher<MethodTree, AnnotationTree> SETUP_OR_TEARDOWN_METHOD =
-      annotations(
-          AT_LEAST_ONE,
-          anyOf(
-              isType("org.junit.jupiter.api.AfterAll"),
-              isType("org.junit.jupiter.api.AfterEach"),
-              isType("org.junit.jupiter.api.BeforeAll"),
-              isType("org.junit.jupiter.api.BeforeEach")));
+      Sets.immutableEnumSet(Modifier.PRIVATE, Modifier.PROTECTED, Modifier.PUBLIC);
+  private static final Matcher<MethodTree> IS_LIKELY_OVERRIDDEN =
+      allOf(
+          not(hasModifier(Modifier.FINAL)),
+          not(hasModifier(Modifier.PRIVATE)),
+          enclosingClass(hasModifier(Modifier.ABSTRACT)));
+
+  /** Instantiates a new {@link JUnitMethodDeclaration} instance. */
+  public JUnitMethodDeclaration() {}
 
   @Override
   public Description matchMethod(MethodTree tree, VisitorState state) {
-    if (HAS_UNMODIFIABLE_SIGNATURE.matches(tree, state)) {
+    if (IS_LIKELY_OVERRIDDEN.matches(tree, state) || isOverride(tree, state)) {
       return Description.NO_MATCH;
     }
 
@@ -103,10 +81,11 @@ public final class JUnitMethodDeclaration extends BugChecker implements MethodTr
 
   private void suggestTestMethodRenameIfApplicable(
       MethodTree tree, SuggestedFix.Builder fixBuilder, VisitorState state) {
-    tryCanonicalizeMethodName(tree)
+    MethodSymbol symbol = ASTHelpers.getSymbol(tree);
+    tryCanonicalizeMethodName(symbol)
         .ifPresent(
             newName ->
-                findMethodRenameBlocker(newName, state)
+                ConflictDetection.findMethodRenameBlocker(symbol, newName, state)
                     .ifPresentOrElse(
                         blocker -> reportMethodRenameBlocker(tree, blocker, state),
                         () -> fixBuilder.merge(SuggestedFixes.renameMethod(tree, newName, state))));
@@ -122,63 +101,8 @@ public final class JUnitMethodDeclaration extends BugChecker implements MethodTr
             .build());
   }
 
-  /**
-   * If applicable, returns a human-readable argument against assigning the given name to an
-   * existing method.
-   *
-   * <p>This method implements imperfect heuristics. Things it currently does not consider include
-   * the following:
-   *
-   * <ul>
-   *   <li>Whether the rename would merely introduce a method overload, rather than clashing with an
-   *       existing method declaration.
-   *   <li>Whether the rename would cause a method in a superclass to be overridden.
-   *   <li>Whether the rename would in fact clash with a static import. (It could be that a static
-   *       import of the same name is only referenced from lexical scopes in which the method under
-   *       consideration cannot be referenced directly.)
-   * </ul>
-   */
-  private static Optional<String> findMethodRenameBlocker(String methodName, VisitorState state) {
-    if (isMethodInEnclosingClass(methodName, state)) {
-      return Optional.of(
-          String.format("a method named `%s` already exists in this class", methodName));
-    }
-
-    if (isSimpleNameStaticallyImported(methodName, state)) {
-      return Optional.of(String.format("`%s` is already statically imported", methodName));
-    }
-
-    if (isReservedKeyword(methodName)) {
-      return Optional.of(String.format("`%s` is a reserved keyword", methodName));
-    }
-
-    return Optional.empty();
-  }
-
-  private static boolean isMethodInEnclosingClass(String methodName, VisitorState state) {
-    return state.findEnclosing(ClassTree.class).getMembers().stream()
-        .filter(MethodTree.class::isInstance)
-        .map(MethodTree.class::cast)
-        .map(MethodTree::getName)
-        .map(Name::toString)
-        .anyMatch(methodName::equals);
-  }
-
-  private static boolean isSimpleNameStaticallyImported(String simpleName, VisitorState state) {
-    return state.getPath().getCompilationUnit().getImports().stream()
-        .filter(ImportTree::isStatic)
-        .map(ImportTree::getQualifiedIdentifier)
-        .map(tree -> getStaticImportSimpleName(tree, state))
-        .anyMatch(simpleName::contentEquals);
-  }
-
-  private static CharSequence getStaticImportSimpleName(Tree tree, VisitorState state) {
-    String source = SourceCode.treeToString(tree, state);
-    return source.subSequence(source.lastIndexOf('.') + 1, source.length());
-  }
-
-  private static Optional<String> tryCanonicalizeMethodName(MethodTree tree) {
-    return Optional.of(ASTHelpers.getSymbol(tree).getQualifiedName().toString())
+  private static Optional<String> tryCanonicalizeMethodName(MethodSymbol symbol) {
+    return Optional.of(symbol.getQualifiedName().toString())
         .filter(name -> name.startsWith(TEST_PREFIX))
         .map(name -> name.substring(TEST_PREFIX.length()))
         .filter(not(String::isEmpty))
@@ -186,17 +110,9 @@ public final class JUnitMethodDeclaration extends BugChecker implements MethodTr
         .filter(name -> !Character.isDigit(name.charAt(0)));
   }
 
-  // XXX: Move to a `MoreMatchers` utility class.
-  private static Matcher<AnnotationTree> hasMetaAnnotation(String annotationClassName) {
-    TypePredicate typePredicate = hasAnnotation(annotationClassName);
-    return (tree, state) -> {
-      Symbol sym = ASTHelpers.getSymbol(tree);
-      return sym != null && typePredicate.apply(sym.type, state);
-    };
-  }
-
-  // XXX: Move to a `MoreTypePredicates` utility class.
-  private static TypePredicate hasAnnotation(String annotationClassName) {
-    return (type, state) -> ASTHelpers.hasAnnotation(type.tsym, annotationClassName, state);
+  private static boolean isOverride(MethodTree tree, VisitorState state) {
+    return ASTHelpers.streamSuperMethods(ASTHelpers.getSymbol(tree), state.getTypes())
+        .findAny()
+        .isPresent();
   }
 }

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/JUnitValueSource.java

@@ -0,0 +1,307 @@
+package tech.picnic.errorprone.bugpatterns;
+
+import static com.google.errorprone.BugPattern.LinkType.CUSTOM;
+import static com.google.errorprone.BugPattern.SeverityLevel.SUGGESTION;
+import static com.google.errorprone.BugPattern.StandardTags.SIMPLIFICATION;
+import static com.google.errorprone.matchers.ChildMultiMatcher.MatchType.ALL;
+import static com.google.errorprone.matchers.ChildMultiMatcher.MatchType.AT_LEAST_ONE;
+import static com.google.errorprone.matchers.Matchers.allOf;
+import static com.google.errorprone.matchers.Matchers.anyOf;
+import static com.google.errorprone.matchers.Matchers.anything;
+import static com.google.errorprone.matchers.Matchers.argument;
+import static com.google.errorprone.matchers.Matchers.argumentCount;
+import static com.google.errorprone.matchers.Matchers.classLiteral;
+import static com.google.errorprone.matchers.Matchers.hasArguments;
+import static com.google.errorprone.matchers.Matchers.isPrimitiveOrBoxedPrimitiveType;
+import static com.google.errorprone.matchers.Matchers.isSameType;
+import static com.google.errorprone.matchers.Matchers.methodHasParameters;
+import static com.google.errorprone.matchers.Matchers.staticMethod;
+import static com.google.errorprone.matchers.Matchers.toType;
+import static java.util.function.Predicate.not;
+import static java.util.stream.Collectors.joining;
+import static tech.picnic.errorprone.bugpatterns.util.Documentation.BUG_PATTERNS_BASE_URL;
+import static tech.picnic.errorprone.bugpatterns.util.MoreJUnitMatchers.HAS_METHOD_SOURCE;
+import static tech.picnic.errorprone.bugpatterns.util.MoreJUnitMatchers.getMethodSourceFactoryNames;
+
+import com.google.auto.service.AutoService;
+import com.google.common.collect.Iterables;
+import com.google.errorprone.BugPattern;
+import com.google.errorprone.VisitorState;
+import com.google.errorprone.bugpatterns.BugChecker;
+import com.google.errorprone.bugpatterns.BugChecker.MethodTreeMatcher;
+import com.google.errorprone.fixes.SuggestedFix;
+import com.google.errorprone.matchers.Description;
+import com.google.errorprone.matchers.Matcher;
+import com.google.errorprone.util.ASTHelpers;
+import com.sun.source.tree.AnnotationTree;
+import com.sun.source.tree.ClassTree;
+import com.sun.source.tree.ExpressionTree;
+import com.sun.source.tree.LambdaExpressionTree;
+import com.sun.source.tree.MethodInvocationTree;
+import com.sun.source.tree.MethodTree;
+import com.sun.source.tree.NewArrayTree;
+import com.sun.source.tree.ReturnTree;
+import com.sun.source.util.TreeScanner;
+import com.sun.tools.javac.code.Type;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.List;
+import java.util.Locale;
+import java.util.Optional;
+import java.util.Set;
+import java.util.function.Predicate;
+import java.util.stream.DoubleStream;
+import java.util.stream.IntStream;
+import java.util.stream.LongStream;
+import java.util.stream.Stream;
+import org.jspecify.annotations.Nullable;
+import tech.picnic.errorprone.bugpatterns.util.SourceCode;
+
+/**
+ * A {@link BugChecker} that flags JUnit tests with a {@link
+ * org.junit.jupiter.params.provider.MethodSource} annotation that can be replaced with an
+ * equivalent {@link org.junit.jupiter.params.provider.ValueSource} annotation.
+ */
+// XXX: Where applicable, also flag `@MethodSource` annotations that reference multiple value
+// factory methods (or that repeat the same value factory method multiple times).
+// XXX: Support inlining of overloaded value factory methods.
+// XXX: Support inlining of value factory methods referenced by multiple `@MethodSource`
+// annotations.
+// XXX: Support value factory return expressions of the form `Stream.of(a, b,
+// c).map(Arguments::argument)`.
+// XXX: Support simplification of test methods that accept additional injected parameters such as
+// `TestInfo`; such parameters should be ignored for the purpose of this check.
+@AutoService(BugChecker.class)
+@BugPattern(
+    summary = "Prefer `@ValueSource` over a `@MethodSource` where possible and reasonable",
+    linkType = CUSTOM,
+    link = BUG_PATTERNS_BASE_URL + "JUnitValueSource",
+    severity = SUGGESTION,
+    tags = SIMPLIFICATION)
+public final class JUnitValueSource extends BugChecker implements MethodTreeMatcher {
+  private static final long serialVersionUID = 1L;
+  private static final Matcher<ExpressionTree> SUPPORTED_VALUE_FACTORY_VALUES =
+      anyOf(
+          isArrayArgumentValueCandidate(),
+          toType(
+              MethodInvocationTree.class,
+              allOf(
+                  staticMethod()
+                      .onClass("org.junit.jupiter.params.provider.Arguments")
+                      .namedAnyOf("arguments", "of"),
+                  argumentCount(1),
+                  argument(0, isArrayArgumentValueCandidate()))));
+  private static final Matcher<ExpressionTree> ARRAY_OF_SUPPORTED_SINGLE_VALUE_ARGUMENTS =
+      isSingleDimensionArrayCreationWithAllElementsMatching(SUPPORTED_VALUE_FACTORY_VALUES);
+  private static final Matcher<ExpressionTree> ENUMERATION_OF_SUPPORTED_SINGLE_VALUE_ARGUMENTS =
+      toType(
+          MethodInvocationTree.class,
+          allOf(
+              staticMethod()
+                  .onClassAny(
+                      Stream.class.getName(),
+                      IntStream.class.getName(),
+                      LongStream.class.getName(),
+                      DoubleStream.class.getName(),
+                      List.class.getName(),
+                      Set.class.getName(),
+                      "com.google.common.collect.ImmutableList",
+                      "com.google.common.collect.ImmutableSet")
+                  .named("of"),
+              hasArguments(AT_LEAST_ONE, anything()),
+              hasArguments(ALL, SUPPORTED_VALUE_FACTORY_VALUES)));
+  private static final Matcher<MethodTree> IS_UNARY_METHOD_WITH_SUPPORTED_PARAMETER =
+      methodHasParameters(
+          anyOf(
+              isPrimitiveOrBoxedPrimitiveType(),
+              isSameType(String.class),
+              isSameType(state -> state.getSymtab().classType)));
+
+  /** Instantiates a new {@link JUnitValueSource} instance. */
+  public JUnitValueSource() {}
+
+  @Override
+  public Description matchMethod(MethodTree tree, VisitorState state) {
+    if (!IS_UNARY_METHOD_WITH_SUPPORTED_PARAMETER.matches(tree, state)) {
+      return Description.NO_MATCH;
+    }
+
+    Type parameterType = ASTHelpers.getType(Iterables.getOnlyElement(tree.getParameters()));
+
+    return findMethodSourceAnnotation(tree, state)
+        .flatMap(
+            methodSourceAnnotation ->
+                getSoleLocalFactoryName(methodSourceAnnotation, tree)
+                    .filter(factory -> !hasSiblingReferencingValueFactory(tree, factory, state))
+                    .flatMap(factory -> findSiblingWithName(tree, factory, state))
+                    .flatMap(
+                        factoryMethod ->
+                            tryConstructValueSourceFix(
+                                parameterType, methodSourceAnnotation, factoryMethod, state))
+                    .map(fix -> describeMatch(methodSourceAnnotation, fix)))
+        .orElse(Description.NO_MATCH);
+  }
+
+  /**
+   * Returns the name of the value factory method pointed to by the given {@code @MethodSource}
+   * annotation, if it (a) is the only one and (b) is a method in the same class as the annotated
+   * method.
+   */
+  private static Optional<String> getSoleLocalFactoryName(
+      AnnotationTree methodSourceAnnotation, MethodTree method) {
+    return getElementIfSingleton(getMethodSourceFactoryNames(methodSourceAnnotation, method))
+        .filter(name -> name.indexOf('#') < 0);
+  }
+
+  /**
+   * Tells whether the given method has a sibling method in the same class that depends on the
+   * specified value factory method.
+   */
+  private static boolean hasSiblingReferencingValueFactory(
+      MethodTree tree, String valueFactory, VisitorState state) {
+    return findMatchingSibling(tree, m -> hasValueFactory(m, valueFactory, state), state)
+        .isPresent();
+  }
+
+  private static Optional<MethodTree> findSiblingWithName(
+      MethodTree tree, String methodName, VisitorState state) {
+    return findMatchingSibling(tree, m -> m.getName().contentEquals(methodName), state);
+  }
+
+  private static Optional<MethodTree> findMatchingSibling(
+      MethodTree tree, Predicate<? super MethodTree> predicate, VisitorState state) {
+    return state.findEnclosing(ClassTree.class).getMembers().stream()
+        .filter(MethodTree.class::isInstance)
+        .map(MethodTree.class::cast)
+        .filter(not(tree::equals))
+        .filter(predicate)
+        .findFirst();
+  }
+
+  private static boolean hasValueFactory(
+      MethodTree tree, String valueFactoryMethodName, VisitorState state) {
+    return findMethodSourceAnnotation(tree, state).stream()
+        .anyMatch(
+            annotation ->
+                getMethodSourceFactoryNames(annotation, tree).contains(valueFactoryMethodName));
+  }
+
+  private static Optional<AnnotationTree> findMethodSourceAnnotation(
+      MethodTree tree, VisitorState state) {
+    return HAS_METHOD_SOURCE.multiMatchResult(tree, state).matchingNodes().stream().findFirst();
+  }
+
+  private static Optional<SuggestedFix> tryConstructValueSourceFix(
+      Type parameterType,
+      AnnotationTree methodSourceAnnotation,
+      MethodTree valueFactoryMethod,
+      VisitorState state) {
+    return getSingleReturnExpression(valueFactoryMethod)
+        .flatMap(expression -> tryExtractValueSourceAttributeValue(expression, state))
+        .map(
+            valueSourceAttributeValue ->
+                SuggestedFix.builder()
+                    .addImport("org.junit.jupiter.params.provider.ValueSource")
+                    .replace(
+                        methodSourceAnnotation,
+                        String.format(
+                            "@ValueSource(%s = %s)",
+                            toValueSourceAttributeName(parameterType), valueSourceAttributeValue))
+                    .delete(valueFactoryMethod)
+                    .build());
+  }
+
+  // XXX: This pattern also occurs a few times inside Error Prone; contribute upstream.
+  private static Optional<ExpressionTree> getSingleReturnExpression(MethodTree methodTree) {
+    List<ExpressionTree> returnExpressions = new ArrayList<>();
+    new TreeScanner<@Nullable Void, @Nullable Void>() {
+      @Override
+      public @Nullable Void visitClass(ClassTree node, @Nullable Void unused) {
+        /* Ignore `return` statements inside anonymous/local classes. */
+        return null;
+      }
+
+      @Override
+      public @Nullable Void visitReturn(ReturnTree node, @Nullable Void unused) {
+        returnExpressions.add(node.getExpression());
+        return super.visitReturn(node, unused);
+      }
+
+      @Override
+      public @Nullable Void visitLambdaExpression(
+          LambdaExpressionTree node, @Nullable Void unused) {
+        /* Ignore `return` statements inside lambda expressions. */
+        return null;
+      }
+    }.scan(methodTree, null);
+
+    return getElementIfSingleton(returnExpressions);
+  }
+
+  private static Optional<String> tryExtractValueSourceAttributeValue(
+      ExpressionTree tree, VisitorState state) {
+    List<? extends ExpressionTree> arguments;
+    if (ENUMERATION_OF_SUPPORTED_SINGLE_VALUE_ARGUMENTS.matches(tree, state)) {
+      arguments = ((MethodInvocationTree) tree).getArguments();
+    } else if (ARRAY_OF_SUPPORTED_SINGLE_VALUE_ARGUMENTS.matches(tree, state)) {
+      arguments = ((NewArrayTree) tree).getInitializers();
+    } else {
+      return Optional.empty();
+    }
+
+    /*
+     * Join the values into a comma-separated string, unwrapping `Arguments` factory method
+     * invocations if applicable.
+     */
+    return Optional.of(
+            arguments.stream()
+                .map(
+                    arg ->
+                        arg instanceof MethodInvocationTree
+                            ? Iterables.getOnlyElement(((MethodInvocationTree) arg).getArguments())
+                            : arg)
+                .map(argument -> SourceCode.treeToString(argument, state))
+                .collect(joining(", ")))
+        .map(value -> arguments.size() > 1 ? String.format("{%s}", value) : value);
+  }
+
+  private static String toValueSourceAttributeName(Type type) {
+    String typeString = type.tsym.name.toString();
+
+    switch (typeString) {
+      case "Class":
+        return "classes";
+      case "Character":
+        return "chars";
+      case "Integer":
+        return "ints";
+      default:
+        return typeString.toLowerCase(Locale.ROOT) + 's';
+    }
+  }
+
+  private static <T> Optional<T> getElementIfSingleton(Collection<T> collection) {
+    return Optional.of(collection)
+        .filter(elements -> elements.size() == 1)
+        .map(Iterables::getOnlyElement);
+  }
+
+  private static Matcher<ExpressionTree> isSingleDimensionArrayCreationWithAllElementsMatching(
+      Matcher<? super ExpressionTree> elementMatcher) {
+    return (tree, state) -> {
+      if (!(tree instanceof NewArrayTree)) {
+        return false;
+      }
+
+      NewArrayTree newArray = (NewArrayTree) tree;
+      return newArray.getDimensions().isEmpty()
+          && !newArray.getInitializers().isEmpty()
+          && newArray.getInitializers().stream()
+              .allMatch(element -> elementMatcher.matches(element, state));
+    };
+  }
+
+  private static Matcher<ExpressionTree> isArrayArgumentValueCandidate() {
+    return anyOf(classLiteral(anything()), (tree, state) -> ASTHelpers.constValue(tree) != null);
+  }
+}

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/LexicographicalAnnotationAttributeListing.java

@@ -1,5 +1,6 @@
 package tech.picnic.errorprone.bugpatterns;
 
+import static com.google.common.collect.ImmutableList.toImmutableList;
 import static com.google.errorprone.BugPattern.LinkType.CUSTOM;
 import static com.google.errorprone.BugPattern.SeverityLevel.SUGGESTION;
 import static com.google.errorprone.BugPattern.StandardTags.STYLE;
@@ -9,6 +10,7 @@ import static java.util.stream.Collectors.joining;
 import static tech.picnic.errorprone.bugpatterns.util.Documentation.BUG_PATTERNS_BASE_URL;
 
 import com.google.auto.service.AutoService;
+import com.google.common.base.Splitter;
 import com.google.common.collect.Comparators;
 import com.google.common.collect.ImmutableList;
 import com.google.common.collect.ImmutableSet;
@@ -38,8 +40,9 @@ import java.util.List;
 import java.util.Optional;
 import java.util.Set;
 import java.util.stream.Stream;
-import javax.annotation.Nullable;
+import org.jspecify.annotations.Nullable;
 import tech.picnic.errorprone.bugpatterns.util.AnnotationAttributeMatcher;
+import tech.picnic.errorprone.bugpatterns.util.Flags;
 import tech.picnic.errorprone.bugpatterns.util.SourceCode;
 
 /**
@@ -71,10 +74,16 @@ public final class LexicographicalAnnotationAttributeListing extends BugChecker
   private static final String FLAG_PREFIX = "LexicographicalAnnotationAttributeListing:";
   private static final String INCLUDED_ANNOTATIONS_FLAG = FLAG_PREFIX + "Includes";
   private static final String EXCLUDED_ANNOTATIONS_FLAG = FLAG_PREFIX + "Excludes";
+  /**
+   * The splitter applied to string-typed annotation arguments prior to lexicographical sorting. By
+   * splitting on {@code =}, strings that represent e.g. inline Spring property declarations are
+   * properly sorted by key, then value.
+   */
+  private static final Splitter STRING_ARGUMENT_SPLITTER = Splitter.on('=');
 
   private final AnnotationAttributeMatcher matcher;
 
-  /** Instantiates the default {@link LexicographicalAnnotationAttributeListing}. */
+  /** Instantiates a default {@link LexicographicalAnnotationAttributeListing} instance. */
   public LexicographicalAnnotationAttributeListing() {
     this(ErrorProneFlags.empty());
   }
@@ -126,7 +135,7 @@ public final class LexicographicalAnnotationAttributeListing extends BugChecker
     }
 
     List<? extends ExpressionTree> actualOrdering = array.getInitializers();
-    ImmutableList<? extends ExpressionTree> desiredOrdering = doSort(actualOrdering, state);
+    ImmutableList<? extends ExpressionTree> desiredOrdering = doSort(actualOrdering);
     if (actualOrdering.equals(desiredOrdering)) {
       /* In the (presumably) common case the elements are already sorted. */
       return Optional.empty();
@@ -156,12 +165,12 @@ public final class LexicographicalAnnotationAttributeListing extends BugChecker
   }
 
   private static ImmutableList<? extends ExpressionTree> doSort(
-      Iterable<? extends ExpressionTree> elements, VisitorState state) {
+      Iterable<? extends ExpressionTree> elements) {
     // XXX: Perhaps we should use `Collator` with `.setStrength(Collator.PRIMARY)` and
     // `getCollationKey`. Not clear whether that's worth the hassle at this point.
     return ImmutableList.sortedCopyOf(
         comparing(
-            e -> getStructure(e, state),
+            LexicographicalAnnotationAttributeListing::getStructure,
             Comparators.lexicographical(
                 Comparators.lexicographical(
                     String.CASE_INSENSITIVE_ORDER.thenComparing(naturalOrder())))),
@@ -173,38 +182,31 @@ public final class LexicographicalAnnotationAttributeListing extends BugChecker
    * performed. This approach disregards e.g. irrelevant whitespace. It also allows special
    * structure within string literals to be respected.
    */
-  private static ImmutableList<ImmutableList<String>> getStructure(
-      ExpressionTree array, VisitorState state) {
+  private static ImmutableList<ImmutableList<String>> getStructure(ExpressionTree array) {
     ImmutableList.Builder<ImmutableList<String>> nodes = ImmutableList.builder();
 
-    new TreeScanner<Void, Void>() {
-      @Nullable
+    new TreeScanner<@Nullable Void, @Nullable Void>() {
       @Override
-      public Void visitIdentifier(IdentifierTree node, @Nullable Void ctx) {
-        nodes.add(tokenize(node));
-        return super.visitIdentifier(node, ctx);
+      public @Nullable Void visitIdentifier(IdentifierTree node, @Nullable Void unused) {
+        nodes.add(ImmutableList.of(node.getName().toString()));
+        return super.visitIdentifier(node, unused);
       }
 
-      @Nullable
       @Override
-      public Void visitLiteral(LiteralTree node, @Nullable Void ctx) {
-        nodes.add(tokenize(node));
-        return super.visitLiteral(node, ctx);
+      public @Nullable Void visitLiteral(LiteralTree node, @Nullable Void unused) {
+        Object value = ASTHelpers.constValue(node);
+        nodes.add(
+            value instanceof String
+                ? STRING_ARGUMENT_SPLITTER.splitToStream((String) value).collect(toImmutableList())
+                : ImmutableList.of(String.valueOf(value)));
+
+        return super.visitLiteral(node, unused);
       }
 
-      @Nullable
       @Override
-      public Void visitPrimitiveType(PrimitiveTypeTree node, @Nullable Void ctx) {
-        nodes.add(tokenize(node));
-        return super.visitPrimitiveType(node, ctx);
-      }
-
-      private ImmutableList<String> tokenize(Tree node) {
-        /*
-         * Tokens are split on `=` so that e.g. inline Spring property declarations are properly
-         * sorted by key, then value.
-         */
-        return ImmutableList.copyOf(SourceCode.treeToString(node, state).split("=", -1));
+      public @Nullable Void visitPrimitiveType(PrimitiveTypeTree node, @Nullable Void unused) {
+        nodes.add(ImmutableList.of(node.getPrimitiveTypeKind().toString()));
+        return super.visitPrimitiveType(node, unused);
       }
     }.scan(array, null);
 
@@ -219,7 +221,7 @@ public final class LexicographicalAnnotationAttributeListing extends BugChecker
 
   private static ImmutableList<String> excludedAnnotations(ErrorProneFlags flags) {
     Set<String> exclusions = new HashSet<>();
-    flags.getList(EXCLUDED_ANNOTATIONS_FLAG).ifPresent(exclusions::addAll);
+    exclusions.addAll(Flags.getList(flags, EXCLUDED_ANNOTATIONS_FLAG));
     exclusions.addAll(BLACKLISTED_ANNOTATIONS);
     return ImmutableList.copyOf(exclusions);
   }

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/LexicographicalAnnotationListing.java

@@ -4,10 +4,13 @@ import static com.google.common.collect.ImmutableList.toImmutableList;
 import static com.google.errorprone.BugPattern.LinkType.CUSTOM;
 import static com.google.errorprone.BugPattern.SeverityLevel.SUGGESTION;
 import static com.google.errorprone.BugPattern.StandardTags.STYLE;
+import static com.sun.tools.javac.code.TypeAnnotations.AnnotationType.DECLARATION;
+import static com.sun.tools.javac.code.TypeAnnotations.AnnotationType.TYPE;
 import static java.util.Comparator.comparing;
 import static tech.picnic.errorprone.bugpatterns.util.Documentation.BUG_PATTERNS_BASE_URL;
 
 import com.google.auto.service.AutoService;
+import com.google.common.base.VerifyException;
 import com.google.common.collect.ImmutableList;
 import com.google.common.collect.Streams;
 import com.google.errorprone.BugPattern;
@@ -17,10 +20,14 @@ import com.google.errorprone.bugpatterns.BugChecker.MethodTreeMatcher;
 import com.google.errorprone.fixes.Fix;
 import com.google.errorprone.fixes.SuggestedFix;
 import com.google.errorprone.matchers.Description;
+import com.google.errorprone.util.ASTHelpers;
 import com.sun.source.tree.AnnotationTree;
 import com.sun.source.tree.MethodTree;
+import com.sun.tools.javac.code.Symbol;
+import com.sun.tools.javac.code.TypeAnnotations.AnnotationType;
+import java.util.Comparator;
 import java.util.List;
-import java.util.Optional;
+import org.jspecify.annotations.Nullable;
 import tech.picnic.errorprone.bugpatterns.util.SourceCode;
 
 /**
@@ -39,6 +46,12 @@ import tech.picnic.errorprone.bugpatterns.util.SourceCode;
 public final class LexicographicalAnnotationListing extends BugChecker
     implements MethodTreeMatcher {
   private static final long serialVersionUID = 1L;
+  private static final Comparator<@Nullable AnnotationType> BY_ANNOTATION_TYPE =
+      (a, b) ->
+          (a == null || a == DECLARATION) && b == TYPE ? -1 : a == TYPE && b == DECLARATION ? 1 : 0;
+
+  /** Instantiates a new {@link LexicographicalAnnotationListing} instance. */
+  public LexicographicalAnnotationListing() {}
 
   @Override
   public Description matchMethod(MethodTree tree, VisitorState state) {
@@ -47,26 +60,29 @@ public final class LexicographicalAnnotationListing extends BugChecker
       return Description.NO_MATCH;
     }
 
-    ImmutableList<? extends AnnotationTree> sortedAnnotations = sort(originalOrdering, state);
+    ImmutableList<? extends AnnotationTree> sortedAnnotations =
+        sort(originalOrdering, ASTHelpers.getSymbol(tree), state);
     if (originalOrdering.equals(sortedAnnotations)) {
       return Description.NO_MATCH;
     }
 
-    Optional<Fix> fix = tryFixOrdering(originalOrdering, sortedAnnotations, state);
-
-    Description.Builder description = buildDescription(originalOrdering.get(0));
-    fix.ifPresent(description::addFix);
-    return description.build();
+    return describeMatch(
+        originalOrdering.get(0), fixOrdering(originalOrdering, sortedAnnotations, state));
   }
 
   private static ImmutableList<? extends AnnotationTree> sort(
-      List<? extends AnnotationTree> annotations, VisitorState state) {
+      List<? extends AnnotationTree> annotations, Symbol symbol, VisitorState state) {
     return annotations.stream()
-        .sorted(comparing(annotation -> SourceCode.treeToString(annotation, state)))
+        .sorted(
+            comparing(
+                    (AnnotationTree annotation) ->
+                        ASTHelpers.getAnnotationType(annotation, symbol, state),
+                    BY_ANNOTATION_TYPE)
+                .thenComparing(annotation -> SourceCode.treeToString(annotation, state)))
         .collect(toImmutableList());
   }
 
-  private static Optional<Fix> tryFixOrdering(
+  private static Fix fixOrdering(
       List<? extends AnnotationTree> originalAnnotations,
       ImmutableList<? extends AnnotationTree> sortedAnnotations,
       VisitorState state) {
@@ -77,6 +93,7 @@ public final class LexicographicalAnnotationListing extends BugChecker
                 SuggestedFix.builder()
                     .replace(original, SourceCode.treeToString(replacement, state)))
         .reduce(SuggestedFix.Builder::merge)
-        .map(SuggestedFix.Builder::build);
+        .map(SuggestedFix.Builder::build)
+        .orElseThrow(() -> new VerifyException("No annotations were provided"));
   }
 }

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/MethodReferenceUsage.java

@@ -37,6 +37,8 @@ import javax.lang.model.element.Name;
 
 /**
  * A {@link BugChecker} that flags lambda expressions that can be replaced with method references.
+ *
+ * @see IsInstanceLambdaUsage
  */
 // XXX: Other custom expressions we could rewrite:
 // - `a -> "str" + a` to `"str"::concat`. But only if `str` is provably non-null.
@@ -50,6 +52,9 @@ import javax.lang.model.element.Name;
 // `not(some::reference)`.
 // XXX: This check is extremely inefficient due to its reliance on `SuggestedFixes.compilesWithFix`.
 // Palantir's `LambdaMethodReference` check seems to suffer a similar issue at this time.
+// XXX: Expressions of the form `i -> SomeType.class.isInstance(i)` are not replaced; fix that using
+// a suitable generalization.
+// XXX: Consider folding the `IsInstanceLambdaUsage` check into this class.
 @AutoService(BugChecker.class)
 @BugPattern(
     summary = "Prefer method references over lambda expressions",
@@ -60,6 +65,9 @@ import javax.lang.model.element.Name;
 public final class MethodReferenceUsage extends BugChecker implements LambdaExpressionTreeMatcher {
   private static final long serialVersionUID = 1L;
 
+  /** Instantiates a new {@link MethodReferenceUsage} instance. */
+  public MethodReferenceUsage() {}
+
   @Override
   public Description matchLambdaExpression(LambdaExpressionTree tree, VisitorState state) {
     /*
@@ -122,7 +130,7 @@ public final class MethodReferenceUsage extends BugChecker implements LambdaExpr
           return Optional.empty();
         }
         Symbol sym = ASTHelpers.getSymbol(methodSelect);
-        if (!sym.isStatic()) {
+        if (!ASTHelpers.isStatic(sym)) {
           return constructFix(lambdaExpr, "this", methodSelect);
         }
         return constructFix(lambdaExpr, sym.owner, methodSelect);
@@ -192,7 +200,7 @@ public final class MethodReferenceUsage extends BugChecker implements LambdaExpr
     Name sName = target.getSimpleName();
     Optional<SuggestedFix.Builder> fix = constructFix(lambdaExpr, sName, methodName);
 
-    if (!"java.lang".equals(target.packge().toString())) {
+    if (!"java.lang".equals(ASTHelpers.enclosingPackage(target).toString())) {
       Name fqName = target.getQualifiedName();
       if (!sName.equals(fqName)) {
         return fix.map(b -> b.addImport(fqName.toString()));

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/MissingRefasterAnnotation.java

@@ -25,7 +25,7 @@ import com.sun.source.tree.Tree;
 /** A {@link BugChecker} that flags likely missing Refaster annotations. */
 @AutoService(BugChecker.class)
 @BugPattern(
-    summary = "The Refaster template contains a method without any Refaster annotations",
+    summary = "The Refaster rule contains a method without any Refaster annotations",
     link = BUG_PATTERNS_BASE_URL + "MissingRefasterAnnotation",
     linkType = CUSTOM,
     severity = WARNING,
@@ -40,6 +40,9 @@ public final class MissingRefasterAnnotation extends BugChecker implements Class
               isType("com.google.errorprone.refaster.annotation.BeforeTemplate"),
               isType("com.google.errorprone.refaster.annotation.AfterTemplate")));
 
+  /** Instantiates a new {@link MissingRefasterAnnotation} instance. */
+  public MissingRefasterAnnotation() {}
+
   @Override
   public Description matchClass(ClassTree tree, VisitorState state) {
     long methodTypes =

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/MockitoMockClassReference.java

@@ -0,0 +1,86 @@
+package tech.picnic.errorprone.bugpatterns;
+
+import static com.google.errorprone.BugPattern.LinkType.CUSTOM;
+import static com.google.errorprone.BugPattern.SeverityLevel.SUGGESTION;
+import static com.google.errorprone.BugPattern.StandardTags.SIMPLIFICATION;
+import static com.google.errorprone.matchers.Matchers.allOf;
+import static com.google.errorprone.matchers.Matchers.argument;
+import static com.google.errorprone.matchers.Matchers.isSameType;
+import static com.google.errorprone.matchers.Matchers.isVariable;
+import static com.google.errorprone.matchers.Matchers.not;
+import static com.google.errorprone.matchers.Matchers.staticMethod;
+import static tech.picnic.errorprone.bugpatterns.util.Documentation.BUG_PATTERNS_BASE_URL;
+
+import com.google.auto.service.AutoService;
+import com.google.errorprone.BugPattern;
+import com.google.errorprone.VisitorState;
+import com.google.errorprone.bugpatterns.BugChecker;
+import com.google.errorprone.bugpatterns.BugChecker.MethodInvocationTreeMatcher;
+import com.google.errorprone.fixes.SuggestedFixes;
+import com.google.errorprone.matchers.Description;
+import com.google.errorprone.matchers.Matcher;
+import com.google.errorprone.util.ASTHelpers;
+import com.sun.source.tree.ExpressionTree;
+import com.sun.source.tree.MethodInvocationTree;
+import com.sun.source.tree.Tree;
+import com.sun.source.tree.VariableTree;
+import java.util.List;
+import tech.picnic.errorprone.bugpatterns.util.MoreASTHelpers;
+
+/**
+ * A {@link BugChecker} that flags the use of {@link org.mockito.Mockito#mock(Class)} and {@link
+ * org.mockito.Mockito#spy(Class)} where instead the type to be mocked or spied can be derived from
+ * context.
+ */
+// XXX: This check currently does not flag method invocation arguments. When adding support for
+// this, consider that in some cases the type to be mocked or spied must be specified explicitly so
+// as to disambiguate between method overloads.
+// XXX: This check currently does not flag (implicit or explicit) lambda return expressions.
+// XXX: This check currently does not drop suppressions that become obsolete after the
+// suggested fix is applied; consider adding support for this.
+@AutoService(BugChecker.class)
+@BugPattern(
+    summary = "Don't unnecessarily pass a type to Mockito's `mock(Class)` and `spy(Class)` methods",
+    link = BUG_PATTERNS_BASE_URL + "MockitoMockClassReference",
+    linkType = CUSTOM,
+    severity = SUGGESTION,
+    tags = SIMPLIFICATION)
+public final class MockitoMockClassReference extends BugChecker
+    implements MethodInvocationTreeMatcher {
+  private static final long serialVersionUID = 1L;
+  private static final Matcher<MethodInvocationTree> MOCKITO_MOCK_OR_SPY_WITH_HARDCODED_TYPE =
+      allOf(
+          argument(0, allOf(isSameType(Class.class.getName()), not(isVariable()))),
+          staticMethod().onClass("org.mockito.Mockito").namedAnyOf("mock", "spy"));
+
+  /** Instantiates a new {@link MockitoMockClassReference} instance. */
+  public MockitoMockClassReference() {}
+
+  @Override
+  public Description matchMethodInvocation(MethodInvocationTree tree, VisitorState state) {
+    if (!MOCKITO_MOCK_OR_SPY_WITH_HARDCODED_TYPE.matches(tree, state)
+        || !isTypeDerivableFromContext(tree, state)) {
+      return Description.NO_MATCH;
+    }
+
+    List<? extends ExpressionTree> arguments = tree.getArguments();
+    return describeMatch(tree, SuggestedFixes.removeElement(arguments.get(0), arguments, state));
+  }
+
+  private static boolean isTypeDerivableFromContext(MethodInvocationTree tree, VisitorState state) {
+    Tree parent = state.getPath().getParentPath().getLeaf();
+    switch (parent.getKind()) {
+      case VARIABLE:
+        return !ASTHelpers.hasNoExplicitType((VariableTree) parent, state)
+            && MoreASTHelpers.areSameType(tree, parent, state);
+      case ASSIGNMENT:
+        return MoreASTHelpers.areSameType(tree, parent, state);
+      case RETURN:
+        return MoreASTHelpers.findMethodExitedOnReturn(state)
+            .filter(m -> MoreASTHelpers.areSameType(tree, m.getReturnType(), state))
+            .isPresent();
+      default:
+        return false;
+    }
+  }
+}

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/MockitoStubbing.java

@@ -36,6 +36,9 @@ public final class MockitoStubbing extends BugChecker implements MethodInvocatio
   private static final Matcher<ExpressionTree> MOCKITO_EQ_METHOD =
       staticMethod().onClass("org.mockito.ArgumentMatchers").named("eq");
 
+  /** Instantiates a new {@link MockitoStubbing} instance. */
+  public MockitoStubbing() {}
+
   @Override
   public Description matchMethodInvocation(MethodInvocationTree tree, VisitorState state) {
     List<? extends ExpressionTree> arguments = tree.getArguments();

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/NestedOptionals.java

@@ -4,9 +4,11 @@ import static com.google.errorprone.BugPattern.LinkType.CUSTOM;
 import static com.google.errorprone.BugPattern.SeverityLevel.WARNING;
 import static com.google.errorprone.BugPattern.StandardTags.FRAGILE_CODE;
 import static tech.picnic.errorprone.bugpatterns.util.Documentation.BUG_PATTERNS_BASE_URL;
+import static tech.picnic.errorprone.bugpatterns.util.MoreTypes.generic;
+import static tech.picnic.errorprone.bugpatterns.util.MoreTypes.raw;
+import static tech.picnic.errorprone.bugpatterns.util.MoreTypes.subOf;
 
 import com.google.auto.service.AutoService;
-import com.google.common.collect.Iterables;
 import com.google.errorprone.BugPattern;
 import com.google.errorprone.VisitorState;
 import com.google.errorprone.bugpatterns.BugChecker;
@@ -16,9 +18,7 @@ import com.google.errorprone.suppliers.Supplier;
 import com.google.errorprone.suppliers.Suppliers;
 import com.google.errorprone.util.ASTHelpers;
 import com.sun.source.tree.MethodInvocationTree;
-import com.sun.source.tree.Tree;
 import com.sun.tools.javac.code.Type;
-import com.sun.tools.javac.util.List;
 import java.util.Optional;
 
 /** A {@link BugChecker} that flags nesting of {@link Optional Optionals}. */
@@ -33,21 +33,19 @@ import java.util.Optional;
 public final class NestedOptionals extends BugChecker implements MethodInvocationTreeMatcher {
   private static final long serialVersionUID = 1L;
   private static final Supplier<Type> OPTIONAL = Suppliers.typeFromClass(Optional.class);
+  private static final Supplier<Type> OPTIONAL_OF_OPTIONAL =
+      VisitorState.memoize(generic(OPTIONAL, subOf(raw(OPTIONAL))));
+
+  /** Instantiates a new {@link NestedOptionals} instance. */
+  public NestedOptionals() {}
 
   @Override
   public Description matchMethodInvocation(MethodInvocationTree tree, VisitorState state) {
-    return isOptionalOfOptional(tree, state) ? describeMatch(tree) : Description.NO_MATCH;
-  }
-
-  private static boolean isOptionalOfOptional(Tree tree, VisitorState state) {
-    Type optionalType = OPTIONAL.get(state);
-    Type type = ASTHelpers.getType(tree);
-    if (!ASTHelpers.isSubtype(type, optionalType, state)) {
-      return false;
+    Type type = OPTIONAL_OF_OPTIONAL.get(state);
+    if (type == null || !state.getTypes().isSubtype(ASTHelpers.getType(tree), type)) {
+      return Description.NO_MATCH;
     }
 
-    List<Type> typeArguments = type.getTypeArguments();
-    return !typeArguments.isEmpty()
-        && ASTHelpers.isSubtype(Iterables.getOnlyElement(typeArguments), optionalType, state);
+    return describeMatch(tree);
   }
 }

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/NonEmptyMono.java

@@ -76,6 +76,9 @@ public final class NonEmptyMono extends BugChecker implements MethodInvocationTr
               .onDescendantOf("reactor.core.publisher.Mono")
               .namedAnyOf("defaultIfEmpty", "hasElement", "single"));
 
+  /** Instantiates a new {@link NonEmptyMono} instance. */
+  public NonEmptyMono() {}
+
   @Override
   public Description matchMethodInvocation(MethodInvocationTree tree, VisitorState state) {
     if (!MONO_SIZE_CHECK.matches(tree, state)) {

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/PrimitiveComparison.java

@@ -70,6 +70,9 @@ public final class PrimitiveComparison extends BugChecker implements MethodInvoc
               .named("thenComparing")
               .withParameters(Function.class.getName()));
 
+  /** Instantiates a new {@link PrimitiveComparison} instance. */
+  public PrimitiveComparison() {}
+
   @Override
   public Description matchMethodInvocation(MethodInvocationTree tree, VisitorState state) {
     boolean isStatic = STATIC_COMPARISON_METHOD.matches(tree, state);

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/RedundantStringConversion.java

@@ -7,6 +7,7 @@ import static com.google.errorprone.BugPattern.StandardTags.SIMPLIFICATION;
 import static com.google.errorprone.matchers.Matchers.allOf;
 import static com.google.errorprone.matchers.Matchers.anyMethod;
 import static com.google.errorprone.matchers.Matchers.anyOf;
+import static com.google.errorprone.matchers.Matchers.anything;
 import static com.google.errorprone.matchers.Matchers.argumentCount;
 import static com.google.errorprone.matchers.Matchers.isNonNullUsingDataflow;
 import static com.google.errorprone.matchers.Matchers.isSameType;
@@ -49,6 +50,7 @@ import java.util.Locale;
 import java.util.Objects;
 import java.util.Optional;
 import java.util.stream.Stream;
+import tech.picnic.errorprone.bugpatterns.util.Flags;
 import tech.picnic.errorprone.bugpatterns.util.MethodMatcherFactory;
 import tech.picnic.errorprone.bugpatterns.util.SourceCode;
 
@@ -63,13 +65,10 @@ import tech.picnic.errorprone.bugpatterns.util.SourceCode;
 public final class RedundantStringConversion extends BugChecker
     implements BinaryTreeMatcher, CompoundAssignmentTreeMatcher, MethodInvocationTreeMatcher {
   private static final long serialVersionUID = 1L;
-  private static final String FLAG_PREFIX = "RedundantStringConversion:";
   private static final String EXTRA_STRING_CONVERSION_METHODS_FLAG =
-      FLAG_PREFIX + "ExtraConversionMethods";
-
-  @SuppressWarnings("UnnecessaryLambda")
-  private static final Matcher<ExpressionTree> ANY_EXPR = (t, s) -> true;
+      "RedundantStringConversion:ExtraConversionMethods";
 
+  private static final Matcher<ExpressionTree> ANY_EXPR = anything();
   private static final Matcher<ExpressionTree> LOCALE = isSameType(Locale.class);
   private static final Matcher<ExpressionTree> MARKER = isSubtypeOf("org.slf4j.Marker");
   private static final Matcher<ExpressionTree> STRING = isSameType(String.class);
@@ -141,7 +140,7 @@ public final class RedundantStringConversion extends BugChecker
 
   private final Matcher<MethodInvocationTree> conversionMethodMatcher;
 
-  /** Instantiates the default {@link RedundantStringConversion}. */
+  /** Instantiates a default {@link RedundantStringConversion} instance. */
   public RedundantStringConversion() {
     this(ErrorProneFlags.empty());
   }
@@ -374,10 +373,9 @@ public final class RedundantStringConversion extends BugChecker
       ErrorProneFlags flags) {
     // XXX: ErrorProneFlags#getList splits by comma, but method signatures may also contain commas.
     // For this class methods accepting more than one argument are not valid, but still: not nice.
-    return flags
-        .getList(EXTRA_STRING_CONVERSION_METHODS_FLAG)
-        .map(new MethodMatcherFactory()::create)
-        .map(m -> anyOf(WELL_KNOWN_STRING_CONVERSION_METHODS, m))
-        .orElse(WELL_KNOWN_STRING_CONVERSION_METHODS);
+    return anyOf(
+        WELL_KNOWN_STRING_CONVERSION_METHODS,
+        new MethodMatcherFactory()
+            .create(Flags.getList(flags, EXTRA_STRING_CONVERSION_METHODS_FLAG)));
   }
 }

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/RefasterAnyOfUsage.java

@@ -22,8 +22,8 @@ import tech.picnic.errorprone.bugpatterns.util.SourceCode;
 /**
  * A {@link BugChecker} that flags unnecessary {@link Refaster#anyOf(Object[])} usages.
  *
- * <p>Note that this logic can't be implemented as a Refaster template, as the {@link Refaster}
- * class is treated specially.
+ * <p>Note that this logic can't be implemented as a Refaster rule, as the {@link Refaster} class is
+ * treated specially.
  */
 @AutoService(BugChecker.class)
 @BugPattern(
@@ -37,6 +37,9 @@ public final class RefasterAnyOfUsage extends BugChecker implements MethodInvoca
   private static final Matcher<ExpressionTree> REFASTER_ANY_OF =
       staticMethod().onClass(Refaster.class.getName()).named("anyOf");
 
+  /** Instantiates a new {@link RefasterAnyOfUsage} instance. */
+  public RefasterAnyOfUsage() {}
+
   @Override
   public Description matchMethodInvocation(MethodInvocationTree tree, VisitorState state) {
     if (REFASTER_ANY_OF.matches(tree, state)) {

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/RefasterRuleModifiers.java

@@ -29,17 +29,17 @@ import java.util.Set;
 import javax.lang.model.element.Modifier;
 
 /**
- * A {@link BugChecker} which suggests a canonical set of modifiers for Refaster class and method
+ * A {@link BugChecker} that suggests a canonical set of modifiers for Refaster class and method
  * definitions.
  */
 @AutoService(BugChecker.class)
 @BugPattern(
     summary = "Refaster class and method definitions should specify a canonical set of modifiers",
-    link = BUG_PATTERNS_BASE_URL + "RefasterTemplateModifiers",
+    link = BUG_PATTERNS_BASE_URL + "RefasterRuleModifiers",
     linkType = CUSTOM,
     severity = SUGGESTION,
     tags = STYLE)
-public final class RefasterTemplateModifiers extends BugChecker
+public final class RefasterRuleModifiers extends BugChecker
     implements ClassTreeMatcher, MethodTreeMatcher {
   private static final long serialVersionUID = 1L;
   private static final Matcher<Tree> BEFORE_TEMPLATE_METHOD = hasAnnotation(BeforeTemplate.class);
@@ -48,6 +48,9 @@ public final class RefasterTemplateModifiers extends BugChecker
   private static final Matcher<Tree> REFASTER_METHOD =
       anyOf(BEFORE_TEMPLATE_METHOD, AFTER_TEMPLATE_METHOD, PLACEHOLDER_METHOD);
 
+  /** Instantiates a new {@link RefasterRuleModifiers} instance. */
+  public RefasterRuleModifiers() {}
+
   @Override
   public Description matchClass(ClassTree tree, VisitorState state) {
     if (!hasMatchingMember(tree, BEFORE_TEMPLATE_METHOD, state)) {
@@ -85,8 +88,8 @@ public final class RefasterTemplateModifiers extends BugChecker
 
     if (!hasMatchingMember(tree, PLACEHOLDER_METHOD, state)) {
       /*
-       * Templates without a `@Placeholder` method should be `final`. Note that Refaster enforces
-       * that `@Placeholder` methods are `abstract`, so templates _with_ such a method will
+       * Rules without a `@Placeholder` method should be `final`. Note that Refaster enforces
+       * that `@Placeholder` methods are `abstract`, so rules _with_ such a method will
        * naturally be `abstract` and non-`final`.
        */
       modifiersToAdd.add(Modifier.FINAL);

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/RequestMappingAnnotation.java

@@ -74,15 +74,22 @@ public final class RequestMappingAnnotation extends BugChecker implements Method
                   isSameType("java.time.ZoneId"),
                   isSameType("java.util.Locale"),
                   isSameType("java.util.TimeZone"),
+                  isSameType("jakarta.servlet.http.HttpServletRequest"),
+                  isSameType("jakarta.servlet.http.HttpServletResponse"),
                   isSameType("javax.servlet.http.HttpServletRequest"),
                   isSameType("javax.servlet.http.HttpServletResponse"),
                   isSameType("org.springframework.http.HttpMethod"),
+                  isSameType("org.springframework.ui.Model"),
+                  isSameType("org.springframework.validation.BindingResult"),
                   isSameType("org.springframework.web.context.request.NativeWebRequest"),
                   isSameType("org.springframework.web.context.request.WebRequest"),
                   isSameType("org.springframework.web.server.ServerWebExchange"),
                   isSameType("org.springframework.web.util.UriBuilder"),
                   isSameType("org.springframework.web.util.UriComponentsBuilder"))));
 
+  /** Instantiates a new {@link RequestMappingAnnotation} instance. */
+  public RequestMappingAnnotation() {}
+
   @Override
   public Description matchMethod(MethodTree tree, VisitorState state) {
     // XXX: Auto-add `@RequestParam` where applicable.

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/RequestParamType.java

@@ -1,5 +1,6 @@
 package tech.picnic.errorprone.bugpatterns;
 
+import static com.google.common.collect.ImmutableList.toImmutableList;
 import static com.google.errorprone.BugPattern.LinkType.CUSTOM;
 import static com.google.errorprone.BugPattern.SeverityLevel.ERROR;
 import static com.google.errorprone.BugPattern.StandardTags.LIKELY_ERROR;
@@ -9,38 +10,72 @@ import static com.google.errorprone.matchers.Matchers.annotations;
 import static com.google.errorprone.matchers.Matchers.anyOf;
 import static com.google.errorprone.matchers.Matchers.isSubtypeOf;
 import static com.google.errorprone.matchers.Matchers.isType;
+import static com.google.errorprone.matchers.Matchers.not;
 import static tech.picnic.errorprone.bugpatterns.util.Documentation.BUG_PATTERNS_BASE_URL;
 
 import com.google.auto.service.AutoService;
 import com.google.common.collect.ImmutableCollection;
+import com.google.common.collect.ImmutableList;
 import com.google.common.collect.ImmutableMap;
 import com.google.errorprone.BugPattern;
+import com.google.errorprone.ErrorProneFlags;
 import com.google.errorprone.VisitorState;
 import com.google.errorprone.bugpatterns.BugChecker;
 import com.google.errorprone.bugpatterns.BugChecker.VariableTreeMatcher;
 import com.google.errorprone.matchers.Description;
 import com.google.errorprone.matchers.Matcher;
+import com.google.errorprone.suppliers.Suppliers;
+import com.sun.source.tree.Tree;
 import com.sun.source.tree.VariableTree;
+import tech.picnic.errorprone.bugpatterns.util.Flags;
 
 /** A {@link BugChecker} that flags {@code @RequestParam} parameters with an unsupported type. */
 @AutoService(BugChecker.class)
 @BugPattern(
-    summary = "`@RequestParam` does not support `ImmutableCollection` and `ImmutableMap` subtypes",
+    summary =
+        "By default, `@RequestParam` does not support `ImmutableCollection` and `ImmutableMap` subtypes",
     link = BUG_PATTERNS_BASE_URL + "RequestParamType",
     linkType = CUSTOM,
     severity = ERROR,
     tags = LIKELY_ERROR)
 public final class RequestParamType extends BugChecker implements VariableTreeMatcher {
   private static final long serialVersionUID = 1L;
-  private static final Matcher<VariableTree> HAS_UNSUPPORTED_REQUEST_PARAM =
-      allOf(
-          annotations(AT_LEAST_ONE, isType("org.springframework.web.bind.annotation.RequestParam")),
-          anyOf(isSubtypeOf(ImmutableCollection.class), isSubtypeOf(ImmutableMap.class)));
+  private static final String SUPPORTED_CUSTOM_TYPES_FLAG = "RequestParamType:SupportedCustomTypes";
+
+  private final Matcher<VariableTree> hasUnsupportedRequestParamType;
+
+  /** Instantiates a default {@link RequestParamType} instance. */
+  public RequestParamType() {
+    this(ErrorProneFlags.empty());
+  }
+
+  /**
+   * Instantiates a customized {@link RequestParamType} instance.
+   *
+   * @param flags Any provided command line flags.
+   */
+  public RequestParamType(ErrorProneFlags flags) {
+    hasUnsupportedRequestParamType = hasUnsupportedRequestParamType(flags);
+  }
 
   @Override
   public Description matchVariable(VariableTree tree, VisitorState state) {
-    return HAS_UNSUPPORTED_REQUEST_PARAM.matches(tree, state)
+    return hasUnsupportedRequestParamType.matches(tree, state)
         ? describeMatch(tree)
         : Description.NO_MATCH;
   }
+
+  private static Matcher<VariableTree> hasUnsupportedRequestParamType(ErrorProneFlags flags) {
+    return allOf(
+        annotations(AT_LEAST_ONE, isType("org.springframework.web.bind.annotation.RequestParam")),
+        anyOf(isSubtypeOf(ImmutableCollection.class), isSubtypeOf(ImmutableMap.class)),
+        not(isSubtypeOfAny(Flags.getList(flags, SUPPORTED_CUSTOM_TYPES_FLAG))));
+  }
+
+  private static Matcher<Tree> isSubtypeOfAny(ImmutableList<String> inclusions) {
+    return anyOf(
+        inclusions.stream()
+            .map(inclusion -> isSubtypeOf(Suppliers.typeFromString(inclusion)))
+            .collect(toImmutableList()));
+  }
 }

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/ScheduledTransactionTrace.java

@@ -26,6 +26,7 @@ import com.google.errorprone.util.ASTHelpers;
 import com.sun.source.tree.AnnotationTree;
 import com.sun.source.tree.MethodTree;
 import com.sun.source.tree.Tree;
+import tech.picnic.errorprone.bugpatterns.util.ThirdPartyLibrary;
 
 /**
  * A {@link BugChecker} that flags methods with Spring's {@code @Scheduled} annotation that lack New
@@ -46,9 +47,13 @@ public final class ScheduledTransactionTrace extends BugChecker implements Metho
   private static final MultiMatcher<Tree, AnnotationTree> TRACE_ANNOTATION =
       annotations(AT_LEAST_ONE, isType(TRACE_ANNOTATION_FQCN));
 
+  /** Instantiates a new {@link ScheduledTransactionTrace} instance. */
+  public ScheduledTransactionTrace() {}
+
   @Override
   public Description matchMethod(MethodTree tree, VisitorState state) {
-    if (!IS_SCHEDULED.matches(tree, state)) {
+    if (!ThirdPartyLibrary.NEW_RELIC_AGENT_API.isIntroductionAllowed(state)
+        || !IS_SCHEDULED.matches(tree, state)) {
       return Description.NO_MATCH;
     }
 

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/Slf4jLogStatement.java

@@ -29,6 +29,7 @@ import tech.picnic.errorprone.bugpatterns.util.SourceCode;
 // XXX: The special-casing of Throwable applies only to SLF4J 1.6.0+; see
 // https://www.slf4j.org/faq.html#paramException. That should be documented.
 // XXX: Also simplify `LOG.error(String.format("Something %s", arg), throwable)`.
+// XXX: Also simplify `LOG.error(String.join("sep", arg1, arg2), throwable)`? Perhaps too obscure.
 // XXX: Write a similar checker for Spring RestTemplates, String.format and friends, Guava
 // preconditions, ...
 @AutoService(BugChecker.class)
@@ -47,6 +48,9 @@ public final class Slf4jLogStatement extends BugChecker implements MethodInvocat
           .onDescendantOf("org.slf4j.Logger")
           .namedAnyOf("trace", "debug", "info", "warn", "error");
 
+  /** Instantiates a new {@link Slf4jLogStatement} instance. */
+  public Slf4jLogStatement() {}
+
   @Override
   public Description matchMethodInvocation(MethodInvocationTree tree, VisitorState state) {
     if (!SLF4J_LOGGER_INVOCATION.matches(tree, state)) {

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/SpringMvcAnnotation.java

@@ -57,6 +57,9 @@ public final class SpringMvcAnnotation extends BugChecker implements AnnotationT
           .put("PUT", "PutMapping")
           .build();
 
+  /** Instantiates a new {@link SpringMvcAnnotation} instance. */
+  public SpringMvcAnnotation() {}
+
   @Override
   public Description matchAnnotation(AnnotationTree tree, VisitorState state) {
     // XXX: We could remove the `@RequestMapping` import if not other usages remain.

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/StaticImport.java

@@ -101,7 +101,8 @@ public final class StaticImport extends BugChecker implements MemberSelectTreeMa
           "org.springframework.http.HttpMethod",
           "org.springframework.http.MediaType",
           "org.testng.Assert",
-          "reactor.function.TupleUtils");
+          "reactor.function.TupleUtils",
+          "tech.picnic.errorprone.bugpatterns.util.MoreTypes");
 
   /** Type members that should be statically imported. */
   @VisibleForTesting
@@ -190,6 +191,9 @@ public final class StaticImport extends BugChecker implements MemberSelectTreeMa
           "of",
           "valueOf");
 
+  /** Instantiates a new {@link StaticImport} instance. */
+  public StaticImport() {}
+
   @Override
   public Description matchMemberSelect(MemberSelectTree tree, VisitorState state) {
     if (!isCandidateContext(state) || !isCandidate(tree)) {

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/StringCaseLocaleUsage.java

@@ -0,0 +1,89 @@
+package tech.picnic.errorprone.bugpatterns;
+
+import static com.google.errorprone.BugPattern.LinkType.CUSTOM;
+import static com.google.errorprone.BugPattern.SeverityLevel.WARNING;
+import static com.google.errorprone.BugPattern.StandardTags.FRAGILE_CODE;
+import static com.google.errorprone.matchers.method.MethodMatchers.instanceMethod;
+import static com.sun.tools.javac.parser.Tokens.TokenKind.RPAREN;
+import static tech.picnic.errorprone.bugpatterns.util.Documentation.BUG_PATTERNS_BASE_URL;
+
+import com.google.auto.service.AutoService;
+import com.google.common.collect.Streams;
+import com.google.errorprone.BugPattern;
+import com.google.errorprone.VisitorState;
+import com.google.errorprone.bugpatterns.BugChecker;
+import com.google.errorprone.bugpatterns.BugChecker.MethodInvocationTreeMatcher;
+import com.google.errorprone.fixes.Fix;
+import com.google.errorprone.fixes.SuggestedFix;
+import com.google.errorprone.matchers.Description;
+import com.google.errorprone.matchers.Matcher;
+import com.google.errorprone.util.ASTHelpers;
+import com.google.errorprone.util.ErrorProneTokens;
+import com.sun.source.tree.ExpressionTree;
+import com.sun.source.tree.MethodInvocationTree;
+import com.sun.tools.javac.util.Position;
+import tech.picnic.errorprone.bugpatterns.util.SourceCode;
+
+/**
+ * A {@link BugChecker} that flags calls to {@link String#toLowerCase()} and {@link
+ * String#toUpperCase()}, as these methods implicitly rely on the environment's default locale.
+ */
+// XXX: Also flag `String::toLowerCase` and `String::toUpperCase` method references. For these cases
+// the suggested fix should introduce a lambda expression with a parameter of which the name does
+// not coincide with the name of an existing variable name. Such functionality should likely be
+// introduced in a utility class.
+@AutoService(BugChecker.class)
+@BugPattern(
+    summary = "Specify a `Locale` when calling `String#to{Lower,Upper}Case`",
+    link = BUG_PATTERNS_BASE_URL + "StringCaseLocaleUsage",
+    linkType = CUSTOM,
+    severity = WARNING,
+    tags = FRAGILE_CODE)
+public final class StringCaseLocaleUsage extends BugChecker implements MethodInvocationTreeMatcher {
+  private static final long serialVersionUID = 1L;
+  private static final Matcher<ExpressionTree> DEFAULT_LOCALE_CASE_CONVERSION =
+      instanceMethod()
+          .onExactClass(String.class.getName())
+          .namedAnyOf("toLowerCase", "toUpperCase")
+          .withNoParameters();
+
+  /** Instantiates a new {@link StringCaseLocaleUsage} instance. */
+  public StringCaseLocaleUsage() {}
+
+  @Override
+  public Description matchMethodInvocation(MethodInvocationTree tree, VisitorState state) {
+    if (!DEFAULT_LOCALE_CASE_CONVERSION.matches(tree, state)) {
+      return Description.NO_MATCH;
+    }
+
+    int closingParenPosition = getClosingParenPosition(tree, state);
+    if (closingParenPosition == Position.NOPOS) {
+      return describeMatch(tree);
+    }
+
+    return buildDescription(tree)
+        .addFix(suggestLocale(closingParenPosition, "Locale.ROOT"))
+        .addFix(suggestLocale(closingParenPosition, "Locale.getDefault()"))
+        .build();
+  }
+
+  private static Fix suggestLocale(int insertPosition, String locale) {
+    return SuggestedFix.builder()
+        .addImport("java.util.Locale")
+        .replace(insertPosition, insertPosition, locale)
+        .build();
+  }
+
+  private static int getClosingParenPosition(MethodInvocationTree tree, VisitorState state) {
+    int startPosition = ASTHelpers.getStartPosition(tree);
+    if (startPosition == Position.NOPOS) {
+      return Position.NOPOS;
+    }
+
+    return Streams.findLast(
+            ErrorProneTokens.getTokens(SourceCode.treeToString(tree, state), state.context).stream()
+                .filter(t -> t.kind() == RPAREN))
+        .map(token -> startPosition + token.pos())
+        .orElse(Position.NOPOS);
+  }
+}

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/StringJoin.java

@@ -0,0 +1,187 @@
+package tech.picnic.errorprone.bugpatterns;
+
+import static com.google.errorprone.BugPattern.LinkType.CUSTOM;
+import static com.google.errorprone.BugPattern.SeverityLevel.SUGGESTION;
+import static com.google.errorprone.BugPattern.StandardTags.SIMPLIFICATION;
+import static com.google.errorprone.matchers.method.MethodMatchers.staticMethod;
+import static tech.picnic.errorprone.bugpatterns.util.Documentation.BUG_PATTERNS_BASE_URL;
+
+import com.google.auto.service.AutoService;
+import com.google.common.base.Splitter;
+import com.google.common.collect.ImmutableSet;
+import com.google.common.collect.Iterables;
+import com.google.errorprone.BugPattern;
+import com.google.errorprone.VisitorState;
+import com.google.errorprone.bugpatterns.BugChecker;
+import com.google.errorprone.bugpatterns.BugChecker.MethodInvocationTreeMatcher;
+import com.google.errorprone.fixes.SuggestedFix;
+import com.google.errorprone.matchers.Description;
+import com.google.errorprone.matchers.Matcher;
+import com.google.errorprone.suppliers.Supplier;
+import com.google.errorprone.suppliers.Suppliers;
+import com.google.errorprone.util.ASTHelpers;
+import com.sun.source.tree.ExpressionTree;
+import com.sun.source.tree.MethodInvocationTree;
+import com.sun.tools.javac.code.Type;
+import com.sun.tools.javac.util.Convert;
+import java.util.Formattable;
+import java.util.Iterator;
+import java.util.List;
+import org.jspecify.annotations.Nullable;
+import tech.picnic.errorprone.bugpatterns.util.SourceCode;
+
+/**
+ * A {@link BugChecker} that flags {@link String#format(String, Object...)} invocations which can be
+ * replaced with a {@link String#join(CharSequence, CharSequence...)} or even a {@link
+ * String#valueOf} invocation.
+ */
+// XXX: What about `v1 + "sep" + v2` and similar expressions? Do we want to rewrite those to
+// `String.join`, or should some `String.join` invocations be rewritten to use the `+` operator?
+// (The latter suggestion would conflict with the `FormatStringConcatenation` check.)
+@AutoService(BugChecker.class)
+@BugPattern(
+    summary = "Prefer `String#join` over `String#format`",
+    link = BUG_PATTERNS_BASE_URL + "StringJoin",
+    linkType = CUSTOM,
+    severity = SUGGESTION,
+    tags = SIMPLIFICATION)
+public final class StringJoin extends BugChecker implements MethodInvocationTreeMatcher {
+  private static final long serialVersionUID = 1L;
+  private static final Splitter FORMAT_SPECIFIER_SPLITTER = Splitter.on("%s");
+  private static final Matcher<ExpressionTree> STRING_FORMAT_INVOCATION =
+      staticMethod().onClass(String.class.getName()).named("format");
+  private static final Supplier<Type> CHAR_SEQUENCE_TYPE =
+      Suppliers.typeFromClass(CharSequence.class);
+  private static final Supplier<Type> FORMATTABLE_TYPE = Suppliers.typeFromClass(Formattable.class);
+
+  /** Instantiates a new {@link StringJoin} instance. */
+  public StringJoin() {}
+
+  @Override
+  public Description matchMethodInvocation(MethodInvocationTree tree, VisitorState state) {
+    if (!STRING_FORMAT_INVOCATION.matches(tree, state)) {
+      return Description.NO_MATCH;
+    }
+
+    // XXX: This check assumes that if the first argument to `String#format` is a `Locale`, that
+    // this argument is not vacuous, and that as a result the expression cannot be simplified using
+    // `#valueOf` or `#join`. Implement a separate check that identifies and drops redundant
+    // `Locale` arguments. See also a related comment in `FormatStringConcatenation`.
+    String formatString = ASTHelpers.constValue(tree.getArguments().get(0), String.class);
+    if (formatString == null) {
+      return Description.NO_MATCH;
+    }
+
+    List<String> separators = FORMAT_SPECIFIER_SPLITTER.splitToList(formatString);
+    if (separators.size() < 2) {
+      /* The format string does not contain `%s` format specifiers. */
+      return Description.NO_MATCH;
+    }
+
+    if (separators.size() != tree.getArguments().size()) {
+      /* The number of arguments does not match the number of `%s` format specifiers. */
+      return Description.NO_MATCH;
+    }
+
+    int lastIndex = separators.size() - 1;
+    if (!separators.get(0).isEmpty() || !separators.get(lastIndex).isEmpty()) {
+      /* The format string contains leading or trailing characters. */
+      return Description.NO_MATCH;
+    }
+
+    ImmutableSet<String> innerSeparators = ImmutableSet.copyOf(separators.subList(1, lastIndex));
+    if (innerSeparators.size() > 1) {
+      /* The `%s` format specifiers are not uniformly separated. */
+      return Description.NO_MATCH;
+    }
+
+    if (innerSeparators.isEmpty()) {
+      /*
+       * This `String#format` invocation performs a straightforward string conversion; use
+       * `String#valueOf` instead.
+       */
+      return trySuggestExplicitStringConversion(tree, state);
+    }
+
+    String separator = Iterables.getOnlyElement(innerSeparators);
+    if (separator.indexOf('%') >= 0) {
+      /* The `%s` format specifiers are separated by another format specifier. */
+      // XXX: Strictly speaking we could support `%%` by mapping it to a literal `%`, but that
+      // doesn't seem worth the trouble.
+      return Description.NO_MATCH;
+    }
+
+    return trySuggestExplicitJoin(tree, separator, state);
+  }
+
+  /**
+   * If guaranteed to be behavior preserving, suggests replacing {@code String.format("%s", arg)}
+   * with {@code String.valueOf(arg)}.
+   *
+   * <p>If {@code arg} is already a string then the resultant conversion is vacuous. The {@link
+   * IdentityConversion} check will subsequently drop it.
+   */
+  private Description trySuggestExplicitStringConversion(
+      MethodInvocationTree tree, VisitorState state) {
+    ExpressionTree argument = tree.getArguments().get(1);
+    if (isSubtype(ASTHelpers.getType(argument), FORMATTABLE_TYPE, state)) {
+      /*
+       * `Formattable` arguments are handled specially; `String#valueOf` is not a suitable
+       * alternative.
+       */
+      return Description.NO_MATCH;
+    }
+
+    return buildDescription(tree)
+        .setMessage("Prefer `String#valueOf` over `String#format`")
+        .addFix(SuggestedFix.replace(tree, withStringConversionExpression(argument, state)))
+        .build();
+  }
+
+  /**
+   * Unless the given {@code String.format} expression includes {@link Formattable} arguments,
+   * suggests replacing it with a {@code String.join} expression using the specified argument
+   * separator.
+   */
+  private Description trySuggestExplicitJoin(
+      MethodInvocationTree tree, String separator, VisitorState state) {
+    Iterator<? extends ExpressionTree> arguments = tree.getArguments().iterator();
+
+    SuggestedFix.Builder fix =
+        SuggestedFix.builder()
+            .replace(tree.getMethodSelect(), "String.join")
+            .replace(arguments.next(), String.format("\"%s\"", Convert.quote(separator)));
+
+    while (arguments.hasNext()) {
+      ExpressionTree argument = arguments.next();
+      Type argumentType = ASTHelpers.getType(argument);
+      if (isSubtype(argumentType, FORMATTABLE_TYPE, state)) {
+        /*
+         * `Formattable` arguments are handled specially; `String#join` is not a suitable
+         * alternative.
+         */
+        return Description.NO_MATCH;
+      }
+
+      if (!isSubtype(argumentType, CHAR_SEQUENCE_TYPE, state)) {
+        /*
+         * The argument was previously implicitly converted to a string; now this must happen
+         * explicitly.
+         */
+        fix.replace(argument, withStringConversionExpression(argument, state));
+      }
+    }
+
+    return describeMatch(tree, fix.build());
+  }
+
+  private static boolean isSubtype(
+      @Nullable Type subType, Supplier<Type> superType, VisitorState state) {
+    return ASTHelpers.isSubtype(subType, superType.get(state), state);
+  }
+
+  private static String withStringConversionExpression(
+      ExpressionTree argument, VisitorState state) {
+    return String.format("String.valueOf(%s)", SourceCode.treeToString(argument, state));
+  }
+}

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/TimeZoneUsage.java

@@ -26,6 +26,9 @@ import java.time.Instant;
 import java.time.LocalDate;
 import java.time.LocalDateTime;
 import java.time.LocalTime;
+import java.time.OffsetDateTime;
+import java.time.OffsetTime;
+import java.time.ZonedDateTime;
 
 /** A {@link BugChecker} that flags illegal time-zone related operations. */
 @AutoService(BugChecker.class)
@@ -58,10 +61,16 @@ public final class TimeZoneUsage extends BugChecker implements MethodInvocationT
               .onClassAny(
                   LocalDate.class.getName(),
                   LocalDateTime.class.getName(),
-                  LocalTime.class.getName())
+                  LocalTime.class.getName(),
+                  OffsetDateTime.class.getName(),
+                  OffsetTime.class.getName(),
+                  ZonedDateTime.class.getName())
               .named("now"),
           staticMethod().onClassAny(Instant.class.getName()).named("now").withNoParameters());
 
+  /** Instantiates a new {@link TimeZoneUsage} instance. */
+  public TimeZoneUsage() {}
+
   @Override
   public Description matchMethodInvocation(MethodInvocationTree tree, VisitorState state) {
     return BANNED_TIME_METHOD.matches(tree, state)

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/package-info.java

@@ -1,4 +1,4 @@
 /** Picnic Error Prone Contrib checks. */
 @com.google.errorprone.annotations.CheckReturnValue
-@javax.annotation.ParametersAreNonnullByDefault
+@org.jspecify.annotations.NullMarked
 package tech.picnic.errorprone.bugpatterns;

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/util/ConflictDetection.java

@@ -0,0 +1,75 @@
+package tech.picnic.errorprone.bugpatterns.util;
+
+import static tech.picnic.errorprone.bugpatterns.util.JavaKeywords.isValidIdentifier;
+
+import com.google.errorprone.VisitorState;
+import com.google.errorprone.util.ASTHelpers;
+import com.sun.source.tree.ImportTree;
+import com.sun.source.tree.Tree;
+import com.sun.tools.javac.code.Symbol.MethodSymbol;
+import com.sun.tools.javac.code.Type;
+import java.util.Optional;
+
+/** A set of helper methods for detecting conflicts that would be caused when applying fixes. */
+public final class ConflictDetection {
+  private ConflictDetection() {}
+
+  /**
+   * If applicable, returns a human-readable argument against assigning the given name to an
+   * existing method.
+   *
+   * <p>This method implements imperfect heuristics. Things it currently does not consider include
+   * the following:
+   *
+   * <ul>
+   *   <li>Whether the rename would merely introduce a method overload, rather than clashing with an
+   *       existing method declaration in its class or a supertype.
+   *   <li>Whether the rename would in fact clash with a static import. (It could be that a static
+   *       import of the same name is only referenced from lexical scopes in which the method under
+   *       consideration cannot be referenced directly.)
+   * </ul>
+   *
+   * @param method The method considered for renaming.
+   * @param newName The newly proposed name for the method.
+   * @param state The {@link VisitorState} to use when searching for blockers.
+   * @return A human-readable argument against assigning the proposed name to the given method, or
+   *     {@link Optional#empty()} if no blocker was found.
+   */
+  public static Optional<String> findMethodRenameBlocker(
+      MethodSymbol method, String newName, VisitorState state) {
+    if (isExistingMethodName(method.owner.type, newName, state)) {
+      return Optional.of(
+          String.format(
+              "a method named `%s` is already defined in this class or a supertype", newName));
+    }
+
+    if (isSimpleNameStaticallyImported(newName, state)) {
+      return Optional.of(String.format("`%s` is already statically imported", newName));
+    }
+
+    if (!isValidIdentifier(newName)) {
+      return Optional.of(String.format("`%s` is not a valid identifier", newName));
+    }
+
+    return Optional.empty();
+  }
+
+  private static boolean isExistingMethodName(Type clazz, String name, VisitorState state) {
+    return ASTHelpers.matchingMethods(state.getName(name), method -> true, clazz, state.getTypes())
+        .findAny()
+        .isPresent();
+  }
+
+  private static boolean isSimpleNameStaticallyImported(String simpleName, VisitorState state) {
+    return state.getPath().getCompilationUnit().getImports().stream()
+        .filter(ImportTree::isStatic)
+        .map(ImportTree::getQualifiedIdentifier)
+        .map(tree -> getStaticImportSimpleName(tree, state))
+        .anyMatch(simpleName::contentEquals);
+  }
+
+  private static CharSequence getStaticImportSimpleName(Tree tree, VisitorState state) {
+    String source = SourceCode.treeToString(tree, state);
+    return source.subSequence(source.lastIndexOf('.') + 1, source.length());
+  }
+}

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/util/Flags.java

@@ -0,0 +1,25 @@
+package tech.picnic.errorprone.bugpatterns.util;
+
+import com.google.common.collect.ImmutableList;
+import com.google.errorprone.ErrorProneFlags;
+
+/** Helper methods for working with {@link ErrorProneFlags}. */
+public final class Flags {
+  private Flags() {}
+
+  /**
+   * Returns the list of (comma-separated) arguments passed using the given Error Prone flag.
+   *
+   * @param errorProneFlags The full set of flags provided.
+   * @param name The name of the flag of interest.
+   * @return A non-{@code null} list of provided arguments; this list is empty if the flag was not
+   *     provided, or if the flag's value is the empty string.
+   */
+  public static ImmutableList<String> getList(ErrorProneFlags errorProneFlags, String name) {
+    return errorProneFlags
+        .getList(name)
+        .map(ImmutableList::copyOf)
+        .filter(flags -> !flags.equals(ImmutableList.of("")))
+        .orElseGet(ImmutableList::of);
+  }
+}

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/util/JavaKeywords.java

@@ -4,7 +4,19 @@ import com.google.common.collect.ImmutableSet;
 import com.google.common.collect.Sets;
 
 /** Utility class that can be used to identify reserved keywords of the Java language. */
+// XXX: This class is no longer only about keywords. Consider changing its name and class-level
+// documentation.
 public final class JavaKeywords {
+  /**
+   * Enumeration of boolean and null literals.
+   *
+   * @see <a href="https://docs.oracle.com/javase/specs/jls/se17/html/jls-3.html#jls-3.10.3">JDK 17
+   *     JLS section 3.10.3: Boolean Literals</a>
+   * @see <a href="https://docs.oracle.com/javase/specs/jls/se17/html/jls-3.html#jls-3.10.8">JDK 17
+   *     JLS section 3.10.8: The Null Literal</a>
+   */
+  private static final ImmutableSet<String> BOOLEAN_AND_NULL_LITERALS =
+      ImmutableSet.of("true", "false", "null");
   /**
    * List of all reserved keywords in the Java language.
    *
@@ -64,7 +76,6 @@ public final class JavaKeywords {
           "void",
           "volatile",
           "while");
-
   /**
    * List of all contextual keywords in the Java language.
    *
@@ -89,13 +100,28 @@ public final class JavaKeywords {
           "var",
           "with",
           "yield");
-
   /** List of all keywords in the Java language. */
   private static final ImmutableSet<String> ALL_KEYWORDS =
       Sets.union(RESERVED_KEYWORDS, CONTEXTUAL_KEYWORDS).immutableCopy();
 
   private JavaKeywords() {}
 
+  /**
+   * Tells whether the given string is a valid identifier in the Java language.
+   *
+   * @param str The string of interest.
+   * @return {@code true} if the given string is a valid identifier in the Java language.
+   * @see <a href="https://docs.oracle.com/javase/specs/jls/se17/html/jls-3.html#jls-3.8">JDK 17 JLS
+   *     section 3.8: Identifiers</a>
+   */
+  public static boolean isValidIdentifier(String str) {
+    return !str.isEmpty()
+        && !isReservedKeyword(str)
+        && !BOOLEAN_AND_NULL_LITERALS.contains(str)
+        && Character.isJavaIdentifierStart(str.codePointAt(0))
+        && str.codePoints().skip(1).allMatch(Character::isUnicodeIdentifierPart);
+  }
+
   /**
    * Tells whether the given string is a reserved keyword in the Java language.
    *

error-prone-contrib/src/main/java/tech/picnic/errorprone/bugpatterns/util/MethodMatcherFactory.java

@@ -21,6 +21,9 @@ public final class MethodMatcherFactory {
   private static final Pattern METHOD_SIGNATURE =
       Pattern.compile("([^\\s#(,)]+)#([^\\s#(,)]+)\\(((?:[^\\s#(,)]+(?:,[^\\s#(,)]+)*)?)\\)");
 
+  /** Instantiates a new {@link MethodMatcherFactory} instance. */
+  public MethodMatcherFactory() {}
+
   /**
    * Creates a {@link Matcher} of methods with any of the given signatures.
    *