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

Conventional Commits Parser

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

Conventional Commits Parser is a TypeScript library that parses raw conventional commit messages according to the Conventional Commits specification. It provides multiple parsing interfaces including a synchronous parser class, async generator functions for handling commit streams, and Node.js Transform streams for pipeline processing.

Package Information

Package Name: conventional-commits-parser
Package Type: npm
Language: TypeScript
Installation: npm install conventional-commits-parser

Core Imports

import { 
  CommitParser, 
  parseCommits, 
  parseCommitsStream, 
  createCommitObject,
  defaultOptions,
  type Commit,
  type ParserOptions,
  type ParserStreamOptions
} from "conventional-commits-parser";

For CommonJS:

const { 
  CommitParser, 
  parseCommits, 
  parseCommitsStream, 
  createCommitObject,
  defaultOptions
} = require("conventional-commits-parser");

Basic Usage

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

// Create parser with default options
const parser = new CommitParser();

// Parse a conventional commit message
const rawCommit = `feat(scope): add new parser functionality

This commit adds support for parsing additional commit formats
with breaking changes.

BREAKING CHANGE: The API has changed for custom regex patterns

Closes #123
Fixes #456`;

const commit = parser.parse(rawCommit);

console.log(commit.type);      // "feat"
console.log(commit.scope);     // "scope"
console.log(commit.subject);   // "add new parser functionality"
console.log(commit.body);      // Multi-line body text
console.log(commit.notes);     // Array of breaking change notes
console.log(commit.references); // Array of issue references

Architecture

Conventional Commits Parser is structured around several key components:

Parser Core: CommitParser class providing synchronous parsing with extensive configuration
Stream Processing: Async generators and Transform streams for handling commit sequences
Type System: Complete TypeScript interfaces for commits, options, and metadata structures
Configuration: Flexible regex-based customization for different commit message formats
CLI Interface: Command-line tool for parsing commits from files or stdin

Capabilities

Synchronous Parsing

Core parser class for processing individual commit messages with full configurability. Ideal for one-off parsing and custom tooling integration.

class CommitParser {
  constructor(options?: ParserOptions);
  parse(input: string): Commit;
}

function createCommitObject(initialData?: Partial<Commit>): Commit;

Synchronous Parser

Stream Processing

Async generator and Transform stream interfaces for processing multiple commits efficiently. Perfect for analyzing git logs and batch commit processing.

function parseCommits(
  options?: ParserStreamOptions
): (rawCommits: Iterable<string | Buffer> | AsyncIterable<string | Buffer>) => AsyncGenerator<Commit>;

function parseCommitsStream(options?: ParserStreamOptions): Transform;

Stream Processing

Configuration Options

Comprehensive configuration system supporting custom regex patterns, keywords, and field mappings for different commit message formats.

interface ParserOptions {
  commentChar?: string;
  mergePattern?: RegExp;
  mergeCorrespondence?: string[];
  headerPattern?: RegExp;
  breakingHeaderPattern?: RegExp;
  headerCorrespondence?: string[];
  revertPattern?: RegExp;
  revertCorrespondence?: string[];
  fieldPattern?: RegExp;
  noteKeywords?: string[];
  notesPattern?(text: string): RegExp;
  issuePrefixes?: string[];
  issuePrefixesCaseSensitive?: boolean;
  referenceActions?: string[];
}

Configuration Options

Command Line Interface

Command-line tool for parsing commit messages from files or stdin with full configuration support.

// CLI command available as 'conventional-commits-parser'
// Usage: conventional-commits-parser [-s <separator>] [<path> ...]
// Options: -s/--separator, -p/--header-pattern, -c/--header-correspondence,
//          -r/--reference-actions, -i/--issue-prefixes, -n/--note-keywords,
//          -f/--field-pattern, --revert-pattern, --revert-correspondence, -v/--verbose

Types

type Commit = CommitBase & CommitMeta;

interface CommitBase {
  merge: string | null;
  revert: CommitMeta | null;
  header: string | null;
  body: string | null;
  footer: string | null;
  notes: CommitNote[];
  mentions: string[];
  references: CommitReference[];
}

interface CommitNote {
  title: string;
  text: string;
}

interface CommitReference {
  raw: string;
  action: string | null;
  owner: string | null;
  repository: string | null;
  issue: string;
  prefix: string;
}

type CommitMeta = Record<string, string | null>;

interface ParserRegexes {
  notes: RegExp;
  referenceParts: RegExp;
  references: RegExp;
  mentions: RegExp;
  url: RegExp;
}