detect-libc 2.1.2: GLIBC, MUSL, family

# Notes on detect-libc Libc Compatibility Checking and Addon Resolution

## `search_known_solution` Result
- Prior samples tested basic API signature and migration traps (`detectLibc.family` as function vs property).
- This sample focuses on concrete libc version comparison without semver parsing crashes (since glibc versions like "2.39" are 2-part and break `semver.satisfies`), safe platform addon resolution, and async/sync parity.

## What a Naive Model Would Write
- A naive model passes `detectLibc.versionSync()` directly into semver comparison utilities, which throws invalid semver version errors on 2-part libc strings (e.g. `2.39`).
- A naive model accesses `detectLibc.isNonGlibcLinux` as a boolean property or calls `detectLibc.family()` without `await`, causing unhandled Promise comparisons.

## How the Wrong Version Fails
- In `detect-libc` v2, functions return Promises when using async methods. When resolving native binary addons synchronously, loaders must use `familySync()` and `versionSync()`. On non-Linux platforms, these functions return `null`, not empty 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: verify pkg:npm/detect-libc@2.1.2
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/detect-libc@2.1.2

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:1935d032c657b0f3a038c22a622b730c15e462bf4173b92f3d888f7f30bbdc55","contract":["assert detect-libc exports GLIBC ('glibc') and MUSL ('musl') string constants and removes legacy v1 property 'method'","assert family, version, and isNonGlibcLinux are async functions returning Promises, while familySync, versionSync, and isNonGlibcLinuxSync are synchronous functions","assert unawaited async family() call returns a Promise instance rather than a string value","assert parity between synchronous and asynchronous APIs where familySync() === await family(), versionSync() === await version(), and isNonGlibcLinuxSync() === await isNonGlibcLinux()","assert on Linux platforms, familySync() returns 'glibc', 'musl', or null, with isNonGlibcLinuxSync() returning true for musl and false for glibc","assert migration trap evaluation confirms functions are truthy in boolean expressions and v1 property access fails","assert parseLibcVersion and compareLibcVersions correctly handle non-semver 2-part libc version strings without throwing errors","assert satisfiesMinLibcVersion accurately validates minimum libc version requirements against detected version","assert resolveAddonBinary maps platform architecture and libc family to the appropriate prebuilt binary suffix"],"goal":"verify pkg:npm/detect-libc@2.1.2","kind":"HOW","packages":["pkg:npm/detect-libc@2.1.2"],"schemaVersion":1,"symbols":["detect-libc.GLIBC","detect-libc.MUSL","detect-libc.family","detect-libc.familySync","detect-libc.isNonGlibcLinux","detect-libc.isNonGlibcLinuxSync","detect-libc.version","detect-libc.versionSync"]},"contractCommand":["node","test/contract.mjs"],"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/detect-libc@2.1.2"],"schemaVersion":1,"subject":"pkg:npm/detect-libc@2.1.2","symbols":["detect-libc.GLIBC","detect-libc.MUSL","detect-libc.family","detect-libc.familySync","detect-libc.isNonGlibcLinux","detect-libc.isNonGlibcLinuxSync","detect-libc.version","detect-libc.versionSync"],"verifierAdapter":"node-typescript@1"}

{
  "name": "detect-libc-verification",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "detect-libc-verification",
      "version": "1.0.0",
      "dependencies": {
        "detect-libc": "2.1.2"
      }
    },
    "node_modules/detect-libc": {
      "version": "2.1.2",
      "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz",
      "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==",
      "license": "Apache-2.0",
      "engines": {
        "node": ">=8"
      }
    }
  }
}

