issue-parser

Parser for Github, GitLab and Bitbucket issues actions, references and mentions

[![Node CI Workflow Status][github-actions-ci-badge]][github-actions-ci-link]

The parser can identify:
- GitHub closing keywords, duplicate keyword, issue references and user mentions
- GitLab closing keywords, duplicate keyword, issue references and user mentions
- Bitbucket closing keywords, issue references and user mentions
- Custom or additional keywords

Install

``bash
$ npm install --save issue-parser
`

Usage

$3

`js
const issueParser = require('issue-parser');
const parse = issueParser('github');

parse('Issue description, ref user/package#1, Fix #2, Duplicate of #3 /cc @user');
/*
{
refs: [{raw: 'user/package#1', slug: 'user/package', prefix: '#', issue: '1'}],
actions: {
close: [{raw: 'Fix #2', action: 'Fix', prefix: '#', issue: '2'}],
duplicate: [{raw: 'Duplicate of #3', action: 'Duplicate of', prefix: '#', issue: '3'}],
},
mentions: [{raw: '@user', prefix: '@', user: 'user'}],
}
*/
`

$3

`js
const issueParser = require('issue-parser');
const parse = issueParser('gitlab');

parse('Issue description, ref group/user/package#1, !2, implement #3, /duplicate #4 /cc @user');
/*
{
refs: [
{raw: 'group/user/package#1', slug: 'group/user/package', prefix: '#', issue: '1'},
{raw: '!2', slug: 'group/user/package', prefix: '!', issue: '2'},
],
actions: {
close: [{raw: 'implement #3', action: 'Implement', prefix: '#', issue: '4'}],
duplicate: [{raw: 'Duplicate of #4', action: 'Duplicate of', prefix: '#', issue: '4'}],
},
mentions: [{raw: '@user', prefix: '@', user: 'user'}],
}
*/
`

$3

`js
const issueParser = require('issue-parser');
const parse = issueParser('bitbucket');

parse('Issue description, ref user/package#1, fixing #2. /cc @user');
/*
{
refs: [{raw: 'user/package#1', slug: 'user/package', prefix: '#', issue: '1'}],
actions: {
close: [{raw: 'fixing #2', action: 'Fixing', prefix: '#', issue: '2'}],
},
mentions: [{raw: '@user', prefix: '@', user: 'user'}],
}
*/
`

$3

`js
const issueParser = require('issue-parser');
const parse = issueParser({actions: {fix: ['complete'], hold: ['holds up']}, issuePrefixes: ['🐛']});

parse('Issue description, related to user/package🐛1, Complete 🐛2, holds up 🐛3');
/*
{
refs: [{raw: 'user/package🐛1', slug: 'user/package', prefix: '🐛', issue: '1'}],
actions: {
fix: [{raw: 'Complete 🐛2', action: 'Complete', prefix: '🐛', issue: '2'}],
hold: [{raw: 'holds up 🐛3', action: 'Holds up', prefix: '🐛', issue: '3'}],
},
}
*/
`

$3

`js
const issueParser = require('issue-parser');
const parse = issueParser('github', {actions: {parent: ['parent of'], related: ['related to']}});

parse('Issue description, ref user/package#1, Fix #2, Parent of #3, related to #4 /cc @user');
/*
{
refs: [{raw: 'user/package#1', slug: 'user/package', prefix: '#', issue: '1'}],
actions: {
close: [{raw: 'Fix #2', action: 'Fix', prefix: '#', issue: '2'}],
parent: [{raw: 'Parent of #3', action: 'Parent of', prefix: '#', issue: '3'}],
related: [{raw: 'related to #4', action: 'Related to', prefix: '#', issue: '4'}],
},
mentions: [{raw: '@user', prefix: '@', user: 'user'}],
}
*/
`

Features

$3

`text
#1
`
`js
{refs: [{raw: '#1', slug: undefined, prefix: '#', issue: '1'}]}
`

$3

`text
owner/repo#1
`
`js
{refs: [{raw: 'owner/repo#1', slug: 'owner/repo', prefix: '#', issue: '1'}]}
`

$3

`text
Fix #1
`
`js
{actions: {close: [{raw: 'Fix #1', action: 'Fix', slug: undefined, prefix: '#', issue: '1'}]}}
`

$3

`text
Duplicate of #1
`
`js
{actions: {duplicate: [{raw: 'Duplicate of #1', action: 'Duplicate of', slug: undefined, prefix: '#', issue: '1'}]}}
`

$3

`text
@user
`
`js
{mentions: [{raw: '@user', prefix: '@', user: 'user'}]}
`

$3

`text
https://github.com/owner/repo/pull/1

