feat(jpms): add module-info for core/reader/writer [WIP]

core/src/main/java/module-info.java

@@ -0,0 +1,27 @@
+/// Vortex core module: shared type model, error contract, low-level I/O, compute kernels, and the
+/// generated FlatBuffers/Protobuf wire codecs.
+///
+/// The model, error, and I/O packages form the public surface shared with downstream tooling. The
+/// compute kernels and the generated `fbs`/`proto` codecs are internal plumbing, exported only to
+/// the reader and writer modules.
+// "module" lint suppressed for two unavoidable warnings under the zero-warning policy:
+// the group-derived name component `dfa1` has a terminal digit, and the qualified-export targets
+// (reader/writer) are not visible when this module is compiled standalone in the reactor.
+@SuppressWarnings("module")
+module io.github.dfa1.vortex.core {
+    // Compile-only: generated proto records carry @javax.annotation.processing.Generated
+    // (SOURCE retention, so not needed at runtime).
+    requires static java.compiler;
+
+    // Public API.
+    exports io.github.dfa1.vortex.core.model;
+    exports io.github.dfa1.vortex.core.error;
+    exports io.github.dfa1.vortex.core.io;
+
+    // Internal compute kernels and generated wire codecs: consumed only by reader/writer (modular
+    // path). Downstream non-modular tooling like the inspector reads them via the classpath, where
+    // these directives are ignored.
+    exports io.github.dfa1.vortex.core.compute to io.github.dfa1.vortex.reader, io.github.dfa1.vortex.writer;
+    exports io.github.dfa1.vortex.core.fbs to io.github.dfa1.vortex.reader, io.github.dfa1.vortex.writer;
+    exports io.github.dfa1.vortex.core.proto to io.github.dfa1.vortex.reader, io.github.dfa1.vortex.writer;
+}

reader/src/main/java/io/github/dfa1/vortex/reader/ArrayStats.java

