feature(api): Proof-of-concept synthetic annotation for hiding methods

annotation-processors/src/main/java/net/kyori/adventure/annotation/processing/SyntheticAnnotationProcessor.java

@@ -0,0 +1,43 @@
+package net.kyori.adventure.annotation.processing;
+
+import com.google.auto.service.AutoService;
+import java.util.Set;
+import javax.annotation.processing.AbstractProcessor;
+import javax.annotation.processing.Processor;
+import javax.annotation.processing.RoundEnvironment;
+import javax.annotation.processing.SupportedAnnotationTypes;
+import javax.lang.model.SourceVersion;
+import javax.lang.model.element.Element;
+import javax.lang.model.element.TypeElement;
+import javax.tools.Diagnostic;
+import org.jetbrains.annotations.ApiStatus;
+
+/**
+ * Validate that Synthetic annotations are used in tandem with the {@link Deprecated} annotation.
+ *
+ * @since 5.0.0
+ */
+@ApiStatus.Internal
+@AutoService(Processor.class)
+@SupportedAnnotationTypes(SyntheticAnnotationProcessor.ADVENTURE_SYNTHETIC_ANNOTATION)
+public class SyntheticAnnotationProcessor extends AbstractProcessor {
+
+  public static final String ADVENTURE_SYNTHETIC_ANNOTATION = "net.kyori.adventure.internal.Synthetic";
+
+  @Override
+  public boolean process(final Set<? extends TypeElement> annotations, final RoundEnvironment roundEnv) {
+    for (final TypeElement annotation : annotations) {
+      for (final Element element : roundEnv.getElementsAnnotatedWith(annotation)) {
+        if (element.getAnnotation(Deprecated.class) == null) {
+          this.processingEnv.getMessager().printMessage(Diagnostic.Kind.ERROR, ADVENTURE_SYNTHETIC_ANNOTATION + " needs to be used together with " + Deprecated.class.getCanonicalName() + ", see Synthetic javadocs", element);
+        }
+      }
+    }
+    return false;
+  }
+
+  @Override
+  public SourceVersion getSupportedSourceVersion() {
+    return SourceVersion.latestSupported();
+  }
+}

api/build.gradle.kts

@@ -1,6 +1,16 @@
+import net.bytebuddy.asm.ModifierAdjustment
+import net.bytebuddy.build.gradle.Adjustment
+import net.bytebuddy.description.method.MethodDescription
+import net.bytebuddy.description.modifier.SyntheticState
+import net.bytebuddy.description.type.TypeDescription
+import net.bytebuddy.dynamic.ClassFileLocator
+import net.bytebuddy.dynamic.DynamicType
+import net.bytebuddy.matcher.ElementMatcher
+
 plugins {
   id("adventure.common-conventions")
   alias(libs.plugins.jmh)
+  alias(libs.plugins.byteBuddy)
 }
 
 configurations {
@@ -20,3 +30,40 @@ dependencies {
 }
 
 applyJarMetadata("net.kyori.adventure")
+
+class SyntheticPlugin : net.bytebuddy.build.Plugin {
+  private val name = "net.kyori.adventure.internal.Synthetic"
+
+  override fun apply(
+    builder: DynamicType.Builder<*>,
+    typeDescription: TypeDescription,
+    classFileLocator: ClassFileLocator,
+  ): DynamicType.Builder<*> {
+    return builder.visit(
+      ModifierAdjustment()
+        .withMethodModifiers(
+          ElementMatcher { methodDescription: MethodDescription -> methodDescription.declaredAnnotations.any { it.annotationType.name == name } },
+          SyntheticState.SYNTHETIC
+        )
+    )
+  }
+
+  override fun matches(target: TypeDescription): Boolean {
+    return target.declaredMethods.any { method ->
+      method.declaredAnnotations.any { annotation ->
+        annotation.annotationType.name == name
+      }
+    }
+  }
+
+  override fun close() {
+    // Nothing to close!
+  }
+}
+
+byteBuddy {
+  adjustment = Adjustment.SELF
+  transformation {
+    plugin = SyntheticPlugin::class.java
+  }
+}

api/src/main/java/net/kyori/adventure/internal/Synthetic.java

@@ -0,0 +1,48 @@
+/*
+ * This file is part of adventure, licensed under the MIT License.
+ *
+ * Copyright (c) 2017-2025 KyoriPowered
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package net.kyori.adventure.internal;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+import org.jetbrains.annotations.ApiStatus;
+
+/**
+ * Marks that a method will be transformed to a synthetic method at build time.
+ *
+ * <p>This is used as a bridge to remove the visibility of methods whilst keeping them
+ * available at runtime for library consumers that have not yet updated to stop using
+ * these old methods.</p>
+ *
+ * <p>Any method with this annotation must also be deprecated and should not be
+ * called from any main, test, or other code.</p>
+ *
+ * @since 5.0.0
+ */
+@ApiStatus.Internal
+@Retention(RetentionPolicy.CLASS)
+@Target(ElementType.METHOD)
+public @interface Synthetic {
+}