Type System

/**
 * Base interface for version bump recommendation
 */
interface WhatBump {
  /** Version bump level: 0 = major, 1 = minor, 2 = patch */
  level: 0 | 1 | 2;
  /** Human-readable reason for the recommended bump */
  reason: string;
}

/**
 * Result type for whatBump functions
 */
type WhatBumpResult = WhatBump | null | undefined;

/**
 * Complete bump recommendation with release type and commits
 */
interface BumperRecommendation extends WhatBump {
  /** Human-readable release type derived from level */
  releaseType: 'major' | 'minor' | 'patch';
  /** Array of commits that contributed to this recommendation */
  commits: Commit[];
}

/**
 * Result when no bump is recommended but commits were analyzed
 */
interface EmptyBumperRecommendation {
  /** Array of commits that were analyzed */
  commits: Commit[];
}

/**
 * Union type for all possible bump analysis results
 */
type BumperRecommendationResult = BumperRecommendation | EmptyBumperRecommendation;

/**
 * Complete preset configuration interface
 */
interface Preset {
  /** Function to determine version bump from commits */  
  whatBump(commits: Commit[]): Promise<WhatBumpResult> | WhatBumpResult;
  /** Optional git tag retrieval parameters */
  tags?: GetSemverTagsParams;
  /** Optional commit retrieval parameters */
  commits?: GetCommitsParams;
  /** Optional commit message parser configuration */
  parser?: ParserStreamOptions;
}

/**
 * Preset configuration parameters (excludes whatBump function)
 */
interface Params extends Omit<Preset, 'whatBump'> {
  /** Optional bumper behavior options */
  options?: Options;
}

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

/**
 * Bumper configuration options
 */
interface Options {
  /** Optional warning message logger */
  warn?: Logger;
  /** Optional debug message logger */
  debug?: Logger;
}

// From @conventional-changelog/git-client

/**
 * Parameters for retrieving semantic version tags
 */
interface GetSemverTagsParams {
  /** Tag prefix to match (e.g., 'v', 'release-') */
  prefix?: string;
  /** Whether to skip unstable versions (alpha, beta, rc) */
  skipUnstable?: boolean;
  /** Lerna package scope for monorepo analysis */
  lernaPackage?: string;
}

/**
 * Parameters for retrieving git commits
 */
interface GetCommitsParams {
  /** Starting commit or tag (exclusive) */
  from?: string;
  /** Ending commit or tag (inclusive) */
  to?: string;
  /** File or directory path to filter commits */
  path?: string;
  /** Custom git log format string */
  format?: string;
  /** Whether to filter out revert commits */
  filterReverts?: boolean;
}

/**
 * Git client for conventional changelog operations
 */
class ConventionalGitClient {
  constructor(cwd: string);
  getLastSemverTag(params?: GetSemverTagsParams): Promise<string | null>;
  getCommits(params: GetCommitsParams, parserOptions?: ParserStreamOptions): AsyncIterable<Commit>;
  debug?: Logger;
}

// From conventional-commits-parser

/**
 * Parsed conventional commit structure
 */
interface Commit {
  /** Commit type (feat, fix, docs, etc.) */
  type: string | null;
  /** Commit scope (optional) */
  scope: string | null;
  /** Commit subject/description */
  subject: string | null;
  /** Merge commit information */
  merge: string | null;
  /** Commit header (first line) */
  header: string;
  /** Commit body */
  body: string | null;
  /** Commit footer */
  footer: string | null;
  /** Array of commit notes (BREAKING CHANGE, etc.) */
  notes: CommitNote[];
  /** Array of issue/PR references */
  references: CommitReference[];
  /** Git commit mentions */
  mentions: string[];
  /** Whether this commit reverts another */
  revert: CommitRevert | null;
  /** Git commit hash */
  hash: string;
  /** Git commit short hash */
  gitTags: string;
  /** Commit author information */
  committerDate: string;
}

/**
 * Commit note (e.g., BREAKING CHANGE)
 */
interface CommitNote {
  /** Note title (BREAKING CHANGE, DEPRECATED, etc.) */
  title: string;
  /** Note text content */
  text: string;
}

/**
 * Reference to issues or pull requests
 */
