test: add property-based tests for NaturalSortOrder, merge, sort, take/drop (#658)

- ValuesTest: reflexivity, antisymmetry, transitivity for NaturalSortOrder;
  commutativity for NumericValue.merge() and SizeValue.merge()
- TextModuleTest: idempotence for Sort; partition property for Take+Drop
- Allow @Property and @provide in UnitTestsFitnessTest architecture rule
- Add jqwik dependency to text and test-support modules
- Add CLAUDE.md with PBT guidance (notes jqwik/JUnit 6 engine incompatibility)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: dfa1

CLAUDE.md

@@ -0,0 +1,19 @@
+# hosh project guidance
+
+## Testing
+
+### Property-Based Testing (PBT)
+
+This project uses [jqwik](https://jqwik.net/) for property-based tests.
+
+**Known issue:** jqwik 1.9.3 targets JUnit Platform 1.x but the project uses JUnit 6 (Platform 6.x). `@Property` tests compile and are structurally correct but the jqwik engine does not execute them at runtime. Track https://github.com/jqwik-team/jqwik/issues for jqwik 2.x release targeting JUnit 6.
+
+**Writing property tests:** use `@Property` + `@ForAll` for parameters, `@Provide` for custom arbitraries, `Assume.that(...)` for preconditions. Follow the existing patterns in `ValuesTest.java` (spi module).
+
+**Key properties to test:**
+- Comparator contract: reflexivity, antisymmetry, transitivity
+- Merge commutativity: `a.merge(b) == b.merge(a)`
+- Sort idempotence: `sort(sort(xs)) == sort(xs)`
+- Partition: `take(n, xs) + drop(n, xs) == xs`
+
+**Architecture rule:** `UnitTestsFitnessTest` allows `@Property` and `@Provide` annotations alongside the standard JUnit annotations (`@Test`, `@BeforeEach`, `@AfterEach`, `@ParameterizedTest`).

modules/text/pom.xml

@@ -47,5 +47,10 @@
 			<artifactId>mockito-junit-jupiter</artifactId>
 			<scope>test</scope>
 		</dependency>
+		<dependency>
+			<groupId>net.jqwik</groupId>
+			<artifactId>jqwik</artifactId>
+			<scope>test</scope>
+		</dependency>
 	</dependencies>
 </project>

modules/text/src/test/java/hosh/modules/text/TextModuleTest.java

@@ -41,6 +41,13 @@
 import hosh.modules.text.TextModule.Trim;
 import hosh.spi.test.support.RecordMatcher;
 import hosh.spi.CommandArguments;
+import net.jqwik.api.Arbitrary;
+import net.jqwik.api.Arbitraries;
+import net.jqwik.api.Assume;
+import net.jqwik.api.ForAll;
+import net.jqwik.api.Property;
+import net.jqwik.api.Provide;
+import net.jqwik.api.constraints.IntRange;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Nested;
 import org.junit.jupiter.api.Test;
@@ -54,6 +61,9 @@
 
 import java.time.Clock;
 import java.time.Instant;
+import java.util.ArrayList;
+import java.util.Iterator;
+import java.util.List;
 import java.util.Optional;
 
 import static hosh.spi.test.support.ExitStatusAssert.assertThat;
@@ -1933,4 +1943,57 @@ void zeroArgs() {
 		}
 	}
 
+	@Nested
+	class SortPropertyTest {
+
+		@Property
+		void sortIsIdempotent(@ForAll("textRecordLists") List<Record> input) {
+			Sort sut = new Sort();
+			List<Record> firstSort = runSort(sut, input);
+			List<Record> secondSort = runSort(sut, firstSort);
+			assertThat(firstSort).containsExactlyElementsOf(secondSort);
+		}
+
+		private List<Record> runSort(Sort sut, List<Record> input) {
+			List<Record> result = new ArrayList<>();
+			sut.run(CommandArguments.of("name"), fromList(input), result::add, record -> {});
+			return result;
+		}
+	}
+
+	@Nested
+	class TakeDropPropertyTest {
+
+		@Property
+		void takeAndDropPartitionInput(@ForAll("textRecordLists") List<Record> input,
+				@ForAll @IntRange(min = 0, max = 20) int n) {
+			Assume.that(n <= input.size());
+			Take takeSut = new Take();
+			Drop dropSut = new Drop();
+			OutputChannel noopErr = record -> {};
+
+			List<Record> taken = new ArrayList<>();
+			takeSut.run(CommandArguments.of(String.valueOf(n)), fromList(input), taken::add, noopErr);
+
+			List<Record> dropped = new ArrayList<>();
+			dropSut.run(CommandArguments.of(String.valueOf(n)), fromList(input), dropped::add, noopErr);
+
+			List<Record> combined = new ArrayList<>(taken);
+			combined.addAll(dropped);
+			assertThat(combined).containsExactlyElementsOf(input);
+		}
+	}
+
+	@Provide
+	Arbitrary<List<Record>> textRecordLists() {
+		return Arbitraries.strings().alpha().ofMinLength(0).ofMaxLength(10)
+				.map(s -> Records.singleton(Keys.NAME, Values.ofText(s)))
+				.list().ofMinSize(0).ofMaxSize(20);
+	}
+
+	private static InputChannel fromList(List<Record> records) {
+		Iterator<Record> it = records.iterator();
+		return () -> it.hasNext() ? Optional.of(it.next()) : Optional.empty();
+	}
+
 }

