Promote no-op visitor, VisitOrderVerifier and SubsetEnforcer to API

src/test/java/net/fabricmc/mappingio/test/visitors/NopMappingVisitor.java → src/main/java/net/fabricmc/mappingio/adapter/NopMappingVisitor.java

@@ -14,16 +14,21 @@
  * limitations under the License.
  */
 
-package net.fabricmc.mappingio.test.visitors;
+package net.fabricmc.mappingio.adapter;
 
 import java.io.IOException;
 import java.util.List;
 
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.Nullable;
 
 import net.fabricmc.mappingio.MappedElementKind;
 import net.fabricmc.mappingio.MappingVisitor;
 
+/**
+ * <b>Experimental feature</b>, may be removed or changed without further notice.
+ */
+@ApiStatus.Experimental
 public class NopMappingVisitor implements MappingVisitor {
 	public NopMappingVisitor(boolean visitSubVisitors) {
 		this.visitSubVisitors = visitSubVisitors;

src/test/java/net/fabricmc/mappingio/test/visitors/SubsetAssertingVisitor.java → src/main/java/net/fabricmc/mappingio/adapter/SubsetEnforcer.java

@@ -14,10 +14,7 @@
  * limitations under the License.
  */
 
-package net.fabricmc.mappingio.test.visitors;
-
-import static org.junit.jupiter.api.Assertions.assertEquals;
-import static org.junit.jupiter.api.Assertions.assertTrue;
+package net.fabricmc.mappingio.adapter;
 
 import java.io.IOException;
 import java.util.ArrayList;
@@ -33,7 +30,7 @@
 import net.fabricmc.mappingio.format.FeatureSet;
 import net.fabricmc.mappingio.format.FeatureSet.ElementCommentSupport;
 import net.fabricmc.mappingio.format.FeatureSet.FeaturePresence;
-import net.fabricmc.mappingio.format.FeatureSetInstantiator;
+import net.fabricmc.mappingio.format.FeatureSetBuilder;
 import net.fabricmc.mappingio.format.MappingFormat;
 import net.fabricmc.mappingio.tree.MappingTreeView;
 import net.fabricmc.mappingio.tree.MappingTreeView.ClassMappingView;
@@ -44,19 +41,21 @@
 
 /**
  * A visitor which asserts that the visited mappings are a subset of a superset tree.
+ *
+ * <p><b>Experimental feature</b>, may be removed or changed without further notice.
  */
-public class SubsetAssertingVisitor implements FlatMappingVisitor {
+public class SubsetEnforcer implements FlatMappingVisitor {
 	/**
 	 * @param supTree The superset tree.
 	 * @param supFormat The superset format, or null if supTree has all the original data.
 	 * @param subFormat The subset format, or null if lossless (i.e. if the visits are coming from a tree).
 	 */
-	public SubsetAssertingVisitor(MappingTreeView supTree, @Nullable MappingFormat supFormat, @Nullable MappingFormat subFormat) {
+	public SubsetEnforcer(MappingTreeView supTree, @Nullable MappingFormat supFormat, @Nullable MappingFormat subFormat) {
 		this.supTree = supTree;
 		this.subFormat = subFormat;
 		this.supDstNsCount = supTree.getMaxNamespaceId();
-		this.supFeatures = supFormat == null ? FeatureSetInstantiator.withFullSupport() : supFormat.features();
-		this.subFeatures = subFormat == null ? FeatureSetInstantiator.withFullSupport() : subFormat.features();
+		this.supFeatures = supFormat == null ? new FeatureSetBuilder(true).build() : supFormat.features();
+		this.subFeatures = subFormat == null ? new FeatureSetBuilder(true).build() : subFormat.features();
 	}
 
 	@Override
@@ -275,7 +274,7 @@ public void visitFieldComment(String srcClsName, String srcName, @Nullable Strin
 		ClassMappingView supCls = Objects.requireNonNull(supTree.getClass(srcClsName), "Incoming field comment's parent class not contained in supTree: " + subFldId);
 		FieldMappingView supFld = Objects.requireNonNull(supCls.getField(srcName, srcDesc), "Incoming field comment's parent field not contained in supTree: " + subFldId);
 
-		assertEquals(supFld.getComment(), comment);
+		assertEquals(supFld.getComment(), comment, "Incoming comment differs from supTree");
 	}
 
 	@Override
@@ -360,7 +359,7 @@ public void visitMethodComment(String srcClsName, String srcName, @Nullable Stri
 		ClassMappingView supCls = Objects.requireNonNull(supTree.getClass(srcClsName), "Incoming method comment's parent class not contained in supTree: " + subMthId);
 		MethodMappingView supMth = Objects.requireNonNull(supCls.getMethod(srcName, srcDesc), "Incoming method comment's parent method not contained in supTree: " + subMthId);
 
-		assertEquals(supMth.getComment(), comment);
+		assertEquals(supMth.getComment(), comment, "Incoming comment differs from supTree");
 	}
 
 	@Override
@@ -436,7 +435,7 @@ public void visitMethodArgComment(String srcClsName, String srcMethodName, @Null
 		MethodMappingView supMth = Objects.requireNonNull(supCls.getMethod(srcMethodName, srcMethodDesc), "Incoming arg comment's parent method not contained in supTree: " + subArgId);
 		MethodArgMappingView supArg = Objects.requireNonNull(supMth.getArg(argPosition, lvIndex, srcArgName), "Incoming arg comment's parent arg not contained in supTree: " + subArgId);
 
-		assertEquals(supArg.getComment(), comment);
+		assertEquals(supArg.getComment(), comment, "Incoming comment differs from supTree");
 	}
 
 	@Override
@@ -524,7 +523,19 @@ public void visitMethodVarComment(String srcClsName, String srcMethodName, @Null
 		MethodMappingView supMth = Objects.requireNonNull(supCls.getMethod(srcMethodName, srcMethodDesc), "Incoming var comment's parent method not contained in supTree: " + subVarId);
 		MethodVarMappingView supVar = Objects.requireNonNull(supMth.getVar(lvtRowIndex, lvIndex, startOpIdx, endOpIdx, srcVarName), "Incoming var comment's parent var not contained in supTree: " + subVarId);
 
-		assertEquals(supVar.getComment(), comment);
+		assertEquals(supVar.getComment(), comment, "Incoming comment differs from supTree");
+	}
+
+	private void assertTrue(boolean condition, String message) {
+		if (!condition) {
+			throw new AssertionError(message);
+		}
+	}
+
+	private void assertEquals(Object expected, Object actual, String message) {
+		if (!Objects.equals(expected, actual)) {
+			throw new AssertionError(message + ": Expected: " + expected + ", Actual: " + actual);
+		}
 	}
 
 	private boolean isEmpty(String[] arr) {

src/test/java/net/fabricmc/mappingio/test/visitors/VisitOrderVerifyingVisitor.java → src/main/java/net/fabricmc/mappingio/adapter/VisitOrderVerifier.java

@@ -14,30 +14,33 @@
  * limitations under the License.
  */
 
-package net.fabricmc.mappingio.test.visitors;
+package net.fabricmc.mappingio.adapter;
 
 import java.io.IOException;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 import java.util.Objects;
 
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.Nullable;
 
 import net.fabricmc.mappingio.MappedElementKind;
 import net.fabricmc.mappingio.MappingVisitor;
-import net.fabricmc.mappingio.adapter.ForwardingMappingVisitor;
 
 /**
  * Visitor which verifies on each visit call that the invoked visits were in accordance
  * with the expected order of visitation, as defined in {@link MappingVisitor}'s Javadocs.
+ *
+ * <p><b>Experimental feature</b>, may be removed or changed without further notice.
  */
-public class VisitOrderVerifyingVisitor extends ForwardingMappingVisitor {
-	public VisitOrderVerifyingVisitor(MappingVisitor next) {
+@ApiStatus.Experimental
+public class VisitOrderVerifier extends ForwardingMappingVisitor {
+	public VisitOrderVerifier(MappingVisitor next) {
 		this(next, false);
 	}
 
-	public VisitOrderVerifyingVisitor(MappingVisitor next, boolean allowConsecutiveDuplicateElementVisits) {
+	public VisitOrderVerifier(MappingVisitor next, boolean allowConsecutiveDuplicateElementVisits) {
 		super(next);
 		this.allowConsecutiveDuplicateElementVisits = allowConsecutiveDuplicateElementVisits;
 		init();

src/main/java/net/fabricmc/mappingio/format/FeatureSetBuilder.java

@@ -55,7 +55,8 @@ public static FeatureSetBuilder createFrom(FeatureSet featureSet) {
 				featureSet.hasFileComments());
 	}
 
-	FeatureSetBuilder(boolean initWithFullSupport) {
+	@ApiStatus.Internal
+	public FeatureSetBuilder(boolean initWithFullSupport) {
 		this(initWithFullSupport,
 				initWithFullSupport ? MetadataSupport.ARBITRARY : MetadataSupport.NONE,
 				initWithFullSupport ? MetadataSupport.ARBITRARY : MetadataSupport.NONE,

src/test/java/net/fabricmc/mappingio/test/TestMappings.java

@@ -35,12 +35,12 @@
 import net.fabricmc.mappingio.MappingUtil;
 import net.fabricmc.mappingio.MappingVisitor;
 import net.fabricmc.mappingio.adapter.ForwardingMappingVisitor;
+import net.fabricmc.mappingio.adapter.NopMappingVisitor;
 import net.fabricmc.mappingio.adapter.OuterClassNamePropagator;
+import net.fabricmc.mappingio.adapter.VisitOrderVerifier;
 import net.fabricmc.mappingio.format.MappingFormat;
 import net.fabricmc.mappingio.format.intellij.MigrationMapConstants;
 import net.fabricmc.mappingio.test.lib.jool.Unchecked;
-import net.fabricmc.mappingio.test.visitors.NopMappingVisitor;
-import net.fabricmc.mappingio.test.visitors.VisitOrderVerifyingVisitor;
 
 /*
  * After any changes to the "generate" methods, run the "generateTestMappings" Gradle task
@@ -50,7 +50,7 @@
  */
 public class TestMappings {
 	public static <T extends MappingVisitor> T generateValid(T target) throws IOException {
-		MappingVisitor delegate = target instanceof VisitOrderVerifyingVisitor ? target : new VisitOrderVerifyingVisitor(target);
+		MappingVisitor delegate = target instanceof VisitOrderVerifier ? target : new VisitOrderVerifier(target);
 
 		if (delegate.visitHeader()) {
 			delegate.visitNamespaces(MappingUtil.NS_SOURCE_FALLBACK, Arrays.asList(MappingUtil.NS_TARGET_FALLBACK, MappingUtil.NS_TARGET_FALLBACK + "2"));
@@ -89,7 +89,7 @@ public static <T extends MappingVisitor> T generateValid(T target) throws IOExce
 	}
 
 	public static <T extends MappingVisitor> T generateRepeatedElements(T target, boolean repeatComments, boolean repeatClasses) throws IOException {
-		generateValid(new ForwardingMappingVisitor(new VisitOrderVerifyingVisitor(target, true)) {
+		generateValid(new ForwardingMappingVisitor(new VisitOrderVerifier(target, true)) {
 			private final List<Runnable> replayQueue = new ArrayList<>();
 
 			@Override
@@ -179,7 +179,7 @@ public void visitComment(MappedElementKind targetKind, String comment) throws IO
 	}
 
 	public static <T extends MappingVisitor> T generateHoles(T target) throws IOException {
-		MappingVisitor delegate = target instanceof VisitOrderVerifyingVisitor ? target : new VisitOrderVerifyingVisitor(target);
+		MappingVisitor delegate = target instanceof VisitOrderVerifier ? target : new VisitOrderVerifier(target);
 
 		if (delegate.visitHeader()) {
 			delegate.visitNamespaces(MappingUtil.NS_SOURCE_FALLBACK, Arrays.asList(MappingUtil.NS_TARGET_FALLBACK, MappingUtil.NS_TARGET_FALLBACK + "2"));
@@ -291,7 +291,7 @@ public static <T extends MappingVisitor> T generateHoles(T target) throws IOExce
 	}
 
 	public static <T extends MappingVisitor> T generateOuterClassNamePropagation(T target) throws IOException {
-		MappingVisitor delegate = target instanceof VisitOrderVerifyingVisitor ? target : new VisitOrderVerifyingVisitor(target);
+		MappingVisitor delegate = target instanceof VisitOrderVerifier ? target : new VisitOrderVerifier(target);
 		String srcNs = MappingUtil.NS_SOURCE_FALLBACK;
 		List<String> dstNamespaces = Arrays.asList("dstNs0", "dstNs1", "dstNs2", "dstNs3", "dstNs4", "dstNs5", "dstNs6");
 

src/test/java/net/fabricmc/mappingio/test/tests/OuterClassNamePropagationTest.java

@@ -32,12 +32,12 @@
 import net.fabricmc.mappingio.MappingFlag;
 import net.fabricmc.mappingio.MappingVisitor;
 import net.fabricmc.mappingio.adapter.FlatAsRegularMappingVisitor;
+import net.fabricmc.mappingio.adapter.NopMappingVisitor;
 import net.fabricmc.mappingio.adapter.OuterClassNamePropagator;
+import net.fabricmc.mappingio.adapter.SubsetEnforcer;
 import net.fabricmc.mappingio.format.MappingFormat;
 import net.fabricmc.mappingio.test.TestMappings;
 import net.fabricmc.mappingio.test.TestMappings.MappingDir;
-import net.fabricmc.mappingio.test.visitors.NopMappingVisitor;
-import net.fabricmc.mappingio.test.visitors.SubsetAssertingVisitor;
 import net.fabricmc.mappingio.tree.MappingTreeView;
 import net.fabricmc.mappingio.tree.MemoryMappingTree;
 import net.fabricmc.mappingio.tree.VisitableMappingTree;
@@ -134,8 +134,8 @@ private void checkDiskEquivalence(VisitableMappingTree tree, boolean processRema
 
 			VisitableMappingTree diskTree = dir.read(format, new MemoryMappingTree());
 
-			tree.accept(new FlatAsRegularMappingVisitor(new SubsetAssertingVisitor(diskTree, format, null)));
-			diskTree.accept(new FlatAsRegularMappingVisitor(new SubsetAssertingVisitor(tree, null, format)));
+			tree.accept(new FlatAsRegularMappingVisitor(new SubsetEnforcer(diskTree, format, null)));
+			diskTree.accept(new FlatAsRegularMappingVisitor(new SubsetEnforcer(tree, null, format)));
 		}
 	}
 

src/test/java/net/fabricmc/mappingio/test/tests/reading/DetectionTest.java

@@ -30,10 +30,10 @@
 import org.opentest4j.AssertionFailedError;
 
 import net.fabricmc.mappingio.MappingReader;
+import net.fabricmc.mappingio.adapter.NopMappingVisitor;
 import net.fabricmc.mappingio.format.MappingFormat;
 import net.fabricmc.mappingio.test.TestMappings;
 import net.fabricmc.mappingio.test.TestMappings.MappingDir;
-import net.fabricmc.mappingio.test.visitors.NopMappingVisitor;
 
 public class DetectionTest {
 	@Test

src/test/java/net/fabricmc/mappingio/test/tests/reading/EmptyContentReadTest.java

@@ -25,6 +25,7 @@
 import org.junit.jupiter.api.Test;
 
 import net.fabricmc.mappingio.MappingVisitor;
+import net.fabricmc.mappingio.adapter.VisitOrderVerifier;
 import net.fabricmc.mappingio.format.enigma.EnigmaFileReader;
 import net.fabricmc.mappingio.format.intellij.MigrationMapFileReader;
 import net.fabricmc.mappingio.format.jobf.JobfFileReader;
@@ -35,15 +36,14 @@
 import net.fabricmc.mappingio.format.srg.TsrgFileReader;
 import net.fabricmc.mappingio.format.tiny.Tiny1FileReader;
 import net.fabricmc.mappingio.format.tiny.Tiny2FileReader;
-import net.fabricmc.mappingio.test.visitors.VisitOrderVerifyingVisitor;
 import net.fabricmc.mappingio.tree.MemoryMappingTree;
 
 public class EmptyContentReadTest {
 	private MappingVisitor target;
 
 	@BeforeEach
 	public void instantiateTree() {
-		target = new VisitOrderVerifyingVisitor(new MemoryMappingTree());
+		target = new VisitOrderVerifier(new MemoryMappingTree());
 	}
 
 	@Test

src/test/java/net/fabricmc/mappingio/test/tests/reading/ValidContentReadTest.java

@@ -25,11 +25,11 @@
 import net.fabricmc.mappingio.MappingVisitor;
 import net.fabricmc.mappingio.adapter.FlatAsRegularMappingVisitor;
 import net.fabricmc.mappingio.adapter.MappingSourceNsSwitch;
+import net.fabricmc.mappingio.adapter.SubsetEnforcer;
+import net.fabricmc.mappingio.adapter.VisitOrderVerifier;
 import net.fabricmc.mappingio.format.MappingFormat;
 import net.fabricmc.mappingio.test.TestMappings;
 import net.fabricmc.mappingio.test.TestMappings.MappingDir;
-import net.fabricmc.mappingio.test.visitors.SubsetAssertingVisitor;
-import net.fabricmc.mappingio.test.visitors.VisitOrderVerifyingVisitor;
 import net.fabricmc.mappingio.tree.MappingTreeView;
 import net.fabricmc.mappingio.tree.MemoryMappingTree;
 import net.fabricmc.mappingio.tree.VisitableMappingTree;
@@ -62,7 +62,7 @@ private void check(MappingDir dir, MappingFormat format) throws Exception {
 		VisitableMappingTree referenceTree = dir.generate(new MemoryMappingTree());
 		VisitableMappingTree tree = new MemoryMappingTree();
 
-		dir.read(format, new VisitOrderVerifyingVisitor(tree, allowConsecutiveDuplicateElementVisits));
+		dir.read(format, new VisitOrderVerifier(tree, allowConsecutiveDuplicateElementVisits));
 		assertEqual(tree, format, referenceTree, allowConsecutiveDuplicateElementVisits);
 
 		if (dir == TestMappings.READING.HOLES && !format.features().hasNamespaces()) {
@@ -74,9 +74,9 @@ private void check(MappingDir dir, MappingFormat format) throws Exception {
 				? referenceTree.getDstNamespaces().get(0)
 				: MappingUtil.NS_TARGET_FALLBACK;
 		MappingVisitor target = new MappingSourceNsSwitch(
-				new VisitOrderVerifyingVisitor(
+				new VisitOrderVerifier(
 						new MappingSourceNsSwitch(
-								new VisitOrderVerifyingVisitor(tree, allowConsecutiveDuplicateElementVisits),
+								new VisitOrderVerifier(tree, allowConsecutiveDuplicateElementVisits),
 								referenceTree.getSrcNamespace()),
 						allowConsecutiveDuplicateElementVisits),
 				newSrcNs);
@@ -91,9 +91,9 @@ private void assertEqual(MappingTreeView tree, MappingFormat format, MappingTree
 	}
 
 	private void assertSubset(MappingTreeView subTree, @Nullable MappingFormat subFormat, MappingTreeView supTree, @Nullable MappingFormat supFormat, boolean allowConsecutiveDuplicateElementVisits) throws Exception {
-		subTree.accept(new VisitOrderVerifyingVisitor(
+		subTree.accept(new VisitOrderVerifier(
 				new FlatAsRegularMappingVisitor(
-						new SubsetAssertingVisitor(supTree, supFormat, subFormat)),
+						new SubsetEnforcer(supTree, supFormat, subFormat)),
 				allowConsecutiveDuplicateElementVisits));
 	}
 }

src/test/java/net/fabricmc/mappingio/test/tests/tree/MergeTest.java

@@ -33,9 +33,9 @@
 import net.fabricmc.mappingio.MappingReader;
 import net.fabricmc.mappingio.MappingVisitor;
 import net.fabricmc.mappingio.adapter.FlatAsRegularMappingVisitor;
+import net.fabricmc.mappingio.adapter.SubsetEnforcer;
+import net.fabricmc.mappingio.adapter.VisitOrderVerifier;
 import net.fabricmc.mappingio.test.TestMappings;
-import net.fabricmc.mappingio.test.visitors.SubsetAssertingVisitor;
-import net.fabricmc.mappingio.test.visitors.VisitOrderVerifyingVisitor;
 import net.fabricmc.mappingio.tree.MappingTree.ClassMapping;
 import net.fabricmc.mappingio.tree.MappingTree.FieldMapping;
 import net.fabricmc.mappingio.tree.MemoryMappingTree;
@@ -61,7 +61,7 @@ public class MergeTest {
 	@BeforeEach
 	public void setup() {
 		tree = new MemoryMappingTree();
-		delegate = new VisitOrderVerifyingVisitor(tree);
+		delegate = new VisitOrderVerifier(tree);
 	}
 
 	@Test
@@ -290,14 +290,14 @@ public void diskMappings() throws IOException {
 
 		MemoryMappingTree referenceTree = new MemoryMappingTree();
 		MappingReader.read(dir.resolve("tree1+2.tiny"), referenceTree);
-		tree.accept(new FlatAsRegularMappingVisitor(new SubsetAssertingVisitor(referenceTree, null, null)));
-		referenceTree.accept(new FlatAsRegularMappingVisitor(new SubsetAssertingVisitor(tree, null, null)));
+		tree.accept(new FlatAsRegularMappingVisitor(new SubsetEnforcer(referenceTree, null, null)));
+		referenceTree.accept(new FlatAsRegularMappingVisitor(new SubsetEnforcer(tree, null, null)));
 
 		MappingReader.read(dir.resolve("tree3.tiny"), delegate);
 
 		referenceTree = new MemoryMappingTree();
 		MappingReader.read(dir.resolve("tree1+2+3.tiny"), referenceTree);
-		tree.accept(new FlatAsRegularMappingVisitor(new SubsetAssertingVisitor(referenceTree, null, null)));
-		referenceTree.accept(new FlatAsRegularMappingVisitor(new SubsetAssertingVisitor(tree, null, null)));
+		tree.accept(new FlatAsRegularMappingVisitor(new SubsetEnforcer(referenceTree, null, null)));
+		referenceTree.accept(new FlatAsRegularMappingVisitor(new SubsetEnforcer(tree, null, null)));
 	}
 }