Configuration Options

interface ParserOptions {
  /**
   * Character used to comment out a line (e.g., '#' for git commit comments)
   */
  commentChar?: string;
  
  /**
   * Pattern to match merge headers (e.g., branch merge, GitHub/GitLab pull request headers)
   * When a merge header is parsed, the next line is used for conventional header parsing
   */
  mergePattern?: RegExp;
  
  /**
   * Used to define what capturing group of mergePattern captures what merge data
   * Order corresponds to regex capturing groups
   */
  mergeCorrespondence?: string[];
  
  /**
   * Used to match header pattern for conventional commits
   */
  headerPattern?: RegExp;
  
  /**
   * Breaking changes header pattern for detecting breaking changes in headers
   */
  breakingHeaderPattern?: RegExp;
  
  /**
   * Used to define what capturing group of headerPattern captures what header part
   * The order should correspond to headerPattern's capturing groups
   */
  headerCorrespondence?: string[];
  
  /**
   * Pattern to match what this commit reverts
   */
  revertPattern?: RegExp;
  
  /**
   * Used to define what capturing group of revertPattern captures what reverted commit fields
   * Order should correspond to revertPattern's capturing groups
   */
  revertCorrespondence?: string[];
  
  /**
   * Pattern to match other custom fields in commit messages
   */
  fieldPattern?: RegExp;
  
  /**
   * Keywords for important notes (case insensitive)
   * Default: ['BREAKING CHANGE', 'BREAKING-CHANGE']
   */
  noteKeywords?: string[];
  
  /**
   * Function that takes noteKeywords selection and returns RegExp for matching notes
   * @param text - Joined note keywords selection
   * @returns RegExp pattern for matching notes
   */
  notesPattern?(text: string): RegExp;
  
  /**
   * The prefixes of an issue (e.g., in 'gh-123', 'gh-' is the prefix)
   * Default: ['#']
   */
  issuePrefixes?: string[];
  
  /**
   * Whether issuePrefixes should be considered case sensitive
   * Default: false
   */
  issuePrefixesCaseSensitive?: boolean;
  
  /**
   * Keywords to reference an issue (case insensitive)
   * Default: ['close', 'closes', 'closed', 'fix', 'fixes', 'fixed', 'resolve', 'resolves', 'resolved']
   */
  referenceActions?: string[];
}

/**
 * Default parser options following Conventional Commits specification
 */
export const defaultOptions: ParserOptions = {
  noteKeywords: ['BREAKING CHANGE', 'BREAKING-CHANGE'],
  issuePrefixes: ['#'],
  referenceActions: [
    'close', 'closes', 'closed',
    'fix', 'fixes', 'fixed',
    'resolve', 'resolves', 'resolved'
  ],
  headerPattern: /^(\w*)(?:\(([\w$@.\-*/ ]*)\))?: (.*)$/,
  headerCorrespondence: ['type', 'scope', 'subject'],
  revertPattern: /^Revert\s"([\s\S]*)"\s*This reverts commit (\w*)\./,
  revertCorrespondence: ['header', 'hash'],
  fieldPattern: /^-(.*?)-$/
};

import { CommitParser, defaultOptions } from "conventional-commits-parser";

// Use default options directly
const parser = new CommitParser(defaultOptions);

// Extend default options with custom settings
const customParser = new CommitParser({
  ...defaultOptions,
  noteKeywords: [...defaultOptions.noteKeywords, 'DEPRECATED'],
  issuePrefixes: [...defaultOptions.issuePrefixes, 'JIRA-']
});

import { CommitParser } from "conventional-commits-parser";

// Custom format: TYPE[SCOPE]: DESCRIPTION
const customParser = new CommitParser({
  headerPattern: /^([A-Z]+)(?:\[([^\]]*)\])?: (.*)$/,
  headerCorrespondence: ['type', 'scope', 'subject'],
  noteKeywords: ['BREAKING', 'DEPRECATED', 'SECURITY'],
  issuePrefixes: ['JIRA-', 'GH-', '#'],
  referenceActions: ['resolves', 'implements', 'addresses']
});

