Support package mappings

src/main/java/net/fabricmc/mappingio/FlatMappingVisitor.java

@@ -62,6 +62,14 @@ default boolean visitContent() throws IOException {
 		return true;
 	}
 
+	// TODO: Un-"default" in the next breaking release
+	default boolean visitPackage(String srcName, @Nullable String[] dstNames) throws IOException {
+		return false;
+	}
+
+	// TODO: Un-"default" in the next breaking release
+	default void visitPackageComment(String srcName, @Nullable String[] dstNames, String comment) throws IOException { }
+
 	boolean visitClass(String srcName, @Nullable String[] dstNames) throws IOException;
 	void visitClassComment(String srcName, @Nullable String[] dstNames, String comment) throws IOException;
 
@@ -149,6 +157,17 @@ default boolean visitMethodVar(String srcClsName, String srcMethodName, @Nullabl
 	}
 
 	// convenience / potentially higher efficiency visit methods for only one dst name
+	default boolean visitPackage(String srcName, String dstName) throws IOException {
+		return visitPackage(srcName, toArray(dstName));
+	}
+
+	default void visitPackageComment(String srcName, String comment) throws IOException {
+		visitPackageComment(srcName, (String) null, comment);
+	}
+
+	default void visitPackageComment(String srcName, @Nullable String dstName, String comment) throws IOException {
+		visitPackageComment(srcName, toArray(dstName), comment);
+	}
 
 	default boolean visitClass(String srcName, String dstName) throws IOException {
 		return visitClass(srcName, toArray(dstName));

src/main/java/net/fabricmc/mappingio/MappedElementKind.java

@@ -20,6 +20,7 @@
  * A kind of element that can be mapped.
  */
 public enum MappedElementKind {
+	PACKAGE(0),
 	CLASS(0),
 	FIELD(1),
 	METHOD(1),

src/main/java/net/fabricmc/mappingio/MappingVisitor.java

@@ -28,7 +28,8 @@
  * <p>The visitation order is as follows (omitting visit prefixes for brevity, lowercase for cross-references):
  * <ul><li>overall: header -> content -> End -> overall
  * <li>header: Header -> Namespaces [-> Metadata]*
- * <li>content: Content [-> class|Metadata]*
+ * <li>content: Content [-> package|class|Metadata]*
+ * <li>package: Package [-> DstName]* -> ElementContent [-> Comment]
  * <li>class: Class [-> DstName]* -> ElementContent [-> field|method|Comment]*
  * <li>field: Field [-> DstName|DstDesc]* -> ElementContent [-> Comment]
  * <li>method: Method [-> DstName|DstDesc]* -> ElementContent [-> arg|var|Comment]*
@@ -85,6 +86,18 @@ default boolean visitContent() throws IOException {
 		return true;
 	}
 
+	/**
+	 * Visit a package.
+	 *
+	 * @param srcName The package path, with slashes instead of dots, and no trailing slash.
+	 * An empty string represents the default package.
+	 * @return Whether the package's content should be visited too.
+	 */
+	// TODO: Un-"default" in the next breaking release
+	default boolean visitPackage(String srcName) throws IOException {
+		return false;
+	}
+
 	/**
 	 * Visit a class.
 	 *

src/main/java/net/fabricmc/mappingio/adapter/FlatAsRegularMappingVisitor.java

@@ -64,10 +64,11 @@ public void visitNamespaces(String srcNamespace, List<String> dstNamespaces) thr
 		Set<MappingFlag> flags = next.getFlags();
 
 		if (flags.contains(MappingFlag.NEEDS_ELEMENT_UNIQUENESS)) {
+			dstPackageNames = new String[count];
 			dstClassNames = new String[count];
 			dstMemberNames = new String[count];
 		} else {
-			dstClassNames = dstMemberNames = null;
+			dstPackageNames = dstClassNames = dstMemberNames = null;
 		}
 
 		dstMemberDescs = flags.contains(MappingFlag.NEEDS_DST_FIELD_DESC) || flags.contains(MappingFlag.NEEDS_DST_METHOD_DESC) ? new String[count] : null;
@@ -83,6 +84,16 @@ public boolean visitContent() throws IOException {
 		return next.visitContent();
 	}
 
+	@Override
+	public boolean visitPackage(String srcName) throws IOException {
+		this.srcPkgName = srcName;
+
+		Arrays.fill(dstNames, null);
+		if (dstPackageNames != null) Arrays.fill(dstPackageNames, null);
+
+		return true;
+	}
+
 	@Override
 	public boolean visitClass(String srcName) {
 		this.srcClsName = srcName;
@@ -161,6 +172,10 @@ public boolean visitElementContent(MappedElementKind targetKind) throws IOExcept
 		boolean relay;
 
 		switch (targetKind) {
+		case PACKAGE:
+			relay = next.visitPackage(srcPkgName, dstNames);
+			if (relay && dstPackageNames != null) System.arraycopy(dstNames, 0, dstPackageNames, 0, dstNames.length);
+			break;
 		case CLASS:
 			relay = next.visitClass(srcClsName, dstNames);
 			if (relay && dstClassNames != null) System.arraycopy(dstNames, 0, dstClassNames, 0, dstNames.length);
@@ -193,6 +208,9 @@ public boolean visitElementContent(MappedElementKind targetKind) throws IOExcept
 	@Override
 	public void visitComment(MappedElementKind targetKind, String comment) throws IOException {
 		switch (targetKind) {
+		case PACKAGE:
+			next.visitPackageComment(srcPkgName, dstNames, comment);
+			break;
 		case CLASS:
 			next.visitClassComment(srcClsName, dstClassNames, comment);
 			break;
@@ -217,12 +235,14 @@ public void visitComment(MappedElementKind targetKind, String comment) throws IO
 
 	private final FlatMappingVisitor next;
 
+	private String srcPkgName;
 	private String srcClsName;
 	private String srcMemberName;
 	private String srcMemberDesc;
 	private String srcMemberSubName;
 	private int argIdx, lvIndex, startOpIdx, endOpIdx;
 	private String[] dstNames;
+	private String[] dstPackageNames;
 	private String[] dstClassNames;
 	private String[] dstMemberNames;
 	private String[] dstMemberDescs;

src/main/java/net/fabricmc/mappingio/adapter/ForwardingMappingVisitor.java

@@ -69,6 +69,11 @@ public boolean visitContent() throws IOException {
 		return next.visitContent();
 	}
 
+	@Override
+	public boolean visitPackage(String srcName) throws IOException {
+		return next.visitPackage(srcName);
+	}
+
 	@Override
 	public boolean visitClass(String srcName) throws IOException {
 		return next.visitClass(srcName);

src/main/java/net/fabricmc/mappingio/adapter/MappingNsCompleter.java

@@ -135,6 +135,13 @@ public boolean visitContent() throws IOException {
 		return next.visitContent();
 	}
 
+	@Override
+	public boolean visitPackage(String srcName) throws IOException {
+		this.srcName = srcName;
+
+		return next.visitPackage(srcName);
+	}
+
 	@Override
 	public boolean visitClass(String srcName) throws IOException {
 		this.srcName = srcName;

src/main/java/net/fabricmc/mappingio/adapter/MappingSourceNsSwitch.java

@@ -142,6 +142,15 @@ public boolean visitContent() throws IOException {
 		return next.visitContent();
 	}
 
+	@Override
+	public boolean visitPackage(String srcName) throws IOException {
+		if (passThrough) return next.visitPackage(srcName);
+
+		this.srcName = srcName;
+
+		return true;
+	}
+
 	@Override
 	public boolean visitClass(String srcName) throws IOException {
 		if (passThrough) return next.visitClass(srcName);
@@ -256,6 +265,9 @@ public boolean visitElementContent(MappedElementKind targetKind) throws IOExcept
 		boolean relay;
 
 		switch (targetKind) {
+		case PACKAGE:
+			relay = next.visitPackage(dstName);
+			break;
 		case CLASS:
 			relay = next.visitClass(dstName);
 			break;

src/main/java/net/fabricmc/mappingio/adapter/RegularAsFlatMappingVisitor.java

@@ -74,7 +74,38 @@ public boolean visitContent() throws IOException {
 	}
 
 	@Override
-	public boolean visitClass(String srcName, String[] dstNames) throws IOException {
+	public boolean visitPackage(String srcName, @Nullable String[] dstNames) throws IOException {
+		return visitPackage(srcName, dstNames, null);
+	}
+
+	@Override
+	public boolean visitPackage(String srcName, String dstName) throws IOException {
+		return visitPackage(srcName, null, dstName);
+	}
+
+	private boolean visitPackage(String srcName, @Nullable String[] dstNames, @Nullable String dstName) throws IOException {
+		if (!srcName.equals(lastPackage)) {
+			lastPackage = srcName;
+			relayLastPackage = next.visitPackage(srcName) && visitDstNames(MappedElementKind.PACKAGE, dstNames, dstName);
+		}
+
+		return relayLastPackage;
+	}
+
+	@Override
+	public void visitPackageComment(String srcName, @Nullable String[] dstNames, String comment) throws IOException {
+		if (!visitPackage(srcName, dstNames, null)) return;
+		next.visitComment(MappedElementKind.PACKAGE, comment);
+	}
+
+	@Override
+	public void visitPackageComment(String srcName, @Nullable String dstName, String comment) throws IOException {
+		if (!visitPackage(srcName, null, dstName)) return;
+		next.visitComment(MappedElementKind.PACKAGE, comment);
+	}
+
+	@Override
+	public boolean visitClass(String srcName, @Nullable String[] dstNames) throws IOException {
 		return visitClass(srcName, dstNames, null);
 	}
 
@@ -367,6 +398,8 @@ private boolean visitDstNamesDescs(MappedElementKind targetKind, @Nullable Strin
 	private boolean relayDstFieldDescs;
 	private boolean relayDstMethodDescs;
 
+	private String lastPackage;
+	private boolean relayLastPackage;
 	private String lastClass;
 	private boolean relayLastClass;
 	private String lastMemberName, lastMemberDesc;

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

@@ -20,7 +20,7 @@ public interface FeatureSet {
 	boolean hasNamespaces();
 	MetadataSupport fileMetadata();
 	MetadataSupport elementMetadata();
-	NameSupport packages();
+	PackageSupport packages();
 	ClassSupport classes();
 	MemberSupport fields();
 	MemberSupport methods();
@@ -30,13 +30,11 @@ public interface FeatureSet {
 	boolean hasFileComments();
 
 	default boolean supportsPackages() {
-		return packages().srcNames() != FeaturePresence.ABSENT
-				|| packages().dstNames() != FeaturePresence.ABSENT;
+		return packages().srcNames() != FeaturePresence.ABSENT;
 	}
 
 	default boolean supportsClasses() {
-		return classes().srcNames() != FeaturePresence.ABSENT
-				|| classes().dstNames() != FeaturePresence.ABSENT;
+		return classes().srcNames() != FeaturePresence.ABSENT;
 	}
 
 	default boolean supportsFields() {
@@ -82,6 +80,10 @@ interface DescSupport {
 		FeaturePresence dstDescs();
 	}
 
+	interface PackageSupport extends NameSupport {
+		boolean hasStructureModification();
+	}
+
 	interface ClassSupport extends NameSupport {
 		boolean hasRepackaging();
 	}

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

@@ -28,11 +28,13 @@
 import net.fabricmc.mappingio.format.FeatureSet.MemberSupport;
 import net.fabricmc.mappingio.format.FeatureSet.MetadataSupport;
 import net.fabricmc.mappingio.format.FeatureSet.NameSupport;
+import net.fabricmc.mappingio.format.FeatureSet.PackageSupport;
 import net.fabricmc.mappingio.format.FeatureSetImpl.ClassSupportImpl;
 import net.fabricmc.mappingio.format.FeatureSetImpl.DescSupportImpl;
 import net.fabricmc.mappingio.format.FeatureSetImpl.LocalSupportImpl;
 import net.fabricmc.mappingio.format.FeatureSetImpl.MemberSupportImpl;
 import net.fabricmc.mappingio.format.FeatureSetImpl.NameSupportImpl;
+import net.fabricmc.mappingio.format.FeatureSetImpl.PackageSupportImpl;
 
 @ApiStatus.Experimental
 public class FeatureSetBuilder {
@@ -45,7 +47,7 @@ public static FeatureSetBuilder createFrom(FeatureSet featureSet) {
 				featureSet.hasNamespaces(),
 				featureSet.fileMetadata(),
 				featureSet.elementMetadata(),
-				new NameFeatureBuilder(featureSet.packages()),
+				new PackageSupportBuilder(featureSet.packages()),
 				new ClassSupportBuilder(featureSet.classes()),
 				new MemberSupportBuilder(featureSet.fields()),
 				new MemberSupportBuilder(featureSet.methods()),
@@ -59,7 +61,7 @@ public static FeatureSetBuilder createFrom(FeatureSet featureSet) {
 		this(initWithFullSupport,
 				initWithFullSupport ? MetadataSupport.ARBITRARY : MetadataSupport.NONE,
 				initWithFullSupport ? MetadataSupport.ARBITRARY : MetadataSupport.NONE,
-				new NameFeatureBuilder(initWithFullSupport),
+				new PackageSupportBuilder(initWithFullSupport),
 				new ClassSupportBuilder(initWithFullSupport),
 				new MemberSupportBuilder(initWithFullSupport),
 				new MemberSupportBuilder(initWithFullSupport),
@@ -69,7 +71,7 @@ public static FeatureSetBuilder createFrom(FeatureSet featureSet) {
 				initWithFullSupport);
 	}
 
-	FeatureSetBuilder(boolean hasNamespaces, MetadataSupport fileMetadata, MetadataSupport elementMetadata, NameFeatureBuilder packages, ClassSupportBuilder classes, MemberSupportBuilder fields, MemberSupportBuilder methods, LocalSupportBuilder args, LocalSupportBuilder vars, ElementCommentSupport elementComments, boolean hasFileComments) {
+	FeatureSetBuilder(boolean hasNamespaces, MetadataSupport fileMetadata, MetadataSupport elementMetadata, PackageSupportBuilder packages, ClassSupportBuilder classes, MemberSupportBuilder fields, MemberSupportBuilder methods, LocalSupportBuilder args, LocalSupportBuilder vars, ElementCommentSupport elementComments, boolean hasFileComments) {
 		this.hasNamespaces = hasNamespaces;
 		this.fileMetadata = fileMetadata;
 		this.elementMetadata = elementMetadata;
@@ -98,7 +100,7 @@ public FeatureSetBuilder withElementMetadata(MetadataSupport featurePresence) {
 		return this;
 	}
 
-	public FeatureSetBuilder withPackages(Consumer<NameFeatureBuilder> featureApplier) {
+	public FeatureSetBuilder withPackages(Consumer<PackageSupportBuilder> featureApplier) {
 		featureApplier.accept(packages);
 		return this;
 	}
@@ -156,7 +158,7 @@ public FeatureSet build() {
 	private boolean hasNamespaces;
 	private MetadataSupport fileMetadata;
 	private MetadataSupport elementMetadata;
-	private NameFeatureBuilder packages;
+	private PackageSupportBuilder packages;
 	private ClassSupportBuilder classes;
 	private MemberSupportBuilder fields;
 	private MemberSupportBuilder methods;
@@ -165,6 +167,47 @@ public FeatureSet build() {
 	private ElementCommentSupport elementComments;
 	private boolean hasFileComments;
 
+	public static class PackageSupportBuilder {
+		PackageSupportBuilder() {
+			this(false);
+		}
+
+		PackageSupportBuilder(boolean initWithFullSupport) {
+			this(new NameFeatureBuilder(initWithFullSupport), initWithFullSupport);
+		}
+
+		PackageSupportBuilder(PackageSupport classFeature) {
+			this(new NameFeatureBuilder(classFeature), classFeature.hasStructureModification());
+		}
+
+		private PackageSupportBuilder(NameFeatureBuilder names, boolean hasStructureModification) {
+			this.names = names;
+			this.hasStructureModification = hasStructureModification;
+		}
+
+		public PackageSupportBuilder withSrcNames(FeaturePresence featurePresence) {
+			names.withSrcNames(featurePresence);
+			return this;
+		}
+
+		public PackageSupportBuilder withDstNames(FeaturePresence featurePresence) {
+			names.withDstNames(featurePresence);
+			return this;
+		}
+
+		public PackageSupportBuilder withStructureModification(boolean value) {
+			hasStructureModification = value;
+			return this;
+		}
+
+		public PackageSupport build() {
+			return new PackageSupportImpl(names.build(), hasStructureModification);
+		}
+
+		private NameFeatureBuilder names;
+		private boolean hasStructureModification;
+	}
+
 	public static class ClassSupportBuilder {
 		ClassSupportBuilder() {
 			this(false);