bare-buffer 3.7.0: Buffer.prototype.readInt32LE

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify Buffer.prototype.readInt32LE in pkg:npm/bare-buffer@3.7.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/bare-buffer@3.7.0
Demonstrate these symbols/APIs:
  - Buffer.prototype.readInt32LE

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:7e9da63552cf55bba38021f22bd58359bde233c5b1f203fadacbcfc46b67528c","contract":["package manifest specifies Bare addon configuration, Bare engine \u003e=1.20.0, and exports for root, global, constants, and package subpaths","declares readInt32LE(offset?: number): number in index.d.ts","Buffer.prototype.readInt32LE reads signed 32-bit integers in little-endian byte order with default offset 0","Buffer.prototype.readInt32LE correctly decodes negative numbers in two's complement, MIN_INT32 (-2147483648), and MAX_INT32 (2147483647)","Buffer.prototype.readInt32LE reads 32-bit signed integers at arbitrary byte offsets","Buffer.prototype.readInt32LE throws RangeError when offset is out of bounds or buffer is shorter than 4 bytes","Buffer.prototype.readInt32LE throws TypeError when offset is not a number"],"goal":"verify Buffer.prototype.readInt32LE in pkg:npm/bare-buffer@3.7.0","kind":"HOW","packages":["pkg:npm/bare-buffer@3.7.0"],"schemaVersion":1,"symbols":["Buffer.prototype.readInt32LE"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/bare-buffer@3.7.0"],"schemaVersion":1,"subject":"pkg:npm/bare-buffer@3.7.0","symbols":["Buffer.prototype.readInt32LE"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-bare-buffer",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-bare-buffer",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "bare-buffer": "3.7.0"
      }
    },
    "node_modules/bare-buffer": {
      "version": "3.7.0",
      "resolved": "https://registry.npmjs.org/bare-buffer/-/bare-buffer-3.7.0.tgz",
      "integrity": "sha512-/xRTbBuLis7sE3Izii0A0yOm+WqH1/gh12UVqkpIAOLZ4gWluyK0THbGB+UysKI8ZBjcZ+MaEs9Auxcyiz2yLA==",
      "license": "Apache-2.0",
      "engines": {
        "bare": ">=1.20.0"
      }
    }
  }
}

{
  "name": "sample-bare-buffer",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "license": "MIT-0",
  "dependencies": {
    "bare-buffer": "3.7.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify Buffer.prototype.readInt32LE in pkg:npm/bare-buffer@3.7.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/bare-buffer@3.7.0"
  ],
  "symbols": [
    "Buffer.prototype.readInt32LE"
  ]
}

import assert from 'node:assert/strict';
import { createRequire } from 'node:module';
import fs from 'node:fs';
import path from 'node:path';

const require = createRequire(import.meta.url);

// 1. Resolve bare-buffer package manifest and verify exports and metadata
const pkgPath = require.resolve('bare-buffer/package');
const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));

assert.equal(pkg.name, 'bare-buffer', 'Package name must be bare-buffer');
assert.equal(pkg.version, '3.7.0', 'Package version must be 3.7.0');
assert.equal(pkg.license, 'Apache-2.0', 'Package license must be Apache-2.0');
assert.equal(pkg.addon, true, 'Package must be marked as addon');
assert.equal(pkg.engines?.bare, '>=1.20.0', 'Package must specify Bare engine >=1.20.0');

assert.ok(pkg.exports, 'Package must define exports');
assert.equal(pkg.exports['.'].types, './index.d.ts', 'Root export must define index.d.ts types');
assert.equal(pkg.exports['.'].default, './index.js', 'Root export must define index.js default');
assert.equal(pkg.exports['./global'].types, './global.d.ts', 'Global export must define global.d.ts types');
assert.equal(pkg.exports['./global'].default, './global.js', 'Global export must define global.js default');
assert.equal(pkg.exports['./constants'].types, './lib/constants.d.ts', 'Constants export must define constants.d.ts types');
assert.equal(pkg.exports['./constants'].default, './lib/constants.js', 'Constants export must define constants.js default');
assert.equal(pkg.exports['./package'], './package.json', 'Package export must point to package.json');

