shapecraft 1.0.0

package/packages/core/src/shape/builder.test.ts

@@ -0,0 +1,728 @@
+import { describe, expect } from "vitest";
+import { R } from "../common";
+import { B } from "./builder";
+import { ValidationError } from "./error";
+
+function expectToBe<Input, Value extends Input>(
+  input: Input,
+  value: Value,
+): asserts input is Value {
+  return expect(input).toBe(value);
+}
+
+function expectOk<T>(
+  res: R.Result<T, ValidationError[]>,
+): asserts res is R.ResultOk<T> {
+  if (!res.ok) {
+    throw new Error(`expected ok, got err: ${JSON.stringify(res.error)}`);
+  }
+}
+
+function expectErr<T>(
+  res: R.Result<T, ValidationError[]>,
+): asserts res is R.ResultErr<ValidationError[]> {
+  if (res.ok) {
+    throw new Error(
+      `expected err, got ok with value: ${JSON.stringify(res.value)}`,
+    );
+  }
+}
+
+describe("B scalar constructors", (it) => {
+  it("builds primitive shapes with the correct type tag", () => {
+    expectToBe(B.string().shape.type, "string");
+    expectToBe(B.boolean().shape.type, "boolean");
+    expectToBe(B.notDefined().shape.type, "undefined");
+    expectToBe(B.date().shape.type, "date");
+    expectToBe(B.nil().shape.type, "nil");
+    expectToBe(B.unknown().shape.type, "unknown");
+    expectToBe(B.binary().shape.type, "binary");
+  });
+
+  it("exposes the shape type via the builder's `type` field", () => {
+    expectToBe(B.string().type, "string");
+    expectToBe(B.boolean().type, "boolean");
+    expectToBe(B.binary().type, "binary");
+  });
+
+  it("marks shapes as shape values with empty default annotations", () => {
+    const b = B.string();
+    expect(b.shape._shape).toBe(true);
+    expect(b.shape.anno).toEqual({});
+  });
+
+  it("attaches the matching number tag for each numeric builder", () => {
+    expectToBe(B.number().shape.tag, "number");
+    expectToBe(B.int().shape.tag, "int");
+    expectToBe(B.int8().shape.tag, "int8");
+    expectToBe(B.uint8().shape.tag, "uint8");
+    expectToBe(B.int16().shape.tag, "int16");
+    expectToBe(B.uint16().shape.tag, "uint16");
+    expectToBe(B.int32().shape.tag, "int32");
+    expectToBe(B.uint32().shape.tag, "uint32");
+    expectToBe(B.int64().shape.tag, "int64");
+    expectToBe(B.uint64().shape.tag, "uint64");
+    expectToBe(B.float().shape.tag, "float");
+    expectToBe(B.float32().shape.tag, "float32");
+    expectToBe(B.float64().shape.tag, "float64");
+  });
+});
+
+describe("B.literal", (it) => {
+  it("creates a literal string shape carrying its input value", () => {
+    const s = B.literal("foo").shape;
+    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 = B.literal(123).shape;
+    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 = B.literal(true).shape;
+    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(() => B.literal(null as any)).toThrow();
+  });
+});
+
+describe("B container constructors", (it) => {
+  it("array stores the item shape on input", () => {
+    const item = B.string();
+    const s = B.array(item).shape;
+    expectToBe(s.type, "array");
+    expect(s.input).toBe(item.shape);
+  });
+
+  it("mapping stores the record of shapes on input", () => {
+    const a = B.number();
+    const b = B.string();
+    const s = B.mapping({ a, b }).shape;
+    expectToBe(s.type, "mapping");
+    expect(Object.keys(s.input).sort()).toEqual(["a", "b"]);
+    expect(s.input.a).toBe(a.shape);
+    expect(s.input.b).toBe(b.shape);
+  });
+
+  it("record stores its key/value shapes as a tuple on input", () => {
+    const k = B.string();
+    const v = B.number();
+    const s = B.record(k, v).shape;
+    expectToBe(s.type, "record");
+    expect(s.input[0]).toBe(k.shape);
+    expect(s.input[1]).toBe(v.shape);
+  });
+
+  it("vector defaults its format to a generic number shape", () => {
+    const s = B.vector(3).shape;
+    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 = B.vector(4, B.float32()).shape;
+    expectToBe(s.type, "vector");
+    expect(s.input.dims).toBe(4);
+    expectToBe(s.input.format.tag, "float32");
+  });
+});
+
+describe("B.union", (it) => {
+  it("accepts variadic arguments", () => {
+    const a = B.string();
+    const b = B.number();
+    const s = B.union(a, b).shape;
+    expectToBe(s.type, "union");
+    expect(s.input).toEqual([a.shape, b.shape]);
+  });
+
+  it("supports a literal-string discriminator across variants", () => {
+    const s = B.union(B.literal("a"), B.literal("b")).shape;
+    expectToBe(s.type, "union");
+    expect(s.input).toHaveLength(2);
+  });
+});
+
+describe("builder annotation methods", (it) => {
+  it("optional() returns a new builder with anno.optional=true", () => {
+    const base = B.string();
+    const opt = base.optional();
+    expect(opt.shape.anno.optional).toBe(true);
+    expect(base.shape.anno).toEqual({});
+    expect(opt).not.toBe(base);
+  });
+
+  it("unique() returns a new builder with anno.unique=true", () => {
+    const base = B.string();
+    const uniq = base.unique();
+    expect(uniq.shape.anno.unique).toBe(true);
+    expect(base.shape.anno).toEqual({});
+  });
+
+  it("uniqueItems() on array builder sets anno.uniqueItems=true", () => {
+    const base = B.array(B.string());
+    const uniq = base.uniqueItems();
+    expect(uniq.shape.anno.uniqueItems).toBe(true);
+    expect(base.shape.anno).toEqual({});
+  });
+
+  it("primary() returns a new builder with anno.primary=true", () => {
+    const base = B.string();
+    const prim = base.primary();
+    expect(prim.shape.anno.primary).toBe(true);
+    expect(base.shape.anno).toEqual({});
+  });
+
+  it("chains optional + unique + primary into the same anno", () => {
+    const b = B.string().optional().unique().primary();
+    expect(b.shape.anno.optional).toBe(true);
+    expect(b.shape.anno.unique).toBe(true);
+    expect(b.shape.anno.primary).toBe(true);
+  });
+
+  it("preserves the underlying shape type after annotation", () => {
+    const item = B.string();
+    const arr = B.array(item).optional();
+    expectToBe(arr.shape.type, "array");
+    expect(arr.shape.input).toBe(item.shape);
+  });
+});
+
+describe("builder bound methods", (it) => {
+  it("min/max on a string builder set the annotation values", () => {
+    const b = B.string().min(2).max(4);
+    expect(b.shape.anno.min).toBe(2);
+    expect(b.shape.anno.max).toBe(4);
+  });
+
+  it("min/max on a number builder set the annotation values", () => {
+    const b = B.number().min(0).max(10);
+    expect(b.shape.anno.min).toBe(0);
+    expect(b.shape.anno.max).toBe(10);
+  });
+
+  it("min/max on an array builder set the annotation values", () => {
+    const b = B.array(B.string()).min(1).max(3);
+    expect(b.shape.anno.min).toBe(1);
+    expect(b.shape.anno.max).toBe(3);
+  });
+
+  it("regex() stores a RegExp pattern on the string anno", () => {
+    const pat = /^[a-z]+$/;
+    const b = B.string().regex(pat);
+    expect(b.shape.anno.pattern).toBe(pat);
+  });
+
+  it("regex() stores a string-source pattern on the string anno", () => {
+    const b = B.string().regex("^[A-Z]{3}$");
+    expect(b.shape.anno.pattern).toBe("^[A-Z]{3}$");
+  });
+});
+
+describe("builder.parse — scalars", (it) => {
+  it("accepts a string against a string builder", () => {
+    const res = B.string().parse("hello");
+    expectOk(res);
+    expect(res.value).toBe("hello");
+  });
+
+  it("rejects a non-string against a string builder", () => {
+    const res = B.string().parse(42);
+    expectErr(res);
+    expect(res.error).toHaveLength(1);
+    expect(res.error[0]!.path).toEqual([]);
+    expect(res.error[0]!.message).toMatch(/string/);
+  });
+
+  it("accepts boolean values against a boolean builder", () => {
+    expectOk(B.boolean().parse(true));
+    expectOk(B.boolean().parse(false));
+  });
+
+  it("rejects a non-castable non-boolean against a boolean builder", () => {
+    const res = B.boolean().parse("not-a-bool");
+    expectErr(res);
+    expect(res.error).toHaveLength(1);
+    expect(res.error[0]!.message).toMatch(/boolean/);
+  });
+
+  it("accepts null against a nil builder", () => {
+    expectOk(B.nil().parse(null));
+  });
+
+  it("rejects a non-null value against a nil builder", () => {
+    const res = B.nil().parse(0);
+    expectErr(res);
+    expect(res.error).toHaveLength(1);
+    expect(res.error[0]!.message).toMatch(/nil/);
+  });
+
+  it("accepts undefined against a notDefined builder", () => {
+    expectOk(B.notDefined().parse(undefined));
+  });
+
+  it("rejects a defined value against a notDefined builder", () => {
+    const res = B.notDefined().parse(null);
+    expectErr(res);
+    expect(res.error).toHaveLength(1);
+  });
+
+  it("accepts a Date against a date builder", () => {
+    expectOk(B.date().parse(new Date()));
+  });
+
+  it("rejects a non-Date against a date builder", () => {
+    const res = B.date().parse(true);
+    expectErr(res);
+    expect(res.error).toHaveLength(1);
+    expect(res.error[0]!.message).toMatch(/date/);
+  });
+
+  it("accepts any value against an unknown builder", () => {
+    expectOk(B.unknown().parse(1));
+    expectOk(B.unknown().parse("x"));
+    expectOk(B.unknown().parse(null));
+    expectOk(B.unknown().parse({ a: 1 }));
+  });
+});
+
+describe("builder.parse — numbers", (it) => {
+  it("accepts a number against a generic number builder", () => {
+    expectOk(B.number().parse(42));
+    expectOk(B.number().parse(-1.5));
+  });
+
+  it("rejects a non-numeric value against a number builder", () => {
+    const res = B.number().parse("foo");
+    expectErr(res);
+    expect(res.error).toHaveLength(1);
+    expect(res.error[0]!.message).toMatch(/number/);
+  });
+
+  it("auto-casts a numeric string against a number builder", () => {
+    const res = B.number().parse("42");
+    expectOk(res);
+    expect(res.value).toBe(42);
+  });
+
+  it("accepts a value that fits the requested integer tag", () => {
+    expectOk(B.uint8().parse(200));
+    expectOk(B.int16().parse(-1000));
+  });
+
+  it("rejects a value that exceeds the requested integer tag's range", () => {
+    const res = B.uint8().parse(0xffff);
+    expectErr(res);
+    expect(res.error).toHaveLength(1);
+    expect(res.error[0]!.message).toMatch(/format/);
+  });
+
+  it("rejects a float when an integer tag is required", () => {
+    const res = B.uint8().parse(0.5);
+    expectErr(res);
+    expect(res.error).toHaveLength(1);
+    expect(res.error[0]!.message).toMatch(/format/);
+  });
+
+  it("rejects an int against a float32 tag", () => {
+    const res = B.float32().parse(1);
+    expectErr(res);
+    expect(res.error).toHaveLength(1);
+  });
+
+  it("accepts a float that fits inside float32", () => {
+    expectOk(B.float32().parse(0.5));
+  });
+});
+
+describe("builder.parse — literals", (it) => {
+  it("accepts the matching literal string", () => {
+    expectOk(B.literal("foo").parse("foo"));
+  });
+
+  it("rejects a non-matching literal string", () => {
+    const res = B.literal("foo").parse("bar");
+    expectErr(res);
+    expect(res.error).toHaveLength(1);
+    expect(res.error[0]!.message).toMatch(/literal/);
+  });
+
+  it("accepts the matching literal number", () => {
+    expectOk(B.literal(7).parse(7));
+  });
+
+  it("rejects a non-matching literal number", () => {
+    const res = B.literal(7).parse(8);
+    expectErr(res);
+    expect(res.error).toHaveLength(1);
+    expect(res.error[0]!.message).toMatch(/literal/);
+  });
+
+  it("accepts the matching literal boolean", () => {
+    expectOk(B.literal(true).parse(true));
+  });
+
+  it("rejects a non-matching literal boolean", () => {
+    const res = B.literal(true).parse(false);
+    expectErr(res);
+    expect(res.error).toHaveLength(1);
+    expect(res.error[0]!.message).toMatch(/literal/);
+  });
+});
+
+describe("builder.parse — binary", (it) => {
+  it("accepts a Uint8Array against a binary builder", () => {
+    expectOk(B.binary().parse(new Uint8Array([1, 2, 3])));
+  });
+
+  it("accepts an array of uint8-fitting numbers against a binary builder", () => {
+    expectOk(B.binary().parse([0, 127, 255]));
+  });
+
+  it("rejects an array containing a non-uint8 value against a binary builder", () => {
+    const res = B.binary().parse([0, 256]);
+    expectErr(res);
+    expect(res.error.length).toBeGreaterThan(0);
+    expect(res.error[0]!.path).toEqual([1]);
+  });
+
+  it("rejects a non-array, non-Uint8Array against a binary builder", () => {
+    const res = B.binary().parse("not binary");
+    expectErr(res);
+    expect(res.error).toHaveLength(1);
+    expect(res.error[0]!.message).toMatch(/binary/);
+  });
+});
+
+describe("builder.parse — array", (it) => {
+  it("accepts an array whose items all match the item builder", () => {
+    expectOk(B.array(B.string()).parse(["a", "b"]));
+  });
+
+  it("accepts an empty array regardless of item builder", () => {
+    expectOk(B.array(B.string()).parse([]));
+  });
+
+  it("rejects a non-array, non-castable input", () => {
+    const res = B.array(B.string()).parse(42);
+    expectErr(res);
+    expect(res.error).toHaveLength(1);
+    expect(res.error[0]!.message).toMatch(/array/);
+  });
+
+  it("reports the index of an invalid item in the path", () => {
+    const res = B.array(B.string()).parse(["a", 1, "c"]);
+    expectErr(res);
+    expect(res.error.length).toBeGreaterThan(0);
+    expect(res.error[0]!.path).toEqual([1]);
+  });
+});
+
+describe("builder.parse — vector", (it) => {
+  it("accepts an array whose length matches dims and items fit the format", () => {
+    expectOk(B.vector(3, B.uint8()).parse([1, 2, 3]));
+  });
+
+  it("rejects a non-array input", () => {
+    const res = B.vector(3).parse(42);
+    expectErr(res);
+    expect(res.error).toHaveLength(1);
+    expect(res.error[0]!.message).toMatch(/vector/);
+  });
+
+  it("rejects a length mismatch", () => {
+    const res = B.vector(3).parse([1, 2]);
+    expectErr(res);
+    expect(res.error).toHaveLength(1);
+    expect(res.error[0]!.message).toMatch(/dimensions/);
+  });
+
+  it("reports the index of a format-mismatched item", () => {
+    const res = B.vector(3, B.uint8()).parse([1, 999, 3]);
+    expectErr(res);
+    expect(res.error.length).toBeGreaterThan(0);
+    expect(res.error[0]!.path).toEqual([1]);
+  });
+});
+
+describe("builder.parse — mapping", (it) => {
+  it("accepts an object where every required key validates", () => {
+    const b = B.mapping({ a: B.string(), b: B.number() });
+    expectOk(b.parse({ a: "x", b: 1 }));
+  });
+
+  it("rejects a non-object input", () => {
+    const b = B.mapping({ a: B.string() });
+    const res = b.parse(42);
+    expectErr(res);
+    expect(res.error).toHaveLength(1);
+    expect(res.error[0]!.message).toMatch(/mapping/);
+  });
+
+  it("rejects null against a mapping builder", () => {
+    const b = B.mapping({ a: B.string() });
+    const res = b.parse(null);
+    expectErr(res);
+    expect(res.error).toHaveLength(1);
+    expect(res.error[0]!.message).toMatch(/mapping/);
+  });
+
+  it("reports a missing required key with the key in the path", () => {
+    const b = B.mapping({ a: B.string(), b: B.number() });
+    const res = b.parse({ a: "x" });
+    expectErr(res);
+    expect(res.error).toHaveLength(1);
+    expect(res.error[0]!.path).toEqual(["b"]);
+    expect(res.error[0]!.message).toMatch(/Missing required key/);
+  });
+
+  it("allows a missing optional key", () => {
+    const b = B.mapping({ a: B.string(), b: B.number().optional() });
+    expectOk(b.parse({ a: "x" }));
+  });
+
+  it("reports value-shape errors with the key in the path", () => {
+    const b = B.mapping({ a: B.string(), b: B.number() });
+    const res = b.parse({ a: "x", b: true });
+    expectErr(res);
+    expect(res.error).toHaveLength(1);
+    expect(res.error[0]!.path).toEqual(["b"]);
+  });
+
+  it("walks the path into nested mappings", () => {
+    const b = B.mapping({
+      outer: B.mapping({ inner: B.number() }),
+    });
+    const res = b.parse({ outer: { inner: true } });
+    expectErr(res);
+    expect(res.error).toHaveLength(1);
+    expect(res.error[0]!.path).toEqual(["outer", "inner"]);
+  });
+});
+
+describe("builder.parse — record", (it) => {
+  it("accepts an object whose keys and values all validate", () => {
+    const b = B.record(B.string(), B.number());
+    expectOk(b.parse({ a: 1, b: 2 }));
+  });
+
+  it("rejects a non-object input", () => {
+    const b = B.record(B.string(), B.number());
+    const res = b.parse(1);
+    expectErr(res);
+    expect(res.error).toHaveLength(1);
+    expect(res.error[0]!.message).toMatch(/record/);
+  });
+
+  it("rejects null against a record builder", () => {
+    const b = B.record(B.string(), B.number());
+    const res = b.parse(null);
+    expectErr(res);
+    expect(res.error).toHaveLength(1);
+  });
+
+  it("reports a value-shape error with the key in the path", () => {
+    const b = B.record(B.string(), B.number());
+    const res = b.parse({ a: 1, b: true });
+    expectErr(res);
+    expect(res.error.length).toBeGreaterThan(0);
+    expect(res.error[0]!.path).toEqual(["b"]);
+  });
+
+  it("accepts an empty object", () => {
+    const b = B.record(B.string(), B.number());
+    expectOk(b.parse({}));
+  });
+});
+
+describe("builder.parse — union", (it) => {
+  it("accepts a value matching any variant", () => {
+    const b = B.union(B.string(), B.number());
+    expectOk(b.parse("hi"));
+    expectOk(b.parse(1));
+  });
+
+  it("rejects a value matching no variant and collects errors from each", () => {
+    const b = B.union(B.string(), B.number());
+    const res = b.parse(true);
+    expectErr(res);
+    expect(res.error.length).toBeGreaterThanOrEqual(2);
+  });
+});
+
+describe("builder.parse — min/max", (it) => {
+  it("accepts a number within [min, max]", () => {
+    const b = B.number().min(0).max(10);
+    expectOk(b.parse(0));
+    expectOk(b.parse(5));
+    expectOk(b.parse(10));
+  });
+
+  it("rejects a number below min", () => {
+    const b = B.number().min(0);
+    const res = b.parse(-1);
+    expectErr(res);
+    expect(res.error).toHaveLength(1);
+    expect(res.error[0]!.message).toMatch(/>= 0/);
+  });
+
+  it("rejects a number above max", () => {
+    const b = B.number().max(10);
+    const res = b.parse(11);
+    expectErr(res);
+    expect(res.error).toHaveLength(1);
+    expect(res.error[0]!.message).toMatch(/<= 10/);
+  });
+
+  it("checks the number format before applying bounds", () => {
+    const b = B.number().min(0).max(10);
+    const res = b.parse("foo");
+    expectErr(res);
+    expect(res.error).toHaveLength(1);
+    expect(res.error[0]!.message).toMatch(/number/);
+  });
+
+  it("accepts a string whose length is within [min, max]", () => {
+    const b = B.string().min(2).max(4);
+    expectOk(b.parse("ab"));
+    expectOk(b.parse("abc"));
+    expectOk(b.parse("abcd"));
+  });
+
+  it("rejects a string shorter than min", () => {
+    const b = B.string().min(2);
+    const res = b.parse("a");
+    expectErr(res);
+    expect(res.error).toHaveLength(1);
+    expect(res.error[0]!.message).toMatch(/string length/);
+    expect(res.error[0]!.message).toMatch(/>= 2/);
+  });
+
+  it("rejects a string longer than max", () => {
+    const b = B.string().max(3);
+    const res = b.parse("abcd");
+    expectErr(res);
+    expect(res.error).toHaveLength(1);
+    expect(res.error[0]!.message).toMatch(/string length/);
+    expect(res.error[0]!.message).toMatch(/<= 3/);
+  });
+
+  it("accepts an array whose length is within [min, max]", () => {
+    const b = B.array(B.number()).min(1).max(3);
+    expectOk(b.parse([1]));
+    expectOk(b.parse([1, 2]));
+    expectOk(b.parse([1, 2, 3]));
+  });
+
+  it("rejects an array shorter than min", () => {
+    const b = B.array(B.number()).min(2);
+    const res = b.parse([1]);
+    expectErr(res);
+    expect(res.error).toHaveLength(1);
+    expect(res.error[0]!.message).toMatch(/array length/);
+    expect(res.error[0]!.message).toMatch(/>= 2/);
+  });
+
+  it("rejects an array longer than max", () => {
+    const b = B.array(B.number()).max(2);
+    const res = b.parse([1, 2, 3]);
+    expectErr(res);
+    expect(res.error).toHaveLength(1);
+    expect(res.error[0]!.message).toMatch(/array length/);
+    expect(res.error[0]!.message).toMatch(/<= 2/);
+  });
+
+  it("reports bounds errors at the shape's path inside a nested mapping", () => {
+    const b = B.mapping({ name: B.string().min(3) });
+    const res = b.parse({ name: "no" });
+    expectErr(res);
+    expect(res.error).toHaveLength(1);
+    expect(res.error[0]!.path).toEqual(["name"]);
+  });
+});
+
+describe("builder.parse — pattern", (it) => {
+  it("accepts a string matching a RegExp pattern", () => {
+    const b = B.string().regex(/^[a-z]+$/);
+    expectOk(b.parse("abc"));
+  });
+
+  it("rejects a string not matching a RegExp pattern", () => {
+    const b = B.string().regex(/^[a-z]+$/);
+    const res = b.parse("abc123");
+    expectErr(res);
+    expect(res.error).toHaveLength(1);
+    expect(res.error[0]!.message).toMatch(/pattern/);
+  });
+
+  it("accepts a string matching a string-source pattern", () => {
+    const b = B.string().regex("^[A-Z]{3}$");
+    expectOk(b.parse("USD"));
+  });
+
+  it("rejects a string not matching a string-source pattern", () => {
+    const b = B.string().regex("^[A-Z]{3}$");
+    const res = b.parse("usd");
+    expectErr(res);
+    expect(res.error).toHaveLength(1);
+    expect(res.error[0]!.message).toMatch(/pattern/);
+  });
+
+  it("checks type before pattern", () => {
+    const b = B.string().regex(/^[a-z]+$/);
+    const res = b.parse(5);
+    expectErr(res);
+    expect(res.error).toHaveLength(1);
+    expect(res.error[0]!.message).toMatch(/string/);
+  });
+
+  it("reports pattern errors at the shape's path inside a nested mapping", () => {
+    const b = B.mapping({ slug: B.string().regex(/^[a-z-]+$/) });
+    const res = b.parse({ slug: "Bad Slug" });
+    expectErr(res);
+    expect(res.error).toHaveLength(1);
+    expect(res.error[0]!.path).toEqual(["slug"]);
+  });
+
+  it("composes with min/max — bounds error takes precedence", () => {
+    const b = B.string()
+      .min(3)
+      .regex(/^[a-z]+$/);
+    const res = b.parse("a");
+    expectErr(res);
+    expect(res.error).toHaveLength(1);
+    expect(res.error[0]!.message).toMatch(/string length/);
+  });
+});
+
+describe("builder.parse — paths", (it) => {
+  it("uses [] as the path for a top-level scalar mismatch", () => {
+    const res = B.string().parse(1);
+    expectErr(res);
+    expect(res.error[0]!.path).toEqual([]);
+  });
+
+  it("threads indices and keys through nested arrays and mappings", () => {
+    const b = B.mapping({
+      items: B.array(B.mapping({ name: B.string() })),
+    });
+    const res = b.parse({ items: [{ name: "ok" }, { name: 5 }] });
+    expectErr(res);
+    expect(res.error).toHaveLength(1);
+    expect(res.error[0]!.path).toEqual(["items", 1, "name"]);
+  });
+});