{
  "name": "detect-libc-verification",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "dependencies": {
    "detect-libc": "2.1.2"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/detect-libc@2.1.2",
  "kind": "HOW",
  "packages": [
    "pkg:npm/detect-libc@2.1.2"
  ]
}

import detectLibc, {
  GLIBC,
  MUSL,
  family,
  familySync,
  isNonGlibcLinux,
  isNonGlibcLinuxSync,
  version,
  versionSync,
} from "detect-libc";

/**
 * Parses a libc version string (e.g. "2.39" or "1.2.4") into an array of integers.
 * Libc versions are often non-semver (2 parts instead of 3).
 *
 * @param {string|null} verStr
 * @returns {number[]}
 */
export function parseLibcVersion(verStr) {
  if (typeof verStr !== "string" || !verStr.trim()) {
    return [];
  }
  return verStr
    .trim()
    .split(".")
    .map((num) => parseInt(num, 10))
    .filter((n) => !Number.isNaN(n));
}

/**
 * Compares two libc version strings.
 * Returns:
 *   1 if v1 > v2
 *  -1 if v1 < v2
 *   0 if v1 === v2
 *
 * @param {string|null} v1
 * @param {string|null} v2
 * @returns {number}
 */
export function compareLibcVersions(v1, v2) {
  const parts1 = parseLibcVersion(v1);
  const parts2 = parseLibcVersion(v2);
  const maxLen = Math.max(parts1.length, parts2.length);

  for (let i = 0; i < maxLen; i++) {
    const num1 = parts1[i] ?? 0;
    const num2 = parts2[i] ?? 0;
    if (num1 > num2) return 1;
    if (num1 < num2) return -1;
  }
  return 0;
}

/**
 * Checks if current libc meets the required minimum version.
 *
 * @param {string} minVersion - e.g. "2.28"
 * @param {string|null} [currentVersion] - optional current version override
 * @returns {boolean}
 */
export function satisfiesMinLibcVersion(minVersion, currentVersion = versionSync()) {
  if (!currentVersion) {
    return false;
  }
  return compareLibcVersions(currentVersion, minVersion) >= 0;
}

/**
 * Resolves the appropriate native addon binary name for the current system.
 * Handles glibc, musl, and non-Linux platforms cleanly.
 *
 * @param {object} [options]
 * @param {string} [options.platform]
 * @param {string} [options.arch]
 * @param {string|null} [options.libcFamily]
 * @param {string|null} [options.libcVersion]
 * @param {string} [options.minGlibcVersion]
 * @returns {string} - Addon target name (e.g. "addon-linux-x64-gnu.node", "addon-linux-x64-musl.node", "addon-darwin-arm64.node")
 */
export function resolveAddonBinary({
  platform = process.platform,
  arch = process.arch,
  libcFamily = undefined,
  libcVersion = undefined,
  minGlibcVersion = "2.17",
} = {}) {
  const detectedFamily = libcFamily !== undefined ? libcFamily : familySync();
  const detectedVersion = libcVersion !== undefined ? libcVersion : versionSync();

  if (platform === "linux") {
    if (detectedFamily === MUSL) {
      return `addon-linux-${arch}-musl.node`;
    }
    if (detectedFamily === GLIBC) {
      if (detectedVersion && compareLibcVersions(detectedVersion, minGlibcVersion) < 0) {
        throw new Error(
          `System glibc version ${detectedVersion} is lower than required minimum ${minGlibcVersion}`
        );
      }
      return `addon-linux-${arch}-gnu.node`;
    }
    // Unknown or undetected libc on Linux
    return `addon-linux-${arch}-generic.node`;
  }

  // Non-Linux platforms (darwin, win32)
  if (platform === "win32") {
    return `addon-win32-${arch}-msvc.node`;
  }
  return `addon-${platform}-${arch}.node`;
}

/**
 * Evaluates common v1 vs v2 breaking changes and migration traps.
 */
export function evaluateV2MigrationTraps() {
  const detectObj = detectLibc;

  return {
    // In v1, family was a string. In v2, it's a function.
    familyIsFunction: typeof detectObj.family === "function",
    familySyncIsFunction: typeof detectObj.familySync === "function",
    // In v1, isNonGlibcLinux was boolean. In v2, it's an async function.
    isNonGlibcLinuxIsFunction: typeof detectObj.isNonGlibcLinux === "function",
    // Evaluating function reference in boolean expression is always truthy
    functionRefIsTruthy: Boolean(detectObj.isNonGlibcLinux),
    // Unawaited async call returns a Promise
    unawaitedIsPromise: detectObj.family() instanceof Promise,
    // v1 property .method is removed (undefined)
    methodProperty: detectObj.method,
  };
}

import assert from "node:assert/strict";
import detectLibc, {
  GLIBC,
  MUSL,
  family,
  familySync,
  isNonGlibcLinux,
  isNonGlibcLinuxSync,
  version,
  versionSync,
} from "detect-libc";

import {
  parseLibcVersion,
  compareLibcVersions,
  satisfiesMinLibcVersion,
  resolveAddonBinary,
  evaluateV2MigrationTraps,
} from "../src/libc-addon-resolver.mjs";

// --- 1. Export Shape & Constants ---
assert.equal(GLIBC, "glibc");
assert.equal(MUSL, "musl");
assert.equal(detectLibc.GLIBC, "glibc");
assert.equal(detectLibc.MUSL, "musl");

// v1 property 'method' is undefined in v2
assert.equal(detectLibc.method, undefined);

// --- 2. Async vs Sync Functions ---
assert.equal(typeof family, "function");
assert.equal(typeof familySync, "function");
assert.equal(typeof version, "function");
assert.equal(typeof versionSync, "function");
assert.equal(typeof isNonGlibcLinux, "function");
assert.equal(typeof isNonGlibcLinuxSync, "function");

// Calling async family() returns Promise
const unawaited = family();
assert.equal(unawaited instanceof Promise, true);
assert.notEqual(unawaited, GLIBC);
assert.notEqual(unawaited, MUSL);

// --- 3. Parity between Sync and Async APIs ---
const sFam = familySync();
const aFam = await family();
assert.equal(sFam, aFam, "familySync() must equal await family()");

const sVer = versionSync();
const aVer = await version();
assert.equal(sVer, aVer, "versionSync() must equal await version()");

const sNonGlibc = isNonGlibcLinuxSync();
const aNonGlibc = await isNonGlibcLinux();
assert.equal(sNonGlibc, aNonGlibc, "isNonGlibcLinuxSync() must equal await isNonGlibcLinux()");

// --- 4. Environment Check ---
if (process.platform === "linux") {
  assert.ok(sFam === GLIBC || sFam === MUSL || sFam === null);
  if (sFam === GLIBC) {
    assert.equal(sNonGlibc, false);
  } else if (sFam === MUSL) {
    assert.equal(sNonGlibc, true);
  }
  if (sVer !== null) {
    assert.equal(typeof sVer, "string");
    assert.ok(sVer.length > 0);
  }
} else {
  assert.equal(sFam, null);
  assert.equal(sVer, null);
  assert.equal(sNonGlibc, false);
}

// --- 5. Migration Traps Evaluation ---
const traps = evaluateV2MigrationTraps();
assert.equal(traps.familyIsFunction, true);
assert.equal(traps.familySyncIsFunction, true);
assert.equal(traps.isNonGlibcLinuxIsFunction, true);
assert.equal(traps.functionRefIsTruthy, true);
assert.equal(traps.unawaitedIsPromise, true);
assert.equal(traps.methodProperty, undefined);

// --- 6. Version Parsing and Comparison ---
assert.deepEqual(parseLibcVersion("2.39"), [2, 39]);
assert.deepEqual(parseLibcVersion("1.2.4"), [1, 2, 4]);
assert.deepEqual(parseLibcVersion(""), []);
assert.deepEqual(parseLibcVersion(null), []);

assert.equal(compareLibcVersions("2.39", "2.28"), 1);
assert.equal(compareLibcVersions("2.28", "2.39"), -1);
assert.equal(compareLibcVersions("2.39", "2.39"), 0);
assert.equal(compareLibcVersions("2.31.1", "2.31"), 1);
assert.equal(compareLibcVersions("1.2.3", "1.2.4"), -1);

assert.equal(satisfiesMinLibcVersion("2.17", "2.39"), true);
assert.equal(satisfiesMinLibcVersion("2.40", "2.39"), false);
assert.equal(satisfiesMinLibcVersion("2.17", null), false);

// --- 7. Native Addon Binary Resolution ---
assert.equal(
  resolveAddonBinary({ platform: "linux", arch: "x64", libcFamily: MUSL, libcVersion: "1.2.4" }),
  "addon-linux-x64-musl.node"
);
assert.equal(
  resolveAddonBinary({ platform: "linux", arch: "x64", libcFamily: GLIBC, libcVersion: "2.39", minGlibcVersion: "2.28" }),
  "addon-linux-x64-gnu.node"
);
assert.throws(
  () => resolveAddonBinary({ platform: "linux", arch: "x64", libcFamily: GLIBC, libcVersion: "2.17", minGlibcVersion: "2.28" }),
  /lower than required minimum/
);
assert.equal(
  resolveAddonBinary({ platform: "darwin", arch: "arm64", libcFamily: null, libcVersion: null }),
  "addon-darwin-arm64.node"
);
assert.equal(
  resolveAddonBinary({ platform: "win32", arch: "x64", libcFamily: null, libcVersion: null }),
  "addon-win32-x64-msvc.node"
);

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