danger-yajp 0.0.1

data/Guardfile

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# A guardfile for making Danger Plugins
+# For more info see https://github.com/guard/guard#readme
+
+# To run, use `bundle exec guard`.
+
+guard :rspec, cmd: 'bundle exec rspec' do
+  require 'guard/rspec/dsl'
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  # RSpec files
+  rspec = dsl.rspec
+  watch(rspec.spec_helper) { rspec.spec_dir }
+  watch(rspec.spec_support) { rspec.spec_dir }
+  watch(rspec.spec_files)
+
+  # Ruby files
+  ruby = dsl.ruby
+  dsl.watch_spec_files_for(ruby.lib_files)
+end

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 juliendms
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,103 @@
+# Yet Another Jira Plugin
+
+[![License](http://img.shields.io/badge/license-MIT-green.svg?style=flat)](LICENSE)
+
+Yet Another Jira Plugin (in short: yajp) is a [Danger](https://danger.systems/ruby/) plugin that provides methods to easily find and manipulate issues from within the Dangerfile. The major difference with the existing Jira plugins is the ability to transition and update issues with the same feeling as manipulating PR data from Danger. This plugin was build in the same mind as Danger, meaning that you will find methods to easily manipulate Jira data, but no predefined warning and/or message.
+
+Inspired by [danger-jira](https://github.com/RestlessThinker/danger-jira), from which I borrowed the issue search, and by [danger-jira_sync](https://github.com/roverdotcom/danger-jira_sync) for their usage of the awesome [jira-ruby](https://github.com/sumoheavy/jira-ruby) gem.
+
+## Installation
+
+Add this line to your Gemfile:
+
+```rb
+gem 'danger-yajp'
+```
+
+## Usage
+
+You first need to define the environment variables `DANGER_JIRA_URL`, `DANGER_JIRA_USER` and `DANGER_JIRA_PASSWORD` in your CI environment, for example:
+
+```
+DANGER_JIRA_URL: https://jira.company.com/jira
+DANGER_JIRA_USER: username
+DANGER_JIRA_PASSWORD: abcd12345
+```
+
+### Find issues
+
+This methode returns an array of Jira issues. All the base fields of each issue are directly accessible thanks to the gem `jira-ruby`. Input can be one project key, or an array of project keys.
+
+```rb
+issues = jira.find_issues(
+    ['PROJECTKEY','MP'],
+    search_title: true,
+    search_commits: false,
+    search_branch: false
+)
+
+issues.each do |issue|
+    message issue.summary
+end
+```
+
+### Transition / update issues
+
+yajp allows to easily transition and update issues without the hassle of building custom json in the Dangerfile. The inputs are:
+
+* An issue (from `jira-ruby`) or an array of issues
+* For the transition action, the ID of the transition
+* Any number of fields to be updated in the form: `key: value`
+
+ ```rb
+ jira.transition(my_issue, 10, assignee: { name: 'username' }, customfield_11005: 'example')
+ ```
+
+The `transition` method only takes fields available in the transition screen. Use the `split_transition_fields` method to separate the fields available in the transition screen, or use the `transition_and_update` method to transition and update issues (and automatically dispatch the fields to the correct action).
+
+> Transition IDs can be found in Jira under Project Workflow > Edit Workflow in Text Mode.
+
+### Issue URL
+
+Use `issue_link` to retrieve the browse URL of the Jira issue.
+
+```rb
+message "<a href='#{jira.issue_link(issue)}'>#{issue.key} - #{issue.summary}</a>"
+```
+
+### API
+
+You can always access the Jira API client from the `jira-ruby` gem via `jira.api`.
+
+```rb
+jira.api.Project.all
+```
+
+### Full example
+
+```rb
+issues = jira.find_issues('KEY')
+
+if issues.empty?
+  warn 'This PR does not contain any Jira issue.'
+else
+  issues.each do |issue|
+    message "<a href='#{jira.issue_link(issue)}'>#{issue.key} - #{issue.summary}</a>"
+
+    case issue.status
+    when 'In Progress'
+      jira.transition_and_update(issue, 10, assignee: { name: 'username' }, customfield_11005: 'example')
+    when 'To Do', 'Blocked'
+      warn "Issue <a href='#{jira.issue_link(issue)}'>#{issue.key}</a> is not in Dev status, please make sure the issue you're working on is in the correct status"
+    end
+  end
+end
+```
+
+## Development
+
+1. Clone this repo
+2. Run `bundle install` to setup dependencies.
+3. Run `bundle exec rake spec` to run the tests.
+4. Use `bundle exec guard` to automatically have tests run as you make changes.
+5. Make your changes.

data/Rakefile

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+
+RSpec::Core::RakeTask.new(:specs)
+
+task default: :specs
+
+task :spec do
+  Rake::Task['specs'].invoke
+  Rake::Task['rubocop'].invoke
+  Rake::Task['spec_docs'].invoke
+end
+
+desc 'Run RuboCop on the lib/specs directory'
+RuboCop::RakeTask.new(:rubocop) do |task|
+  task.patterns = ['lib/**/*.rb', 'spec/**/*.rb']
+end
+
+desc 'Ensure that the plugin passes `danger plugins lint`'
+task :spec_docs do
+  sh 'bundle exec danger plugins lint'
+end

data/danger-yajp.gemspec

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'yajp/gem_version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'danger-yajp'
+  spec.version       = Yajp::VERSION
+  spec.authors       = ['juliendms']
+  spec.email         = ['j-dumas@live.fr']
+  spec.description   = 'Synchronize your Jira issues with your PR/MR, and more.'
+  spec.summary       = 'Yet Another Jira Plugin is a danger plugin to find issues, access their parameters and perform operations on them.'
+  spec.homepage      = 'https://github.com/juliendms/danger-yajp'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.required_ruby_version = '>= 2.6.0'
+
+  spec.add_runtime_dependency 'danger-plugin-api'
+  spec.add_runtime_dependency 'jira-ruby'
+
+  # General ruby development
+  spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'rake', '~> 13.0'
+
+  # Testing support
+  spec.add_development_dependency 'rspec', '~> 3.9'
+  spec.add_development_dependency 'webmock', '~> 3.9'
+
+  # Linting code and docs
+  spec.add_development_dependency 'rubocop', '~> 1.0.0'
+  spec.add_development_dependency 'yard', '~> 0.9.11'
+
+  # Makes testing easy via `bundle exec guard`
+  spec.add_development_dependency 'guard', '~> 2.16'
+  spec.add_development_dependency 'guard-rspec', '~> 4.7'
+
+  # This gives you the chance to run a REPL inside your tests
+  # via:
+  #
+  #    require 'pry'
+  #    binding.pry
+  #
+  # This will stop test execution and let you inspect the results
+  spec.add_development_dependency 'pry'
+end

data/lib/danger_plugin.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require 'yajp/plugin'

data/lib/danger_yajp.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require 'yajp/gem_version'

data/lib/yajp/gem_version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Yajp
+  VERSION = '0.0.1'
+end

data/lib/yajp/plugin.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+require 'jira-ruby'
+
+module Danger
+  # Yet Another Jira Plugin (in short: yajp) provides methods to easily find and manipulate issues from within the Dangerfile.
+  # The major difference with the existing Jira plugins is the ability to transition and update issues with the same feeling as manipulating PR data from Danger.
+  # This plugin was build in the same mind as Danger, meaning that you will find methods to easily manipulate Jira data, but no predefined warning and/or message.
+  # Like Danger, it requires environment variables to work:
+  #   * DANGER_JIRA_URL: the URL of the Jira server (ex: `https://jira.company.com/jira`)
+  #   * DANGER_JIRA_USER: the Jira user that will use the Jira API
+  #   * DANGER_JIRA_API_TOKEN: the token associated to the user (Jira Cloud) or the password of the user (Jira Server)
+  #
+  # @example Full example of a Dangerfile
+  #   issues = jira.find_issues('KEY')
+  #
+  #   if issues.empty?
+  #     warn 'This PR does not contain any Jira issue.'
+  #   else
+  #     issues.each do |issue|
+  #       message "<a href='#{jira.issue_link(issue)}'>#{issue.key} - #{issue.summary}</a>"
+  #
+  #       case issue.status
+  #       when 'In Progress'
+  #         jira.transition_and_update(issue, 10, assignee: { name: 'username' }, customfield_11005: 'example')
+  #       when 'To Do', 'Blocked'
+  #         warn "Issue <a href='#{jira.issue_link(issue)}'>#{issue.key}</a> is not in Dev status, please make sure the issue you're working on is in the correct status"
+  #       end
+  #     end
+  #   end
+  #
+  # @example Access the Jira client of `jira-ruby` and list all Jira projects
+  #   jira.api.Project.all
+  #
+  # @see  juliendms/danger-yajp
+  # @tags jira, danger, gitlab, github
+  #
+  class DangerYajp < Plugin
+    # Give access to the Jira API via `jira-ruby` client.
+    #
+    # @return [JIRA::Client] Jira API client from `jira-ruby`
+    #
+    attr_reader :api
+
+    def initialize(dangerfile)
+      throw Error('The environment variable DANGER_JIRA_URL is required') if ENV['DANGER_JIRA_URL'].nil?
+
+      super(dangerfile)
+      url_parser = %r{(?<site>https?://[^/]+)(?<context_path>/.+)}.match(ENV['DANGER_JIRA_URL'])
+
+      options = {
+        username:       ENV['DANGER_JIRA_USER'],
+        password:       ENV['DANGER_JIRA_API_TOKEN'],
+        site:           url_parser[:site],
+        context_path:   url_parser[:context_path],
+        auth_type:      :basic
+      }
+
+      @api = JIRA::Client.new(options)
+    end
+
+    def self.instance_name
+      return 'jira'
+    end
+
+    # Find Jira issues (keys) in the specified parameters of the PR.
+    #
+    # @example Find issues in project KEY from the name of the PR branch
+    #   jira.find_issues('KEY', search_title: false, search_branch: true)
+    #
+    # @param [Array<String>]  key An array of Jira project keys like `['KEY', 'JIRA']`, or a single `String` with a Jira project key
+    # @param [Boolean] search_title Option to search Jira issues from PR title, default `true`
+    # @param [Boolean] search_commits Option to search Jira issues from from commit messages, default `false`
+    # @param [Boolean] search_branch Option to search Jira issues from the name of the PR branch, default `false`
+    #
+    # @return [Array<JIRA::Issue>] An array containing all the unique issues found in the PR.
+    #
+    def find_issues(key, search_title: true, search_commits: false, search_branch: false)
+      regexp = build_regexp_from_key(key)
+      jira_issues = []
+
+      jira_issues.concat(search_title(regexp)) if search_title
+      jira_issues.concat(search_commits(regexp)) if search_commits
+      jira_issues.concat(search_branch(regexp)) if search_branch
+      jira_issues.concat(search_pr_body(regexp)) if jira_issues.empty?
+
+      jira_issues.uniq.map { |issue_key| @api.Issue.find(issue_key) }
+    end
+
+    # Transition the given Jira issue(s) using the ID of the transition. Transition IDs can be found in Jira under Project Workflow > Edit Workflow in Text Mode.
+    # The fields that can be updated with this method are only the fields available in the transition screen of the transition. Otherwise use `transition_and_update`.
+    #
+    # @example Transition the issue `my_issue` and set the fields `assignee` and `customfield_11005` available on the transition screens
+    #   jira.transition(my_issue, 10, assignee: { name: 'username' }, customfield_11005: 'example')
+    #
+    # @param [Array<JIRA::Issue>] issue An array of issues, or a single `JIRA::Issue`
+    # @param [Integer] transition_id
+    # @param [Hash] fields Fields that can be updated on the transition screen
+    #
+    # @return [Boolean] `true` if all the issues were transitioned successfully, `false` otherwise.
+    #
+    def transition(issue, transition_id, **fields)
+      issues = issue.kind_of?(Array) ? issue : [] << issue
+      data = { transition: { id: transition_id.to_s } }
+      data[:fields] = fields unless fields.empty?
+      result = true
+
+      issues.each do |key|
+        result &= key.transitions.build.save(data)
+      end
+
+      return result
+    end
+
+    # Update the given Jira issue(s).
+    #
+    # @example Update the issue `my_issue` and set the fields `assignee` and `customfield_11005`
+    #   jira.update(my_issue, assignee: { name: 'username' }, customfield_11005: 'example')
+    #
+    # @param [Array<JIRA::Issue>] issue An array of issue, or a single `JIRA::Issue`
+    # @param [Hash] fields Fields to update
+    #
+    # @return [Boolean] `true` if all the issues were updated successfully, `false` otherwise.
+    #
+    def update(issue, **fields)
+      return if fields.empty?
+
+      issues = issue.kind_of?(Array) ? issue : [] << issue
+      result = true
+
+      issues.each do |key|
+        result &= key.save(fields)
+      end
+    end
+
+    # Utility to split the given fields into fields that can be updated on the transition screen corresponding to the `transition_id` of the given `issue`.
+    #
+    # @param [JIRA::Issue] issue
+    # @param [Integer] transition_id
+    # @param [Hash] fields Fields to split
+    #
+    # @return [Hash]
+    #   * :transition_fields [Hash] A hash containing the fields available in the transition screens
+    #   * :other_fields [Hash] A hash containing the other fields
+    #
+    def split_transition_fields(issue, transition_id, **fields)
+      transitions = issue.transitions.all.keep_if { |transition| transition.attrs['id'] == transition_id.to_s }
+      transition_fields = transitions.first.attrs['fields']
+      transition_data = {}
+
+      fields.each_key do |field|
+        transition_data[field] = fields.delete(field) if transition_fields&.key?(field.to_s)
+      end
+
+      { transition_fields: transition_data, other_fields: fields }
+    end
+
+    # Transition and update the given issues. It will use the `split_transition_fields` method to provide the right fields for the transition action,
+    # and use the other fields with the update action.
+    #
+    # @example Transition the issue `my_issue` and set the fields `assignee` and `customfield_11005`
+    #   jira.transition_and_update(my_issue, 10, assignee: { name: 'username' }, customfield_11005: 'example')
+    #
+    # @param [Array<JIRA::Issue>] issue An array of issues, or a single `JIRA::Issue`
+    # @param [Integer] transition_id
+    # @param [Hash] fields Fields to update
+    #
+    # @return [Boolean] `true` if all the issues were transitioned and updated successfully, `false` otherwise.
+    #
+    def transition_and_update(issue, transition_id, **fields)
+      issues = issue.kind_of?(Array) ? issue : [] << issue
+      result = issues.first.split_transition_fields(transition_id, fields)
+      transition_fields = result[:transition_fields]
+      fields = result[:other_fields]
+
+      result = transition(issues, transition_id, **transition_fields)
+      result & update(issues, **fields)
+    end
+
+    # Get the browse URL of a Jira issue.
+    #
+    # @param [JIRA::Issue] issue
+    #
+    # @return [String] the URL of the issue
+    def issue_link(issue)
+      "#{ENV['DANGER_JIRA_URL']}/browse/#{issue.key}"
+    end
+
+    private
+
+    def vcs_host
+      return gitlab if defined? @dangerfile.gitlab
+
+      github
+    end
+
+    def build_regexp_from_key(key)
+      keys = key.kind_of?(Array) ? key.join('|') : key
+      return /((?:#{keys})-[0-9]+)/
+    end
+
+    def search_title(regexp)
+      jira_issues = []
+
+      vcs_host.pr_title.gsub(regexp) do |match|
+        jira_issues << match
+      end
+
+      jira_issues
+    end
+
+    def search_commits(regexp)
+      jira_issues = []
+
+      git.commits.map do |commit|
+        commit.message.gsub(regexp) do |match|
+          jira_issues << match
+        end
+      end
+
+      jira_issues
+    end
+
+    def search_branch(regexp)
+      jira_issues = []
+
+      vcs_host.branch_for_head.gsub(regexp) do |match|
+        jira_issues << match
+      end
+
+      jira_issues
+    end
+
+    def search_pr_body(regexp)
+      jira_issues = []
+
+      vcs_host.pr_body.gsub(regexp) do |match|
+        jira_issues << match
+      end
+
+      jira_issues
+    end
+  end
+end