netmask 2.1.1: Parse IPv4 CIDR blocks and test IP containment and subnet iteration with Netmask

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: Parse IPv4 CIDR blocks and test IP containment and subnet iteration with Netmask
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/netmask@2.1.1
Demonstrate these symbols/APIs:
  - Netmask
  - Netmask.prototype.contains
  - Netmask.prototype.forEach

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:7cf2e0bae4f0e150ab90ee9aee5297bdef35570ce01dd5dc1213fc189d1a9eaf","contract":["Netmask constructor parses CIDR notation and calculates base, mask, bitmask, hostmask, broadcast, size, first, and last properties","Netmask constructor parses separate IP and netmask arguments correctly","Netmask.prototype.contains validates whether an IPv4 address is within the subnet","Netmask.prototype.contains validates whether a subnet block is entirely contained within another block","Netmask.prototype.forEach iterates through all usable host IP addresses with index and integer representation","Netmask.prototype.next navigates forward and backward to adjacent network blocks","Netmask.prototype.toString returns the canonical CIDR block string","Netmask constructor throws Error on invalid IP address or netmask format"],"goal":"Parse IPv4 CIDR blocks and test IP containment and subnet iteration with Netmask","kind":"HOW","packages":["pkg:npm/netmask@2.1.1"],"schemaVersion":1,"symbols":["Netmask","Netmask.prototype.contains","Netmask.prototype.forEach"]},"contractCommand":["node","test/contract.cjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/netmask@2.1.1"],"schemaVersion":1,"subject":"pkg:npm/netmask@2.1.1","symbols":["Netmask","Netmask.prototype.contains","Netmask.prototype.forEach"],"verifierAdapter":"node-typescript@1"}

{
  "name": "netmask-sample",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "netmask-sample",
      "version": "1.0.0",
      "dependencies": {
        "netmask": "2.1.1"
      }
    },
    "node_modules/netmask": {
      "version": "2.1.1",
      "resolved": "https://registry.npmjs.org/netmask/-/netmask-2.1.1.tgz",
      "integrity": "sha512-eonl3sLUha+S1GzTPxychyhnUzKyeQkZ7jLjKrBagJgPla13F+uQ71HgpFefyHgqrjEbCPkDArxYsjY8/+gLKA==",
      "license": "MIT",
      "engines": {
        "node": ">= 0.4.0"
      }
    }
  }
}

{
  "name": "netmask-sample",
  "version": "1.0.0",
  "private": true,
  "description": "Verification sample for netmask 2.1.1",
  "dependencies": {
    "netmask": "2.1.1"
  }
}

{
  "schemaVersion": 1,
  "goal": "Parse IPv4 CIDR blocks and test IP containment and subnet iteration with Netmask",
  "kind": "HOW",
  "packages": [
    "pkg:npm/netmask@2.1.1"
  ],
  "symbols": [
    "Netmask",
    "Netmask.prototype.contains",
    "Netmask.prototype.forEach"
  ]
}

const assert = require("node:assert/strict");
const { Netmask } = require("netmask");

// 1. Netmask constructor parses CIDR notation and calculates base, mask, bitmask, hostmask, broadcast, size, first, and last properties
const block = new Netmask("192.168.1.0/24");
assert.equal(block.base, "192.168.1.0");
assert.equal(block.mask, "255.255.255.0");
assert.equal(block.bitmask, 24);
assert.equal(block.hostmask, "0.0.0.255");
assert.equal(block.broadcast, "192.168.1.255");
assert.equal(block.size, 256);
assert.equal(block.first, "192.168.1.1");
assert.equal(block.last, "192.168.1.254");

// 2. Netmask constructor parses separate IP and netmask arguments correctly
const blockWithMask = new Netmask("10.0.0.0", "255.255.0.0");
assert.equal(blockWithMask.base, "10.0.0.0");
assert.equal(blockWithMask.bitmask, 16);
assert.equal(blockWithMask.mask, "255.255.0.0");
assert.equal(blockWithMask.broadcast, "10.0.255.255");
assert.equal(blockWithMask.size, 65536);

// 3. Netmask.prototype.contains validates whether an IPv4 address is within the subnet
assert.equal(block.contains("192.168.1.1"), true);
assert.equal(block.contains("192.168.1.100"), true);
assert.equal(block.contains("192.168.1.254"), true);
assert.equal(block.contains("192.168.2.1"), false);
assert.equal(block.contains("10.0.0.1"), false);

// 4. Netmask.prototype.contains validates whether a subnet block is entirely contained within another block
const subBlock = new Netmask("192.168.1.64/26");
const outsideBlock = new Netmask("192.168.2.0/24");
const parentBlock = new Netmask("192.168.0.0/16");
assert.equal(block.contains(subBlock), true);
assert.equal(block.contains(outsideBlock), false);
assert.equal(block.contains(parentBlock), false);

// 5. Netmask.prototype.forEach iterates through all usable host IP addresses with index and integer representation
const smallBlock = new Netmask("172.16.0.0/29");
const visited = [];
smallBlock.forEach((ip, long, index) => {
  visited.push({ ip, index, isNumber: typeof long === "number" });
});

assert.equal(visited.length, 6);
assert.equal(visited[0].ip, "172.16.0.1");
assert.equal(visited[0].index, 0);
assert.equal(visited[0].isNumber, true);
assert.equal(visited[5].ip, "172.16.0.6");
assert.equal(visited[5].index, 5);

// 6. Netmask.prototype.next navigates forward and backward to adjacent network blocks
const nextBlock = block.next();
assert.equal(nextBlock.base, "192.168.2.0");
assert.equal(nextBlock.bitmask, 24);

const prevBlock = nextBlock.next(-1);
assert.equal(prevBlock.base, "192.168.1.0");
assert.equal(prevBlock.bitmask, 24);

// 7. Netmask.prototype.toString returns the canonical CIDR block string
assert.equal(block.toString(), "192.168.1.0/24");
assert.equal(smallBlock.toString(), "172.16.0.0/29");

// 8. Netmask constructor throws Error on invalid IP address or netmask format
assert.throws(
  () => new Netmask("999.999.999.999/24"),
  (err) => err instanceof Error && /Invalid/i.test(err.message)
);
assert.throws(
  () => new Netmask("192.168.1.0/35"),
  (err) => err instanceof Error && /Invalid/i.test(err.message)
);

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