https://github.com/conventional-commits/parser

reference implementation of conventionalcommits.org spec
https://github.com/conventional-commits/parser

Last synced: 2 days ago
JSON representation

reference implementation of conventionalcommits.org spec

• Host: GitHub
• URL: https://github.com/conventional-commits/parser
• Owner: conventional-commits
• License: isc
• Created: 2020-12-18T22:58:07.000Z (almost 4 years ago)
• Default Branch: main
• Last Pushed: 2024-03-19T06:33:06.000Z (8 months ago)
• Last Synced: 2024-10-31T07:34:03.563Z (14 days ago)
• Language: JavaScript
• Size: 63.5 KB
• Stars: 46
• Watchers: 5
• Forks: 7
• Open Issues: 16
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE.txt

Awesome Lists containing this project

README

        
## Conventional Commits Parser

![ci](https://github.com/conventional-commits/parser/workflows/ci/badge.svg)

![nycrc config on GitHub](https://img.shields.io/nycrc/conventional-commits/parser)

[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org)

Reference implementation of Conventional Commits specification.

Outputs a tree structure based on the

[unist specification](https://github.com/syntax-tree/unist).

## Install

```

npm i @conventional-commits/parser

```

## Usage

```js

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](https://github.com/syntax-tree/unist).

### `toConventionalChangelogFormat(ast: object)`

Given an `object`, representing the parsed commit messages in `unist` format,

returns an object useable by the [conventional-changelog](https://github.com/conventional-changelog/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.

```ebnf

/* See: https://tools.ietf.org/html/rfc3629#section-4 */

       ::= "Placeholder for UTF-8 grammar"

     ::= +

              ::= "0x000D"

              ::= "0x000A"

         ::= [], 

          ::= "(" | ")"

          ::= "U+FEFF"

             ::= "U+0009"

              ::= "U+000B"

              ::= "U+000C"

              ::= "U+0020"

            ::= "U+00A0"

/* See: https://www.ecma-international.org/ecma-262/11.0/index.html#sec-white-space */

             ::= "Any other Unicode 'Space_Separator' code point"

/* Any non-newline whitespace: */

      ::=  |  |  |  |  |  | 

         ::= , +, , (+, )*

                   |  , (+, )*

                   |  , *

/* "!" should be added to the AST as a  node with the value "!" */

         ::= , "(", , ")", ["!"], ":", *, 

                   |  , ["!"], ":", *, 

            ::= +

           ::= +

            ::= *

            ::= [], , *

                   |  []

/* For convenience the , , , and

 *  tokens of  should be appended as children to  */

       ::= [, ":", *], text

/* Note:  is used during parsing, but not returned in the AST. */

      ::= +, 

          ::= , , *, 

/* "!" should be added to the AST as a  node with the value "!" */

           ::= 

                   |  , "("  ")", ["!"]

                   |  , ["!"]

       ::= ":" | " #"

           ::= , +

                   |  

    ::= , +, 

 ::= "BREAKING CHANGE" | "BREAKING-CHANGE"

```