Augment Descriptions of Refaster rule matches (#255)

By emitting a website link, if available, and reporting the matching Refaster
rule in the description's message rather than the check name. Additionally, it
is now possible to provide a custom explanatory text, to assign a custom
severity to Refaster rules, and to override the severity of matches for all
Refaster rules by passing `-Xep:Refaster:[SEVERITY]`.

Violations of Refaster rules defined in this repository now include a link to
the rule's documentation, hosted on https://error-prone.picnic.tech.

error-prone-contrib/src/main/java/tech/picnic/errorprone/refasterrules/AssertJBigDecimalRules.java

@@ -9,6 +9,7 @@
 import java.math.BigDecimal;
 import org.assertj.core.api.AbstractBigDecimalAssert;
 import org.assertj.core.api.BigDecimalAssert;
+import tech.picnic.errorprone.refaster.annotation.OnlineDocumentation;
 
 /**
  * Refaster rules related to AssertJ assertions over {@link BigDecimal}s.
@@ -20,6 +21,7 @@
  * instances, but also their scale. As a result various seemingly straightforward transformations
  * would actually subtly change the assertion's semantics.
  */
+@OnlineDocumentation
 final class AssertJBigDecimalRules {
   private AssertJBigDecimalRules() {}
 

error-prone-contrib/src/main/java/tech/picnic/errorprone/refasterrules/AssertJBigIntegerRules.java

@@ -8,9 +8,11 @@
 import com.google.errorprone.refaster.annotation.BeforeTemplate;
 import java.math.BigInteger;
 import org.assertj.core.api.AbstractBigIntegerAssert;
+import tech.picnic.errorprone.refaster.annotation.OnlineDocumentation;
 
 // XXX: If we add a rule that drops unnecessary `L` suffixes from literal longs, then the `0L`/`1L`
 // cases below can go.
+@OnlineDocumentation
 final class AssertJBigIntegerRules {
   private AssertJBigIntegerRules() {}
 

error-prone-contrib/src/main/java/tech/picnic/errorprone/refasterrules/AssertJBooleanRules.java

@@ -8,7 +8,9 @@
 import com.google.errorprone.refaster.annotation.BeforeTemplate;
 import com.google.errorprone.refaster.annotation.UseImportPolicy;
 import org.assertj.core.api.AbstractBooleanAssert;
+import tech.picnic.errorprone.refaster.annotation.OnlineDocumentation;
 
+@OnlineDocumentation
 final class AssertJBooleanRules {
   private AssertJBooleanRules() {}
 

error-prone-contrib/src/main/java/tech/picnic/errorprone/refasterrules/AssertJByteRules.java

@@ -7,7 +7,9 @@
 import com.google.errorprone.refaster.annotation.AfterTemplate;
 import com.google.errorprone.refaster.annotation.BeforeTemplate;
 import org.assertj.core.api.AbstractByteAssert;
+import tech.picnic.errorprone.refaster.annotation.OnlineDocumentation;
 
+@OnlineDocumentation
 final class AssertJByteRules {
   private AssertJByteRules() {}
 

error-prone-contrib/src/main/java/tech/picnic/errorprone/refasterrules/AssertJCharSequenceRules.java

@@ -8,7 +8,9 @@
 import com.google.errorprone.refaster.annotation.BeforeTemplate;
 import com.google.errorprone.refaster.annotation.UseImportPolicy;
 import org.assertj.core.api.AbstractAssert;
+import tech.picnic.errorprone.refaster.annotation.OnlineDocumentation;
 
+@OnlineDocumentation
 final class AssertJCharSequenceRules {
   private AssertJCharSequenceRules() {}
 

error-prone-contrib/src/main/java/tech/picnic/errorprone/refasterrules/AssertJComparableRules.java

@@ -8,7 +8,9 @@
 import com.google.errorprone.refaster.annotation.UseImportPolicy;
 import org.assertj.core.api.AbstractComparableAssert;
 import org.assertj.core.api.AbstractIntegerAssert;
+import tech.picnic.errorprone.refaster.annotation.OnlineDocumentation;
 
+@OnlineDocumentation
 final class AssertJComparableRules {
   private AssertJComparableRules() {}
 

error-prone-contrib/src/main/java/tech/picnic/errorprone/refasterrules/AssertJDoubleRules.java

@@ -8,7 +8,9 @@
 import com.google.errorprone.refaster.annotation.BeforeTemplate;
 import org.assertj.core.api.AbstractDoubleAssert;
 import org.assertj.core.data.Offset;
+import tech.picnic.errorprone.refaster.annotation.OnlineDocumentation;
 
+@OnlineDocumentation
 final class AssertJDoubleRules {
   private AssertJDoubleRules() {}
 

error-prone-contrib/src/main/java/tech/picnic/errorprone/refasterrules/AssertJEnumerableRules.java

@@ -6,7 +6,9 @@
 import com.google.errorprone.refaster.annotation.BeforeTemplate;
 import java.util.Collection;
 import org.assertj.core.api.EnumerableAssert;
+import tech.picnic.errorprone.refaster.annotation.OnlineDocumentation;
 
+@OnlineDocumentation
 final class AssertJEnumerableRules {
   private AssertJEnumerableRules() {}
 

error-prone-contrib/src/main/java/tech/picnic/errorprone/refasterrules/AssertJFloatRules.java

@@ -8,7 +8,9 @@
 import com.google.errorprone.refaster.annotation.BeforeTemplate;
 import org.assertj.core.api.AbstractFloatAssert;
 import org.assertj.core.data.Offset;
+import tech.picnic.errorprone.refaster.annotation.OnlineDocumentation;
 
+@OnlineDocumentation
 final class AssertJFloatRules {
   private AssertJFloatRules() {}
 

error-prone-contrib/src/main/java/tech/picnic/errorprone/refasterrules/AssertJIntegerRules.java

@@ -7,7 +7,9 @@
 import com.google.errorprone.refaster.annotation.AfterTemplate;
 import com.google.errorprone.refaster.annotation.BeforeTemplate;
 import org.assertj.core.api.AbstractIntegerAssert;
+import tech.picnic.errorprone.refaster.annotation.OnlineDocumentation;
 
+@OnlineDocumentation
 final class AssertJIntegerRules {
   private AssertJIntegerRules() {}
 

error-prone-contrib/src/main/java/tech/picnic/errorprone/refasterrules/AssertJLongRules.java

@@ -7,7 +7,9 @@
 import com.google.errorprone.refaster.annotation.AfterTemplate;
 import com.google.errorprone.refaster.annotation.BeforeTemplate;
 import org.assertj.core.api.AbstractLongAssert;
+import tech.picnic.errorprone.refaster.annotation.OnlineDocumentation;
 
+@OnlineDocumentation
 final class AssertJLongRules {
   private AssertJLongRules() {}
 

error-prone-contrib/src/main/java/tech/picnic/errorprone/refasterrules/AssertJMapRules.java

@@ -5,7 +5,9 @@
 import com.google.errorprone.refaster.annotation.BeforeTemplate;
 import java.util.Map;
 import org.assertj.core.api.AbstractMapAssert;
+import tech.picnic.errorprone.refaster.annotation.OnlineDocumentation;
 
+@OnlineDocumentation
 final class AssertJMapRules {
   private AssertJMapRules() {}
 

error-prone-contrib/src/main/java/tech/picnic/errorprone/refasterrules/AssertJNumberRules.java

@@ -19,8 +19,10 @@
 import org.assertj.core.api.AbstractLongAssert;
 import org.assertj.core.api.AbstractShortAssert;
 import org.assertj.core.api.NumberAssert;
+import tech.picnic.errorprone.refaster.annotation.OnlineDocumentation;
 import tech.picnic.errorprone.refaster.matchers.IsCharacter;
 
+@OnlineDocumentation
 final class AssertJNumberRules {
   private AssertJNumberRules() {}
 

error-prone-contrib/src/main/java/tech/picnic/errorprone/refasterrules/AssertJObjectRules.java

@@ -10,7 +10,9 @@
 import org.assertj.core.api.AbstractBooleanAssert;
 import org.assertj.core.api.AbstractStringAssert;
 import org.assertj.core.api.ObjectAssert;
+import tech.picnic.errorprone.refaster.annotation.OnlineDocumentation;
 
+@OnlineDocumentation
 final class AssertJObjectRules {
   private AssertJObjectRules() {}
 

error-prone-contrib/src/main/java/tech/picnic/errorprone/refasterrules/AssertJOptionalRules.java

@@ -14,7 +14,9 @@
 import org.assertj.core.api.AbstractOptionalAssert;
 import org.assertj.core.api.ObjectAssert;
 import org.assertj.core.api.OptionalAssert;
+import tech.picnic.errorprone.refaster.annotation.OnlineDocumentation;
 
+@OnlineDocumentation
 final class AssertJOptionalRules {
   private AssertJOptionalRules() {}
 

error-prone-contrib/src/main/java/tech/picnic/errorprone/refasterrules/AssertJPrimitiveRules.java

@@ -9,7 +9,9 @@
 import com.google.errorprone.refaster.annotation.UseImportPolicy;
 import org.assertj.core.api.AbstractBooleanAssert;
 import org.assertj.core.api.AbstractDoubleAssert;
+import tech.picnic.errorprone.refaster.annotation.OnlineDocumentation;
 
+@OnlineDocumentation
 final class AssertJPrimitiveRules {
   private AssertJPrimitiveRules() {}
 

error-prone-contrib/src/main/java/tech/picnic/errorprone/refasterrules/AssertJRules.java

@@ -53,6 +53,7 @@
 import org.assertj.core.api.OptionalDoubleAssert;
 import org.assertj.core.api.OptionalIntAssert;
 import org.assertj.core.api.OptionalLongAssert;
+import tech.picnic.errorprone.refaster.annotation.OnlineDocumentation;
 import tech.picnic.errorprone.refaster.matchers.IsArray;
 
 /** Refaster rules related to AssertJ expressions and statements. */
@@ -118,8 +119,9 @@
 // XXX: `assertThat(ImmutableList.sortedCopyOf(cmp, values)).somethingExactOrder` -> just compare
 // "in any order".
 // XXX: Turns out a lot of this is also covered by https://github.com/palantir/assertj-automation.
-// See how we can combine these things. Do note that (at present) their Refaster rules don't show up
-// as Error Prone checks. So we'd have to build an integration for that.
+// See how we can combine these things. Do note that (at present) their Refaster rules don't
+// show up as Error Prone checks. So we'd have to build an integration for that.
+@OnlineDocumentation
 final class AssertJRules {
   private AssertJRules() {}
 

error-prone-contrib/src/main/java/tech/picnic/errorprone/refasterrules/AssertJShortRules.java

@@ -7,7 +7,9 @@
 import com.google.errorprone.refaster.annotation.AfterTemplate;
 import com.google.errorprone.refaster.annotation.BeforeTemplate;
 import org.assertj.core.api.AbstractShortAssert;
+import tech.picnic.errorprone.refaster.annotation.OnlineDocumentation;
 
+@OnlineDocumentation
 final class AssertJShortRules {
   private AssertJShortRules() {}
 

error-prone-contrib/src/main/java/tech/picnic/errorprone/refasterrules/AssertJStringRules.java

@@ -8,7 +8,9 @@
 import com.google.errorprone.refaster.annotation.UseImportPolicy;
 import org.assertj.core.api.AbstractAssert;
 import org.assertj.core.api.AbstractStringAssert;
+import tech.picnic.errorprone.refaster.annotation.OnlineDocumentation;
 
+@OnlineDocumentation
 final class AssertJStringRules {
   private AssertJStringRules() {}
 

error-prone-contrib/src/main/java/tech/picnic/errorprone/refasterrules/AssertJThrowingCallableRules.java

@@ -16,6 +16,7 @@
 import org.assertj.core.api.AbstractObjectAssert;
 import org.assertj.core.api.AbstractThrowableAssert;
 import org.assertj.core.api.ThrowableAssert.ThrowingCallable;
+import tech.picnic.errorprone.refaster.annotation.OnlineDocumentation;
 
 /**
  * Refaster rules related to AssertJ assertions over expressions that may throw a {@link Throwable}
@@ -26,6 +27,7 @@
  * types. Note that only the most common assertion expressions are rewritten here; covering all
  * cases would require the implementation of an Error Prone check instead.
  */
+@OnlineDocumentation
 final class AssertJThrowingCallableRules {
   private AssertJThrowingCallableRules() {}
 

error-prone-contrib/src/main/java/tech/picnic/errorprone/refasterrules/AssortedRules.java

@@ -28,11 +28,13 @@
 import java.util.Set;
 import java.util.stream.Stream;
 import javax.annotation.Nullable;
+import tech.picnic.errorprone.refaster.annotation.OnlineDocumentation;
 
 /**
  * Assorted Refaster rules that do not (yet) belong in one of the other classes with more topical
  * Refaster rules.
  */
+@OnlineDocumentation
 final class AssortedRules {
   private AssortedRules() {}
 

error-prone-contrib/src/main/java/tech/picnic/errorprone/refasterrules/BigDecimalRules.java

@@ -4,8 +4,10 @@
 import com.google.errorprone.refaster.annotation.AfterTemplate;
 import com.google.errorprone.refaster.annotation.BeforeTemplate;
 import java.math.BigDecimal;
+import tech.picnic.errorprone.refaster.annotation.OnlineDocumentation;
 
 /** Refaster rules related to expressions dealing with {@link BigDecimal}s. */
+@OnlineDocumentation
 final class BigDecimalRules {
   private BigDecimalRules() {}
 

error-prone-contrib/src/main/java/tech/picnic/errorprone/refasterrules/CollectionRules.java

@@ -19,10 +19,12 @@
 import java.util.SortedSet;
 import java.util.function.IntFunction;
 import java.util.stream.Stream;
+import tech.picnic.errorprone.refaster.annotation.OnlineDocumentation;
 
 /** Refaster rules related to expressions dealing with (arbitrary) collections. */
 // XXX: There are other Guava `Iterables` methods that should not be called if the input is known to
 // be a `Collection`. Add those here.
+@OnlineDocumentation
 final class CollectionRules {
   private CollectionRules() {}
 

error-prone-contrib/src/main/java/tech/picnic/errorprone/refasterrules/ComparatorRules.java

@@ -24,8 +24,10 @@
 import java.util.function.ToDoubleFunction;
 import java.util.function.ToIntFunction;
 import java.util.function.ToLongFunction;
+import tech.picnic.errorprone.refaster.annotation.OnlineDocumentation;
 
 /** Refaster rules related to expressions dealing with {@link Comparator}s. */
+@OnlineDocumentation
 final class ComparatorRules {
   private ComparatorRules() {}
 

error-prone-contrib/src/main/java/tech/picnic/errorprone/refasterrules/DoubleStreamRules.java

@@ -12,8 +12,10 @@
 import java.util.function.DoubleUnaryOperator;
 import java.util.stream.DoubleStream;
 import java.util.stream.Stream;
+import tech.picnic.errorprone.refaster.annotation.OnlineDocumentation;
 
 /** Refaster rules related to expressions dealing with {@link DoubleStream}s. */
+@OnlineDocumentation
 final class DoubleStreamRules {
   private DoubleStreamRules() {}
 

error-prone-contrib/src/main/java/tech/picnic/errorprone/refasterrules/EqualityRules.java

@@ -6,8 +6,10 @@
 import com.google.errorprone.refaster.annotation.BeforeTemplate;
 import java.util.Objects;
 import java.util.function.Predicate;
+import tech.picnic.errorprone.refaster.annotation.OnlineDocumentation;
 
 /** Refaster rules related to expressions dealing with (in)equalities. */
+@OnlineDocumentation
 final class EqualityRules {
   private EqualityRules() {}
 

error-prone-contrib/src/main/java/tech/picnic/errorprone/refasterrules/ImmutableListMultimapRules.java

@@ -24,8 +24,10 @@
 import java.util.Map;
 import java.util.function.Function;
 import java.util.stream.Stream;
+import tech.picnic.errorprone.refaster.annotation.OnlineDocumentation;
 
 /** Refaster rules related to expressions dealing with {@link ImmutableListMultimap}s. */
+@OnlineDocumentation
 final class ImmutableListMultimapRules {
   private ImmutableListMultimapRules() {}
 

error-prone-contrib/src/main/java/tech/picnic/errorprone/refasterrules/ImmutableListRules.java

@@ -20,8 +20,10 @@
 import java.util.Iterator;
 import java.util.List;
 import java.util.stream.Stream;
+import tech.picnic.errorprone.refaster.annotation.OnlineDocumentation;
 
 /** Refaster rules related to expressions dealing with {@link ImmutableList}s. */
+@OnlineDocumentation
 final class ImmutableListRules {
   private ImmutableListRules() {}
 

error-prone-contrib/src/main/java/tech/picnic/errorprone/refasterrules/ImmutableMapRules.java

@@ -21,8 +21,10 @@
 import java.util.Set;
 import java.util.function.Function;
 import java.util.stream.Stream;
+import tech.picnic.errorprone.refaster.annotation.OnlineDocumentation;
 
 /** Refaster rules related to expressions dealing with {@link ImmutableMap}s. */
+@OnlineDocumentation
 final class ImmutableMapRules {
   private ImmutableMapRules() {}
 

error-prone-contrib/src/main/java/tech/picnic/errorprone/refasterrules/ImmutableMultisetRules.java

@@ -13,8 +13,10 @@
 import java.util.Collection;
 import java.util.Iterator;
 import java.util.stream.Stream;
+import tech.picnic.errorprone.refaster.annotation.OnlineDocumentation;
 
 /** Refaster rules related to expressions dealing with {@link ImmutableMultiset}s. */
+@OnlineDocumentation
 final class ImmutableMultisetRules {
   private ImmutableMultisetRules() {}
 

error-prone-contrib/src/main/java/tech/picnic/errorprone/refasterrules/ImmutableSetMultimapRules.java

@@ -21,8 +21,10 @@
 import java.util.Map;
 import java.util.function.Function;
 import java.util.stream.Stream;
+import tech.picnic.errorprone.refaster.annotation.OnlineDocumentation;
 
 /** Refaster rules related to expressions dealing with {@link ImmutableSetMultimap}s. */
+@OnlineDocumentation
 final class ImmutableSetMultimapRules {
   private ImmutableSetMultimapRules() {}
 

error-prone-contrib/src/main/java/tech/picnic/errorprone/refasterrules/ImmutableSetRules.java

@@ -17,8 +17,10 @@
 import java.util.Iterator;
 import java.util.Set;
 import java.util.stream.Stream;
+import tech.picnic.errorprone.refaster.annotation.OnlineDocumentation;
 
 /** Refaster rules related to expressions dealing with {@link ImmutableSet}s. */
+@OnlineDocumentation
 final class ImmutableSetRules {
   private ImmutableSetRules() {}
 

error-prone-contrib/src/main/java/tech/picnic/errorprone/refasterrules/ImmutableSortedMapRules.java

@@ -13,8 +13,10 @@
 import java.util.Comparator;
 import java.util.Map;
 import java.util.stream.Stream;
+import tech.picnic.errorprone.refaster.annotation.OnlineDocumentation;
 
 /** Refaster rules related to expressions dealing with {@link ImmutableSortedMap}s. */
+@OnlineDocumentation
 final class ImmutableSortedMapRules {
   private ImmutableSortedMapRules() {}
 

error-prone-contrib/src/main/java/tech/picnic/errorprone/refasterrules/ImmutableSortedMultisetRules.java

@@ -15,8 +15,10 @@
 import java.util.Comparator;
 import java.util.Iterator;
 import java.util.stream.Stream;
+import tech.picnic.errorprone.refaster.annotation.OnlineDocumentation;
 
 /** Refaster rules related to expressions dealing with {@link ImmutableSortedMultiset}s. */
+@OnlineDocumentation
 final class ImmutableSortedMultisetRules {
   private ImmutableSortedMultisetRules() {}
 

error-prone-contrib/src/main/java/tech/picnic/errorprone/refasterrules/ImmutableSortedSetRules.java

@@ -15,8 +15,10 @@
 import java.util.Comparator;
 import java.util.Iterator;
 import java.util.stream.Stream;
+import tech.picnic.errorprone.refaster.annotation.OnlineDocumentation;
 
 /** Refaster rules related to expressions dealing with {@link ImmutableSortedSet}s. */
+@OnlineDocumentation
 final class ImmutableSortedSetRules {
   private ImmutableSortedSetRules() {}