♻️ Label arrange-act-assert blocks in specs

Rework every test body into // Arrange / // Act / // Assert blocks
separated by blank lines: the factory is arranged once, the matcher is
built from it in a single act, and all type/runtime checks sink to the
end. index.test.ts adopts the same shape.

Also migrate off expect-type's deprecated toMatchTypeOf: the checks
are assignability tests, so toExtend is the faithful replacement.

src/primitive.test.ts

@@ -16,26 +16,37 @@ import {
 // ============================================================================
 
 test("getPrimitiveUnionMatcherW requires every literal key", () => {
-    const matcher = getPrimitiveUnionMatcherW<"a" | "b">()({
+    // Arrange
+    const factory = getPrimitiveUnionMatcherW<"a" | "b">();
+
+    // Act
+    const matcher = factory({
         a: () => 1 as const,
         b: () => "two" as const,
     });
+
+    // Assert
     // ❌ ReturnsStrict: mixed handler returns widen to their union.
     expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b") => 1 | "two">();
     // A pattern missing a key must not satisfy the parameter type.
-    const factory = getPrimitiveUnionMatcherW<"a" | "b">();
     expectTypeOf<{
         a: () => number;
-    }>().not.toMatchTypeOf<Parameters<typeof factory>[0]>();
+    }>().not.toExtend<Parameters<typeof factory>[0]>();
     assert.equal(matcher("a"), 1);
     assert.equal(matcher("b"), "two");
 });
 
 test("getPrimitiveUnionMatcherW dispatches on numeric literal keys", () => {
-    const matcher = getPrimitiveUnionMatcherW<1 | 2>()({
+    // Arrange
+    const factory = getPrimitiveUnionMatcherW<1 | 2>();
+
+    // Act
+    const matcher = factory({
         1: (n) => n + 1,
         2: (n) => n * 10,
     });
+
+    // Assert
     expectTypeOf(matcher).toEqualTypeOf<(shape: 1 | 2) => number>();
     assert.equal(matcher(1), 2);
     assert.equal(matcher(2), 20);
@@ -46,10 +57,16 @@ test("getPrimitiveUnionMatcherW dispatches on numeric literal keys", () => {
 // ============================================================================
 
 test("getPrimitiveUnionMatcher infers a single return type shared by all handlers", () => {
-    const matcher = getPrimitiveUnionMatcher<"a" | "b">()({
+    // Arrange
+    const factory = getPrimitiveUnionMatcher<"a" | "b">();
+
+    // Act
+    const matcher = factory({
         a: (): number => 1,
         b: (): 1 | 2 => 2,
     });
+
+    // Assert
     // ✔️ ReturnsStrict: R is the best common return type, not a widening union.
     expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b") => number>();
     assert.equal(matcher("a"), 1);
@@ -57,7 +74,11 @@ test("getPrimitiveUnionMatcher infers a single return type shared by all handler
 });
 
 test("getPrimitiveUnionMatcher handlers receive the matched literal", () => {
-    const matcher = getPrimitiveUnionMatcher<"on" | "off">()({
+    // Arrange
+    const factory = getPrimitiveUnionMatcher<"on" | "off">();
+
+    // Act
+    const matcher = factory({
         on: (s) => {
             expectTypeOf(s).toEqualTypeOf<"on">();
             return `handler ${s}`;
@@ -67,6 +88,8 @@ test("getPrimitiveUnionMatcher handlers receive the matched literal", () => {
             return `handler ${s}`;
         },
     });
+
+    // Assert
     expectTypeOf(matcher).toEqualTypeOf<(shape: "on" | "off") => string>();
     assert.equal(matcher("on"), "handler on");
     assert.equal(matcher("off"), "handler off");
@@ -77,7 +100,13 @@ test("getPrimitiveUnionMatcher handlers receive the matched literal", () => {
 // ============================================================================
 
 test("getPrimitiveUnionMatcherPartial routes shapes without a handler to _", () => {
-    const matcher = getPrimitiveUnionMatcherPartial<"a" | "b" | "c">()({
+    // Arrange
+    const factory = getPrimitiveUnionMatcherPartial<"a" | "b" | "c">();
+    // Two keys, so `{ a }` lacks only the `_` fallback, nothing else.
+    const sparseFactory = getPrimitiveUnionMatcherPartial<"a" | "b">();
+
+    // Act
+    const matcher = factory({
         a: (): 1 | 2 => 1,
         _: (s): 1 | 2 => {
             // The fallback sees the whole union, not a single literal.
@@ -85,22 +114,29 @@ test("getPrimitiveUnionMatcherPartial routes shapes without a handler to _", ()
             return 2;
         },
     });
+
+    // Assert
     expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b" | "c") => 1 | 2>();
     // ❌ Exhaustive: gaps are allowed, but only with a `_` fallback.
-    const factory = getPrimitiveUnionMatcherPartial<"a" | "b">();
     expectTypeOf<{
         a: () => number;
-    }>().not.toMatchTypeOf<Parameters<typeof factory>[0]>();
+    }>().not.toExtend<Parameters<typeof sparseFactory>[0]>();
     assert.equal(matcher("a"), 1);
     assert.equal(matcher("b"), 2);
     assert.equal(matcher("c"), 2);
 });
 
 test("getPrimitiveUnionMatcherPartial also accepts an exhaustive pattern", () => {
-    const matcher = getPrimitiveUnionMatcherPartial<"a" | "b">()({
+    // Arrange
+    const factory = getPrimitiveUnionMatcherPartial<"a" | "b">();
+
+    // Act
+    const matcher = factory({
         a: () => "A",
         b: () => "B",
     });
+
+    // Assert
     expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b") => string>();
     assert.equal(matcher("a"), "A");
     assert.equal(matcher("b"), "B");
@@ -111,17 +147,25 @@ test("getPrimitiveUnionMatcherPartial also accepts an exhaustive pattern", () =>
 // ============================================================================
 
 test("getPrimitiveUnionMatcherPartialW allows gaps and widens to the union of handler returns", () => {
-    const matcher = getPrimitiveUnionMatcherPartialW<"x" | "y" | "z">()({
+    // Arrange
+    const factory = getPrimitiveUnionMatcherPartialW<"x" | "y" | "z">();
+    // Two keys, so `{ x }` lacks only the `_` fallback, nothing else.
+    const sparseFactory = getPrimitiveUnionMatcherPartialW<"x" | "y">();
+
+    // Act
+    const matcher = factory({
         x: () => 1 as const,
         _: () => "fallback" as const,
     });
+
+    // Assert
     expectTypeOf(matcher).toEqualTypeOf<
         (shape: "x" | "y" | "z") => 1 | "fallback"
     >();
-    const factory = getPrimitiveUnionMatcherPartialW<"x" | "y">();
+    // ❌ Exhaustive: gaps are allowed, but only with a `_` fallback.
     expectTypeOf<{
         x: () => number;
-    }>().not.toMatchTypeOf<Parameters<typeof factory>[0]>();
+    }>().not.toExtend<Parameters<typeof sparseFactory>[0]>();
     assert.equal(matcher("x"), 1);
     assert.equal(matcher("y"), "fallback");
     assert.equal(matcher("z"), "fallback");