const commit = customParser.parse(`FEAT[auth]: implement OAuth2 support

Added OAuth2 authentication flow with refresh token support.

BREAKING: Authentication interface has changed
SECURITY: Fixes potential token exposure

Resolves JIRA-1234
Implements GH-567`);

console.log(commit.type);     // "FEAT"
console.log(commit.scope);    // "auth"
console.log(commit.notes);    // Array with BREAKING and SECURITY notes
console.log(commit.references); // Array with JIRA and GH references

const angularParser = new CommitParser({
  headerPattern: /^(\w*)(?:\(([^)]*)\))?: (.*)$/,
  headerCorrespondence: ['type', 'scope', 'subject'],
  breakingHeaderPattern: /^(\w*)(?:\(([^)]*)\))?!: (.*)$/,
  noteKeywords: ['BREAKING CHANGE'],
  issuePrefixes: ['#'],
  referenceActions: ['closes', 'fixes', 'refs']
});

// Handles both regular and breaking change syntax
const breakingCommit = angularParser.parse("feat(core)!: remove deprecated API");
console.log(breakingCommit.notes.length); // 1 (breaking change detected)

const customNotesParser = new CommitParser({
  noteKeywords: ['BREAKING', 'FEATURE', 'BUGFIX'],
  notesPattern: (keywords) => {
    // Custom pattern: [KEYWORD]: note text
    return new RegExp(`\\[\\s*(${keywords})\\s*\\]:\\s*(.*)`, 'i');
  }
});

const commit = customNotesParser.parse(`feat: add new feature

[BREAKING]: This changes the API interface
[FEATURE]: New functionality available`);

console.log(commit.notes.length); // 2
console.log(commit.notes[0].title); // "BREAKING"
console.log(commit.notes[1].title); // "FEATURE"

const mergeParser = new CommitParser({
  mergePattern: /^Merge pull request #(\d+) from (.*)$/,
  mergeCorrespondence: ['pr', 'branch'],
  headerPattern: /^(\w*)(?:\(([^)]*)\))?: (.*)$/,
  headerCorrespondence: ['type', 'scope', 'subject']
});

const mergeCommit = mergeParser.parse(`Merge pull request #123 from feature/auth

feat(auth): implement OAuth2 support`);

console.log(mergeCommit.merge);   // Full merge header
console.log(mergeCommit.pr);      // "123"
console.log(mergeCommit.branch);  // "feature/auth"
console.log(mergeCommit.type);    // "feat" (from next line)

const fieldParser = new CommitParser({
  fieldPattern: /^([A-Z-]+):\s*(.*)$/,
  headerPattern: /^(\w+): (.*)$/,
  headerCorrespondence: ['type', 'subject']
});

const commit = fieldParser.parse(`feat: add new feature

AUTHOR: John Doe
REVIEWER: Jane Smith
TICKET: ABC-123`);

console.log(commit.AUTHOR);   // "John Doe"
console.log(commit.REVIEWER); // "Jane Smith"
console.log(commit.TICKET);   // "ABC-123"

const commentParser = new CommitParser({
  commentChar: '#'
});

const commit = commentParser.parse(`feat: add feature

# This is a comment line that will be filtered out
# Another comment

This line will be included in the body.`);

console.log(commit.body); // "This line will be included in the body."

interface ParserStreamOptions extends ParserOptions {
  /**
   * What warn function to use for handling parse errors:
   * - true: Strict mode, throws errors for unparseable commits
   * - function: Custom warning handler receiving error message
   * - false/undefined: Silent mode, skips unparseable commits
   */
  warn?: boolean | ((message: string) => void);
}

import { parseCommits } from "conventional-commits-parser";

// Custom stream configuration with warning
const streamParser = parseCommits({
  // Parser options
  headerPattern: /^(\w+)(?:\(([^)]*)\))?: (.+)$/,
  headerCorrespondence: ['type', 'scope', 'subject'],
  noteKeywords: ['BREAKING', 'DEPRECATED'],
  
  // Stream-specific option
  warn: (message) => console.error(`Parse warning: ${message}`)
});