ci-info 3.9.0

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/ci-info@3.9.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/ci-info@3.9.0

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:ab0657e80d94d4ff9901ac330ecda923cb65cd755ff75c5751998250c4b67f7d","contract":["getCISummary returns boolean isCI and nullable isPR and name properties","getVendorConstants returns list of supported vendor constants including GITHUB_ACTIONS and GITLAB","isVendorCI returns boolean indicating whether specific vendor flag is active","detectEnvironment identifies GitHub Actions environment and pull request status","detectEnvironment identifies GitLab CI environment and merge request status","detectEnvironment identifies Travis CI environment and pull request status","detectEnvironment identifies CircleCI environment and pull request status","detectEnvironment respects CI=false environment override to disable isCI"],"goal":"verify pkg:npm/ci-info@3.9.0","kind":"HOW","packages":["pkg:npm/ci-info@3.9.0"],"schemaVersion":1},"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/ci-info@3.9.0"],"schemaVersion":1,"subject":"pkg:npm/ci-info@3.9.0","verifierAdapter":"node-typescript@1"}

{
  "name": "sample-ci-info",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-ci-info",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "ci-info": "3.9.0"
      }
    },
    "node_modules/ci-info": {
      "version": "3.9.0",
      "resolved": "https://registry.npmjs.org/ci-info/-/ci-info-3.9.0.tgz",
      "integrity": "sha512-NIxF55hv4nSqQswkAeiOi1r83xy8JldOFDTWiug55KBu9Jnblncd2U6ViHmYgHf01TPZS77NJBhBMKdWj9HQMQ==",
      "funding": [
        {
          "type": "github",
          "url": "https://github.com/sponsors/sibiraj-s"
        }
      ],
      "license": "MIT",
      "engines": {
        "node": ">=8"
      }
    }
  }
}

{
  "name": "sample-ci-info",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room code sample for ci-info@3.9.0",
  "main": "src/index.js",
  "license": "MIT-0",
  "dependencies": {
    "ci-info": "3.9.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/ci-info@3.9.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/ci-info@3.9.0"
  ]
}

'use strict';

const ci = require('ci-info');

/**
 * Returns summary of CI environment flags.
 *
 * @returns {{ isCI: boolean, isPR: boolean | null, name: string | null }}
 */
function getCISummary() {
  return {
    isCI: ci.isCI,
    isPR: ci.isPR,
    name: ci.name
  };
}

/**
 * Returns all supported vendor constant names declared by ci-info.
 *
 * @returns {string[]} List of vendor constants.
 */
function getVendorConstants() {
  return Array.isArray(ci._vendors) ? [...ci._vendors] : [];
}

/**
 * Checks if a specific CI vendor flag is set to true.
 *
 * @param {string} vendorConstant - The vendor constant name.
 * @returns {boolean} Whether the vendor flag is true.
 */
function isVendorCI(vendorConstant) {
  return Boolean(ci[vendorConstant]);
}

/**
 * Evaluates CI detection under a simulated environment map.
 * Isolates process.env modifications and reloads ci-info module.
 *
 * @param {Record<string, string>} envOverrides - Environment variables to set.
 * @returns {{ isCI: boolean, isPR: boolean | null, name: string | null, vendorFlags: Record<string, boolean> }}
 */
function detectEnvironment(envOverrides) {
  const previousEnv = {};
  for (const key of Object.keys(envOverrides)) {
    previousEnv[key] = process.env[key];
    process.env[key] = envOverrides[key];
  }

  let freshCi;
  try {
    delete require.cache[require.resolve('ci-info')];
    freshCi = require('ci-info');
  } finally {
    for (const key of Object.keys(envOverrides)) {
      if (previousEnv[key] === undefined) {
        delete process.env[key];
      } else {
        process.env[key] = previousEnv[key];
      }
    }
    delete require.cache[require.resolve('ci-info')];
  }

  const vendorFlags = {};
  if (Array.isArray(freshCi._vendors)) {
    for (const vendor of freshCi._vendors) {
      if (freshCi[vendor]) {
        vendorFlags[vendor] = true;
      }
    }
  }

  return {
    isCI: freshCi.isCI,
    isPR: freshCi.isPR,
    name: freshCi.name,
    vendorFlags
  };
}

module.exports = {
  ci,
  getCISummary,
  getVendorConstants,
  isVendorCI,
  detectEnvironment
};

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

const require = createRequire(import.meta.url);
const {
  ci,
  getCISummary,
  getVendorConstants,
  isVendorCI,
  detectEnvironment
} = require('../src/index.js');

