@shapecraft/core 1.0.0

package/src/shape/shape.test.ts

@@ -0,0 +1,792 @@
+import { describe, expect } from "vitest";
+import { NumberTag } from "./tags";
+import { annotate, shapes } from "./shape";
+
+function expectToBe<Input, Value extends Input>(
+  input: Input,
+  value: Value,
+): asserts input is Value {
+  return expect(input).toBe(value);
+}
+
+describe("shapes.auto", (it) => {
+  it("returns the correct shape for numbers", () => {
+    const samples: Array<{ value: number; tag: NumberTag }> = [
+      { value: 0, tag: "uint8" },
+      { value: 0.5, tag: "float32" },
+      { value: -0.5, tag: "float32" },
+      { value: 0xffffffff, tag: "uint32" },
+      { value: -0xffffffff, tag: "int64" },
+      { value: 0xfffffffff, tag: "uint64" },
+      { value: -0xfffffffff, tag: "int64" },
+    ];
+
+    samples.forEach((sample) => {
+      const shape = shapes.auto(sample.value);
+      expectToBe(shape.type, "number");
+      expectToBe(shape.tag, sample.tag);
+    });
+  });
+
+  it("returns nil for null input", () => {
+    const shape = shapes.auto(null);
+    expectToBe(shape.type, "nil");
+  });
+
+  it("returns undefined-shape for undefined input", () => {
+    const shape = shapes.auto(undefined);
+    expectToBe(shape.type, "undefined");
+  });
+
+  it("returns string shape for string input", () => {
+    const shape = shapes.auto("hello");
+    expectToBe(shape.type, "string");
+  });
+
+  it("returns boolean shape for boolean input", () => {
+    const shape = shapes.auto(true);
+    expectToBe(shape.type, "boolean");
+  });
+
+  it("returns date shape for Date input", () => {
+    const shape = shapes.auto(new Date());
+    expectToBe(shape.type, "date");
+  });
+
+  it("returns binary shape for Uint8Array input", () => {
+    const shape = shapes.auto(new Uint8Array([1, 2, 3]));
+    expectToBe(shape.type, "binary");
+  });
+
+  it("returns unknown shape for unsupported input (e.g. functions)", () => {
+    const shape = shapes.auto(() => {});
+    expectToBe(shape.type, "unknown");
+  });
+
+  it("returns an array of inferred numeric tag for homogenous number arrays", () => {
+    const shape = shapes.auto([1, 2, 3]);
+    expectToBe(shape.type, "array");
+    if (shape.input.type !== "number") {
+      throw new Error("expected array item to be a number shape");
+    }
+    expectToBe(shape.input.tag, "uint8");
+  });
+
+  it("widens the numeric tag across a homogenous number array", () => {
+    const shape = shapes.auto([1, 0xffff, 0.5]);
+    expectToBe(shape.type, "array");
+    if (shape.input.type !== "number") {
+      throw new Error("expected array item to be a number shape");
+    }
+    expectToBe(shape.input.tag, "float64");
+  });
+
+  it("infers item shape from a single-element array", () => {
+    const shape = shapes.auto(["only"]);
+    expectToBe(shape.type, "array");
+    expectToBe(shape.input.type, "string");
+  });
+
+  it("returns array<union> for heterogeneous arrays with multiple elements", () => {
+    const shape = shapes.auto(["a", 1]);
+    expectToBe(shape.type, "array");
+    expectToBe(shape.input.type, "union");
+  });
+
+  it("returns a mapping shape for plain objects", () => {
+    const shape = shapes.auto({ a: 1, b: "two", c: true });
+    expectToBe(shape.type, "mapping");
+    expect(Object.keys(shape.input).sort()).toEqual(["a", "b", "c"]);
+    expectToBe(shape.input.a!.type, "number");
+    expectToBe(shape.input.b!.type, "string");
+    expectToBe(shape.input.c!.type, "boolean");
+  });
+
+  it("recurses into nested objects and arrays", () => {
+    const shape = shapes.auto({ nested: { count: 5 }, tags: ["x"] });
+    expectToBe(shape.type, "mapping");
+    const nested = shape.input.nested!;
+    expectToBe(nested.type, "mapping");
+    if (nested.type !== "mapping") return;
+    expectToBe(nested.input.count!.type, "number");
+    const tags = shape.input.tags!;
+    expectToBe(tags.type, "array");
+    if (tags.type !== "array") return;
+    expectToBe(tags.input.type, "string");
+  });
+
+  it("produces literal number shapes when literalNumbers is true", () => {
+    const shape = shapes.auto(42, { literalNumbers: true });
+    expectToBe(shape.type, "number");
+    if (shape.type !== "number") return;
+    expect((shape as any).literal).toBe(true);
+    expect(shape.input).toBe(42);
+  });
+
+  it("produces literal string shapes when literalStrings is true", () => {
+    const shape = shapes.auto("hi", { literalStrings: true });
+    expectToBe(shape.type, "string");
+    if (shape.type !== "string") return;
+    expect((shape as any).literal).toBe(true);
+    expect(shape.input).toBe("hi");
+  });
+
+  it("produces literal boolean shapes when literalBooleans is true", () => {
+    const shape = shapes.auto(false, { literalBooleans: true });
+    expectToBe(shape.type, "boolean");
+    if (shape.type !== "boolean") return;
+    expect((shape as any).literal).toBe(true);
+    expect(shape.input).toBe(false);
+  });
+
+  it("does not produce literals by default", () => {
+    const shape = shapes.auto(7);
+    expect((shape as any).literal).toBeUndefined();
+  });
+});
+
+describe("scalar shape constructors", (it) => {
+  it("builds primitive shapes with the correct type tag", () => {
+    expectToBe(shapes.string().type, "string");
+    expectToBe(shapes.boolean().type, "boolean");
+    expectToBe(shapes.notDefined().type, "undefined");
+    expectToBe(shapes.date().type, "date");
+    expectToBe(shapes.nil().type, "nil");
+    expectToBe(shapes.unknown().type, "unknown");
+    expectToBe(shapes.binary().type, "binary");
+  });
+
+  it("marks shapes as shape values with empty default annotations", () => {
+    const s = shapes.string();
+    expect(s._shape).toBe(true);
+    expect(s.anno).toEqual({});
+  });
+
+  it("attaches the matching number tag for each numeric constructor", () => {
+    expectToBe(shapes.number().tag, "number");
+    expectToBe(shapes.int().tag, "int");
+    expectToBe(shapes.int8().tag, "int8");
+    expectToBe(shapes.uint8().tag, "uint8");
+    expectToBe(shapes.int16().tag, "int16");
+    expectToBe(shapes.uint16().tag, "uint16");
+    expectToBe(shapes.int32().tag, "int32");
+    expectToBe(shapes.uint32().tag, "uint32");
+    expectToBe(shapes.int64().tag, "int64");
+    expectToBe(shapes.uint64().tag, "uint64");
+    expectToBe(shapes.float().tag, "float");
+    expectToBe(shapes.float32().tag, "float32");
+    expectToBe(shapes.float64().tag, "float64");
+  });
+});
+
+describe("shapes.literal", (it) => {
+  it("creates a literal string shape carrying its input value", () => {
+    const s = shapes.literal("foo");
+    expectToBe(s.type, "string");
+    if (s.type !== "string") return;
+    expect(s.literal).toBe(true);
+    expect(s.input).toBe("foo");
+  });
+
+  it("creates a literal number shape carrying its input value", () => {
+    const s = shapes.literal(123);
+    expectToBe(s.type, "number");
+    if (s.type !== "number") return;
+    expect(s.literal).toBe(true);
+    expect(s.input).toBe(123);
+  });
+
+  it("creates a literal boolean shape carrying its input value", () => {
+    const s = shapes.literal(true);
+    expectToBe(s.type, "boolean");
+    if (s.type !== "boolean") return;
+    expect(s.literal).toBe(true);
+    expect(s.input).toBe(true);
+  });
+
+  it("throws when given a non-literal-eligible value", () => {
+    expect(() => shapes.literal(null as any)).toThrow();
+  });
+});
+
+describe("container shape constructors", (it) => {
+  it("array stores the item shape on input", () => {
+    const item = shapes.string();
+    const s = shapes.array(item);
+    expectToBe(s.type, "array");
+    expect(s.input).toBe(item);
+  });
+
+  it("mapping stores the record of shapes on input", () => {
+    const rec = { a: shapes.number(), b: shapes.string() };
+    const s = shapes.mapping(rec);
+    expectToBe(s.type, "mapping");
+    expect(s.input).toBe(rec);
+  });
+
+  it("record stores its key/value shapes as a tuple on input", () => {
+    const k = shapes.string();
+    const v = shapes.number();
+    const s = shapes.record(k, v);
+    expectToBe(s.type, "record");
+    expect(s.input[0]).toBe(k);
+    expect(s.input[1]).toBe(v);
+  });
+
+  it("vector defaults its format to a generic number shape", () => {
+    const s = shapes.vector(3);
+    expectToBe(s.type, "vector");
+    expect(s.input.dims).toBe(3);
+    expectToBe(s.input.format.type, "number");
+    expectToBe(s.input.format.tag, "number");
+  });
+
+  it("vector accepts an explicit numeric format", () => {
+    const s = shapes.vector(4, shapes.float32());
+    expect(s.input.dims).toBe(4);
+    expectToBe(s.input.format.tag, "float32");
+  });
+});
+
+describe("shapes.union", (it) => {
+  it("accepts variadic arguments", () => {
+    const a = shapes.string();
+    const b = shapes.number();
+    const s = shapes.union(a, b);
+    expectToBe(s.type, "union");
+    expect(s.input).toEqual([a, b]);
+  });
+
+  it("accepts a single array of shapes", () => {
+    const a = shapes.string();
+    const b = shapes.number();
+    const s = shapes.union([a, b]);
+    expectToBe(s.type, "union");
+    expect(s.input).toEqual([a, b]);
+  });
+});
+
+describe("annotate", (it) => {
+  it("annotate.as merges annotations without mutating the source", () => {
+    const original = shapes.number();
+    const annotated = annotate.as(original, { min: 0, max: 10 });
+    expect(annotated.anno).toEqual({ min: 0, max: 10 });
+    expect(original.anno).toEqual({});
+    expect(annotated).not.toBe(original);
+  });
+
+  it("annotate.as preserves prior annotations when merging", () => {
+    const base = annotate.as(shapes.number(), { min: 0 });
+    const merged = annotate.as(base, { max: 5 });
+    expect(merged.anno).toEqual({ min: 0, max: 5 });
+  });
+
+  it("annotate.as overrides overlapping annotation fields", () => {
+    const base = annotate.as(shapes.number(), { min: 0 });
+    const merged = annotate.as(base, { min: 10 });
+    expectToBe(merged.anno.min, 10);
+  });
+
+  it("annotate.optional sets optional=true", () => {
+    const s = annotate.optional(shapes.string());
+    expect(s.anno.optional).toBe(true);
+  });
+
+  it("annotate preserves the underlying shape type and input", () => {
+    const inner = shapes.string();
+    const arr = shapes.array(inner);
+    const annotated = annotate.optional(arr);
+    expectToBe(annotated.type, "array");
+    expect(annotated.input).toBe(inner);
+  });
+});
+
+describe("shapes.validate — scalars", (it) => {
+  it("returns no errors when a string matches a string shape", () => {
+    expect(shapes.validate(shapes.string(), "hello")).toEqual([]);
+  });
+
+  it("flags a non-string against a string shape", () => {
+    const errors = shapes.validate(shapes.string(), 42);
+    expect(errors).toHaveLength(1);
+    expect(errors[0]!.path).toEqual([]);
+    expect(errors[0]!.message).toMatch(/string/);
+  });
+
+  it("returns no errors when a boolean matches a boolean shape", () => {
+    expect(shapes.validate(shapes.boolean(), true)).toEqual([]);
+    expect(shapes.validate(shapes.boolean(), false)).toEqual([]);
+  });
+
+  it("flags a non-boolean against a boolean shape", () => {
+    const errors = shapes.validate(shapes.boolean(), "true");
+    expect(errors).toHaveLength(1);
+    expect(errors[0]!.message).toMatch(/boolean/);
+  });
+
+  it("returns no errors when null matches a nil shape", () => {
+    expect(shapes.validate(shapes.nil(), null)).toEqual([]);
+  });
+
+  it("flags a non-null value against a nil shape", () => {
+    const errors = shapes.validate(shapes.nil(), 0);
+    expect(errors).toHaveLength(1);
+    expect(errors[0]!.message).toMatch(/nil/);
+  });
+
+  it("returns no errors when undefined matches an undefined shape", () => {
+    expect(shapes.validate(shapes.notDefined(), undefined)).toEqual([]);
+  });
+
+  it("flags a defined value against an undefined shape", () => {
+    const errors = shapes.validate(shapes.notDefined(), null);
+    expect(errors).toHaveLength(1);
+  });
+
+  it("returns no errors when a Date matches a date shape", () => {
+    expect(shapes.validate(shapes.date(), new Date())).toEqual([]);
+  });
+
+  it("flags a non-Date against a date shape", () => {
+    const errors = shapes.validate(shapes.date(), "2026-01-01");
+    expect(errors).toHaveLength(1);
+    expect(errors[0]!.message).toMatch(/date/);
+  });
+
+  it("accepts any value against an unknown shape", () => {
+    expect(shapes.validate(shapes.unknown(), 1)).toEqual([]);
+    expect(shapes.validate(shapes.unknown(), "x")).toEqual([]);
+    expect(shapes.validate(shapes.unknown(), null)).toEqual([]);
+    expect(shapes.validate(shapes.unknown(), { a: 1 })).toEqual([]);
+  });
+});
+
+describe("shapes.validate — numbers", (it) => {
+  it("returns no errors when a number matches a generic number shape", () => {
+    expect(shapes.validate(shapes.number(), 42)).toEqual([]);
+    expect(shapes.validate(shapes.number(), -1.5)).toEqual([]);
+  });
+
+  it("flags a non-number against a number shape", () => {
+    const errors = shapes.validate(shapes.number(), "42");
+    expect(errors).toHaveLength(1);
+    expect(errors[0]!.message).toMatch(/number/);
+  });
+
+  it("accepts a value that fits the requested integer tag", () => {
+    expect(shapes.validate(shapes.uint8(), 200)).toEqual([]);
+    expect(shapes.validate(shapes.int16(), -1000)).toEqual([]);
+  });
+
+  it("rejects a value that exceeds the requested integer tag's range", () => {
+    const errors = shapes.validate(shapes.uint8(), 0xffff);
+    expect(errors).toHaveLength(1);
+    expect(errors[0]!.message).toMatch(/format/);
+  });
+
+  it("rejects a float when an integer tag is required", () => {
+    const errors = shapes.validate(shapes.uint8(), 0.5);
+    expect(errors).toHaveLength(1);
+    expect(errors[0]!.message).toMatch(/format/);
+  });
+
+  it("accepts an int that fits inside a float32 tag", () => {
+    // int tags cannot be cast to float tags directly per numberTagCanBeCastedTo,
+    // so a uint8 input should fail against float32.
+    const errors = shapes.validate(shapes.float32(), 1);
+    expect(errors).toHaveLength(1);
+  });
+
+  it("accepts a float that fits inside float32", () => {
+    expect(shapes.validate(shapes.float32(), 0.5)).toEqual([]);
+  });
+});
+
+describe("shapes.validate — literals", (it) => {
+  it("accepts the matching literal string", () => {
+    expect(shapes.validate(shapes.literal("foo"), "foo")).toEqual([]);
+  });
+
+  it("rejects a non-matching literal string", () => {
+    const errors = shapes.validate(shapes.literal("foo"), "bar");
+    expect(errors).toHaveLength(1);
+    expect(errors[0]!.message).toMatch(/literal/);
+  });
+
+  it("accepts the matching literal number", () => {
+    expect(shapes.validate(shapes.literal(7), 7)).toEqual([]);
+  });
+
+  it("rejects a non-matching literal number", () => {
+    const errors = shapes.validate(shapes.literal(7), 8);
+    expect(errors).toHaveLength(1);
+    expect(errors[0]!.message).toMatch(/literal/);
+  });
+
+  it("accepts the matching literal boolean", () => {
+    expect(shapes.validate(shapes.literal(true), true)).toEqual([]);
+  });
+
+  it("rejects a non-matching literal boolean", () => {
+    const errors = shapes.validate(shapes.literal(true), false);
+    expect(errors).toHaveLength(1);
+    expect(errors[0]!.message).toMatch(/literal/);
+  });
+});
+
+describe("shapes.validate — binary", (it) => {
+  it("accepts a Uint8Array against a binary shape", () => {
+    expect(shapes.validate(shapes.binary(), new Uint8Array([1, 2, 3]))).toEqual(
+      [],
+    );
+  });
+
+  it("accepts an array of uint8-fitting numbers against a binary shape", () => {
+    expect(shapes.validate(shapes.binary(), [0, 127, 255])).toEqual([]);
+  });
+
+  it("rejects an array containing a non-uint8 value against a binary shape", () => {
+    const errors = shapes.validate(shapes.binary(), [0, 256]);
+    expect(errors.length).toBeGreaterThan(0);
+    expect(errors[0]!.path).toEqual([1]);
+  });
+
+  it("rejects a non-array, non-Uint8Array against a binary shape", () => {
+    const errors = shapes.validate(shapes.binary(), "not binary");
+    expect(errors).toHaveLength(1);
+    expect(errors[0]!.message).toMatch(/binary/);
+  });
+});
+
+describe("shapes.validate — array", (it) => {
+  it("accepts an array whose items all match the item shape", () => {
+    expect(shapes.validate(shapes.array(shapes.string()), ["a", "b"])).toEqual(
+      [],
+    );
+  });
+
+  it("accepts an empty array regardless of item shape", () => {
+    expect(shapes.validate(shapes.array(shapes.string()), [])).toEqual([]);
+  });
+
+  it("rejects a non-array input", () => {
+    const errors = shapes.validate(shapes.array(shapes.string()), "abc");
+    expect(errors).toHaveLength(1);
+    expect(errors[0]!.message).toMatch(/array/);
+  });
+
+  it("reports the index of an invalid item in the path", () => {
+    const errors = shapes.validate(shapes.array(shapes.string()), [
+      "a",
+      1,
+      "c",
+    ]);
+    expect(errors.length).toBeGreaterThan(0);
+    expect(errors[0]!.path).toEqual([1]);
+  });
+});
+
+describe("shapes.validate — vector", (it) => {
+  it("accepts an array whose length matches dims and items fit the format", () => {
+    expect(
+      shapes.validate(shapes.vector(3, shapes.uint8()), [1, 2, 3]),
+    ).toEqual([]);
+  });
+
+  it("rejects a non-array input", () => {
+    const errors = shapes.validate(shapes.vector(3), "nope");
+    expect(errors).toHaveLength(1);
+    expect(errors[0]!.message).toMatch(/vector/);
+  });
+
+  it("rejects a length mismatch", () => {
+    const errors = shapes.validate(shapes.vector(3), [1, 2]);
+    expect(errors).toHaveLength(1);
+    expect(errors[0]!.message).toMatch(/dimensions/);
+  });
+
+  it("reports the index of a format-mismatched item", () => {
+    const errors = shapes.validate(
+      shapes.vector(3, shapes.uint8()),
+      [1, 999, 3],
+    );
+    expect(errors.length).toBeGreaterThan(0);
+    expect(errors[0]!.path).toEqual([1]);
+  });
+});
+
+describe("shapes.validate — mapping", (it) => {
+  it("accepts an object where every required key validates", () => {
+    const shape = shapes.mapping({
+      a: shapes.string(),
+      b: shapes.number(),
+    });
+    expect(shapes.validate(shape, { a: "x", b: 1 })).toEqual([]);
+  });
+
+  it("rejects a non-object input", () => {
+    const shape = shapes.mapping({ a: shapes.string() });
+    const errors = shapes.validate(shape, "not an object");
+    expect(errors).toHaveLength(1);
+    expect(errors[0]!.message).toMatch(/mapping/);
+  });
+
+  it("rejects null against a mapping shape", () => {
+    const shape = shapes.mapping({ a: shapes.string() });
+    const errors = shapes.validate(shape, null);
+    expect(errors).toHaveLength(1);
+    expect(errors[0]!.message).toMatch(/mapping/);
+  });
+
+  it("reports a missing required key with the key in the path", () => {
+    const shape = shapes.mapping({
+      a: shapes.string(),
+      b: shapes.number(),
+    });
+    const errors = shapes.validate(shape, { a: "x" });
+    expect(errors).toHaveLength(1);
+    expect(errors[0]!.path).toEqual(["b"]);
+    expect(errors[0]!.message).toMatch(/Missing required key/);
+  });
+
+  it("allows a missing optional key", () => {
+    const shape = shapes.mapping({
+      a: shapes.string(),
+      b: annotate.optional(shapes.number()),
+    });
+    expect(shapes.validate(shape, { a: "x" })).toEqual([]);
+  });
+
+  it("reports value-shape errors with the key in the path", () => {
+    const shape = shapes.mapping({
+      a: shapes.string(),
+      b: shapes.number(),
+    });
+    const errors = shapes.validate(shape, { a: "x", b: "not a number" });
+    expect(errors).toHaveLength(1);
+    expect(errors[0]!.path).toEqual(["b"]);
+  });
+
+  it("walks the path into nested mappings", () => {
+    const shape = shapes.mapping({
+      outer: shapes.mapping({
+        inner: shapes.number(),
+      }) as unknown as shapes.Shape,
+    });
+    const errors = shapes.validate(shape, { outer: { inner: "oops" } });
+    expect(errors).toHaveLength(1);
+    expect(errors[0]!.path).toEqual(["outer", "inner"]);
+  });
+});
+
+describe("shapes.validate — record", (it) => {
+  it("accepts an object whose keys and values all validate", () => {
+    const shape = shapes.record(shapes.string(), shapes.number());
+    expect(shapes.validate(shape, { a: 1, b: 2 })).toEqual([]);
+  });
+
+  it("rejects a non-object input", () => {
+    const shape = shapes.record(shapes.string(), shapes.number());
+    const errors = shapes.validate(shape, 1);
+    expect(errors).toHaveLength(1);
+    expect(errors[0]!.message).toMatch(/record/);
+  });
+
+  it("rejects null against a record shape", () => {
+    const shape = shapes.record(shapes.string(), shapes.number());
+    const errors = shapes.validate(shape, null);
+    expect(errors).toHaveLength(1);
+  });
+
+  it("reports a value-shape error with the key in the path", () => {
+    const shape = shapes.record(shapes.string(), shapes.number());
+    const errors = shapes.validate(shape, { a: 1, b: "no" });
+    expect(errors.length).toBeGreaterThan(0);
+    expect(errors[0]!.path).toEqual(["b"]);
+  });
+
+  it("accepts an empty object", () => {
+    const shape = shapes.record(shapes.string(), shapes.number());
+    expect(shapes.validate(shape, {})).toEqual([]);
+  });
+});
+
+describe("shapes.validate — union", (it) => {
+  it("accepts a value matching any variant", () => {
+    const shape = shapes.union(shapes.string(), shapes.number());
+    expect(shapes.validate(shape, "hi")).toEqual([]);
+    expect(shapes.validate(shape, 1)).toEqual([]);
+  });
+
+  it("rejects a value matching no variant and collects errors from each", () => {
+    const shape = shapes.union(shapes.string(), shapes.number());
+    const errors = shapes.validate(shape, true);
+    expect(errors.length).toBeGreaterThanOrEqual(2);
+  });
+});
+
+describe("shapes.validate — min/max", (it) => {
+  it("accepts a number within [min, max]", () => {
+    const shape = annotate.as(shapes.number(), { min: 0, max: 10 });
+    expect(shapes.validate(shape, 0)).toEqual([]);
+    expect(shapes.validate(shape, 5)).toEqual([]);
+    expect(shapes.validate(shape, 10)).toEqual([]);
+  });
+
+  it("rejects a number below min", () => {
+    const shape = annotate.as(shapes.number(), { min: 0 });
+    const errors = shapes.validate(shape, -1);
+    expect(errors).toHaveLength(1);
+    expect(errors[0]!.message).toMatch(/>= 0/);
+  });
+
+  it("rejects a number above max", () => {
+    const shape = annotate.as(shapes.number(), { max: 10 });
+    const errors = shapes.validate(shape, 11);
+    expect(errors).toHaveLength(1);
+    expect(errors[0]!.message).toMatch(/<= 10/);
+  });
+
+  it("checks the number format before applying bounds", () => {
+    // "foo" fails the type check first; bounds should not run on a non-number
+    const shape = annotate.as(shapes.number(), { min: 0, max: 10 });
+    const errors = shapes.validate(shape, "foo");
+    expect(errors).toHaveLength(1);
+    expect(errors[0]!.message).toMatch(/number/);
+  });
+
+  it("accepts a string whose length is within [min, max]", () => {
+    const shape = annotate.as(shapes.string(), { min: 2, max: 4 });
+    expect(shapes.validate(shape, "ab")).toEqual([]);
+    expect(shapes.validate(shape, "abc")).toEqual([]);
+    expect(shapes.validate(shape, "abcd")).toEqual([]);
+  });
+
+  it("rejects a string shorter than min", () => {
+    const shape = annotate.as(shapes.string(), { min: 2 });
+    const errors = shapes.validate(shape, "a");
+    expect(errors).toHaveLength(1);
+    expect(errors[0]!.message).toMatch(/string length/);
+    expect(errors[0]!.message).toMatch(/>= 2/);
+  });
+
+  it("rejects a string longer than max", () => {
+    const shape = annotate.as(shapes.string(), { max: 3 });
+    const errors = shapes.validate(shape, "abcd");
+    expect(errors).toHaveLength(1);
+    expect(errors[0]!.message).toMatch(/string length/);
+    expect(errors[0]!.message).toMatch(/<= 3/);
+  });
+
+  it("accepts an array whose length is within [min, max]", () => {
+    const shape = annotate.as(shapes.array(shapes.number()), {
+      min: 1,
+      max: 3,
+    });
+    expect(shapes.validate(shape, [1])).toEqual([]);
+    expect(shapes.validate(shape, [1, 2])).toEqual([]);
+    expect(shapes.validate(shape, [1, 2, 3])).toEqual([]);
+  });
+
+  it("rejects an array shorter than min", () => {
+    const shape = annotate.as(shapes.array(shapes.number()), { min: 2 });
+    const errors = shapes.validate(shape, [1]);
+    expect(errors).toHaveLength(1);
+    expect(errors[0]!.message).toMatch(/array length/);
+    expect(errors[0]!.message).toMatch(/>= 2/);
+  });
+
+  it("rejects an array longer than max", () => {
+    const shape = annotate.as(shapes.array(shapes.number()), { max: 2 });
+    const errors = shapes.validate(shape, [1, 2, 3]);
+    expect(errors).toHaveLength(1);
+    expect(errors[0]!.message).toMatch(/array length/);
+    expect(errors[0]!.message).toMatch(/<= 2/);
+  });
+
+  it("reports bounds errors at the shape's path inside a nested mapping", () => {
+    const shape = shapes.mapping({
+      name: annotate.as(shapes.string(), { min: 3 }),
+    });
+    const errors = shapes.validate(shape, { name: "no" });
+    expect(errors).toHaveLength(1);
+    expect(errors[0]!.path).toEqual(["name"]);
+  });
+
+  it("ignores min/max on shapes where they don't apply (e.g. boolean)", () => {
+    const shape = annotate.as(shapes.boolean(), { min: 100, max: 200 });
+    expect(shapes.validate(shape, true)).toEqual([]);
+  });
+});
+
+describe("shapes.validate — pattern", (it) => {
+  it("accepts a string matching a RegExp pattern", () => {
+    const shape = annotate.pattern(shapes.string(), /^[a-z]+$/);
+    expect(shapes.validate(shape, "abc")).toEqual([]);
+  });
+
+  it("rejects a string not matching a RegExp pattern", () => {
+    const shape = annotate.pattern(shapes.string(), /^[a-z]+$/);
+    const errors = shapes.validate(shape, "abc123");
+    expect(errors).toHaveLength(1);
+    expect(errors[0]!.message).toMatch(/pattern/);
+  });
+
+  it("accepts a string matching a string-source pattern", () => {
+    const shape = annotate.pattern(shapes.string(), "^[A-Z]{3}$");
+    expect(shapes.validate(shape, "USD")).toEqual([]);
+  });
+
+  it("rejects a string not matching a string-source pattern", () => {
+    const shape = annotate.pattern(shapes.string(), "^[A-Z]{3}$");
+    const errors = shapes.validate(shape, "usd");
+    expect(errors).toHaveLength(1);
+    expect(errors[0]!.message).toMatch(/pattern/);
+  });
+
+  it("checks type before pattern", () => {
+    const shape = annotate.pattern(shapes.string(), /^[a-z]+$/);
+    const errors = shapes.validate(shape, 5);
+    expect(errors).toHaveLength(1);
+    expect(errors[0]!.message).toMatch(/string/);
+  });
+
+  it("reports pattern errors at the shape's path inside a nested mapping", () => {
+    const shape = shapes.mapping({
+      slug: annotate.pattern(shapes.string(), /^[a-z-]+$/),
+    });
+    const errors = shapes.validate(shape, { slug: "Bad Slug" });
+    expect(errors).toHaveLength(1);
+    expect(errors[0]!.path).toEqual(["slug"]);
+  });
+
+  it("composes with min/max — bounds error takes precedence", () => {
+    const shape = annotate.as(shapes.string(), {
+      min: 3,
+      pattern: /^[a-z]+$/,
+    });
+    const errors = shapes.validate(shape, "a");
+    expect(errors).toHaveLength(1);
+    expect(errors[0]!.message).toMatch(/string length/);
+  });
+});
+
+describe("shapes.validate — paths", (it) => {
+  it("uses [] as the path for a top-level scalar mismatch", () => {
+    const errors = shapes.validate(shapes.string(), 1);
+    expect(errors[0]!.path).toEqual([]);
+  });
+
+  it("threads indices and keys through nested arrays and mappings", () => {
+    const shape = shapes.mapping({
+      items: shapes.array(
+        shapes.mapping({ name: shapes.string() }) as unknown as shapes.Shape,
+      ),
+    });
+    const errors = shapes.validate(shape, {
+      items: [{ name: "ok" }, { name: 5 }],
+    });
+    expect(errors).toHaveLength(1);
+    expect(errors[0]!.path).toEqual(["items", 1, "name"]);
+  });
+});