tessl/npm-coveralls

Node.js library and CLI tool for sending code coverage data to Coveralls.io

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Configuration Management

Name: tessl/npm-coveralls
Author: tessl

Extracts and manages configuration options from environment variables, CI system detection, YAML files, and user overrides to configure coverage submission parameters.

Capabilities

Complete Options Resolution

Gets complete configuration by combining base options with user-provided overrides and command-line arguments.

/**
 * Get complete configuration options with user overrides
 * @param callback - Error-first callback with resolved options
 * @param userOptions - Optional user-provided configuration overrides
 */
function getOptions(
  callback: (err: Error | null, options?: CoverallsOptions) => void,
  userOptions?: object
): void;

interface CoverallsOptions {
  // CI Service Configuration
  service_name?: string;       // CI service name (auto-detected)
  service_number?: string;     // Build number
  service_job_id?: string;     // Job ID  
  service_job_number?: string; // Job number
  service_pull_request?: string; // Pull request number
  
  // Repository Configuration
  repo_token?: string;         // Repository token for private repos
  
  // Coverage Configuration  
  filepath?: string;           // Base directory for file paths
  flag_name?: string;          // Flag name for parallel builds
  parallel?: boolean;          // Enable parallel build mode
  run_at?: string;            // Timestamp for the build
  
  // Git Metadata
  git?: GitData;              // Git repository information
}

Base Options Extraction

Extracts base configuration from environment variables and CI system detection without user overrides.

/**
 * Extract base configuration from environment and CI detection
 * @param callback - Error-first callback with base options
 */
function getBaseOptions(
  callback: (err: Error | null, options?: CoverallsOptions) => void
): void;

Usage Examples:

const { getOptions, getBaseOptions } = require('coveralls');

// Get complete options with defaults
getOptions((err, options) => {
  if (err) {
    console.error('Configuration error:', err);
    return;
  }
  
  console.log('Service:', options.service_name);
  console.log('Job ID:', options.service_job_id);
  console.log('Repo token:', options.repo_token ? '[REDACTED]' : 'not set');
});

// Get base options only
getBaseOptions((err, baseOptions) => {
  if (err) {
    console.error('Base config error:', err);
    return;
  }
  
  console.log('Detected CI:', baseOptions.service_name);
  console.log('Git branch:', baseOptions.git?.branch);
});

// With user overrides
const userConfig = {
  service_name: 'custom-ci',
  repo_token: 'custom-token',
  flag_name: 'integration-tests'
};

getOptions((err, options) => {
  console.log('Final service:', options.service_name); // 'custom-ci'
  console.log('Flag name:', options.flag_name);        // 'integration-tests'
}, userConfig);

CI System Detection

Automatic detection and configuration for supported CI systems based on environment variables:

Travis CI

if (process.env.TRAVIS) {
  options.service_name = 'travis-ci';
  options.service_number = process.env.TRAVIS_BUILD_NUMBER;
  options.service_job_id = process.env.TRAVIS_JOB_ID;
  options.service_pull_request = process.env.TRAVIS_PULL_REQUEST;
}

CircleCI

if (process.env.CIRCLECI) {
  options.service_name = 'circleci';
  options.service_number = process.env.CIRCLE_WORKFLOW_ID;
  options.service_job_number = process.env.CIRCLE_BUILD_NUM;
}

Jenkins

if (process.env.JENKINS_URL || process.env.JENKINS_HOME) {
  options.service_name = 'jenkins';
  options.service_job_id = process.env.BUILD_ID;
  options.service_pull_request = process.env.CHANGE_ID || process.env.ghprbPullId;
}

Additional Supported Systems

GitLab CI: GITLAB_CI
AppVeyor: APPVEYOR
Buildkite: BUILDKITE
Drone: DRONE
CodeShip: CI_NAME=codeship
Wercker: WERCKER
Semaphore: SEMAPHORE
Azure Pipelines: TF_BUILD
Codefresh: CF_BRANCH

Environment Variable Configuration

Primary Configuration

process.env.COVERALLS_SERVICE_NAME     // Override service name
process.env.COVERALLS_REPO_TOKEN       // Repository token
process.env.COVERALLS_GIT_BRANCH       // Git branch override
process.env.COVERALLS_FLAG_NAME        // Flag name for parallel builds

Build Information

process.env.COVERALLS_SERVICE_NUMBER    // Build number override
process.env.COVERALLS_SERVICE_JOB_ID    // Job ID override  
process.env.COVERALLS_SERVICE_JOB_NUMBER // Job number override
process.env.COVERALLS_RUN_AT            // Timestamp override
process.env.COVERALLS_PARALLEL          // Enable parallel mode

Git Overrides

process.env.COVERALLS_GIT_COMMIT       // Commit SHA override
process.env.COVERALLS_GIT_BRANCH       // Branch name override

YAML Configuration

Configuration can be provided via .coveralls.yml file in the project root:

# .coveralls.yml
repo_token: your-repo-token-here
service_name: custom-ci

The YAML file is loaded and merged with environment variables:

// YAML configuration takes precedence over defaults
// Environment variables take precedence over YAML
// User options take precedence over everything

Git Metadata Integration

The configuration system integrates with Git metadata extraction:

getOptions((err, options) => {
  if (options.git) {
    console.log('Git info available:');
    console.log('- Commit:', options.git.head.id);
    console.log('- Branch:', options.git.branch);
    console.log('- Author:', options.git.head.author_name);
    console.log('- Message:', options.git.head.message);
  }
});

Git data includes:

Commit SHA and metadata
Branch name
Author and committer information
Commit message
Remote repository URLs

Command-Line Arguments

Options can be provided via command-line arguments:

# File path argument
coveralls path/to/coverage.lcov

# Verbose mode
coveralls --verbose

# Stdout mode  
coveralls --stdout

Arguments are parsed and included in the final options object.

Configuration Priority

Options are resolved in this priority order (highest to lowest):

User-provided options (passed to getOptions)
Command-line arguments
Environment variables (prefixed with COVERALLS_)
YAML configuration (.coveralls.yml)
CI system detection (automatic based on environment)
Default values

Error Handling

Configuration errors are handled gracefully:

getOptions((err, options) => {
  if (err) {
    if (err.message.includes('git')) {
      console.error('Git metadata extraction failed');
    } else {
      console.error('Configuration error:', err.message);
    }
    return;
  }
  
  // Validate required options
  if (!options.repo_token && options.service_name === 'travis-pro') {
    console.warn('Repo token required for private repos');
  }
});

Local Git Detection

When CI environment variables are not available, the system falls back to local Git detection:

// Automatically detects:
// - Current Git commit SHA
// - Current branch name  
// - Repository root directory

const localGitData = detectLocalGit();
if (localGitData) {
  options.git = {
    head: { id: localGitData.git_commit },
    branch: localGitData.git_branch
  };
}