Core Bumper Interface

/**
 * Create a new Bumper instance
 * @param cwdOrGitClient - Current working directory path or ConventionalGitClient instance
 */
constructor(cwdOrGitClient?: string | ConventionalGitClient);

import { Bumper } from "conventional-recommended-bump";

// Default to current working directory
const bumper = new Bumper();

// Specify working directory
const bumper = new Bumper("/path/to/repo");

// Use custom Git client
import { ConventionalGitClient } from "@conventional-changelog/git-client";
const gitClient = new ConventionalGitClient("/path/to/repo");
const bumper = new Bumper(gitClient);

/**
 * Load configs from a preset
 * @param preset - Preset name or configuration parameters  
 * @param loader - Optional custom preset module loader
 * @returns this (for method chaining)
 */
loadPreset<PresetCreatorParams extends UnknownPresetCreatorParams = UnknownPresetCreatorParams>(
  preset: PresetParams<PresetCreatorParams>,
  loader?: PresetModuleLoader
): this;

// Load Angular preset
const bumper = new Bumper().loadPreset("angular");

// Load preset with custom parameters
const bumper = new Bumper().loadPreset({
  name: "angular",
  preMajor: false
});

// Load preset with custom loader
import { createPresetLoader } from "conventional-changelog-preset-loader";
const customLoader = createPresetLoader(/* custom loader config */);
const bumper = new Bumper().loadPreset("angular", customLoader);

/**
 * Set config directly - sets tags, commits, parser options only
 * @param config - Preset configuration object (whatBump function is ignored)
 * @returns this (for method chaining)
 */
config(config: Preset | Promise<Preset>): this;

const configParams = {
  tags: {
    prefix: 'v',
    skipUnstable: true
  },
  commits: {
    path: './src'
  },
  parser: {
    headerPattern: /^(\w*)(?:\((.*)\))?: (.*)$/,
    headerCorrespondence: ['type', 'scope', 'subject']
  }
};

// This only sets config params, not whatBump
const bumper = new Bumper().config(configParams);

// You still need to provide whatBump via loadPreset() or bump() parameter
const result = await bumper.loadPreset('angular').bump();

/**
 * Set bumper options
 * @param options - Bumper configuration options
 * @returns this (for method chaining)
 */
options(options: Options): this;

interface Options {
  warn?: Logger;
  debug?: Logger;
}

type Logger = (source: string, messages: string | string[]) => void;

const bumper = new Bumper().options({
  warn: (source, messages) => console.warn(`[${source}]`, messages),
  debug: (source, messages) => console.debug(`[${source}]`, messages)
});

/**
 * Set params to get the last semver tag
 * @param paramsOrTag - Tag parameters or specific tag name
 * @returns this (for method chaining)
 */
tag(paramsOrTag: GetSemverTagsParams | string): this;

// Use specific tag
const bumper = new Bumper().tag("v1.2.0");

// Configure tag parameters
const bumper = new Bumper().tag({
  prefix: "v",
  skipUnstable: true
});

// Lerna package prefix
const bumper = new Bumper().tag({
  prefix: "package-name@"
});

/**
 * Set params to get commits since last release
 * @param params - Commit retrieval parameters
 * @param parserOptions - Optional parser configuration
 * @returns this (for method chaining)
 */
commits(params: GetCommitsParams, parserOptions?: ParserStreamOptions): this;

/**
 * Set commits since last release
 * @param commits - Iterable or async iterable of commits
 * @returns this (for method chaining) 
 */
commits(commits: Iterable<Commit> | AsyncIterable<Commit>): this;

// Configure commit retrieval
const bumper = new Bumper().commits({
  from: "v1.0.0",
  to: "HEAD",
  path: "./src"
});

// Provide commits directly
const commits = [
  { type: 'feat', subject: 'add new feature', hash: 'abc123' },
  { type: 'fix', subject: 'fix bug', hash: 'def456' }
];
const bumper = new Bumper().commits(commits);

// With parser options
const bumper = new Bumper().commits({
  from: "v1.0.0"
}, {
  headerPattern: /^(\w*)(?:\((.*)\))?: (.*)$/,
  headerCorrespondence: ['type', 'scope', 'subject']
});

/**
 * Recommend a bump by whatBump function
 * @param whatBump - Optional custom function to determine bump from commits
 * @returns Promise resolving to bump recommendation
 */
async bump(whatBump?: (commits: Commit[]) => Promise<BumperRecommendation | null | undefined>): Promise<BumperRecommendationResult>;

// Basic bump with preset
const bumper = new Bumper().loadPreset("angular");
const recommendation = await bumper.bump();

if ("releaseType" in recommendation) {
  console.log(`Recommended bump: ${recommendation.releaseType}`);
  console.log(`Reason: ${recommendation.reason}`);
  console.log(`Commits analyzed: ${recommendation.commits.length}`);
} else {
  console.log("No bump recommended");
  console.log(`Commits analyzed: ${recommendation.commits.length}`);
}

// Custom whatBump function
const customBump = (commits) => {
  const breakingChanges = commits.filter(c => 
    c.notes.some(n => n.title === 'BREAKING CHANGE')
  );
  
  if (breakingChanges.length > 0) {
    return {
      level: 0,
      reason: `${breakingChanges.length} breaking changes detected`
    };
  }
  
  return null; // No bump needed
};

const recommendation = await bumper.bump(customBump);

const recommendation = await new Bumper()
  .loadPreset("angular")
  .tag({ prefix: "v", skipUnstable: true })
  .commits({ path: "./src" })
  .options({ 
    warn: console.warn.bind(console),
    debug: console.debug.bind(console)
  })
  .bump();