Fix https://github.com/owner/repo/issues/2
`
`js
{
refs: [{raw: 'https://github.com/owner/repo/pull/1', slug: 'owner/repo', prefix: undefined, issue: '1'},]
actions: {
close: [
{raw: 'Fix https://github.com/owner/repo/issues/2', action: 'Fix', slug: 'owner/repo', prefix: undefined, issue: '2'}
]
}
}
`

$3

`text
FIX #1
`
`js
{actions: {close: [{raw: 'FIX #1', action: 'Fix', slug: undefined, prefix: '#', issue: '1'}]}}
`

$3

`text
Fix: #1
`
`js
{actions: {close: [{raw: 'Fix: #1', action: 'Fix', slug: undefined, prefix: '#', issue: '1'}]}}
`

$3

`text
Fix #1 Fix #2 @user1 @user2
`
`js
{
actions: {close: [{raw: 'Fix #1', action: 'Fix', slug: undefined, prefix: '#', issue: '1'}]},
mentions: [{raw: '@user1', prefix: '@', user: 'user1'}]
}
`

$3

`text
\Fix #1\ \@user\
`
`js
{
actions: {close: [{raw: 'Fix #1', action: 'Fix', slug: undefined, prefix: '#', issue: '1'}]},
mentions: [{raw: '@user1', prefix: '@', user: 'user1'}]
}
`

$3

``text
Fix #1

`js
console.log('Fix #2');
`

@user1

`js
console.log('@user2');
`
``
`js
{
actions: {close: [{raw: 'Fix #1', action: 'Fix', slug: undefined, prefix: '#', issue: '1'}]},
mentions: [{raw: '@user1', prefix: '@', user: 'user1'}]
}
`

$3

`text
\\\
Fix #1
\\\

\\\
@user
\\\
`
`js
{
actions: {close: [{raw: 'Fix #1', action: 'Fix', slug: undefined, prefix: '#', issue: '1'}]},
mentions: [{raw: '@user', prefix: '@', user: 'user'}]
}
`

$3

`text
Fix #1
Fix #2
Fix #3
@user1
@user2
`
`js
{
actions: {close: [{raw: 'Fix #1', action: 'Fix', slug: undefined, prefix: '#', issue: '1'}]},
mentions: [{raw: '@user1', prefix: '@', user: 'user1'}]
}
`

$3

`text
Fix #1
@user
`
`js
{
actions: {close: [{raw: 'Fix #1', action: 'Fix', slug: undefined, prefix: '#', issue: '1'}]},
mentions: [{raw: '@user', prefix: '@', user: 'user'}]
}
`

$3

`text
Fix #1 Fix #2a Fix a#3
`
`js
{actions: {close: [{raw: 'Fix #1', action: 'Fix', slug: undefined, prefix: '#', issue: '1'}]}}
`

API

$3

Create a parser.

#### options

Type: Object String

Parser options. Can be github, gitlab or bitbucket for predefined options, or an object for custom options.

##### actions

Type: Object

Default:
{close: ['close', 'closes', 'closed', 'closing', 'fix', 'fixes', 'fixed', 'fixing', 'resolve', 'resolves', 'resolved', 'resolving', 'implement', 'implements', 'implemented', 'implementing'],
duplicate: ['Duplicate of', '/duplicate']}

Object with type of action as key and array of keywords as value.

Each keyword match will be placed in the corresponding property of the result action object. For example the with the configuration {actions: fix: ['fixed', 'fixing']} each action matching fixed or fixing will be under result.actions.fix.

##### delimiters

Type: Array String

Default: [':']

List of delimiter characters allowed between an action keywords and the issue reference. The characters space ( ) and tab ( ) are always allowed.

##### mentionsPrefixes

Type: Array String

Default: ['@']

List of keywords used to identify user mentions.

##### issuePrefixes

Type: Array String

Default: ['#', 'gh-']

List of keywords used to identify issues and pull requests.

##### hosts

Type: Array String

Default: ['https://github.com', 'https://gitlab.com']

List of base URL used to identify issues and pull requests with full URL.

##### issueURLSegments

Type: Array String

Default: ['issues', 'pull', 'merge_requests']

List of URL segment used to identify issues and pull requests with full URL.

#### overrides

Type: Object

Option overrides. Useful when using predefined options (such as github, gitlab or bitbucket). The overrides object can define the same properties as options.

For example, the following will use all the github predefined options but with a different hosts option:
`js
const issueParser = require('issue-parser');
const parse = issueParser('github', {hosts: ['https://custom-url.com']});
`

$3

Parse an issue description and returns a Result object.

#### text

Type: String

Issue text to parse.

$3

#### actions

Type: Object

List of matching actions by type.

Each type of action is an array of objects with the following properties:

| Name | Type | Description |
|--------|----------|---------------------------------------------------------------------------------------|
| raw | String | The raw value parsed, for example Fix #1. |
| action | String | The keyword used to identify the action, capitalized. |
| slug | String | The repository owner and name, for issue referred as /#. |
| prefix | String | The prefix used to identify the issue. |
| issue | String | The issue number. |

#### refs

Type: Array