or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdindex.mdstream-processing.mdsynchronous-parser.md
tile.json

index.mddocs/

Conventional Commits Parser

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;
}