semver 5.7.2: satisfies

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 semver.satisfies in pkg:npm/semver@5.7.2
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/semver@5.7.2
Demonstrate these symbols/APIs:
  - semver.satisfies

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:0e44fe61f7437cea329c825c4191136e1aa572c1243f20234a359324bfb94063","contract":["assert semver.satisfies returns true when version matches caret and tilde ranges","assert semver.satisfies returns false when version does not satisfy comparison operators or range sets","assert semver.satisfies supports advanced range syntaxes including hyphens, wildcards, and logical OR unions","assert semver.satisfies excludes prerelease versions by default but includes them when includePrerelease option is true","assert semver.satisfies throws a TypeError when given an unparseable version string"],"goal":"verify semver.satisfies in pkg:npm/semver@5.7.2","kind":"HOW","packages":["pkg:npm/semver@5.7.2"],"schemaVersion":1,"symbols":["semver.satisfies"]},"contractCommand":["node","test/contract.js"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","os":"linux","osVersionBucket":"24","packageManager":"npm","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/semver@5.7.2"],"schemaVersion":1,"subject":"pkg:npm/semver@5.7.2","symbols":["semver.satisfies"],"verifierAdapter":"node-typescript@1"}

const semver = require('semver');

/**
 * Checks if a version satisfies a range.
 * @param {string} version
 * @param {string} range
 * @param {boolean|object} [options]
 * @returns {boolean}
 */
function isSatisfied(version, range, options) {
  return semver.satisfies(version, range, options);
}

/**
 * Filters a list of versions matching a given range.
 * @param {string[]} versions
 * @param {string} range
 * @param {boolean|object} [options]
 * @returns {string[]}
 */
function filterMatchingVersions(versions, range, options) {
  return versions.filter((v) => semver.satisfies(v, range, options));
}

module.exports = {
  isSatisfied,
  filterMatchingVersions,
};

{
  "name": "sample-semver-satisfies",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-semver-satisfies",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "semver": "5.7.2"
      }
    },
    "node_modules/semver": {
      "version": "5.7.2",
      "resolved": "https://registry.npmjs.org/semver/-/semver-5.7.2.tgz",
      "integrity": "sha512-cBznnQ9KjJqU67B52RMC65CMarK2600WFnbkcaiwWq3xy/5haFJlshgnpjovMVJ+Hff49d8GEn0b87C5pDQ10g==",
      "license": "ISC",
      "bin": {
        "semver": "bin/semver"
      }
    }
  }
}

{
  "name": "sample-semver-satisfies",
  "version": "1.0.0",
  "description": "Demonstrate semver.satisfies semantic version range matching",
  "main": "index.js",
  "scripts": {
    "test": "node test/contract.js"
  },
  "license": "MIT-0",
  "dependencies": {
    "semver": "5.7.2"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify semver.satisfies in pkg:npm/semver@5.7.2",
  "kind": "HOW",
  "packages": [
    "pkg:npm/semver@5.7.2"
  ],
  "symbols": [
    "semver.satisfies"
  ]
}

const assert = require('assert');
const semver = require('semver');
const { isSatisfied, filterMatchingVersions } = require('../index');

function runContractTests() {
  // 1. Caret and tilde ranges
  assert.strictEqual(semver.satisfies('1.2.3', '^1.2.0'), true, 'Version 1.2.3 should satisfy ^1.2.0');
  assert.strictEqual(isSatisfied('1.2.4', '~1.2.0'), true, 'Version 1.2.4 should satisfy ~1.2.0');
  assert.strictEqual(isSatisfied('0.2.3', '^0.2.0'), true, 'Version 0.2.3 should satisfy ^0.2.0');

  // 2. Out-of-range versions and comparison bounds
  assert.strictEqual(semver.satisfies('2.0.0', '^1.2.0'), false, 'Version 2.0.0 should not satisfy ^1.2.0');
  assert.strictEqual(isSatisfied('1.3.0', '~1.2.0'), false, 'Version 1.3.0 should not satisfy ~1.2.0');
  assert.strictEqual(isSatisfied('0.3.0', '^0.2.0'), false, 'Version 0.3.0 should not satisfy ^0.2.0');
  assert.strictEqual(isSatisfied('0.9.0', '>=1.0.0'), false, 'Version 0.9.0 should not satisfy >=1.0.0');

  // 3. Advanced range syntaxes: hyphens, wildcards, and logical OR unions
  assert.strictEqual(semver.satisfies('1.5.0', '1.2.3 - 2.3.4'), true, 'Version 1.5.0 should satisfy hyphen range 1.2.3 - 2.3.4');
  assert.strictEqual(isSatisfied('2.5.0', '1.2.3 - 2.3.4'), false, 'Version 2.5.0 should not satisfy hyphen range 1.2.3 - 2.3.4');
  assert.strictEqual(isSatisfied('1.2.9', '1.2.x'), true, 'Version 1.2.9 should satisfy wildcard 1.2.x');
  assert.strictEqual(isSatisfied('1.8.0', '*'), true, 'Version 1.8.0 should satisfy wildcard *');
  assert.strictEqual(isSatisfied('2.5.0', '<1.0.0 || >=2.0.0'), true, 'Version 2.5.0 should satisfy union <1.0.0 || >=2.0.0');
  assert.strictEqual(isSatisfied('1.5.0', '<1.0.0 || >=2.0.0'), false, 'Version 1.5.0 should not satisfy union <1.0.0 || >=2.0.0');

  const candidates = ['0.9.0', '1.2.0', '1.5.2', '2.0.1'];
  const matched = filterMatchingVersions(candidates, '>=1.0.0 <2.0.0');
  assert.deepStrictEqual(matched, ['1.2.0', '1.5.2'], 'filterMatchingVersions should filter versions satisfying the range');

  // 4. Prerelease behavior and includePrerelease option
  assert.strictEqual(
    semver.satisfies('1.2.3-alpha.1', '^1.2.0'),
    false,
    'Prerelease version should not satisfy range by default'
  );
  assert.strictEqual(
    semver.satisfies('1.2.3-alpha.1', '^1.2.0', { includePrerelease: true }),
    true,
    'Prerelease version within range should satisfy when includePrerelease is true'
  );
  assert.strictEqual(
    semver.satisfies('2.0.0-alpha.1', '^1.2.0', { includePrerelease: true }),
    true,
    'Prerelease 2.0.0-alpha.1 is < 2.0.0 and satisfies ^1.2.0 when includePrerelease is true'
  );
  assert.strictEqual(
    semver.satisfies('2.0.1-alpha.0', '^1.2.0', { includePrerelease: true }),
    false,
    'Prerelease 2.0.1-alpha.0 is >= 2.0.0 and does not satisfy ^1.2.0 even with includePrerelease'
  );
  assert.strictEqual(
    semver.satisfies('1.2.3-beta.2', '>=1.2.3-beta.1 <1.2.3-beta.3'),
    true,
    'Prerelease directly bounded in range should satisfy without options'
  );

  // 5. TypeError on unparseable version string
  assert.throws(
    () => {
      semver.satisfies('not-a-version', '^1.0.0');
    },
    {
      name: 'TypeError',
      message: 'Invalid Version: not-a-version',
    },
    'Invalid version string must throw a TypeError'
  );

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

runContractTests();