Have ideas to improve npm?Join in the discussion! »

    issue-parser
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/issue-parser package

    6.0.0 • Public • Published

    issue-parser

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

    Travis Codecov Greenkeeper badge

    The parser can identify:

    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: {
        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'}],
    }
    */

    GitLab format

    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'}],
    }
    */

    Bitbucket format

    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'}],
    }
    */

    Custom format

    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'}],
      },
    }
    */

    Extend existing format

    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

    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: {close: [{raw: 'Fix #1', action: 'Fix', slug: undefined, prefix: '#', issue: '1'}]}}

    Parse duplicate keywords

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

    Ignore keywords case

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

    Support delimiters between action keyword and issue

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

    Ignore references in back-tick quotes

    Fix #1 `Fix #2` @user1 `@user2`
    {
      actions: {close: [{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: {close: [{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('@user2');
    ```
    {
      actions: {close: [{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: {close: [{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: {close: [{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: {close: [{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: {close: [{raw: 'Fix #1', action: 'Fix', slug: undefined, prefix: '#', issue: '1'}]}}

    API

    issueParser([options], [overrides]) => 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.

    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> 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> 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.

    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:

    const issueParser = require('issue-parser');
    const parse = issueParser('github', {hosts: ['https://custom-url.com']});

    parse(text) => Result

    Parse an issue description and returns a Result object.

    text

    Type: String

    Issue text to parse.

    Result

    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 <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 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.

    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 @user.
    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 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.

    Install

    npm i issue-parser

    DownloadsWeekly Downloads

    471,402

    Version

    6.0.0

    License

    MIT

    Unpacked Size

    25.1 kB

    Total Files

    5

    Last publish

    Collaborators

    • avatar