async function runContractTests() {
  // 1. Module export verification
  assert.ok(ci !== null && typeof ci === 'object', 'ci must be exported as an object');
  assert.equal(typeof getCISummary, 'function', 'getCISummary must be a function');
  assert.equal(typeof getVendorConstants, 'function', 'getVendorConstants must be a function');
  assert.equal(typeof isVendorCI, 'function', 'isVendorCI must be a function');
  assert.equal(typeof detectEnvironment, 'function', 'detectEnvironment must be a function');

  // 2. getCISummary returns boolean isCI and nullable isPR and name properties
  const summary = getCISummary();
  assert.equal(typeof summary.isCI, 'boolean', 'summary.isCI must be boolean');
  assert.ok(typeof summary.isPR === 'boolean' || summary.isPR === null, 'summary.isPR must be boolean or null');
  assert.ok(typeof summary.name === 'string' || summary.name === null, 'summary.name must be string or null');

  // 3. getVendorConstants returns list of supported vendor constants including GITHUB_ACTIONS and GITLAB
  const vendorConstants = getVendorConstants();
  assert.ok(Array.isArray(vendorConstants), 'vendorConstants must be an array');
  assert.ok(vendorConstants.length > 20, 'vendorConstants must declare known vendors');
  assert.ok(vendorConstants.includes('GITHUB_ACTIONS'), 'vendorConstants must include GITHUB_ACTIONS');
  assert.ok(vendorConstants.includes('GITLAB'), 'vendorConstants must include GITLAB');
  assert.ok(vendorConstants.includes('TRAVIS'), 'vendorConstants must include TRAVIS');
  assert.ok(vendorConstants.includes('CIRCLE'), 'vendorConstants must include CIRCLE');

  // 4. isVendorCI returns boolean indicating whether specific vendor flag is active
  const isGithub = isVendorCI('GITHUB_ACTIONS');
  assert.equal(typeof isGithub, 'boolean', 'isVendorCI must return boolean');
  const isUnknown = isVendorCI('NON_EXISTENT_VENDOR');
  assert.equal(isUnknown, false, 'isVendorCI for unknown vendor must return false');

  // 5. detectEnvironment identifies GitHub Actions environment and pull request status
  const githubPrEnv = detectEnvironment({
    GITHUB_ACTIONS: 'true',
    GITHUB_EVENT_NAME: 'pull_request'
  });
  assert.equal(githubPrEnv.isCI, true, 'GitHub Actions should be detected as CI');
  assert.equal(githubPrEnv.name, 'GitHub Actions', 'CI name should be GitHub Actions');
  assert.equal(githubPrEnv.isPR, true, 'GitHub PR event should be detected as PR');
  assert.equal(githubPrEnv.vendorFlags.GITHUB_ACTIONS, true, 'GITHUB_ACTIONS vendor flag must be true');

  // 6. detectEnvironment identifies GitLab CI environment and merge request status
  const gitlabMrEnv = detectEnvironment({
    GITLAB_CI: 'true',
    CI_MERGE_REQUEST_ID: '42'
  });
  assert.equal(gitlabMrEnv.isCI, true, 'GitLab CI should be detected as CI');
  assert.equal(gitlabMrEnv.name, 'GitLab CI', 'CI name should be GitLab CI');
  assert.equal(gitlabMrEnv.isPR, true, 'GitLab MR should be detected as PR');
  assert.equal(gitlabMrEnv.vendorFlags.GITLAB, true, 'GITLAB vendor flag must be true');

  // 7. detectEnvironment identifies Travis CI environment and pull request status
  const travisPrEnv = detectEnvironment({
    TRAVIS: 'true',
    TRAVIS_PULL_REQUEST: '100'
  });
  assert.equal(travisPrEnv.isCI, true, 'Travis CI should be detected as CI');
  assert.equal(travisPrEnv.name, 'Travis CI', 'CI name should be Travis CI');
  assert.equal(travisPrEnv.isPR, true, 'Travis PR should be detected as PR');
  assert.equal(travisPrEnv.vendorFlags.TRAVIS, true, 'TRAVIS vendor flag must be true');

  // 8. detectEnvironment identifies CircleCI environment and pull request status
  const circlePrEnv = detectEnvironment({
    CIRCLECI: 'true',
    CIRCLE_PULL_REQUEST: 'https://example.com/org/repo/pull/1'
  });
  assert.equal(circlePrEnv.isCI, true, 'CircleCI should be detected as CI');
  assert.equal(circlePrEnv.name, 'CircleCI', 'CI name should be CircleCI');
  assert.equal(circlePrEnv.isPR, true, 'CircleCI PR should be detected as PR');
  assert.equal(circlePrEnv.vendorFlags.CIRCLE, true, 'CIRCLE vendor flag must be true');

  // 9. detectEnvironment respects CI=false environment override to disable isCI
  const disabledEnv = detectEnvironment({
    CI: 'false',
    GITHUB_ACTIONS: 'true'
  });
  assert.equal(disabledEnv.isCI, false, 'CI=false must override CI detection to false');

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

runContractTests().catch((err) => {
  console.error('Contract test failure:', err);
  process.exit(1);
});