Parser for Github, GitLab and Bitbucket issues actions, references and mentions
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
$ npm install --save issue-parser
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'}],
}
*/
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'}],
}
*/
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'}],
}
*/
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'}],
},
}
*/
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'}],
}
*/
#1
{refs: [{raw: '#1', slug: undefined, prefix: '#', issue: '1'}]}
owner/repo#1
{refs: [{raw: 'owner/repo#1', slug: 'owner/repo', prefix: '#', issue: '1'}]}
Fix #1
{actions: {close: [{raw: 'Fix #1', action: 'Fix', slug: undefined, prefix: '#', issue: '1'}]}}
Duplicate of #1
{actions: {duplicate: [{raw: 'Duplicate of #1', action: 'Duplicate of', slug: undefined, prefix: '#', issue: '1'}]}}
@user
{mentions: [{raw: '@user', prefix: '@', user: 'user'}]}
https://github.com/owner/repo/pull/1
Fix https://github.com/owner/repo/issues/2
{
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'}
]
}
}
FIX #1
{actions: {close: [{raw: 'FIX #1', action: 'Fix', slug: undefined, prefix: '#', issue: '1'}]}}
Fix: #1
{actions: {close: [{raw: 'Fix: #1', action: 'Fix', slug: undefined, prefix: '#', issue: '1'}]}}
Fix #1 `Fix #2` @user1 `@user2`
{
actions: {close: [{raw: 'Fix #1', action: 'Fix', slug: undefined, prefix: '#', issue: '1'}]},
mentions: [{raw: '@user1', prefix: '@', user: 'user1'}]
}
\`Fix #1\` \`@user\`
{
actions: {close: [{raw: 'Fix #1', action: 'Fix', slug: undefined, prefix: '#', issue: '1'}]},
mentions: [{raw: '@user1', prefix: '@', user: 'user1'}]
}
Fix #1
```js
console.log('Fix #2');
```
@user1
```js
console.log('@user2');
```
{
actions: {close: [{raw: 'Fix #1', action: 'Fix', slug: undefined, prefix: '#', issue: '1'}]},
mentions: [{raw: '@user1', prefix: '@', user: 'user1'}]
}
\`\`\`
Fix #1
\`\`\`
\`\`\`
@user
\`\`\`
{
actions: {close: [{raw: 'Fix #1', action: 'Fix', slug: undefined, prefix: '#', issue: '1'}]},
mentions: [{raw: '@user', prefix: '@', user: 'user'}]
}
Fix #1
<code>Fix #2</code>
<code><code>Fix #3</code></code>
@user1
<code>@user2</code>
{
actions: {close: [{raw: 'Fix #1', action: 'Fix', slug: undefined, prefix: '#', issue: '1'}]},
mentions: [{raw: '@user1', prefix: '@', user: 'user1'}]
}
`<code>`Fix #1`</code>`
`<code>`@user`</code>`
{
actions: {close: [{raw: 'Fix #1', action: 'Fix', slug: undefined, prefix: '#', issue: '1'}]},
mentions: [{raw: '@user', prefix: '@', user: 'user'}]
}
Fix #1 Fix #2a Fix a#3
{actions: {close: [{raw: 'Fix #1', action: 'Fix', slug: undefined, prefix: '#', issue: '1'}]}}
Create a parser.
Type: Object
String
Parser options. Can be github
, gitlab
or bitbucket
for predefined options, or an object for custom options.
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
.
Type: Array<String>
String
Default: [':']
List of delimiter characters allowed between an action keywords and the issue reference. The characters space (
) and tab (
) are always allowed.
Type: Array<String>
String
Default: ['@']
List of keywords used to identify user mentions.
Type: Array<String>
String
Default: ['#', 'gh-']
List of keywords used to identify issues and pull requests.
Type: Array<String>
String
Default: ['https://github.com', 'https://gitlab.com']
List of base URL used to identify issues and pull requests with full URL.
Type: Array<String>
String
Default: ['issues', 'pull', 'merge_requests']
List of URL segment used to identify issues and pull requests with full URL.
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:
const issueParser = require('issue-parser');
const parse = issueParser('github', {hosts: ['https://custom-url.com']});
Parse an issue description and returns a Result object.
Type: String
Issue text to parse.
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 <owner>/<repo>#<issue number> . |
prefix | String |
The prefix used to identify the issue. |
issue | String |
The issue number. |
Type: Array<Object>
List of issues and pull requests referenced, but not matched with an action.
Each reference has the following properties:
Name | Type | Description |
---|---|---|
raw | String |
The raw value parsed, for example #1 . |
slug | String |
The repository owner and name, for issue referred as <owner>/<repo>#<issue number> . |
prefix | String |
The prefix used to identify the issue. |
issue | String |
The issue number. |
Type: Array<Object>
List of users mentioned.
Each mention has the following properties:
Name | Type | Description |
---|---|---|
raw | String |
The raw value parsed, for example @user . |
prefix | String |
The prefix used to identify the mention. |
user | String |
The user name |
Type: Array<Object>
List of all issues and pull requests referenced or matching an action.
Each reference has 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 or the duplicate, capitalized. Only if matched by an action. |
slug | String |
The repository owner and name, for issue referred as <owner>/<repo>#<issue number> . |
prefix | String |
The prefix used to identify the issue. |
issue | String |
The issue number. |