semver-compare 1.0.0: compare semantic version strings

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: compare semantic version strings
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/semver-compare@1.0.0
Demonstrate these symbols/APIs:
  - semver-compare

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:e2ee1e3360120d9e62062c02325267ded59bd3c983f7b12416f1c88988d27eab","contract":["semver-compare exports a comparison function","returns 0 when two semantic versions are identical","returns 1 when the first version is greater than the second version","returns -1 when the first version is less than the second version","can be used as a comparator callback for Array.prototype.sort to sort semantic versions in ascending order"],"goal":"compare semantic version strings","kind":"HOW","packages":["pkg:npm/semver-compare@1.0.0"],"schemaVersion":1,"symbols":["semver-compare"]},"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/semver-compare@1.0.0"],"schemaVersion":1,"subject":"pkg:npm/semver-compare@1.0.0","symbols":["semver-compare"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-semver-compare",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-semver-compare",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "semver-compare": "1.0.0"
      }
    },
    "node_modules/semver-compare": {
      "version": "1.0.0",
      "resolved": "https://registry.npmjs.org/semver-compare/-/semver-compare-1.0.0.tgz",
      "integrity": "sha512-YM3/ITh2MJ5MtzaM429anh+x2jiLVjqILF4m4oyQB18W7Ggea7BfqdH/wGMK7dDiMghv/6WG7znWMwUDzJiXow==",
      "license": "MIT"
    }
  }
}

{
  "name": "sample-semver-compare",
  "version": "1.0.0",
  "private": true,
  "license": "MIT-0",
  "main": "src/index.js",
  "dependencies": {
    "semver-compare": "1.0.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "compare semantic version strings",
  "kind": "HOW",
  "packages": [
    "pkg:npm/semver-compare@1.0.0"
  ],
  "symbols": [
    "semver-compare"
  ]
}

const semverCompare = require('semver-compare');

/**
 * Compares two semantic version strings.
 *
 * @param {string} a - First semantic version string.
 * @param {string} b - Second semantic version string.
 * @returns {number} 1 if a > b, -1 if a < b, 0 if a == b.
 */
function compareVersions(a, b) {
  return semverCompare(a, b);
}

/**
 * Sorts an array of semantic version strings in ascending order.
 *
 * @param {string[]} versions - Array of version strings to sort.
 * @returns {string[]} A new sorted array of version strings.
 */
function sortVersions(versions) {
  return [...versions].sort(semverCompare);
}

module.exports = {
  semverCompare,
  compareVersions,
  sortVersions
};

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

const require = createRequire(import.meta.url);
const semverCompare = require('semver-compare');
const {
  semverCompare: exportedCmp,
  compareVersions,
  sortVersions
} = require('../src/index.js');

// 1. semver-compare exports a comparison function
assert.equal(typeof semverCompare, 'function', 'semver-compare must export a function');
assert.strictEqual(exportedCmp, semverCompare, 'src/index.js must export the semver-compare function');

// 2. returns 0 when two semantic versions are identical
assert.strictEqual(semverCompare('1.0.0', '1.0.0'), 0, 'identical major.minor.patch must return 0');
assert.strictEqual(semverCompare('2.3.4', '2.3.4'), 0, 'identical versions must return 0');
assert.strictEqual(compareVersions('0.0.1', '0.0.1'), 0, 'compareVersions helper must return 0 for equal versions');

// 3. returns 1 when first version is greater than second version
assert.strictEqual(semverCompare('2.0.0', '1.9.9'), 1, 'greater major must return 1');
assert.strictEqual(semverCompare('1.3.0', '1.2.9'), 1, 'greater minor must return 1');
assert.strictEqual(semverCompare('1.2.4', '1.2.3'), 1, 'greater patch must return 1');
assert.strictEqual(compareVersions('10.0.0', '2.0.0'), 1, 'numeric 10.0.0 must be greater than 2.0.0');

// 4. returns -1 when first version is less than second version
assert.strictEqual(semverCompare('1.0.0', '2.0.0'), -1, 'smaller major must return -1');
assert.strictEqual(semverCompare('1.2.0', '1.3.0'), -1, 'smaller minor must return -1');
assert.strictEqual(semverCompare('1.2.3', '1.2.4'), -1, 'smaller patch must return -1');
assert.strictEqual(compareVersions('2.0.0', '10.0.0'), -1, 'numeric 2.0.0 must be smaller than 10.0.0');

// 5. can be used as a comparator callback for Array.prototype.sort
const unsorted = [
  '1.2.3',
  '4.11.6',
  '4.2.0',
  '1.5.19',
  '1.5.5',
  '4.1.3',
  '2.3.1',
  '10.5.5',
  '11.3.0'
];

const sorted = sortVersions(unsorted);
assert.deepStrictEqual(
  sorted,
  [
    '1.2.3',
    '1.5.5',
    '1.5.19',
    '2.3.1',
    '4.1.3',
    '4.2.0',
    '4.11.6',
    '10.5.5',
    '11.3.0'
  ],
  'sortVersions must correctly sort semantic versions in ascending order'
);

console.log('Contract assertions passed.');