Cleaned up Snapshot naming, path and location to be consistent

Author: oskardudycz

src/jvm/src/main/java/io/eventdriven/strictland/FileSnapshotStorage.java

@@ -20,13 +20,13 @@
  * and fails the check.</p>
  *
  * <p> `FileSnapshotStorage` is a thin wrapper that just writes bytes and reads them back.
- * The path, layout, test variant label are resolved byt the caller (so test suite).</p>
+ * The path, layout, and variant are resolved by the caller before the bytes reach storage.</p>
  */
 class FileSnapshotStorage implements SnapshotStorage {
 
     private static final String APPROVED_MARKER = ".approved.";
     private static final String RECEIVED_MARKER = ".received.";
-    private static final String SNAP_APPROVED_MARKER = ".snap.approved.";
+    static final String SNAP_APPROVED_MARKER = ".snap.approved.";
 
     @Override
     public void store(String pathWithName, byte[] payload) {
@@ -68,17 +68,16 @@ public Optional<byte[]> read(String pathWithName) {
     }
 
     @Override
-    public List<byte[]> readAll(SnapshotReadLocation location) {
-        var folder = location.folder();
+    public List<byte[]> readAll(@Nullable Path folder, String prefix, @Nullable String variant) {
         if (folder == null || !Files.isDirectory(folder)) {
             return List.of();
         }
         try (Stream<Path> files = Files.list(folder)) {
             var matches = files.filter(path -> {
                         var name = path.getFileName().toString();
-                        return name.startsWith(location.prefix())
+                        return name.startsWith(prefix)
                                 && name.contains(APPROVED_MARKER)
-                                && matchesVariant(name, location.variant());
+                                && matchesVariant(name, variant);
                     })
                     .sorted(Comparator.comparing(path -> path.getFileName().toString()))
                     .toList();

src/jvm/src/main/java/io/eventdriven/strictland/GivenStep.java

@@ -17,7 +17,8 @@ public class GivenStep<S> {
     final String version;
     final MessageSerializer serializer;
     final SnapshotStorage storage;
-    final SnapshotLocation location;
+    final @Nullable SnapshotLayout layout;
+    final String fileExtension;
     final MessageTypeMapper typeMapper;
 
     GivenStep(
@@ -26,14 +27,16 @@ public class GivenStep<S> {
             String version,
             MessageSerializer serializer,
             SnapshotStorage storage,
-            SnapshotLocation location,
+            @Nullable SnapshotLayout layout,
+            String fileExtension,
             MessageTypeMapper typeMapper) {
         this.snapshot = snapshot;
         this.instance = instance;
         this.version = version;
         this.serializer = serializer;
         this.storage = storage;
-        this.location = location;
+        this.layout = layout;
+        this.fileExtension = fileExtension;
         this.typeMapper = typeMapper;
     }
 
@@ -57,7 +60,7 @@ public class GivenStep<S> {
      */
     public ThenContractStep<S> whenSerialized() {
         var instance = requireInstance();
-        return new ThenContractStep<>(instance, null, version, serializer, storage, location, typeMapper);
+        return new ThenContractStep<>(instance, null, version, serializer, storage, layout, fileExtension, typeMapper);
     }
 
     /**
@@ -81,7 +84,8 @@ public ThenContractStep<S> whenSerialized() {
      */
     public ThenContractStep<S> whenSerializedAs(Snapshot destination) {
         var instance = requireInstance();
-        return new ThenContractStep<>(instance, destination, version, serializer, storage, location, typeMapper);
+        return new ThenContractStep<>(
+                instance, destination, version, serializer, storage, layout, fileExtension, typeMapper);
     }
 
     /**
@@ -112,7 +116,8 @@ public ThenContractStep<S> whenSerializedAs(SnapshotVariant variant) {
                 version,
                 serializer,
                 storage,
-                location,
+                layout,
+                fileExtension,
                 typeMapper);
     }
 
@@ -145,6 +150,6 @@ private S requireInstance() {
      */
     public <T> ThenCompatibilityStep<S, T> whenDeserializedAs(Class<T> targetType) {
         return new ThenCompatibilityStep<>(
-                snapshot, instance, version, targetType, serializer, storage, location, typeMapper);
+                snapshot, instance, version, targetType, serializer, storage, layout, typeMapper);
     }
 }

src/jvm/src/main/java/io/eventdriven/strictland/MessageContract.java

@@ -1,5 +1,7 @@
 package io.eventdriven.strictland;
 
+import org.jspecify.annotations.Nullable;
+
 /**
  * Strictland is a contract-testing library for the messages your code sends and stores: events,
  * commands, queue messages, HTTP requests and responses, and anything else you serialize for someone
@@ -24,28 +26,26 @@
  * </pre>
  *
  * <p>The approved file each check compares against lives in a committed contract registry, under
- * {@code src/test/resources/contract-snapshots} by default, so a contract change shows up in the same
+ * {@code src/test/resources/contract-registry} by default, so a contract change shows up in the same
  * pull request as the code that caused it.
  * {@link Snapshot} picks which file backs a check, and {@link PublicApiScanner} renders a package's
  * public API as text so you can approval-test the surface itself.</p>
  */
 public class MessageContract {
     private final MessageSerializer serializer;
     private final SnapshotStorage storage;
-    private final SnapshotLocation location;
+    private final @Nullable SnapshotLayout layout;
     private final MessageTypeMapper typeMapper;
 
     private MessageContract(SpecificationOptions options) {
         this.serializer = options.serializer();
         var configuredStorage = options.storage();
         if (configuredStorage != null) {
             this.storage = configuredStorage;
-            this.location = new SnapshotLocation(null, options.serializer().fileExtension(), TestClassNaming.SIMPLE);
+            this.layout = null;
         } else {
-            var layout = SnapshotLayoutResolver.resolve(options.snapshotLayout());
+            this.layout = SnapshotLayoutResolver.resolve(options.snapshotLayout());
             this.storage = new FileSnapshotStorage();
-            this.location =
-                    new SnapshotLocation(layout, options.serializer().fileExtension(), layout.testClassNaming());
         }
         var configuredTypeMapper = options.typeMapper();
         this.typeMapper = configuredTypeMapper != null ? configuredTypeMapper : MessageTypeMapper.fullyQualifiedName();
@@ -90,7 +90,15 @@ public static MessageContract specification(SpecificationOptions options) {
      * @return the next step, where you choose what to check
      */
     public <S> GivenStep<S> given(Snapshot.ByClass<S> snapshot) {
-        return new GivenStep<>(snapshot, null, snapshot.version(), serializer, storage, location, typeMapper);
+        return new GivenStep<>(
+                snapshot,
+                null,
+                snapshot.version(),
+                serializer,
+                storage,
+                layout,
+                serializer.fileExtension(),
+                typeMapper);
     }
 
     /**
@@ -105,7 +113,15 @@ public <S> GivenStep<S> given(Snapshot.ByClass<S> snapshot) {
      * @return the next step, where you choose what to check
      */
     public GivenStep<Object> given(Snapshot.ByMessageType snapshot) {
-        return new GivenStep<>(snapshot, null, snapshot.version(), serializer, storage, location, typeMapper);
+        return new GivenStep<>(
+                snapshot,
+                null,
+                snapshot.version(),
+                serializer,
+                storage,
+                layout,
+                serializer.fileExtension(),
+                typeMapper);
     }
 
     /**
@@ -119,7 +135,15 @@ public GivenStep<Object> given(Snapshot.ByMessageType snapshot) {
      * @return the next step, where you choose what to check
      */
     public GivenStep<Object> given(Snapshot.ByPath snapshot) {
-        return new GivenStep<>(snapshot, null, Snapshot.DEFAULT_VERSION, serializer, storage, location, typeMapper);
+        return new GivenStep<>(
+                snapshot,
+                null,
+                Snapshot.DEFAULT_VERSION,
+                serializer,
+                storage,
+                layout,
+                serializer.fileExtension(),
+                typeMapper);
     }
 
     /**
@@ -134,7 +158,15 @@ public GivenStep<Object> given(Snapshot.ByPath snapshot) {
      * @return the next step, where you choose what to check
      */
     public <S> GivenStep<S> given(S instance) {
-        return new GivenStep<>(null, instance, Snapshot.DEFAULT_VERSION, serializer, storage, location, typeMapper);
+        return new GivenStep<>(
+                null,
+                instance,
+                Snapshot.DEFAULT_VERSION,
+                serializer,
+                storage,
+                layout,
+                serializer.fileExtension(),
+                typeMapper);
     }
 
     /**
@@ -151,6 +183,7 @@ public <S> GivenStep<S> given(S instance) {
      * @return the next step, where you choose what to check
      */
     public <S> GivenStep<S> given(S instance, String version) {
-        return new GivenStep<>(null, instance, version, serializer, storage, location, typeMapper);
+        return new GivenStep<>(
+                null, instance, version, serializer, storage, layout, serializer.fileExtension(), typeMapper);
     }
 }

src/jvm/src/main/java/io/eventdriven/strictland/MessageTypeName.java

@@ -0,0 +1,31 @@
+package io.eventdriven.strictland;
+
+/**
+ * A message type's name split into its namespace and short name. The snapshot machinery names files by
+ * the short name and lays out folders by the namespace, so splitting once here keeps that math in one
+ * place.
+ *
+ * <p>The namespace is everything before the last dot, the short name everything after it. A dotless
+ * logical name has an empty namespace and is its own short name.</p>
+ *
+ * @param namespace the part before the last dot, empty when the name has none
+ * @param shortName the part after the last dot, the whole name when it has none
+ */
+record MessageTypeName(String namespace, String shortName) {
+
+    /**
+     * Splits a message type's name on its last dot into a namespace and a short name. A fully-qualified
+     * name like {@code com.acme.orders.OrderPlaced} splits into the namespace {@code com.acme.orders}
+     * and the short name {@code OrderPlaced}. A dotless logical name keeps an empty namespace and is its
+     * own short name.
+     *
+     * @param messageType the message type's name to split
+     * @return the namespace and short name the message type's name carries
+     */
+    static MessageTypeName of(String messageType) {
+        var dot = messageType.lastIndexOf('.');
+        return dot < 0
+                ? new MessageTypeName("", messageType)
+                : new MessageTypeName(messageType.substring(0, dot), messageType.substring(dot + 1));
+    }
+}

src/jvm/src/main/java/io/eventdriven/strictland/SnapshotLayout.java

@@ -10,39 +10,38 @@
  * <p>The layout is a single registry tree. Snapshots gather under {@code rootPath/wrapperFolder}, and
  * the message type's namespace becomes folders beneath that, ending in a folder named after the short
  * message type. So {@code com.acme.orders.OrderPlaced} resolves under {@code
- * src/test/resources/contract-snapshots/com/acme/orders/OrderPlaced}. A dotless message type has no
+ * src/test/resources/contract-registry/com/acme/orders/OrderPlaced}. A dotless message type has no
  * namespace folders. Each refinement returns a copy, so a layout stays immutable.</p>
  *
  * <pre>
  * SnapshotLayout layout = SnapshotLayout.registry();
  * Path path = layout.resolve("com.acme.orders.OrderPlaced", "OrderPlaced", ".json");
- * // src/test/resources/contract-snapshots/com/acme/orders/OrderPlaced/OrderPlaced.snap.approved.json
+ * // src/test/resources/contract-registry/com/acme/orders/OrderPlaced/OrderPlaced.snap.approved.json
  * </pre>
  *
  * @param rootPath the directory the snapshot tree is rooted at
  * @param wrapperFolder the segment under the root that holds the per-namespace folders
- * @param testClassNaming how the test class is named in an owned snapshot's file name
  */
-public record SnapshotLayout(String rootPath, String wrapperFolder, TestClassNaming testClassNaming) {
+public record SnapshotLayout(String rootPath, String wrapperFolder) {
 
     private static final String DEFAULT_ROOT_PATH = "src/test/resources";
-    private static final String DEFAULT_WRAPPER_FOLDER = "contract-snapshots";
+    private static final String DEFAULT_WRAPPER_FOLDER = "contract-registry";
     private static final String SNAP_APPROVED_SUFFIX = ".snap.approved";
 
     /**
-     * The default registry layout: snapshots under {@code src/test/resources/contract-snapshots}, with
-     * the message type's namespace as folders beneath it and the test class named by its simple name.
+     * The default registry layout: snapshots under {@code src/test/resources/contract-registry}, with
+     * the message type's namespace as folders beneath it.
      *
      * <pre>
      * SnapshotLayout layout = SnapshotLayout.registry();
      * Path path = layout.resolve("com.acme.orders.OrderPlaced", "OrderPlaced", ".json");
-     * // src/test/resources/contract-snapshots/com/acme/orders/OrderPlaced/OrderPlaced.snap.approved.json
+     * // src/test/resources/contract-registry/com/acme/orders/OrderPlaced/OrderPlaced.snap.approved.json
      * </pre>
      *
      * @return the default registry layout
      */
     public static SnapshotLayout registry() {
-        return new SnapshotLayout(DEFAULT_ROOT_PATH, DEFAULT_WRAPPER_FOLDER, TestClassNaming.SIMPLE);
+        return new SnapshotLayout(DEFAULT_ROOT_PATH, DEFAULT_WRAPPER_FOLDER);
     }
 
     /**
@@ -57,12 +56,12 @@ public static SnapshotLayout registry() {
      * @return a copy of this layout rooted at the given directory
      */
     public SnapshotLayout rootPath(String rootPath) {
-        return new SnapshotLayout(rootPath, wrapperFolder, testClassNaming);
+        return new SnapshotLayout(rootPath, wrapperFolder);
     }
 
     /**
      * Returns a copy with a different wrapper folder, the segment under the root that holds the
-     * per-namespace folders. The default is {@code contract-snapshots}; set it to match your convention.
+     * per-namespace folders. The default is {@code contract-registry}; set it to match your convention.
      *
      * <pre>
      * SnapshotLayout underApproved = SnapshotLayout.registry().wrapperFolder("approved");
@@ -72,23 +71,7 @@ public SnapshotLayout rootPath(String rootPath) {
      * @return a copy of this layout using the given wrapper folder
      */
     public SnapshotLayout wrapperFolder(String wrapperFolder) {
-        return new SnapshotLayout(rootPath, wrapperFolder, testClassNaming);
-    }
-
-    /**
-     * Returns a copy that names the test class differently inside an owned snapshot's file name, for
-     * keeping snapshots distinct when two test classes share a simple name. It changes only the file
-     * name, never the folder a snapshot resolves under.
-     *
-     * <pre>
-     * SnapshotLayout qualified = SnapshotLayout.registry().testClassNaming(TestClassNaming.FULL);
-     * </pre>
-     *
-     * @param testClassNaming how the test class is named in an owned snapshot's file name
-     * @return a copy of this layout using the given test-class naming
-     */
-    public SnapshotLayout testClassNaming(TestClassNaming testClassNaming) {
-        return new SnapshotLayout(rootPath, wrapperFolder, testClassNaming);
+        return new SnapshotLayout(rootPath, wrapperFolder);
     }
 
     /**
@@ -101,7 +84,7 @@ public SnapshotLayout testClassNaming(TestClassNaming testClassNaming) {
      *
      * <pre>
      * Path path = SnapshotLayout.registry().resolve("com.acme.orders.OrderPlaced", "withCoupon", ".json");
-     * // src/test/resources/contract-snapshots/com/acme/orders/OrderPlaced/withCoupon.snap.approved.json
+     * // src/test/resources/contract-registry/com/acme/orders/OrderPlaced/withCoupon.snap.approved.json
      * </pre>
      *
      * @param messageType the message type's fully-qualified name, whose namespace and short name shape
@@ -112,11 +95,22 @@ public SnapshotLayout testClassNaming(TestClassNaming testClassNaming) {
      */
     public Path resolve(String messageType, String snapshotName, String fileExtension) {
         var fileName = snapshotName + SNAP_APPROVED_SUFFIX + fileExtension;
+        return folder(MessageTypeName.of(messageType)).resolve(fileName);
+    }
+
+    /**
+     * Resolves the directory a message type's snapshots live in: the namespace as folders under {@code
+     * rootPath/wrapperFolder}, ending in a folder named after the short message type. A dotless message
+     * type has no namespace folders.
+     *
+     * @param messageType the message type whose namespace and short name shape the folder
+     * @return the directory the message type's approved files live in
+     */
+    Path folder(MessageTypeName messageType) {
         var folder = Path.of(rootPath, wrapperFolder);
-        var namespace = SnapshotName.namespace(messageType);
-        if (!namespace.isEmpty()) {
-            folder = folder.resolve(namespace.replace('.', '/'));
+        if (!messageType.namespace().isEmpty()) {
+            folder = folder.resolve(messageType.namespace().replace('.', '/'));
         }
-        return folder.resolve(SnapshotName.shortName(messageType)).resolve(fileName);
+        return folder.resolve(messageType.shortName());
     }
 }