tinyspy 4.0.4: spy

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 pkg:npm/tinyspy@4.0.4
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/tinyspy@4.0.4
Demonstrate these symbols/APIs:
  - spy

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:ea5a8e1f4f116aa0e37069e433602eb64ad9c9434dad5636ef0fe2ed5fc73e01","contract":["spy wraps a function and records calls, arguments, and return values","spy tracks callCount and called state accurately across multiple invocations","spy captures thrown errors in results array when wrapped implementation fails","spy nextResult overrides return value for a single subsequent call","spy reset clears recorded calls, results, and invocation count"],"goal":"verify pkg:npm/tinyspy@4.0.4","kind":"HOW","packages":["pkg:npm/tinyspy@4.0.4"],"schemaVersion":1,"symbols":["spy"]},"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/tinyspy@4.0.4"],"schemaVersion":1,"subject":"pkg:npm/tinyspy@4.0.4","symbols":["spy"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-tinyspy-spy",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-tinyspy-spy",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "tinyspy": "4.0.4"
      }
    },
    "node_modules/tinyspy": {
      "version": "4.0.4",
      "resolved": "https://registry.npmjs.org/tinyspy/-/tinyspy-4.0.4.tgz",
      "integrity": "sha512-azl+t0z7pw/z958Gy9svOTuzqIk6xq+NSheJzn5MMWtWTFywIacg2wUlzKFGtt3cthx0r2SxMK0yzJOR0IES7Q==",
      "license": "MIT",
      "engines": {
        "node": ">=14.0.0"
      }
    }
  }
}

{
  "name": "sample-tinyspy-spy",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "description": "Clean-room verification for spy in tinyspy@4.0.4",
  "main": "test/contract.mjs",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "tinyspy": "4.0.4"
  },
  "license": "MIT-0"
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/tinyspy@4.0.4",
  "kind": "HOW",
  "packages": [
    "pkg:npm/tinyspy@4.0.4"
  ],
  "symbols": [
    "spy"
  ]
}

import assert from "node:assert";
import { spy } from "tinyspy";

async function runContract() {
  // 1. Basic wrapping, call recording, and return values
  const add = (a, b) => a + b;
  const fn = spy(add);

  assert.strictEqual(fn.called, false, "spy.called should initially be false");
  assert.strictEqual(fn.callCount, 0, "spy.callCount should initially be 0");
  assert.deepStrictEqual(fn.calls, [], "spy.calls should initially be empty");

  const result1 = fn(2, 3);
  assert.strictEqual(result1, 5, "spy should return implementation result");
  assert.strictEqual(fn.called, true, "spy.called should be true after invocation");
  assert.strictEqual(fn.callCount, 1, "spy.callCount should be 1 after one invocation");
  assert.deepStrictEqual(fn.calls, [[2, 3]], "spy.calls should record passed arguments");
  assert.deepStrictEqual(fn.returns, [5], "spy.returns should record return values");
  assert.deepStrictEqual(fn.results, [["ok", 5]], "spy.results should record ok tuple");

  // 2. Multiple invocations tracking
  const result2 = fn(10, 20);
  assert.strictEqual(result2, 30, "spy should return second invocation result");
  assert.strictEqual(fn.callCount, 2, "spy.callCount should be 2 after two invocations");
  assert.deepStrictEqual(fn.calls, [[2, 3], [10, 20]], "spy.calls should record all invocation arguments");
  assert.deepStrictEqual(fn.returns, [5, 30], "spy.returns should record all return values");

  // 3. Error capturing in results array
  const failingFn = spy((msg) => {
    throw new Error(msg);
  });
  assert.throws(() => failingFn("boom"), /boom/, "spy should propagate thrown error");
  assert.strictEqual(failingFn.called, true, "failingFn.called should be true");
  assert.strictEqual(failingFn.callCount, 1, "failingFn.callCount should be 1");
  assert.strictEqual(failingFn.results.length, 1, "failingFn.results should record one result");
  assert.strictEqual(failingFn.results[0][0], "error", "failingFn.results status should be error");
  assert.strictEqual(failingFn.results[0][1].message, "boom", "failingFn.results should hold the error object");

  // 4. nextResult override
  const spyOverride = spy((x) => x * 2);
  spyOverride.nextResult(999);
  const overridden = spyOverride(5);
  assert.strictEqual(overridden, 999, "spy.nextResult should override return value for single call");
  const regular = spyOverride(5);
  assert.strictEqual(regular, 10, "spy should resume original implementation after nextResult");

  // 5. Reset clears recorded state
  fn.reset();
  assert.strictEqual(fn.called, false, "spy.called should be false after reset");
  assert.strictEqual(fn.callCount, 0, "spy.callCount should be 0 after reset");
  assert.deepStrictEqual(fn.calls, [], "spy.calls should be empty after reset");
  assert.deepStrictEqual(fn.returns, [], "spy.returns should be empty after reset");
  assert.deepStrictEqual(fn.results, [], "spy.results should be empty after reset");

  console.log("Contract assertions verified successfully.");
}

runContract().catch((err) => {
  console.error("Contract test failed:", err);
  process.exit(1);
});