@conventional-commits/parser

What is @conventional-commits/parser?

@conventional-commits/parser is an npm package designed to parse conventional commit messages. It helps in extracting structured information from commit messages that follow the Conventional Commits specification. This can be useful for generating changelogs, automating versioning, and ensuring commit message consistency.

What are @conventional-commits/parser's main functionalities?

Parse Commit Messages

This feature allows you to parse a conventional commit message and extract structured information such as type, scope, and description.

const parser = require('@conventional-commits/parser');
const commitMessage = 'feat(core): add new feature';
const parsed = parser.sync(commitMessage);
console.log(parsed);

Handle Commit Message with Body and Footer

This feature allows you to parse commit messages that include a body and footer, extracting detailed information including breaking changes.

const parser = require('@conventional-commits/parser');
const commitMessage = 'fix(core): fix bug\n\nThis fixes a critical bug in the core module.\n\nBREAKING CHANGE: This change breaks the API.';
const parsed = parser.sync(commitMessage);
console.log(parsed);

Custom Parser Options

This feature allows you to customize the parser options to fit different commit message patterns.

const parser = require('@conventional-commits/parser');
const commitMessage = 'chore: update dependencies';
const options = { headerPattern: /^(	ype)(?:	ype)?(?:	ype)?$/ };
const parsed = parser.sync(commitMessage, options);
console.log(parsed);

Other packages similar to @conventional-commits/parser

conventional-commits-parser

conventional-commits-parser is another package that parses conventional commit messages. It offers similar functionality to @conventional-commits/parser, allowing you to extract structured information from commit messages. It is widely used in the community and integrates well with other tools in the Conventional Commits ecosystem.

commitizen

commitizen is a tool that helps you write commit messages following the Conventional Commits specification. While it doesn't parse commit messages, it ensures that the messages are formatted correctly, which can then be parsed by tools like @conventional-commits/parser.

semantic-release

semantic-release automates the versioning and package publishing process based on the commit messages. It uses conventional commit messages to determine the type of release (major, minor, patch) and can be used in conjunction with @conventional-commits/parser for parsing commit messages.

README

Conventional Commits Parser

Reference implementation of Conventional Commits specification.

Outputs a tree structure based on the unist specification.

Install

npm i @conventional-commits/parser

Usage

const {parser} = require('@conventional-commits/parser')
const ast = parser('feat(parser): add support for scopes')

API

parser(text: string)

Runs conventional commits parser on the string provided.

• Returns: Object adhering to unist spec.

toConventionalChangelogFormat(ast: object)

Given an object, representing the parsed commit messages in unist format, returns an object useable by the conventional-changelog ecosystem of libraries.

The Grammar

The parser is based on the following grammar. An effort is made to keep this in sync with the written specification on conventionalcommits.org.

/* See: https://tools.ietf.org/html/rfc3629#section-4 */
<UTF8-char>       ::= "Placeholder for UTF-8 grammar"
<UTF8-octets>     ::= <UTF8char>+

<CR>              ::= "0x000D"
<LF>              ::= "0x000A"
<newline>         ::= [<CR>], <LF>
<parens>          ::= "(" | ")"
<ZWNBSP>          ::= "U+FEFF"
<TAB>             ::= "U+0009"
<VT>              ::= "U+000B"
<FF>              ::= "U+000C"
<SP>              ::= "U+0020"
<NBSP>            ::= "U+00A0"
/* See: https://www.ecma-international.org/ecma-262/11.0/index.html#sec-white-space */
<USP>             ::= "Any other Unicode 'Space_Separator' code point"
/* Any non-newline whitespace: */
<whitespace>      ::= <ZWNBSP> | <TAB> | <VT> | <FF> | <SP> | <NBSP> | <USP>

<message>         ::= <summary>, <newline>+, <body>, <newline>*, <footer>+
                   |  <summary>, <newline>*, <footer>+
                   |  <summary>, <newline>*

/* "!" should be added to the AST as a <breaking-change> node with the value "!" */
<summary>         ::= <type>, "(", <scope>, ")", ["!"], ":", <whitespace>*, <text>
                   |  <type>, ["!"], ":", <whitespace>*, <text>
<type>            ::= <any UTF8-octets except newline or parens or ":" or "!:" or whitespace>+
<scope>           ::= <any UTF8-octets except newline or parens>+
<text>            ::= <any UTF8-octets except newline>*


<body>            ::= [<any body-text except pre-footer>], <newline>, <body>*
                   |  [<any body-text except pre-footer>]
/* For convenience the <breaking-change>, <separator>, <whitespace>, and
 * <text> tokens of <body-text> should be appended as children to <body> */
<body-text>       ::= [<breaking-change>, ":", <whitespace>*], text
/* Note: <pre-footer> is used during parsing, but not returned in the AST. */
<pre-footer>      ::= <newline>*, <footer>+

<footer>          ::= <token>, <separator>, <whitespace>*, <value>, [<newline>]
/* "!" should be added to the AST as a <breaking-change> node with the value "!" */
<token>           ::= <breaking-change>
                   |  <type>, "(" <scope> ")", ["!"]
                   |  <type>, ["!"]
<separator>       ::= ":" | " #"
<value>           ::= <text>, <continuation>+
                   |  <text>
<continuation>    ::= <newline>, <whitespace>+, <text>

<breaking-change> ::= "BREAKING CHANGE" | "BREAKING-CHANGE"

Changelog

0.3.0 (2020-12-30)

Features

• conventional-changelog: handle BREAKING CHANGE in footer and body (#32) (5ad6785)
• support BREAKING CHANGE in body (#30) (8f3f5c7)
• types: add TypeScript definitions (#29) (2a2474b)