@@ -37,6 +37,10 @@ public static ArrayStats empty() {
     ///
     /// @param fbs the FlatBuffers stats table, or `null`
     /// @return parsed stats, or an empty instance if no usable data is present
+    // Low-level entry point for the parse path and the inspector tool; intentionally exposes the
+    // generated FlatBuffers type, which core only qualified-exports. Suppress the resulting
+    // exports-leak lint rather than widen the core export or hide this factory.
+    @SuppressWarnings("exports")
     public static ArrayStats fromFbs(io.github.dfa1.vortex.core.fbs.FbsArrayStats fbs) {
         if (fbs == null) {
             return EMPTY;

reader/src/main/java/module-info.java

@@ -0,0 +1,58 @@
+/// Vortex reader module: memory-mapped file parsing, the layout/scan engine, decoded `Array`
+/// types, and the encoding/extension decoders dispatched via [java.util.ServiceLoader].
+///
+/// `vortex.core` is re-exported (`requires transitive`) because decoded types surface core model
+/// types (`DType`, `PType`, …) in the public API. The native zstd codec is optional
+/// (`requires static`): the `vortex.zstd` decoder loads only when the `zstd` module is present.
+// Lint suppressed: `module` for the group-derived terminal-digit name component `dfa1`;
+// `requires-automatic` because the optional `zstd` codec ships as an automatic module (no
+// module descriptor yet) and is pulled in via `requires static`.
+@SuppressWarnings({"module", "requires-automatic"})
+module io.github.dfa1.vortex.reader {
+    requires transitive io.github.dfa1.vortex.core;
+    requires static zstd;
+    // transitive: VortexHttpReader.open exposes java.net.http.HttpClient in its public signature.
+    requires transitive java.net.http;
+
+    exports io.github.dfa1.vortex.reader;
+    exports io.github.dfa1.vortex.reader.array;
+    exports io.github.dfa1.vortex.reader.decode;
+    exports io.github.dfa1.vortex.reader.extension;
+
+    uses io.github.dfa1.vortex.reader.decode.EncodingDecoder;
+
+    provides io.github.dfa1.vortex.reader.decode.EncodingDecoder with
+            io.github.dfa1.vortex.reader.decode.AlpEncodingDecoder,
+            io.github.dfa1.vortex.reader.decode.AlpRdEncodingDecoder,
+            io.github.dfa1.vortex.reader.decode.BitpackedEncodingDecoder,
+            io.github.dfa1.vortex.reader.decode.BoolEncodingDecoder,
+            io.github.dfa1.vortex.reader.decode.ByteBoolEncodingDecoder,
+            io.github.dfa1.vortex.reader.decode.ChunkedEncodingDecoder,
+            io.github.dfa1.vortex.reader.decode.ConstantEncodingDecoder,
+            io.github.dfa1.vortex.reader.decode.DateTimePartsEncodingDecoder,
+            io.github.dfa1.vortex.reader.decode.DecimalBytePartsEncodingDecoder,
+            io.github.dfa1.vortex.reader.decode.DecimalEncodingDecoder,
+            io.github.dfa1.vortex.reader.decode.DeltaEncodingDecoder,
+            io.github.dfa1.vortex.reader.decode.DictEncodingDecoder,
+            io.github.dfa1.vortex.reader.decode.ExtEncodingDecoder,
+            io.github.dfa1.vortex.reader.decode.FixedSizeListEncodingDecoder,
+            io.github.dfa1.vortex.reader.decode.FrameOfReferenceEncodingDecoder,
+            io.github.dfa1.vortex.reader.decode.FsstEncodingDecoder,
+            io.github.dfa1.vortex.reader.decode.ListEncodingDecoder,
+            io.github.dfa1.vortex.reader.decode.ListViewEncodingDecoder,
+            io.github.dfa1.vortex.reader.decode.MaskedEncodingDecoder,
+            io.github.dfa1.vortex.reader.decode.NullEncodingDecoder,
+            io.github.dfa1.vortex.reader.decode.PatchedEncodingDecoder,
+            io.github.dfa1.vortex.reader.decode.PcoEncodingDecoder,
+            io.github.dfa1.vortex.reader.decode.PrimitiveEncodingDecoder,
+            io.github.dfa1.vortex.reader.decode.RleEncodingDecoder,
+            io.github.dfa1.vortex.reader.decode.RunEndEncodingDecoder,
+            io.github.dfa1.vortex.reader.decode.SequenceEncodingDecoder,
+            io.github.dfa1.vortex.reader.decode.SparseEncodingDecoder,
+            io.github.dfa1.vortex.reader.decode.StructEncodingDecoder,
+            io.github.dfa1.vortex.reader.decode.VarBinEncodingDecoder,
+            io.github.dfa1.vortex.reader.decode.VariantEncodingDecoder,
+            io.github.dfa1.vortex.reader.decode.VarBinViewEncodingDecoder,
+            io.github.dfa1.vortex.reader.decode.ZigZagEncodingDecoder,
+            io.github.dfa1.vortex.reader.decode.ZstdEncodingDecoder;
+}

writer/pom.xml

@@ -61,6 +61,38 @@
 		</dependency>
 	</dependencies>
 
+	<build>
+		<plugins>
+			<!-- The writer is a JPMS module that (correctly) does not require the reader. Its tests,
+			     however, decode-verify round-trips and so use reader types via the test-scope reader
+			     dependency. Let the test-patched module read the whole module path at test compile,
+			     and run the tests on the classpath so the test JVM sees reader + its services. -->
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-compiler-plugin</artifactId>
+				<executions>
+					<execution>
+						<id>default-testCompile</id>
+						<configuration>
+							<compilerArgs>
+								<arg>-Xlint:all</arg>
+								<arg>--add-reads</arg>
+								<arg>io.github.dfa1.vortex.writer=ALL-MODULE-PATH</arg>
+							</compilerArgs>
+						</configuration>
+					</execution>
+				</executions>
+			</plugin>
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-surefire-plugin</artifactId>
+				<configuration>
+					<useModulePath>false</useModulePath>
+				</configuration>
+			</plugin>
+		</plugins>
+	</build>
+
 	<profiles>
 		<!-- Mutation testing (opt-in: -P pitest). Common PIT setup is inherited from the parent
 		     `pitest` profile; only the scope differs. Run: ./mvnw -pl writer -am -P pitest verify

writer/src/main/java/io/github/dfa1/vortex/writer/encode/VariantData.java

@@ -23,6 +23,10 @@
 /// @param values       one inner scalar per row, in row order
 /// @param shreddedData  optional typed column data for the shredded child, or `null`
 /// @param shreddedDtype dtype of `shreddedData`, or `null`
+// Variant authoring takes inner scalars as the generated ProtoScalar (mirroring Rust), which core
+// only qualified-exports. Suppress the exports-leak lint rather than widen the core proto export
+// (which would publish the whole generated codec) or invent a parallel public scalar type.
+@SuppressWarnings("exports")
 public record VariantData(List<ProtoScalar> values, Object shreddedData, DType shreddedDtype) {
 
     /// Validates and defensively copies the per-row values; rejects empty input and a

writer/src/main/java/module-info.java

@@ -0,0 +1,60 @@
+/// Vortex writer module: the columnar file writer, encode pipeline, and the encoding/extension
+/// encoders dispatched via [java.util.ServiceLoader].
+///
+/// `vortex.core` is re-exported (`requires transitive`) because the write API surfaces core model
+/// types (`DType`, …). The writer never depends on the reader. The native zstd codec is optional
+/// (`requires static`).
+// Lint suppressed: `module` for the group-derived terminal-digit name component `dfa1`;
+// `requires-automatic` because the optional `zstd` codec ships as an automatic module.
+@SuppressWarnings({"module", "requires-automatic"})
+module io.github.dfa1.vortex.writer {
+    requires transitive io.github.dfa1.vortex.core;
+    requires static zstd;
+
+    exports io.github.dfa1.vortex.writer;
+    exports io.github.dfa1.vortex.writer.encode;
+
+    uses io.github.dfa1.vortex.writer.encode.EncodingEncoder;
+    uses io.github.dfa1.vortex.writer.ExtensionEncoder;
+
+    provides io.github.dfa1.vortex.writer.encode.EncodingEncoder with
+            io.github.dfa1.vortex.writer.encode.AlpEncodingEncoder,
+            io.github.dfa1.vortex.writer.encode.AlpRdEncodingEncoder,
+            io.github.dfa1.vortex.writer.encode.BitpackedEncodingEncoder,
+            io.github.dfa1.vortex.writer.encode.BoolEncodingEncoder,
+            io.github.dfa1.vortex.writer.encode.ByteBoolEncodingEncoder,
+            io.github.dfa1.vortex.writer.encode.ChunkedEncodingEncoder,
+            io.github.dfa1.vortex.writer.encode.ConstantEncodingEncoder,
+            io.github.dfa1.vortex.writer.encode.DateTimePartsEncodingEncoder,
+            io.github.dfa1.vortex.writer.encode.DecimalBytePartsEncodingEncoder,
+            io.github.dfa1.vortex.writer.encode.DecimalEncodingEncoder,
+            io.github.dfa1.vortex.writer.encode.DeltaEncodingEncoder,
+            io.github.dfa1.vortex.writer.encode.DictEncodingEncoder,
+            io.github.dfa1.vortex.writer.encode.ExtEncodingEncoder,
+            io.github.dfa1.vortex.writer.encode.FixedSizeListEncodingEncoder,
+            io.github.dfa1.vortex.writer.encode.FrameOfReferenceEncodingEncoder,
+            io.github.dfa1.vortex.writer.encode.FsstEncodingEncoder,
+            io.github.dfa1.vortex.writer.encode.ListEncodingEncoder,
+            io.github.dfa1.vortex.writer.encode.ListViewEncodingEncoder,
+            io.github.dfa1.vortex.writer.encode.MaskedEncodingEncoder,
+            io.github.dfa1.vortex.writer.encode.NullEncodingEncoder,
+            io.github.dfa1.vortex.writer.encode.PatchedEncodingEncoder,
+            io.github.dfa1.vortex.writer.encode.PcoEncodingEncoder,
+            io.github.dfa1.vortex.writer.encode.PrimitiveEncodingEncoder,
+            io.github.dfa1.vortex.writer.encode.RleEncodingEncoder,
+            io.github.dfa1.vortex.writer.encode.RunEndEncodingEncoder,
+            io.github.dfa1.vortex.writer.encode.SequenceEncodingEncoder,
+            io.github.dfa1.vortex.writer.encode.SparseEncodingEncoder,
+            io.github.dfa1.vortex.writer.encode.StructEncodingEncoder,
+            io.github.dfa1.vortex.writer.encode.VarBinEncodingEncoder,
+            io.github.dfa1.vortex.writer.encode.VariantEncodingEncoder,
+            io.github.dfa1.vortex.writer.encode.VarBinViewEncodingEncoder,
+            io.github.dfa1.vortex.writer.encode.ZigZagEncodingEncoder,
+            io.github.dfa1.vortex.writer.encode.ZstdEncodingEncoder;
+
+    provides io.github.dfa1.vortex.writer.ExtensionEncoder with
+            io.github.dfa1.vortex.writer.encode.DateExtensionEncoder,
+            io.github.dfa1.vortex.writer.encode.TimeExtensionEncoder,
+            io.github.dfa1.vortex.writer.encode.TimestampExtensionEncoder,
+            io.github.dfa1.vortex.writer.encode.UuidExtensionEncoder;
+}