Configuration Management

/**
 * 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
}

/**
 * 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;

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);

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;
}

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;
}

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;
}

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

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

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

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

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

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);
  }
});

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

# Verbose mode
coveralls --verbose

# Stdout mode  
coveralls --stdout

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');
  }
});

// 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
  };
}