const pkgDir = path.dirname(pkgPath);
const indexDts = fs.readFileSync(path.join(pkgDir, 'index.d.ts'), 'utf8');

// 2. Verify TypeScript declaration for Buffer.prototype.readInt32LE
assert.ok(indexDts.includes('readInt32LE(offset?: number): number'), 'index.d.ts must declare readInt32LE method');

// 3. Mock Bare native binding to test Buffer.prototype.readInt32LE implementation
const bindingPath = path.join(pkgDir, 'binding.js');
require.cache[bindingPath] = {
  id: bindingPath,
  filename: bindingPath,
  loaded: true,
  exports: {
    alloc(n) { return new ArrayBuffer(n); },
    allocUnsafe(n) { return new ArrayBuffer(n); },
    compare: () => 0,
    swap16: () => {},
    swap32: () => {},
    swap64: () => {},
    indexOf: () => -1,
    lastIndexOf: () => -1,
    constants: {
      MAX_LENGTH: 4294967296,
      MAX_STRING_LENGTH: 1073741799
    }
  }
};

const Buffer = require('bare-buffer');

assert.equal(typeof Buffer, 'function', 'bare-buffer must export Buffer class');
assert.equal(typeof Buffer.prototype.readInt32LE, 'function', 'Buffer.prototype.readInt32LE must be a function');

// 4. Test reading 32-bit signed integers in Little-Endian byte order
// Positive values (e.g. 0x12345678 in LE: [0x78, 0x56, 0x34, 0x12])
const buf1 = Buffer.from([0x78, 0x56, 0x34, 0x12]);
assert.equal(buf1.readInt32LE(0), 0x12345678, 'readInt32LE(0) reads 0x12345678');
assert.equal(buf1.readInt32LE(), 0x12345678, 'readInt32LE() defaults offset to 0');

// Negative values (e.g. -1 is 0xFFFFFFFF in 32-bit two\'s complement)
const bufNeg1 = Buffer.from([0xff, 0xff, 0xff, 0xff]);
assert.equal(bufNeg1.readInt32LE(0), -1, 'readInt32LE reads -1 for 0xFFFFFFFF');

// Signed range boundary tests (min int32: -2147483648 / 0x80000000, max int32: 2147483647 / 0x7FFFFFFF)
const bufMin = Buffer.from([0x00, 0x00, 0x00, 0x80]);
assert.equal(bufMin.readInt32LE(0), -2147483648, 'readInt32LE reads MIN_INT32 (-2147483648)');

const bufMax = Buffer.from([0xff, 0xff, 0xff, 0x7f]);
assert.equal(bufMax.readInt32LE(0), 2147483647, 'readInt32LE reads MAX_INT32 (2147483647)');

const bufZero = Buffer.from([0x00, 0x00, 0x00, 0x00]);
assert.equal(bufZero.readInt32LE(0), 0, 'readInt32LE reads 0 for all zero bytes');

// 5. Test reading with offset
const bufOffset = Buffer.from([0xaa, 0xbb, 0x78, 0x56, 0x34, 0x12, 0xcc]);
assert.equal(bufOffset.readInt32LE(2), 0x12345678, 'readInt32LE reads 32-bit int from given offset');

// 6. Test bounds and validation errors
assert.throws(
  () => buf1.readInt32LE(1),
  { name: 'RangeError', message: 'Offset is outside the bounds of the buffer' },
  'Throws RangeError when offset + 4 exceeds buffer length'
);

assert.throws(
  () => buf1.readInt32LE(-1),
  { name: 'RangeError', message: 'Offset is outside the bounds of the buffer' },
  'Throws RangeError when offset is negative'
);

assert.throws(
  () => buf1.readInt32LE('0'),
  { name: 'TypeError', message: 'Offset must be a number, received type string' },
  'Throws TypeError when offset is not a number'
);

const shortBuf = Buffer.from([0x01, 0x02, 0x03]);
assert.throws(
  () => shortBuf.readInt32LE(0),
  { name: 'RangeError', message: 'Offset is outside the bounds of the buffer' },
  'Throws RangeError on buffers smaller than 4 bytes'
);

console.log('Contract tests passed successfully.');