Package Exports

issue-parser

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (issue-parser) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

issue-parser

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

Install

$ npm install --save issue-parser

Usage

GitHub format

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: [{raw: 'Fix #2', action: 'Fix', prefix: '#', issue: '2'}],
  duplicates: [{raw: 'Duplicate of #3', action: 'Duplicate of', prefix: '#', issue: '3'}],
  mentions: [{raw: '@user', prefix: '@', user: 'user'}],
}
*/

GitLab format

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

issueParser('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: [{raw: 'implement #3', action: 'Implement', prefix: '#', issue: '4'}],
  duplicates: [{raw: 'Duplicate of #4', action: 'Duplicate of', prefix: '#', issue: '4'}],
  mentions: [{raw: '@user', prefix: '@', user: 'user'}],
}
*/

Bitbucket format

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

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

Custom format

const issueParser = require('issue-parser')
const parse = issueParser({referenceActions: ['complete'], issuePrefixes: ['🐛']});

issueParser('Issue description, related to user/package🐛1, Complete 🐛2');
/*
{
  refs: [{raw: 'user/package🐛1', slug: 'user/package', prefix: '🐛', issue: '1'}],
  actions: [{raw: 'Complete 🐛2', action: 'Complete', prefix: '🐛', issue: '2'}],
  duplicates: [],
  mentions: [],
}
*/

Features

Parse references

#1

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

Parse repository slug

owner/repo#1

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

Parse closing keywords

Fix #1

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

Parse duplicate keywords

Duplicate of #1

{duplicates: [{raw: 'Duplicate of #1', action: 'Duplicate of', slug: undefined, prefix: '#', issue: '1'}]}

Parse user mentions

@user

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

Parse references with full issue URL

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: [
    {raw: 'Fix https://github.com/owner/repo/issues/2', action: 'Fix', slug: 'owner/repo', prefix: undefined, issue: '2'}
  ]
}

Ignore keywords case

FIX #1

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

Ignore references in back-tick quotes

Fix #1 `Fix #2` @user1 `@user2`

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

Include references in escaped back-tick quotes

\`Fix #1\` \`@user\`

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

Ignore references in fenced blocks

Fix #1

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

@user1

```js
console.log('@user1');
```

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

Include references in escaped fenced blocks

\`\`\`
Fix #1
\`\`\`

\`\`\`
@user
\`\`\`

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

Ignore references in <code> tags

Fix #1
<code>Fix #2</code>
<code><code>Fix #3</code></code>
@user1
<code>@user2</code>

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

Include references in escaped <code> tags

`<code>`Fix #1`</code>`
`<code>`@user`</code>`

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

Ignore malformed references

Fix #1 Fix #2a Fix a#3

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

API

issueParser([options]) => parse

Create a parser.

options

Type: Object String
Parser options. Can be github, gitlab or bitbucket for predefined options, or an object for custom options.

referenceActions

Type: Array<String> String
Default: ['close', 'closes', 'closed', 'closing', 'fix', 'fixes', 'fixed', 'fixing', 'resolve', 'resolves', 'resolved', 'resolving', 'implement', 'implements', 'implemented', 'implementing']

List of action keywords used to close issues and pull requests.

duplicateActions

Type: Array<String> String
Default: ['Duplicate of', '/duplicate']

List of keywords used to identify duplicate issues and pull requests.

mentionsPrefixes

Type: Array<String> String
Default: ['@']

List of keywords used to identify user mentions.

issuePrefixes

Type: Array<String> String
Default: ['#', 'gh-']

List of keywords used to identify issues and pull requests.

hosts

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.

issueURLSegments

Type: Array<String> String
Default: ['issues', 'pull', 'merge_requests']

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

parse(text) => Result

Parse an issue description and returns a Result object.

text

Type: String

Issue text to parse.

Result

actions

Type: Array<Object>

List of issues and pull requests closed.
Each action 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, 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.

duplicates

Type: Array<Object>

List of issues and pull requests marked as duplicate.
Each duplicate 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 duplicate, 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.

refs

Type: Array<Object>

List of issues and pull requests referenced, but not closed or marked as duplicates.
Each reference has the following properties:

Name	Type	Description
raw	`String`	The raw value parsed, for example `Fix #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.

mentions

Type: Array<Object>

List of users mentioned.
Each mention has the following properties:

Name	Type	Description
raw	`String`	The raw value parsed, for example `Fix #1`.
prefix	`String`	The prefix used to identify the mention.
user	`String`	The user name

allRefs

Type: Array<Object>

List of all issues and pull requests closed, marked as duplicate or referenced.
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.
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.