This checker locates all {@code *.refaster} classpath resources and assumes they contain a - * {@link CodeTransformer}. The set of loaded Refaster rules can be restricted by passing {@code + *
This checker locates all {@code *.refaster} classpath resources and assumes that they contain
+ * a {@link CodeTransformer}. The set of loaded Refaster rules can be restricted by passing {@code
* -XepOpt:Refaster:NamePattern= The assigned severity is overridden only if this bug checker's severity was explicitly
+ * configured.
+ *
+ * The original check name (i.e. the Refaster rule name) is prepended to the {@link
+ * Description}'s message. The replacement check name ("Refaster Rule", a name which includes a
+ * space) is chosen such that it is guaranteed not to match any canonical bug checker name (as
+ * that could cause {@link VisitorState#reportMatch(Description)}} to override the reported
+ * severity).
+ */
+ private static Description augmentDescription(
+ Description description, Optional The content is augmented based on custom {@link tech.picnic.errorprone.refaster.annotation
+ * annotations} available on the matching {@link CodeTransformer} or on this {@link
+ * CompositeCodeTransformer} as a fallback, if any.
+ */
+@AutoValue
+public abstract class AnnotatedCompositeCodeTransformer implements CodeTransformer, Serializable {
+ private static final long serialVersionUID = 1L;
+ private static final Splitter CLASS_NAME_SPLITTER = Splitter.on('.').limit(2);
+
+ abstract String packageName();
+
+ abstract ImmutableList Annotations on nested classes override the description associated with any enclosing class.
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.SOURCE)
+public @interface Description {
+ /**
+ * A description of the annotated Refaster rule(s).
+ *
+ * @return A non-{@code null} string.
+ */
+ String value();
+}
diff --git a/refaster-support/src/main/java/tech/picnic/errorprone/refaster/annotation/OnlineDocumentation.java b/refaster-support/src/main/java/tech/picnic/errorprone/refaster/annotation/OnlineDocumentation.java
new file mode 100644
index 0000000000..f41a2f1b67
--- /dev/null
+++ b/refaster-support/src/main/java/tech/picnic/errorprone/refaster/annotation/OnlineDocumentation.java
@@ -0,0 +1,48 @@
+package tech.picnic.errorprone.refaster.annotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Signals that a Refaster rule or group of Refaster rules comes with online documentation.
+ *
+ * The provided value may be a full URL, or a URL pattern containing either or both of the
+ * {@value TOP_LEVEL_CLASS_URL_PLACEHOLDER} and {@value NESTED_CLASS_URL_PLACEHOLDER} placeholders.
+ *
+ * By default it is assumed that the Refaster rule(s) are documented on the Error Prone Support
+ * website. Annotations on nested classes override the documentation URL associated with any
+ * enclosing class.
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.SOURCE)
+public @interface OnlineDocumentation {
+ /**
+ * The URL placeholder value that will be replaced with the name of the top-level class in which
+ * the annotated Refaster rule is located.
+ */
+ String TOP_LEVEL_CLASS_URL_PLACEHOLDER = "${topLevelClassName}";
+ /**
+ * The URL placeholder value that will be replaced with the name of the nested class in which the
+ * annotated Refaster rule is located, if applicable.
+ *
+ * If the Refaster rule is not defined in a nested class then this placeholder will be replaced
+ * with the empty string. In case the Refaster rule is syntactically nested inside a deeper
+ * hierarchy of classes, then this placeholder will be replaced with concatenation of the names of
+ * all these classes (except the top-level class name), separated by dots.
+ */
+ String NESTED_CLASS_URL_PLACEHOLDER = "${nestedClassName}";
+
+ /**
+ * The URL or URL pattern of the website at which the annotated Refaster rule(s) are documented.
+ *
+ * @return A non-{@code null} string, optionally containing the {@value
+ * TOP_LEVEL_CLASS_URL_PLACEHOLDER} and {@value NESTED_CLASS_URL_PLACEHOLDER} placeholders.
+ */
+ String value() default
+ "https://error-prone.picnic.tech/refasterrules/"
+ + TOP_LEVEL_CLASS_URL_PLACEHOLDER
+ + '#'
+ + NESTED_CLASS_URL_PLACEHOLDER;
+}
diff --git a/refaster-support/src/main/java/tech/picnic/errorprone/refaster/annotation/Severity.java b/refaster-support/src/main/java/tech/picnic/errorprone/refaster/annotation/Severity.java
new file mode 100644
index 0000000000..afa5a6c6e1
--- /dev/null
+++ b/refaster-support/src/main/java/tech/picnic/errorprone/refaster/annotation/Severity.java
@@ -0,0 +1,25 @@
+package tech.picnic.errorprone.refaster.annotation;
+
+import com.google.errorprone.BugPattern.SeverityLevel;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Describes the severity of a Refaster rule or group of Refaster rules.
+ *
+ * The default severity is the severity assigned to the {@code Refaster} bug checker, which may
+ * be controlled explicitly by running Error Prone with e.g. {@code -Xep:Refaster:WARN}. Annotations
+ * on nested classes override the severity associated with any enclosing class.
+ */
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.SOURCE)
+public @interface Severity {
+ /**
+ * The expected severity of any match of the annotated Refaster rule(s).
+ *
+ * @return An Error Prone severity level.
+ */
+ SeverityLevel value();
+}
diff --git a/refaster-support/src/main/java/tech/picnic/errorprone/refaster/annotation/package-info.java b/refaster-support/src/main/java/tech/picnic/errorprone/refaster/annotation/package-info.java
new file mode 100644
index 0000000000..53e8e88739
--- /dev/null
+++ b/refaster-support/src/main/java/tech/picnic/errorprone/refaster/annotation/package-info.java
@@ -0,0 +1,8 @@
+/**
+ * A collection of annotations that can be placed on Refaster rule classes and Refaster rule
+ * collection classes, thus influencing the way in which associated rule matches are reported in
+ * non-patch mode.
+ */
+@com.google.errorprone.annotations.CheckReturnValue
+@javax.annotation.ParametersAreNonnullByDefault
+package tech.picnic.errorprone.refaster.annotation;
diff --git a/refaster-support/src/main/java/tech/picnic/errorprone/refaster/package-info.java b/refaster-support/src/main/java/tech/picnic/errorprone/refaster/package-info.java
new file mode 100644
index 0000000000..4955569986
--- /dev/null
+++ b/refaster-support/src/main/java/tech/picnic/errorprone/refaster/package-info.java
@@ -0,0 +1,4 @@
+/** Assorted classes that aid the compilation or evaluation of Refaster rules. */
+@com.google.errorprone.annotations.CheckReturnValue
+@javax.annotation.ParametersAreNonnullByDefault
+package tech.picnic.errorprone.refaster;
diff --git a/refaster-support/src/test/java/tech/picnic/errorprone/refaster/AnnotatedCompositeCodeTransformerTest.java b/refaster-support/src/test/java/tech/picnic/errorprone/refaster/AnnotatedCompositeCodeTransformerTest.java
new file mode 100644
index 0000000000..d49dcf3006
--- /dev/null
+++ b/refaster-support/src/test/java/tech/picnic/errorprone/refaster/AnnotatedCompositeCodeTransformerTest.java
@@ -0,0 +1,204 @@
+package tech.picnic.errorprone.refaster;
+
+import static com.google.errorprone.BugPattern.SeverityLevel.ERROR;
+import static com.google.errorprone.BugPattern.SeverityLevel.SUGGESTION;
+import static com.google.errorprone.BugPattern.SeverityLevel.WARNING;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.junit.jupiter.params.provider.Arguments.arguments;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.ArgumentMatchers.notNull;
+import static org.mockito.Mockito.doAnswer;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+import com.google.auto.value.AutoAnnotation;
+import com.google.common.collect.ImmutableClassToInstanceMap;
+import com.google.common.collect.ImmutableList;
+import com.google.common.collect.ImmutableSet;
+import com.google.common.collect.Maps;
+import com.google.errorprone.BugPattern.SeverityLevel;
+import com.google.errorprone.CodeTransformer;
+import com.google.errorprone.DescriptionListener;
+import com.google.errorprone.ErrorProneOptions;
+import com.google.errorprone.fixes.Fix;
+import com.google.errorprone.matchers.Description;
+import com.sun.source.util.TreePath;
+import com.sun.tools.javac.util.Context;
+import com.sun.tools.javac.util.JCDiagnostic.DiagnosticPosition;
+import java.lang.annotation.Annotation;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Optional;
+import java.util.stream.Stream;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.Arguments;
+import org.junit.jupiter.params.provider.MethodSource;
+import tech.picnic.errorprone.refaster.annotation.OnlineDocumentation;
+import tech.picnic.errorprone.refaster.annotation.Severity;
+
+// XXX: Test the `ErrorProneOptions`-based severity override logic. (Right now that logic is tested
+// through `RefasterTest`, but ideally it is covered by tests in this class, closer to the code that
+// implements the relevant logic.) See the comment in `#context()` below.
+final class AnnotatedCompositeCodeTransformerTest {
+ private static final DiagnosticPosition DUMMY_POSITION = mock(DiagnosticPosition.class);
+ private static final Fix DUMMY_FIX = mock(Fix.class);
+ private static final TreePath DUMMY_PATH = mock(TreePath.class);
+ private static final String DEFAULT_PACKAGE = "";
+ private static final String CUSTOM_PACKAGE = "com.example";
+ private static final String SIMPLE_CLASS_NAME = "MyRefasterRule";
+
+ private static Stream