cmp-jira-issues

Extend blink.cmp to auto-complete Jira Cloud issue keys.

Prerequisites

• Using NeoVim (tested with 0.11.x on unix-like environment)
• acli (Atlassian CLI) is installed and is available in $PATH
• You are already authenticated in Jira Cloud with acli jira auth login (can check with acli jira auth status)
• blink.cmp is installed

Installation

Use plugin manager of your choice. Minimal installation example for lazy.nvim:

require('lazy').setup({
  {
    'saghen/blink.cmp',
    dependencies = {
      'artem-nefedov/cmp-jira-issues.nvim',
    },
  },
})

Setup

Below is the example how to add the source to blink.cmp.

require('blink.cmp').setup({
  sources = {
    default = { 'lsp', 'path', 'snippets', 'lazydev', 'buffer', 'jira' }, -- specify here...
    providers = {
      lazydev = { module = 'lazydev.integrations.blink', score_offset = 100 },
      jira = { -- and here
        name = 'Jira',
        module = 'cmp-jira-issues',
        opts = {},
        should_show_items = function(ctx) -- show results only after specific character
          return ctx.trigger.initial_character == '['
        end,
      },
    },
  },
  -- ... other fields for blink.cmp setup
})

Available options

Below are all available options with their respective default values.

opts = {
  get_trigger_characters = function() -- on which characters completion is triggered
    return { '[' }
  end,
  enabled = function() -- determine whether source is available for current buffer
    return vim.bo.filetype == 'gitcommit' or
        (vim.bo.filetype == 'markdown' and vim.fs.basename(vim.api.nvim_buf_get_name(0)) == 'CHANGELOG.md')
  end,
  clear_cache = function() -- set to boolean false value to disable user command creation
    cache = nil -- plugin-local var
  end,
  complete_opts = {
    jql = 'assignee = currentUser() and statusCategory != Done',
    fields = 'summary,description', -- what fields to fetch from jira api
    items = { -- what fields to lookup in response and how to format them
      { '[%s] ',   { { 'key' } } }, -- key only
      { '[%s] %s', { { 'key' }, { 'fields', 'summary' } } }, -- key + summary
    },
    get_cache = function(_)
      return cache
    end,
    set_cache = function(_, items)
      cache = items
    end,
  },
}

Customizing returned values

You can change complete_opts.items to change what values will be returned, e.g. this value will make it so only return lines with both issue keys and summary are returned:

items = {
  { '[%s] %s', { { 'key' }, { 'fields', 'summary' } } },
}

Number of %s in LHS must match total number of defined elements in RHS.

Note that RHS is a list which itself contains other lists of values that correspond to structure of returned "issue" JSON object, with arbitrary depth, e.g. { 'fields', 'summary' } means get value from issue.fields.summary.

Caching

By default, response from server is cached globally for the entire session duration, and JiraClearCache user command is provided to clear cached results.

You can change the behavior by implementing your own caching mechanics using complete_opts.get_cache, complete_opt.set_cache, and clear_cache callbacks.

• complete_opts.get_cache receives 1 argument: self table
• complete_opt.set_cache receives 2 arguments: self table and items table
• clear_cache doesn't receive anything and gets called by JiraClearCache command

To disable cache completely, pass complete_opts.get_cache function that always returns nil.