interface CommitReference {
  /** Reference action (closes, fixes, etc.) */  
  action: string;
  /** Issue/PR number or identifier */
  issue: string;
  /** Whether this is the main reference */
  raw: string;
  /** Reference prefix (#, gh-, etc.) */
  prefix: string;
}

/**
 * Information about reverted commit
 */
interface CommitRevert {
  /** Hash of reverted commit */
  hash: string;
  /** Header of reverted commit */
  header: string;
}

/**
 * Parser configuration options
 */
interface ParserStreamOptions {
  /** Regex pattern to parse commit headers */
  headerPattern?: RegExp;
  /** Field names corresponding to header pattern groups */
  headerCorrespondence?: string[];
  /** Keywords that indicate issue references */
  referenceActions?: string[];
  /** Prefixes for issue numbers */
  issuePrefixes?: string[];
  /** Keywords for important notes */
  noteKeywords?: string[];
  /** Regex pattern for parsing additional fields */
  fieldPattern?: RegExp;
  /** Regex pattern for identifying revert commits */
  revertPattern?: RegExp;
  /** Field names for revert pattern groups */
  revertCorrespondence?: string[];
  /** Regex pattern for identifying merge commits */
  mergePattern?: RegExp;
  /** Warning message handler */
  warn?: Logger | boolean;
}

// From conventional-changelog-preset-loader

/**
 * Parameters for loading a preset
 */
type PresetParams<T = any> = string | { name: string } & T;

/**
 * Unknown preset creator parameters  
 */
type UnknownPresetCreatorParams = Record<string, unknown>;

/**
 * Custom preset module loader function
 */
type PresetModuleLoader = (presetName: string) => Promise<any> | any;

import { Bumper, type BumperRecommendationResult } from "conventional-recommended-bump";

const bumper = new Bumper();
const result: BumperRecommendationResult = await bumper
  .loadPreset("angular")
  .bump();

// Type guard to check if bump is recommended
if ("releaseType" in result) {
  // result is BumperRecommendation
  console.log(`Bump: ${result.releaseType}`);
  console.log(`Level: ${result.level}`);
  console.log(`Reason: ${result.reason}`);
  console.log(`Commits: ${result.commits.length}`);
} else {
  // result is EmptyBumperRecommendation  
  console.log(`No bump recommended, analyzed ${result.commits.length} commits`);
}

import type { Commit, WhatBumpResult } from "conventional-recommended-bump";

const customWhatBump = (commits: Commit[]): WhatBumpResult => {
  // Look for breaking changes
  const hasBreaking = commits.some(commit => 
    commit.notes.some(note => note.title === 'BREAKING CHANGE')
  );
  
  if (hasBreaking) {
    return {
      level: 0, // major
      reason: 'Breaking changes detected'
    };
  }
  
  // Look for new features
  const hasFeatures = commits.some(commit => commit.type === 'feat');
  
  if (hasFeatures) {
    return {
      level: 1, // minor  
      reason: 'New features added'
    };
  }
  
  // Look for bug fixes
  const hasFixes = commits.some(commit => commit.type === 'fix');
  
  if (hasFixes) {
    return {
      level: 2, // patch
      reason: 'Bug fixes included'
    };
  }
  
  // No significant changes
  return null;
};

const result = await new Bumper().bump(customWhatBump);

import type { Preset, Logger } from "conventional-recommended-bump";

const customLogger: Logger = (source, messages) => {
  const messageArray = Array.isArray(messages) ? messages : [messages];
  messageArray.forEach(msg => console.log(`[${source}] ${msg}`));
};

const customPreset: Preset = {
  whatBump: async (commits) => {
    // Custom analysis logic
    return { level: 1, reason: 'Custom analysis' };
  },
  tags: {
    prefix: 'release-',
    skipUnstable: true
  },
  commits: {
    format: '%B%n-hash-%n%H',
    filterReverts: true
  },
  parser: {
    headerPattern: /^(\w*)(?:\((.*)\))?: (.*)$/,
    headerCorrespondence: ['type', 'scope', 'subject'],
    noteKeywords: ['BREAKING CHANGE', 'DEPRECATED'],
    warn: customLogger
  }
};

const result = await new Bumper().config(customPreset).bump();