tessl/npm-conventional-commits-parser

Parse raw conventional commits according to the Conventional Commits specification.

—

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

Synchronous Parser

Name: tessl/npm-conventional-commits-parser
Author: tessl

Core parser functionality for processing individual commit messages with full configurability and error handling.

Capabilities

CommitParser Class

Main class for parsing conventional commit messages with customizable options and detailed error reporting.

/**
 * Commit message parser with configurable options
 */
class CommitParser {
  /**
   * Create a new parser with optional configuration
   * @param options - Parser configuration options
   */
  constructor(options?: ParserOptions);
  
  /**
   * Parse commit message string into structured object
   * @param input - Raw commit message string
   * @returns Parsed commit object with structured data
   * @throws TypeError if input is empty or whitespace only
   */
  parse(input: string): Commit;
}

Usage Examples:

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

// Basic parsing with default options
const parser = new CommitParser();
const commit = parser.parse("feat: add new feature");

console.log(commit.type);     // "feat"
console.log(commit.subject);  // "add new feature"

// Parsing with custom options
const customParser = new CommitParser({
  headerPattern: /^(\w*)(?:\(([\w$.\-* ]*)\))?: (.*)$/,
  headerCorrespondence: ['type', 'scope', 'subject'],
  noteKeywords: ['BREAKING CHANGE', 'DEPRECATED'],
  issuePrefixes: ['#', 'gh-'],
  referenceActions: ['closes', 'fixes', 'resolves']
});

const complexCommit = `feat(parser): add custom regex support

Added support for custom regex patterns to handle
different commit message formats.

BREAKING CHANGE: Parser constructor now requires options parameter

Closes #123
Fixes gh-456`;

const result = customParser.parse(complexCommit);
console.log(result.type);        // "feat"
console.log(result.scope);       // "parser" 
console.log(result.body);        // Multi-line body text
console.log(result.notes.length); // 1 (breaking change note)
console.log(result.references.length); // 2 (issue references)

Commit Object Creation

Utility function for creating empty commit objects with proper structure initialization.

/**
 * Helper to create commit object with default empty structure
 * @param initialData - Optional initial commit data to merge
 * @returns Commit object with empty/default values
 */
function createCommitObject(initialData?: Partial<Commit>): Commit;

Usage Examples:

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

// Create empty commit object
const emptyCommit = createCommitObject();
console.log(emptyCommit.header);     // null
console.log(emptyCommit.notes);      // []
console.log(emptyCommit.references); // []

// Create commit with initial data
const partialCommit = createCommitObject({
  header: "feat: initial commit",
  type: "feat",
  subject: "initial commit"
});
console.log(partialCommit.header);  // "feat: initial commit"
console.log(partialCommit.type);    // "feat"
console.log(partialCommit.body);    // null (default)

Error Handling

The parser throws specific errors for invalid input:

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

const parser = new CommitParser();

try {
  parser.parse("");  // Empty string
} catch (error) {
  console.log(error.message); // "Expected a raw commit"
}

try {
  parser.parse("   ");  // Whitespace only
} catch (error) {
  console.log(error.message); // "Expected a raw commit"
}

Parsing Features

The synchronous parser handles:

Header Parsing: Extracts type, scope, and subject from commit headers using configurable regex patterns
Body Processing: Separates commit body from header and footer sections
Footer Analysis: Identifies breaking changes, issue references, and custom fields
Merge Commit Detection: Recognizes and processes merge commit patterns
Revert Commit Handling: Extracts information about reverted commits
Reference Extraction: Finds and structures issue/PR references with action keywords
Mention Detection: Identifies @mentions in commit messages
Note Processing: Handles breaking changes and other important notes
Custom Field Support: Processes custom metadata fields using configurable patterns
Comment Filtering: Removes comment lines and GPG signatures
Whitespace Normalization: Proper handling of newlines and spacing