spi/src/test/java/hosh/spi/ValuesTest.java

@@ -32,9 +32,11 @@
 import org.junit.jupiter.params.provider.CsvSource;
 import net.jqwik.api.Arbitraries;
 import net.jqwik.api.Arbitrary;
+import net.jqwik.api.Assume;
 import net.jqwik.api.ForAll;
 import net.jqwik.api.Property;
 import net.jqwik.api.Provide;
+import net.jqwik.api.constraints.IntRange;
 
 import java.nio.file.Path;
 import java.nio.file.Paths;
@@ -907,6 +909,22 @@ void sortMisc() {
 				// Then
 				assertThat(input).containsExactly("1.a", "2.a", "a.1", "b.1");
 			}
+
+			@Property
+			void reflexive(@ForAll String s) {
+				assertThat(sut.compare(s, s)).isEqualTo(0);
+			}
+
+			@Property
+			void antisymmetric(@ForAll String a, @ForAll String b) {
+				assertThat(Integer.signum(sut.compare(a, b))).isEqualTo(-Integer.signum(sut.compare(b, a)));
+			}
+
+			@Property
+			void transitive(@ForAll String a, @ForAll String b, @ForAll String c) {
+				Assume.that(sut.compare(a, b) <= 0 && sut.compare(b, c) <= 0);
+				assertThat(sut.compare(a, c)).isLessThanOrEqualTo(0);
+			}
 		}
 
 		@Nested
@@ -984,6 +1002,20 @@ void mergeSizeValues() {
 			assertThat(none.merge(size)).hasValue(size);
 			assertThat(size.merge(none)).hasValue(size);
 		}
+
+		@Property
+		void numericMergeIsCommutative(@ForAll int a, @ForAll int b) {
+			Value va = Values.ofNumeric(a);
+			Value vb = Values.ofNumeric(b);
+			assertThat(va.merge(vb)).isEqualTo(vb.merge(va));
+		}
+
+		@Property
+		void sizesMergeIsCommutative(@ForAll @IntRange(min = 0) int a, @ForAll @IntRange(min = 0) int b) {
+			Value va = Values.ofSize(a);
+			Value vb = Values.ofSize(b);
+			assertThat(va.merge(vb)).isEqualTo(vb.merge(va));
+		}
 	}
 
 }

test-support/pom.xml

@@ -32,6 +32,10 @@
 			<groupId>org.slf4j</groupId>
 			<artifactId>slf4j-simple</artifactId>
 		</dependency>
+		<dependency>
+			<groupId>net.jqwik</groupId>
+			<artifactId>jqwik</artifactId>
+		</dependency>
 		<!-- test classpath -->
 		<dependency>
 			<groupId>org.junit.jupiter</groupId>

test-support/src/main/java/hosh/test/fitness/UnitTestsFitnessTest.java

@@ -31,6 +31,8 @@
 import com.tngtech.archunit.lang.ConditionEvents;
 import com.tngtech.archunit.lang.SimpleConditionEvent;
 import com.tngtech.archunit.lang.syntax.ArchRuleDefinition;
+import net.jqwik.api.Property;
+import net.jqwik.api.Provide;
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
@@ -55,7 +57,9 @@ public abstract class UnitTestsFitnessTest {
 					.should().beAnnotatedWith(Test.class)
 					.orShould().beAnnotatedWith(BeforeEach.class)
 					.orShould().beAnnotatedWith(AfterEach.class)
-					.orShould().beAnnotatedWith(ParameterizedTest.class);
+					.orShould().beAnnotatedWith(ParameterizedTest.class)
+					.orShould().beAnnotatedWith(Property.class)
+					.orShould().beAnnotatedWith(Provide.class);
 
 	@SuppressWarnings("unused")
 	@ArchTag("fitness")