diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 247f256..9529b52 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -36,6 +36,19 @@ jobs: - name: Test run: pnpm test:js + test-fuzz: + name: Fuzz Tests + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 + - uses: ./.github/actions/setup-env + - name: Build + run: pnpm build + - name: Fuzz + run: pnpm test:fuzz:round_trip + env: + FUZZ_RUNS: "1000" + lint: name: Lint runs-on: ubuntu-latest diff --git a/README.md b/README.md index 2a6993f..5235008 100644 --- a/README.md +++ b/README.md @@ -84,7 +84,7 @@ c.count; // 1 (getter, not a method call) | `Number` | `number` | `toI32()`, `toF64()`, `assertI32()`, `from(anytype)` | | `String` | `string` | `toSlice(buf)`, `toOwnedSlice(alloc)`, `len()`, `from([]const u8)` | | `Boolean` | `boolean` | `toBool()`, `assertBool()`, `from(bool)` | -| `BigInt` | `bigint` | `toI64()`, `toU64()`, `toI128()`, `from(anytype)` | +| `BigInt` | `bigint` | `toI64()`, `toU64()`, `toI128()`, `to*LowBits()`, `from(anytype)`, `fromWords(sign, words)` | | `Date` | `Date` | `toTimestamp()`, `from(f64)` | | `Array` | `Array` | `get(i)`, `getNumber(i)`, `length()`, `set(i, val)` | | `Object(T)` | `object` | `get()`, `set(value)` — `T` fields must be DSL types | diff --git a/build.zig.zon b/build.zig.zon index d595321..421c92a 100644 --- a/build.zig.zon +++ b/build.zig.zon @@ -49,6 +49,11 @@ .imports = .{.zapi}, .link_libc = true, }, + .test_fuzz_numeric = .{ + .root_source_file = "tests/fuzz/mod.zig", + .imports = .{.zapi}, + .link_libc = true, + }, }, .libraries = .{ .example_hello_world = .{ @@ -69,6 +74,12 @@ .linker_allow_shlib_undefined = true, .dest_sub_path = "example_js_dsl.node", }, + .test_fuzz_numeric = .{ + .root_module = .test_fuzz_numeric, + .linkage = .dynamic, + .linker_allow_shlib_undefined = true, + .dest_sub_path = "test_fuzz_numeric.node", + }, }, .tests = .{ .napi = .{ .root_module = .napi }, diff --git a/examples/js_dsl/mod.zig b/examples/js_dsl/mod.zig index 59ee1c8..0d1c34b 100644 --- a/examples/js_dsl/mod.zig +++ b/examples/js_dsl/mod.zig @@ -95,8 +95,7 @@ pub fn reverseString(s: String) !String { /// Double a BigInt value. pub fn doubleBigInt(n: BigInt) !BigInt { - var lossless: bool = false; - const val = try n.toI64(&lossless); + const val = try n.toI64(); return BigInt.from(val * 2); } diff --git a/package.json b/package.json index ba0c546..33bb9e8 100644 --- a/package.json +++ b/package.json @@ -15,6 +15,7 @@ "build:zig": "zig build", "test:zig": "zig build test:zapi", "test:js": "vitest run examples/**/*.test.ts", + "test:fuzz:round_trip": "pnpm build:zig && vitest run tests/**/*.test.ts", "test": "pnpm test:zig && pnpm test:js", "lint:zig": "zig fmt src", "lint:js": "pnpm biome check", @@ -34,6 +35,7 @@ "@biomejs/biome": "^2.4.6", "@chainsafe/biomejs-config": "^1.0.0", "@types/node": "^24.1.0", + "fast-check": "^4.8.0", "typescript": "^5.8.3", "vitest": "^4.0.18" }, diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index e5affa3..a811fce 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -17,6 +17,9 @@ importers: '@types/node': specifier: ^24.1.0 version: 24.10.10 + fast-check: + specifier: ^4.8.0 + version: 4.8.0 typescript: specifier: ^5.8.3 version: 5.9.3 @@ -435,6 +438,10 @@ packages: resolution: {integrity: sha512-knvyeauYhqjOYvQ66MznSMs83wmHrCycNEN6Ao+2AeYEfxUIkuiVxdEa1qlGEPK+We3n0THiDciYSsCcgW/DoA==} engines: {node: '>=12.0.0'} + fast-check@4.8.0: + resolution: {integrity: sha512-GOJ158CUMnN6cSahsv4+ExARvIDuzzinFjkp0E9WtiBa5zcVeLozVkWaE4IzFcc+Y48Wp1EDlUZsXRyAztQcSg==} + engines: {node: '>=12.17.0'} + fdir@6.5.0: resolution: {integrity: sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==} engines: {node: '>=12.0.0'} @@ -474,6 +481,9 @@ packages: resolution: {integrity: sha512-OW/rX8O/jXnm82Ey1k44pObPtdblfiuWnrd8X7GJ7emImCOstunGbXUpp7HdBrFQX6rJzn3sPT397Wp5aCwCHg==} engines: {node: ^10 || ^12 || >=14} + pure-rand@8.4.0: + resolution: {integrity: sha512-IoM8YF/jY0hiugFo/wOWqfmarlE6J0wc6fDK1PhftMk7MGhVZl88sZimmqBBFomLOCSmcCCpsfj7wXASCpvK9A==} + rollup@4.59.0: resolution: {integrity: sha512-2oMpl67a3zCH9H79LeMcbDhXW/UmWG/y2zuqnF2jQq5uq9TbM9TVyXvA4+t+ne2IIkBdrLpAaRQAvo7YI/Yyeg==} engines: {node: '>=18.0.0', npm: '>=8.0.0'} @@ -885,6 +895,10 @@ snapshots: expect-type@1.3.0: {} + fast-check@4.8.0: + dependencies: + pure-rand: 8.4.0 + fdir@6.5.0(picomatch@4.0.3): optionalDependencies: picomatch: 4.0.3 @@ -912,6 +926,8 @@ snapshots: picocolors: 1.1.1 source-map-js: 1.2.1 + pure-rand@8.4.0: {} + rollup@4.59.0: dependencies: '@types/estree': 1.0.8 diff --git a/src/Value.zig b/src/Value.zig index bd3b206..7c2157f 100644 --- a/src/Value.zig +++ b/src/Value.zig @@ -235,7 +235,11 @@ pub fn getValueBigintWords(self: Value, sign_bit: ?*u1, words: []u64) NapiError! ); // napi guarantees raw_sign ∈ {0, 1} if (sign_bit) |s| s.* = @intCast(raw_sign); - return words[0..word_count]; + // `word_count` is set by NAPI to the actual number of 64-bit words in the + // BigInt, which may exceed `words.len` when the value is larger than the + // buffer. NAPI fills `words` up to `words.len`; clamp the returned slice + // so callers get only the words that were actually written. + return words[0..@min(word_count, words.len)]; } /// https://nodejs.org/api/n-api.html#napi_get_value_external diff --git a/src/create_callback.zig b/src/create_callback.zig index a8f9575..796b1ae 100644 --- a/src/create_callback.zig +++ b/src/create_callback.zig @@ -38,7 +38,7 @@ pub fn createCallback( const is_value_arg = arg_hint == .value or (arg_hint == .auto and param_type == Value); if (arg_hint == .data) { - args[i] = @alignCast(@ptrCast(info.data)); + args[i] = @ptrCast(@alignCast(info.data)); } else if (is_env_arg) { args[i] = env; } else if (is_value_arg) { diff --git a/src/js/bigint.zig b/src/js/bigint.zig index fd38ebd..5092ce8 100644 --- a/src/js/bigint.zig +++ b/src/js/bigint.zig @@ -14,66 +14,136 @@ pub const BigInt = struct { if ((try val.typeof()) != .bigint) return error.TypeMismatch; } - /// Attempts to convert the JavaScript BigInt to a Zig `i64`. + /// Attempts to convert the JavaScript BigInt exactly to a Zig `i64`. /// - /// If `lossless` is provided, it will be set to `true` if the BigInt can be - /// represented exactly as an `i64`, and `false` otherwise (e.g., if the - /// BigInt is too large or too small for `i64`). - /// Returns an error if the conversion fails or the `napi_env` is invalid. - pub fn toI64(self: BigInt, lossless: ?*bool) !i64 { + /// Returns `error.InvalidArg` if the value is outside the `i64` range. Use + /// `toI64LowBits` when low-64-bit conversion is intended. + pub fn toI64(self: BigInt) !i64 { + var lossless = false; + const value = try self.toI64LowBits(&lossless); + if (!lossless) return error.InvalidArg; + return value; + } + + /// Converts the JavaScript BigInt to the low 64 bits as a Zig `i64`. + /// + /// If `lossless` is provided, it is set to whether the returned `i64` + /// represents the original BigInt exactly. Out-of-range values still return + /// their low 64 bits, matching N-API BigInt conversion semantics, but set + /// `lossless` to false. + pub fn toI64LowBits(self: BigInt, lossless: ?*bool) !i64 { return self.val.getValueBigintInt64(lossless); } - /// Attempts to convert the JavaScript BigInt to a Zig `u64`. + /// Attempts to convert the JavaScript BigInt exactly to a Zig `u64`. + /// + /// Returns `error.InvalidArg` if the value is negative or outside the `u64` + /// range. Use `toU64LowBits` when low-64-bit conversion is intended. + pub fn toU64(self: BigInt) !u64 { + var lossless = false; + const value = try self.toU64LowBits(&lossless); + if (!lossless) return error.InvalidArg; + return value; + } + + /// Converts the JavaScript BigInt to the low 64 bits as a Zig `u64`. /// - /// If `lossless` is provided, it will be set to `true` if the BigInt can be - /// represented exactly as a `u64`, and `false` otherwise. - /// Returns an error if the conversion fails (e.g., BigInt is negative) or - /// the `napi_env` is invalid. - pub fn toU64(self: BigInt, lossless: ?*bool) !u64 { + /// If `lossless` is provided, it is set to whether the returned `u64` + /// represents the original BigInt exactly. Out-of-range or negative values + /// still return their low 64 bits, matching N-API BigInt conversion + /// semantics, but set `lossless` to false. + pub fn toU64LowBits(self: BigInt, lossless: ?*bool) !u64 { return self.val.getValueBigintUint64(lossless); } - /// Attempts to convert the JavaScript BigInt to a Zig `i128`. + /// Attempts to convert the JavaScript BigInt exactly to a Zig `i128`. + /// + /// Returns `error.InvalidArg` if the value is outside `[-2^127, 2^127)`. + /// Use `toI128LowBits` when low-128-bit conversion is intended. /// - /// This function reads the BigInt as two 64-bit words and reconstructs it - /// into a Zig `i128`. It handles both positive and negative BigInts. /// Returns an error if N-API operations fail. pub fn toI128(self: BigInt) !i128 { var sign_bit: u1 = 0; - var words: [2]u64 = .{ 0, 0 }; + // Three words are enough to distinguish every in-range i128 from any + // oversized value, even when the lower 128 bits are zero. + var words: [3]u64 = .{ 0, 0, 0 }; const result = try self.val.getValueBigintWords(&sign_bit, &words); - const lo: u128 = result[0]; - const hi: u128 = if (result.len > 1) result[1] else 0; + if (result.len > 2) return error.InvalidArg; + + const lo: u128 = words[0]; + const hi: u128 = words[1]; const magnitude: u128 = (hi << 64) | lo; if (sign_bit == 1) { - // Negative: negate the magnitude if (magnitude == 0) return 0; - return -@as(i128, @intCast(magnitude)); + if (magnitude > (@as(u128, 1) << 127)) return error.InvalidArg; + return @bitCast(0 -% magnitude); + } + + if (magnitude > @as(u128, @intCast(std.math.maxInt(i128)))) { + return error.InvalidArg; } return @intCast(magnitude); } + /// Converts the JavaScript BigInt to the low 128 bits as a Zig `i128`. + /// + /// This returns `BigInt.asIntN(128, b)`, i.e. the low 128 bits + /// of the magnitude reinterpreted as a signed i128. This matches the + /// ECMAScript `BigInt.asIntN` semantics defined at + /// https://tc39.es/ecma262/#sec-bigint.asintn. + /// + /// Returns an error if N-API operations fail. + pub fn toI128LowBits(self: BigInt) !i128 { + var sign_bit: u1 = 0; + // Pre-zeroed: NAPI writes only as many words as the BigInt has; unused + // words stay 0. When the value is 0n NAPI returns word_count == 0, so + // both words[0] and words[1] remain 0 — magnitude correctly becomes 0. + // When the BigInt exceeds 128 bits, getValueBigintWords fills only the + // two lower words (truncation to low 128 bits), giving BigInt.asIntN(128) + // semantics for out-of-range values. + var words: [2]u64 = .{ 0, 0 }; + _ = try self.val.getValueBigintWords(&sign_bit, &words); + const lo: u128 = words[0]; + const hi: u128 = words[1]; + const magnitude: u128 = (hi << 64) | lo; + if (sign_bit == 1) { + // Negative: result = -magnitude interpreted as i128. + // Use wrapping subtraction + bitcast to handle both minInt(i128) + // (magnitude == 2^127, which doesn't fit in i128 as positive) and + // out-of-range values (magnitude > 2^127, truncated to low 128 bits). + // Guard: out-of-range negatives whose low 128 bits are all zero + // (e.g. -2^128n → words [0, 0]) give magnitude == 0. asIntN(128) + // of such values is 0n; return early rather than relying on the + // `0 -% 0 == 0` coincidence below. + if (magnitude == 0) return 0; + return @bitCast(0 -% magnitude); + } + // Positive: bitcast u128 → i128 gives BigInt.asIntN(128) semantics. + // In-range values have magnitude ≤ 2^127-1 so the sign bit is clear; + // out-of-range values have the sign bit set, matching JS asIntN(128). + return @bitCast(magnitude); + } + /// Converts the JavaScript BigInt to a Zig `i64`, panicking on failure. /// /// This is a convenience method for cases where the BigInt is guaranteed - /// to be representable as an `i64` without loss. + /// to be exactly representable as an `i64`. pub fn assertI64(self: BigInt) i64 { - return self.toI64(null) catch @panic("BigInt.assertI64 failed"); + return self.toI64() catch @panic("BigInt.assertI64 failed"); } /// Converts the JavaScript BigInt to a Zig `u64`, panicking on failure. /// /// This is a convenience method for cases where the BigInt is guaranteed - /// to be representable as a `u64` without loss. + /// to be exactly representable as a `u64`. pub fn assertU64(self: BigInt) u64 { - return self.toU64(null) catch @panic("BigInt.assertU64 failed"); + return self.toU64() catch @panic("BigInt.assertU64 failed"); } /// Converts the JavaScript BigInt to a Zig `i128`, panicking on failure. /// /// This is a convenience method for cases where the BigInt is guaranteed - /// to be representable as an `i128`. + /// to be exactly representable as an `i128`. pub fn assertI128(self: BigInt) i128 { return self.toI128() catch @panic("BigInt.assertI128 failed"); } @@ -81,8 +151,7 @@ pub const BigInt = struct { /// Creates a JavaScript `BigInt` from a Zig integer value. /// /// Accepts `i64`, `u64`, and `comptime_int` values within this range. - /// For `i128`/`u128` values, use `fromWords` (not currently exposed but - /// available at the `napi.Env` level). + /// For `i128`/`u128` values, use `fromWords`. /// /// Panics if N-API operations fail (e.g., invalid environment) or for Zig /// integer types larger than `u64` that cannot be converted to `i64`/`u64`. @@ -115,6 +184,23 @@ pub const BigInt = struct { return .{ .val = val }; } + /// Creates a JavaScript `BigInt` from a sign bit and word array. + /// + /// `sign_bit` is 0 for non-negative, 1 for negative. `words` is the + /// little-endian unsigned magnitude. The resulting BigInt equals + /// `(sign_bit == 1 ? -1 : 1) * sum(words[i] << (64 * i))`. + /// + /// Use this for constructing BigInts whose magnitude exceeds `u64` (e.g., + /// i128 or larger). For `i64`/`u64` values, prefer `BigInt.from`. + /// + /// Panics if N-API operations fail (e.g., invalid environment). + pub fn fromWords(sign_bit: u1, words: []const u64) BigInt { + const e = context.env(); + const val = e.createBigintWords(sign_bit, words) catch + @panic("BigInt.fromWords: createBigintWords failed"); + return .{ .val = val }; + } + /// Returns the underlying `napi.Value` representation of this JavaScript BigInt. pub fn toValue(self: BigInt) napi.Value { return self.val; diff --git a/src/js/number.zig b/src/js/number.zig index 9dc04e0..37bea40 100644 --- a/src/js/number.zig +++ b/src/js/number.zig @@ -27,19 +27,24 @@ pub const Number = struct { /// Attempts to convert the JavaScript number to a Zig `i32`. /// - /// Returns an error if the conversion fails (e.g., number is too large). + /// Follows N-API int32 conversion semantics: finite values outside the + /// 32-bit range are truncated to the equivalent low 32 bits, and non-finite + /// values (`NaN`, `+Infinity`, `-Infinity`) become 0. + /// + /// Returns an error if the underlying value is not a number or the N-API + /// call fails. pub fn toI32(self: Number) !i32 { return self.val.getValueInt32(); } /// Attempts to convert the JavaScript number to a Zig `u32`. /// - /// Safety: The underlying napi implementation does not reject numbers out of - /// the range [0, 2^32). The caller is responsible for bounds checking. - /// - /// Returns an error if the given `self.val` is not a number. + /// Follows N-API uint32 conversion semantics: finite values outside the + /// 32-bit range are truncated to the equivalent low 32 bits, and non-finite + /// values (`NaN`, `+Infinity`, `-Infinity`) become 0. /// - /// Source: https://tc39.es/ecma262/#sec-touint32 + /// Returns an error if the underlying value is not a number or the N-API + /// call fails. pub fn toU32(self: Number) !u32 { return self.val.getValueUint32(); } @@ -53,7 +58,13 @@ pub const Number = struct { /// Attempts to convert the JavaScript number to a Zig `i64`. /// - /// Returns an error if the conversion fails (e.g., number is too large). + /// Follows N-API int64 conversion semantics: non-finite values (`NaN`, + /// `+Infinity`, `-Infinity`) become 0. Values outside JavaScript's safe + /// integer range may lose precision, and finite values outside the `i64` + /// range are clamped by Node to `minInt(i64)`/`maxInt(i64)`. + /// + /// Returns an error if the underlying value is not a number or the N-API + /// call fails. pub fn toI64(self: Number) !i64 { return self.val.getValueInt64(); } diff --git a/tests/fuzz/README.md b/tests/fuzz/README.md new file mode 100644 index 0000000..67cac6b --- /dev/null +++ b/tests/fuzz/README.md @@ -0,0 +1,58 @@ +# fuzz + +Property-based fuzz tests for zapi's Number, BigInt, and selected binary conversion surfaces. Driven from JS through the `test_fuzz_numeric.node` addon (built by `zig build`) using vitest + fast-check. + +See `docs/superpowers/specs/2026-05-28-fuzz-testing-design.md` for design rationale. + +## Running + +```bash +# Full run (10 000 cases per property) +pnpm test:fuzz:round_trip + +# CI-equivalent (1 000 cases per property) +FUZZ_RUNS=1000 pnpm test:fuzz:round_trip + +# Single property +pnpm vitest run tests/fuzz/bigint.fuzz.test.ts -t "rtBigIntI128" +``` + +## When a property fails + +fast-check shrinks the counterexample and prints something like: + +``` +Property failed after 47 tests +Counterexample: 170141183460469231731687303715884105728n +Shrunk 14 times to: 170141183460469231731687303715884105728n +Seed: 1234567890, Path: 0:0:1 +``` + +To reproduce locally, paste the seed into a temporary `it.only`: + +```ts +it.only("repro", () => { + fc.assert( + fc.property(bigIntArbI128, (b) => ... ), + { seed: 1234567890, path: "0:0:1", numRuns: 1 }, + ); +}); +``` + +Once fixed, **persist the counterexample** so it runs forever: + +1. Create or open `tests/fuzz/seeds/.json`. +2. Append the counterexample to the JSON array. For bigints, use: + ```json + { "__bigint": "170141183460469231731687303715884105728" } + ``` + For numbers, use a JSON number directly. For `Uint8Array`, use a JSON array of byte values, e.g. `[0, 255, 1]`. NaN and ±Infinity aren't representable in JSON and are not currently supported as persisted seeds — those values are already in `edgeNumbers` and exercised on every run, so persisting them as regression cases adds nothing. If a future fuzz target needs persisted special-number seeds, extend `loadSeeds` and the relevant `revive*` helper at that time. +3. Commit with the fix. + +## Adding a new fuzz target + +1. Add the round-trip export to `mod.zig`. +2. Add the oracle to `oracle.test.ts` and run it against every entry in the relevant edge list. +3. Add the fast-check property to the relevant `*.fuzz.test.ts` file. +4. Update `tests/utils/edge.ts` if the target needs new edge values. +5. Run `pnpm test:fuzz:round_trip` and watch it pass (or find a bug). diff --git a/tests/fuzz/bigint.fuzz.test.ts b/tests/fuzz/bigint.fuzz.test.ts new file mode 100644 index 0000000..844d728 --- /dev/null +++ b/tests/fuzz/bigint.fuzz.test.ts @@ -0,0 +1,154 @@ +import { describe, it } from "vitest"; +import fc from "fast-check"; +import { edgeBigInts } from "../utils/edge.ts"; +import { + fitsBigIntI128, + fitsBigIntI64, + fitsBigIntU64, + oracleBigIntI128, + oracleBigIntI128LowBits, + oracleLosslessI64, + oracleLosslessU64, +} from "../utils/oracles.ts"; +import { FUZZ_RUNS, loadSeeds, mod, reviveBigInt } from "../utils/support.ts"; + +const bigIntArbI64 = fc.oneof( + { arbitrary: fc.bigInt({ min: -(2n ** 65n), max: 2n ** 65n }), weight: 4 }, + { arbitrary: fc.constantFrom(...edgeBigInts), weight: 1 }, +); + +describe("rtBigIntI64", () => { + it("is exact in [-2^63, 2^63) and throws outside that range", () => { + fc.assert( + fc.property(bigIntArbI64, (b) => { + if (fitsBigIntI64(b)) return mod.rtBigIntI64(b) === b; + + try { + mod.rtBigIntI64(b); + return false; + } catch { + return true; + } + }), + { + numRuns: FUZZ_RUNS, + examples: loadSeeds("rtBigIntI64", reviveBigInt), + }, + ); + }); +}); + +describe("rtBigIntU64", () => { + it("is exact in [0, 2^64) and throws outside that range", () => { + fc.assert( + fc.property(bigIntArbI64, (b) => { + if (fitsBigIntU64(b)) return mod.rtBigIntU64(b) === b; + + try { + mod.rtBigIntU64(b); + return false; + } catch { + return true; + } + }), + { + numRuns: FUZZ_RUNS, + examples: loadSeeds("rtBigIntU64", reviveBigInt), + }, + ); + }); +}); + +describe("losslessI64", () => { + it("lossless ⇔ b ∈ [-2^63, 2^63) and value matches asIntN", () => { + fc.assert( + fc.property(bigIntArbI64, (b) => { + const { value, lossless } = mod.losslessI64(b); + const expected = oracleLosslessI64(b); + return value === expected.value && lossless === expected.lossless; + }), + { + numRuns: FUZZ_RUNS, + examples: loadSeeds("losslessI64", reviveBigInt), + }, + ); + }); +}); + +describe("losslessU64", () => { + it("lossless ⇔ b ∈ [0, 2^64) and value matches asUintN", () => { + fc.assert( + fc.property(bigIntArbI64, (b) => { + const { value, lossless } = mod.losslessU64(b); + const expected = oracleLosslessU64(b); + return value === expected.value && lossless === expected.lossless; + }), + { + numRuns: FUZZ_RUNS, + examples: loadSeeds("losslessU64", reviveBigInt), + }, + ); + }); +}); + +const bigIntArbI128 = fc.oneof( + { arbitrary: fc.bigInt({ min: -(2n ** 129n), max: 2n ** 129n }), weight: 4 }, + { arbitrary: fc.constantFrom(...edgeBigInts), weight: 1 }, +); + +describe("rtBigIntI128", () => { + it("is exact in [-2^127, 2^127) and throws outside that range", () => { + fc.assert( + fc.property(bigIntArbI128, (b) => { + if (fitsBigIntI128(b)) return mod.rtBigIntI128(b) === oracleBigIntI128(b); + + try { + mod.rtBigIntI128(b); + return false; + } catch { + return true; + } + }), + { + numRuns: FUZZ_RUNS, + examples: loadSeeds("rtBigIntI128", reviveBigInt), + }, + ); + }); +}); + +describe("rtBigIntI128LowBits", () => { + it("matches BigInt.asIntN(128, ·)", () => { + fc.assert( + fc.property( + bigIntArbI128, + (b) => mod.rtBigIntI128LowBits(b) === oracleBigIntI128LowBits(b), + ), + { + numRuns: FUZZ_RUNS, + examples: loadSeeds("rtBigIntI128LowBits", reviveBigInt), + }, + ); + }); +}); + +const bigIntArbWords = fc.oneof( + // Keep within the addon's 64-word cap (4096 bits). + { + arbitrary: fc.bigInt({ min: -(2n ** 4000n), max: 2n ** 4000n }), + weight: 4, + }, + { arbitrary: fc.constantFrom(...edgeBigInts), weight: 1 }, +); + +describe("rtBigIntWords", () => { + it("is identity for any BigInt under the word-buffer cap", () => { + fc.assert( + fc.property(bigIntArbWords, (b) => mod.rtBigIntWords(b) === b), + { + numRuns: FUZZ_RUNS, + examples: loadSeeds("rtBigIntWords", reviveBigInt), + }, + ); + }); +}); diff --git a/tests/fuzz/mod.zig b/tests/fuzz/mod.zig new file mode 100644 index 0000000..aebe211 --- /dev/null +++ b/tests/fuzz/mod.zig @@ -0,0 +1,115 @@ +//! Fuzz harness addon: per-converter round-trip exports for numeric types. + +const std = @import("std"); +const js = @import("zapi").js; + +/// Round-trip JS number → f64 → JS number. Oracle: identity for all finite +/// numbers, NaN ↔ NaN, ±0 preserved. +pub fn rtNumberF64(n: js.Number) !js.Number { + return js.Number.from(try n.toF64()); +} + +/// Round-trip via ToInt32 (`value | 0` semantics). +pub fn rtNumberI32(n: js.Number) !js.Number { + return js.Number.from(try n.toI32()); +} + +/// Round-trip via ToUint32 (`value >>> 0` semantics). +pub fn rtNumberU32(n: js.Number) !js.Number { + return js.Number.from(try n.toU32()); +} + +/// Round-trip via NAPI int64. Returns a JS BigInt so the result is lossless +/// in JS (a JS number cannot represent all of i64 exactly). +pub fn rtNumberI64(n: js.Number) !js.BigInt { + return js.BigInt.from(try n.toI64()); +} + +/// Exact round-trip via i64. Throws for out-of-range inputs. +pub fn rtBigIntI64(b: js.BigInt) !js.BigInt { + return js.BigInt.from(try b.toI64()); +} + +/// Exact round-trip via u64. Throws for negative or out-of-range inputs. +pub fn rtBigIntU64(b: js.BigInt) !js.BigInt { + return js.BigInt.from(try b.toU64()); +} + +/// Returns `{ value: BigInt, lossless: Boolean }` exposing the lossy low-bits +/// conversion flag to the fuzzer. +pub fn losslessI64(b: js.BigInt) !js.Value { + var lossless: bool = false; + const v = try b.toI64LowBits(&lossless); + const value = js.BigInt.from(v); + const flag = js.Boolean.from(lossless); + const obj = try js.env().createObject(); + try obj.setNamedProperty("value", value.toValue()); + try obj.setNamedProperty("lossless", flag.toValue()); + return .{ .val = obj }; +} + +/// Returns `{ value: BigInt, lossless: Boolean }` for the u64 low-bits path. +pub fn losslessU64(b: js.BigInt) !js.Value { + var lossless: bool = false; + const v = try b.toU64LowBits(&lossless); + const value = js.BigInt.from(v); + const flag = js.Boolean.from(lossless); + const obj = try js.env().createObject(); + try obj.setNamedProperty("value", value.toValue()); + try obj.setNamedProperty("lossless", flag.toValue()); + return .{ .val = obj }; +} + +fn i128ToBigInt(v: i128) !js.BigInt { + const is_negative = v < 0; + const magnitude: u128 = if (is_negative) + @as(u128, @intCast(-(v + 1))) + 1 // safe for i128.minInt + else + @as(u128, @intCast(v)); + const words = [_]u64{ + @truncate(magnitude), + @truncate(magnitude >> 64), + }; + return js.BigInt.fromWords(if (is_negative) 1 else 0, &words); +} + +/// Round-trip JS BigInt → i128 → JS BigInt via fromWords. +/// +/// In-domain (b ∈ [-2^127, 2^127)) this is identity. Out-of-domain values +/// throw instead of silently dropping high bits. +pub fn rtBigIntI128(b: js.BigInt) !js.BigInt { + return i128ToBigInt(try b.toI128()); +} + +/// Round-trip JS BigInt → low 128 bits → JS BigInt. +/// +/// Oracle: `BigInt.asIntN(128, b)`. +pub fn rtBigIntI128LowBits(b: js.BigInt) !js.BigInt { + return i128ToBigInt(try b.toI128LowBits()); +} + +/// Round-trip via getValueBigintWords → createBigintWords (via fromWords). +/// Identity for any BigInt that fits in the addon's word buffer (64 words = +/// 4096 bits is the practical cap). +/// +/// Implementation notes: +/// - We pass a 64-word buffer to `getValueBigintWords`. The `src/Value.zig` +/// wrapper now clamps the returned slice to `@min(word_count, buffer.len)`, +/// so oversized BigInts silently truncate. The 64-word cap covers all +/// entries in `edgeBigInts` (the largest, `1n << 256n`, is 5 words). +/// - Sign bit and the populated word slice are forwarded to `fromWords`. +pub fn rtBigIntWords(b: js.BigInt) !js.BigInt { + var sign_bit: u1 = 0; + var buf: [64]u64 = @splat(0); + const slice = try b.toValue().getValueBigintWords(&sign_bit, &buf); + return js.BigInt.fromWords(sign_bit, slice); +} + +/// Round-trip JS Uint8Array → []u8 → JS Uint8Array. +pub fn rtUint8Array(value: js.Uint8Array) !js.Uint8Array { + return js.Uint8Array.from(try value.toSlice()); +} + +comptime { + js.exportModule(@This(), .{}); +} diff --git a/tests/fuzz/number.fuzz.test.ts b/tests/fuzz/number.fuzz.test.ts new file mode 100644 index 0000000..bc8cba0 --- /dev/null +++ b/tests/fuzz/number.fuzz.test.ts @@ -0,0 +1,77 @@ +import { describe, it } from "vitest"; +import fc from "fast-check"; +import { edgeNumbers } from "../utils/edge.ts"; +import { + oracleNumberF64, + oracleNumberI32, + oracleNumberI64, + oracleNumberU32, +} from "../utils/oracles.ts"; +import { FUZZ_RUNS, loadSeeds, mod } from "../utils/support.ts"; + +const numberArb = fc.oneof( + { arbitrary: fc.double(), weight: 4 }, + { arbitrary: fc.constantFrom(...edgeNumbers), weight: 1 }, +); + +describe("rtNumberF64", () => { + it("round-trip is identity for all JS numbers", () => { + fc.assert( + fc.property(numberArb, (n) => { + const result = mod.rtNumberF64(n); + const expected = oracleNumberF64(n); + if (Number.isNaN(expected)) return Number.isNaN(result); + return Object.is(result, expected); + }), + { + numRuns: FUZZ_RUNS, + examples: loadSeeds("rtNumberF64", (raw) => raw as number), + }, + ); + }); +}); + +const numberIntArb = fc.oneof( + { arbitrary: fc.integer({ min: -(2 ** 33), max: 2 ** 33 }), weight: 3 }, + { arbitrary: fc.double(), weight: 2 }, + { arbitrary: fc.constantFrom(...edgeNumbers), weight: 1 }, +); + +describe("rtNumberI32", () => { + it("matches ECMAScript ToInt32 (`| 0`)", () => { + fc.assert( + fc.property(numberIntArb, (n) => mod.rtNumberI32(n) === oracleNumberI32(n)), + { + numRuns: FUZZ_RUNS, + examples: loadSeeds("rtNumberI32", (r) => r as number), + }, + ); + }); +}); + +describe("rtNumberU32", () => { + it("matches ECMAScript ToUint32 (`>>> 0`)", () => { + fc.assert( + fc.property(numberIntArb, (n) => mod.rtNumberU32(n) === oracleNumberU32(n)), + { + numRuns: FUZZ_RUNS, + examples: loadSeeds("rtNumberU32", (r) => r as number), + }, + ); + }); +}); + +describe("rtNumberI64", () => { + it("matches NAPI int64 semantics (clamped)", () => { + fc.assert( + fc.property( + numberIntArb, + (n) => mod.rtNumberI64(n) === oracleNumberI64(n), + ), + { + numRuns: FUZZ_RUNS, + examples: loadSeeds("rtNumberI64", (r) => r as number), + }, + ); + }); +}); diff --git a/tests/fuzz/oracle.test.ts b/tests/fuzz/oracle.test.ts new file mode 100644 index 0000000..9f81852 --- /dev/null +++ b/tests/fuzz/oracle.test.ts @@ -0,0 +1,174 @@ +import { describe, it, expect } from "vitest"; +import { edgeNumbers, edgeBigInts, edgeUint8Arrays } from "../utils/edge.ts"; +import { + equalUint8Array, + fitsBigIntI128, + fitsBigIntI64, + fitsBigIntU64, + oracleBigIntI128, + oracleBigIntI128LowBits, + oracleLosslessI64, + oracleLosslessU64, + oracleNumberF64, + oracleNumberI32, + oracleNumberI64, + oracleNumberU32, + oracleUint8Array, +} from "../utils/oracles.ts"; +import { mod } from "../utils/support.ts"; + +function describeValue(v: number): string { + if (Number.isNaN(v)) return "NaN"; + if (Object.is(v, -0)) return "-0"; + return String(v); +} + +describe("oracle sanity: rtNumberF64", () => { + for (const v of edgeNumbers) { + it(`agrees with oracle on ${describeValue(v)}`, () => { + const expected = oracleNumberF64(v); + const actual = mod.rtNumberF64(v); + if (Number.isNaN(expected)) { + expect(Number.isNaN(actual)).toBe(true); + } else { + expect(Object.is(actual, expected)).toBe(true); + } + }); + } +}); + +describe("oracle sanity: rtNumberI32", () => { + for (const v of edgeNumbers) { + it(`agrees with oracle on ${describeValue(v)}`, () => { + expect(mod.rtNumberI32(v)).toBe(oracleNumberI32(v)); + }); + } +}); + +describe("oracle sanity: rtNumberU32", () => { + for (const v of edgeNumbers) { + it(`agrees with oracle on ${describeValue(v)}`, () => { + expect(mod.rtNumberU32(v)).toBe(oracleNumberU32(v)); + }); + } +}); + +describe("oracle sanity: rtNumberI64", () => { + for (const v of edgeNumbers) { + it(`agrees with oracle on ${describeValue(v)}`, () => { + expect(mod.rtNumberI64(v)).toBe(oracleNumberI64(v)); + }); + } +}); + +describe("oracle sanity: rtBigIntI64", () => { + for (const b of edgeBigInts) { + it(`is exact-or-throw on ${b}n`, () => { + if (fitsBigIntI64(b)) { + expect(mod.rtBigIntI64(b)).toBe(b); + } else { + expect(() => mod.rtBigIntI64(b)).toThrow(); + } + }); + } +}); + +describe("oracle sanity: rtBigIntU64", () => { + for (const b of edgeBigInts) { + it(`is exact-or-throw on ${b}n`, () => { + if (fitsBigIntU64(b)) { + expect(mod.rtBigIntU64(b)).toBe(b); + } else { + expect(() => mod.rtBigIntU64(b)).toThrow(); + } + }); + } +}); + +describe("oracle sanity: losslessI64", () => { + for (const b of edgeBigInts) { + it(`agrees with oracle on ${b}n`, () => { + expect(mod.losslessI64(b)).toEqual(oracleLosslessI64(b)); + }); + } +}); + +describe("oracle sanity: losslessU64", () => { + for (const b of edgeBigInts) { + it(`agrees with oracle on ${b}n`, () => { + expect(mod.losslessU64(b)).toEqual(oracleLosslessU64(b)); + }); + } +}); + +describe("oracle sanity: rtBigIntI128", () => { + for (const b of edgeBigInts) { + it(`is exact-or-throw on ${b}n`, () => { + if (fitsBigIntI128(b)) { + expect(mod.rtBigIntI128(b)).toBe(oracleBigIntI128(b)); + } else { + expect(() => mod.rtBigIntI128(b)).toThrow(); + } + }); + } +}); + +describe("rtBigIntI128 boundary cases", () => { + it("0n → 0n (zero)", () => { + expect(mod.rtBigIntI128(0n)).toBe(0n); + }); + + it("I128_MIN = -(1n << 127n) → -(1n << 127n) (in-range lower bound)", () => { + const b = -(1n << 127n); + expect(mod.rtBigIntI128(b)).toBe(b); + }); + + it("I128_MAX = (1n << 127n) - 1n → (1n << 127n) - 1n (in-range upper bound)", () => { + const b = (1n << 127n) - 1n; + expect(mod.rtBigIntI128(b)).toBe(b); + }); + + it("1n << 127n (just out-of-range positive) throws", () => { + const b = 1n << 127n; + expect(() => mod.rtBigIntI128(b)).toThrow(); + }); + + it("-(1n << 127n) - 1n (just out-of-range negative) throws", () => { + const b = -(1n << 127n) - 1n; + expect(() => mod.rtBigIntI128(b)).toThrow(); + }); + + it("1n << 128n (oversized positive) throws", () => { + expect(() => mod.rtBigIntI128(1n << 128n)).toThrow(); + }); + + it("-(1n << 128n) (oversized negative) throws", () => { + expect(() => mod.rtBigIntI128(-(1n << 128n))).toThrow(); + }); +}); + +describe("oracle sanity: rtBigIntI128LowBits", () => { + for (const b of edgeBigInts) { + it(`agrees with low-bits oracle on ${b}n`, () => { + expect(mod.rtBigIntI128LowBits(b)).toBe(oracleBigIntI128LowBits(b)); + }); + } +}); + +describe("oracle sanity: rtBigIntWords", () => { + for (const b of edgeBigInts) { + it(`round-trips ${b}n`, () => { + expect(mod.rtBigIntWords(b)).toBe(b); + }); + } +}); + +describe("oracle sanity: rtUint8Array", () => { + for (const value of edgeUint8Arrays) { + it(`round-trips ${value.length} byte(s)`, () => { + expect(equalUint8Array(mod.rtUint8Array(value), oracleUint8Array(value))).toBe( + true, + ); + }); + } +}); diff --git a/tests/fuzz/seeds/.gitkeep b/tests/fuzz/seeds/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/tests/fuzz/uint8array.fuzz.test.ts b/tests/fuzz/uint8array.fuzz.test.ts new file mode 100644 index 0000000..23909c9 --- /dev/null +++ b/tests/fuzz/uint8array.fuzz.test.ts @@ -0,0 +1,29 @@ +import { describe, it } from "vitest"; +import fc from "fast-check"; +import { edgeUint8Arrays } from "../utils/edge.ts"; +import { equalUint8Array, oracleUint8Array } from "../utils/oracles.ts"; +import { + FUZZ_RUNS, + loadSeeds, + mod, + reviveUint8Array, +} from "../utils/support.ts"; + +const uint8ArrayArb = fc.oneof( + { arbitrary: fc.uint8Array({ maxLength: 4096 }), weight: 4 }, + { arbitrary: fc.constantFrom(...edgeUint8Arrays), weight: 1 }, +); + +describe("rtUint8Array", () => { + it("round-trips bytes unchanged", () => { + fc.assert( + fc.property(uint8ArrayArb, (value) => + equalUint8Array(mod.rtUint8Array(value), oracleUint8Array(value)), + ), + { + numRuns: FUZZ_RUNS, + examples: loadSeeds("rtUint8Array", reviveUint8Array), + }, + ); + }); +}); diff --git a/tests/utils/edge.ts b/tests/utils/edge.ts new file mode 100644 index 0000000..105cb70 --- /dev/null +++ b/tests/utils/edge.ts @@ -0,0 +1,60 @@ +/** + * Hand-curated edge values that any decent numeric converter should handle. + * Mixed into fast-check generators via fc.constantFrom(...). + * + * BigInt list is added incrementally as BigInt-targeting tasks land. + */ + +export const edgeNumbers: readonly number[] = [ + 0, + -0, + NaN, + Infinity, + -Infinity, + Number.MIN_VALUE, + -Number.MIN_VALUE, + Number.MAX_SAFE_INTEGER, + -Number.MAX_SAFE_INTEGER, + 2 ** 31, + -(2 ** 31), + 2 ** 31 - 1, + -(2 ** 31) - 1, + 2 ** 32, + 2 ** 32 - 1, + 2 ** 53, + 2 ** 53 + 1, + 2 ** 63, + -(2 ** 63), +]; + +export const edgeBigInts: readonly bigint[] = [ + 0n, + 1n, + -1n, + 1n << 63n, + -(1n << 63n), + (1n << 63n) - 1n, + -((1n << 63n) - 1n), + 1n << 64n, + (1n << 64n) - 1n, + -(1n << 64n), + // i128 boundary + (1n << 127n) - 1n, + -(1n << 127n), + -((1n << 127n) - 1n), + // multi-word (beyond i128) + (1n << 128n) - 1n, + -((1n << 128n) - 1n), + 1n << 128n, + 1n << 191n, + (1n << 192n) - 1n, + 1n << 256n, +]; + +export const edgeUint8Arrays: readonly Uint8Array[] = [ + new Uint8Array([]), + new Uint8Array([0]), + new Uint8Array([255]), + new Uint8Array([0, 255, 1, 254]), + new Uint8Array(Array.from({ length: 256 }, (_, i) => i)), +]; diff --git a/tests/utils/oracles.ts b/tests/utils/oracles.ts new file mode 100644 index 0000000..7fa64c3 --- /dev/null +++ b/tests/utils/oracles.ts @@ -0,0 +1,86 @@ +/** + * Shared JS-side reference transforms for numeric fuzz targets. + * + * These are intentionally small and spec-shaped: the properties and oracle + * sanity tests should import the same functions so they cannot drift. + */ + +export const I64_MAX = (1n << 63n) - 1n; +export const I64_MIN = -(1n << 63n); +export const I128_MIN = -(1n << 127n); +export const I128_MAX = (1n << 127n) - 1n; + +export function oracleNumberF64(value: number): number { + return value; +} + +export function oracleNumberI32(value: number): number { + return value | 0; +} + +export function oracleNumberU32(value: number): number { + return value >>> 0; +} + +export function oracleNumberI64(value: number): bigint { + if (Number.isNaN(value) || !Number.isFinite(value)) return 0n; + if (value >= 2 ** 63) return I64_MAX; + if (value < -(2 ** 63)) return I64_MIN; + return BigInt(Math.trunc(value)); +} + +export function oracleBigIntI64(value: bigint): bigint { + return BigInt.asIntN(64, value); +} + +export function fitsBigIntI64(value: bigint): boolean { + return value >= I64_MIN && value <= I64_MAX; +} + +export function oracleBigIntU64(value: bigint): bigint { + return BigInt.asUintN(64, value); +} + +export function fitsBigIntU64(value: bigint): boolean { + return value >= 0n && value < 1n << 64n; +} + +export function oracleLosslessI64(value: bigint): { + value: bigint; + lossless: boolean; +} { + const lossless = fitsBigIntI64(value); + return { value: oracleBigIntI64(value), lossless }; +} + +export function oracleLosslessU64(value: bigint): { + value: bigint; + lossless: boolean; +} { + const lossless = fitsBigIntU64(value); + return { value: oracleBigIntU64(value), lossless }; +} + +export function fitsBigIntI128(value: bigint): boolean { + return value >= I128_MIN && value <= I128_MAX; +} + +export function oracleBigIntI128(value: bigint): bigint { + return value; +} + +export function oracleBigIntI128LowBits(value: bigint): bigint { + return BigInt.asIntN(128, value); +} + +export function oracleUint8Array(value: Uint8Array): Uint8Array { + return new Uint8Array(value); +} + +export function equalUint8Array(a: Uint8Array, b: Uint8Array): boolean { + if (a.length !== b.length) return false; + for (let i = 0; i < a.length; i += 1) { + if (a[i] !== b[i]) return false; + } + return true; +} diff --git a/tests/utils/support.ts b/tests/utils/support.ts new file mode 100644 index 0000000..6d4827a --- /dev/null +++ b/tests/utils/support.ts @@ -0,0 +1,54 @@ +import { createRequire } from "node:module"; +import * as fs from "node:fs"; +import * as path from "node:path"; +import * as url from "node:url"; + +export type FuzzAddon = { + rtNumberF64(n: number): number; + rtNumberI32(n: number): number; + rtNumberU32(n: number): number; + rtNumberI64(n: number): bigint; + rtBigIntI64(b: bigint): bigint; + rtBigIntU64(b: bigint): bigint; + losslessI64(b: bigint): { value: bigint; lossless: boolean }; + losslessU64(b: bigint): { value: bigint; lossless: boolean }; + rtBigIntI128(b: bigint): bigint; + rtBigIntI128LowBits(b: bigint): bigint; + rtBigIntWords(b: bigint): bigint; + rtUint8Array(value: Uint8Array): Uint8Array; +}; + +const require = createRequire(import.meta.url); + +export const mod = require("../../zig-out/lib/test_fuzz_numeric.node") as FuzzAddon; +export const FUZZ_RUNS = Number(process.env.FUZZ_RUNS ?? 10_000); + +const __dirname = path.dirname(url.fileURLToPath(import.meta.url)); +const seedsDir = path.join(__dirname, "../fuzz/seeds"); + +/** + * Load persisted regression cases for a target. + * + * Each file under tests/fuzz/seeds/ is a JSON array of values. + * Missing file -> empty examples list; not an error. + */ +export function loadSeeds(target: string, revive: (raw: unknown) => T): T[] { + const file = path.join(seedsDir, `${target}.json`); + if (!fs.existsSync(file)) return []; + const raw = JSON.parse(fs.readFileSync(file, "utf8")) as unknown[]; + return raw.map(revive); +} + +export function reviveBigInt(raw: unknown): bigint { + if (typeof raw === "object" && raw !== null && "__bigint" in raw) { + return BigInt((raw as { __bigint: string }).__bigint); + } + throw new Error(`Cannot revive as bigint: ${JSON.stringify(raw)}`); +} + +export function reviveUint8Array(raw: unknown): Uint8Array { + if (Array.isArray(raw) && raw.every((v) => Number.isInteger(v))) { + return new Uint8Array(raw); + } + throw new Error(`Cannot revive as Uint8Array: ${JSON.stringify(raw)}`); +}