jira-ruby 2.3.0 → 3.0.0.beta2

data/lib/jira/resource/attachment.rb

@@ -1,4 +1,7 @@
+# frozen_string_literal: true
+
 require 'net/http/post/multipart'
+require 'open-uri'
 
 module JIRA
   module Resource
@@ -6,27 +9,149 @@ module JIRA
       delegate_to_target_class :meta
     end
 
+    # This class provides the Attachment object <-> REST mapping for JIRA::Resource::Attachment derived class,
+    # i.e. the Create, Retrieve, Update, Delete lifecycle methods.
+    #
+    # == Lifecycle methods
+    #
+    # === Retrieving a single attachment by Issue and attachment id
+    #
+    #     # Find attachment with id 30076 on issue SUP-3000.
+    #     issue =  JIRA::Resource::Issue.find(client, 'SUP-3000', { fields: 'attachment' } )
+    #     attachment = issue.attachments.find do |attachment_curr|
+    #         30076 == attachment_curr.id.to_i
+    #     end
+    #
+    # === Retrieving meta information for an attachments
+    #
+    #     attachment.meta
+    #
+    # === Retrieving file contents of attachment
+    #
+    #     content = URI.open(attachment.content).read
+    #     content = attachment.download_contents
+    #     content = attachment.download_file { |file| file.read }
+    #
+    # === Adding an attachment to an issue
+    #
+    #     Dir.mktmpdir do |dir|
+    #       path = File.join(dir, filename)
+    #       IO.copy_stream(file.path, path)
+    #
+    #       issue =  JIRA::Resource::Issue.find(client, 'SUP-3000', { fields: 'attachment' } )
+    #       attachment = issue.attachments.build
+    #       attachment.save!( { file: path, mimeType: content_type } )
+    #     end
+    #
+    # === Deleting an attachment
+    #
+    #   attachment.delete
+    #
+    # @!method save(attrs, path = url)
+    #   Uploads a file as an attachment to its issue.
+    #
+    #   Filename used will be the basename of the given file.
+    #
+    #   @param [Hash] attrs the options to create a message with.
+    #   @option attrs [IO,String] :file The file to upload, either a file object or a file path to find the file.
+    #   @option attrs [String] :mimeType The MIME type of the file.
+    #   @return [Boolean] True if successful, false if failed.
+    #
+    # @!attribute [r] self
+    #   @return [String] URL to JSON of this attachment
+    # @!attribute [r] filename
+    #   @return [String] the filename
+    # @!attribute [r] author
+    #   @return [JIRA::Resource::User] the user who created the attachment
+    # @!attribute [r] created
+    #   @return [String] timestamp when the attachment was created
+    # @!attribute [r] size
+    #   @return [Integer] the file size
+    # @!attribute [r] mimeType
+    #   @return [String] MIME of the content type
+    # @!attribute [r] content
+    #   @return [String] URL (not the contents) to download the contents of the attachment
+    # @!attribute [r] thumbnail
+    #   @return [String] URL to download the thumbnail of the attachment
+    #
     class Attachment < JIRA::Base
       belongs_to :issue
       has_one :author, class: JIRA::Resource::User
 
+      # @private
       def self.endpoint_name
         'attachments'
       end
 
+      # Gets metadata about attachments on the server.
+      # @example Return metadata
+      #   Attachment.meta(client)
+      #   =>  { "enabled" => true, "uploadLimit" => 1000000 }
+      # @return [Hash] The metadata for attachments.  (See example.)
       def self.meta(client)
-        response = client.get(client.options[:rest_base_path] + '/attachment/meta')
+        response = client.get("#{client.options[:rest_base_path]}/attachment/meta")
         parse_json(response.body)
       end
 
+      # Opens a file streaming the download of the attachment.
+      # @example Write file contents to a file.
+      #   File.open('some-filename', 'wb') do |output|
+      #     download_file do |file|
+      #       IO.copy_stream(file, output)
+      #     end
+      #   end
+      # @example Stream file contents for an HTTP response.
+      #   response.headers[ "Content-Type" ] = "application/octet-stream"
+      #   download_file do |file|
+      #     chunk = file.read(8000)
+      #     while chunk.present? do
+      #       response.stream.write(chunk)
+      #       chunk = file.read(8000)
+      #     end
+      #   end
+      #   response.stream.close
+      # @param [Hash] headers Any additional headers to call Jira.
+      # @yield |file|
+      # @yieldparam [IO] file The IO object streaming the download.
+      def download_file(headers = {}, &)
+        default_headers = client.options[:default_headers]
+        URI.parse(content).open(default_headers.merge(headers), &)
+      end
+
+      # Downloads the file contents as a string object.
+      #
+      # Note that this reads the contents into a ruby string in memory.
+      # A file might be very large so it is recommended to avoid this unless you are certain about doing so.
+      # Use the download_file method instead and avoid calling the read method without a limit.
+      #
+      # @example Save file contents to a string.
+      #   content = download_contents
+      # @param [Hash] headers Any additional headers to call Jira.
+      # @return [String,NilClass] The file contents.
+      def download_contents(headers = {})
+        download_file(headers, &:read)
+      end
+
+      # Uploads a file as an attachment to its issue.
+      #
+      # Filename used will be the basename of the given file.
+      #
+      # @example Save a file as an attachment
+      #   issue =  JIRA::Resource::Issue.find(client, 'SUP-3000', { fields: 'attachment' } )
+      #   attachment = issue.attachments.build
+      #   attachment.save!( { file: path, mimeType: 'text/plain' } )
+      # @param [Hash] attrs the options to create a message with.
+      # @option attrs [IO,String] :file The file to upload, either a file object or a file path to find the file.
+      # @option attrs [String] :mimeType The MIME type of the file.
+      # @raise [JIRA::HTTPError] if failed
       def save!(attrs, path = url)
         file = attrs['file'] || attrs[:file] # Keep supporting 'file' parameter as a string for backward compatibility
         mime_type = attrs[:mimeType] || 'application/binary'
 
         headers = { 'X-Atlassian-Token' => 'nocheck' }
-        data = { 'file' => UploadIO.new(file, mime_type, file) }
+        data = { 'file' => Multipart::Post::UploadIO.new(file, mime_type, file) }
 
-        response = client.post_multipart(path, data , headers)
+        response = client.post_multipart(path, data, headers)
 
         set_attributes(attrs, response)
 

data/lib/jira/resource/board.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'cgi'
 
 module JIRA
@@ -7,7 +9,7 @@ module JIRA
 
     class Board < JIRA::Base
       def self.all(client)
-        path = path_base(client) + '/board'
+        path = "#{path_base(client)}/board"
         response = client.get(path)
         json = parse_json(response.body)
         results = json['values']
@@ -74,13 +76,13 @@ module JIRA
       end
 
       def add_issue_to_backlog(issue)
-        client.post(path_base(client) + '/backlog/issue', { issues: [issue.id] }.to_json)
+        client.post("#{path_base(client)}/backlog/issue", { issues: [issue.id] }.to_json)
       end
 
       private
 
       def self.path_base(client)
-        client.options[:context_path] + '/rest/agile/1.0'
+        "#{client.options[:context_path]}/rest/agile/1.0"
       end
 
       def path_base(client)

data/lib/jira/resource/board_configuration.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module JIRA
   module Resource
     class BoardConfigurationFactory < JIRA::BaseFactory # :nodoc:

data/lib/jira/resource/comment.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module JIRA
   module Resource
     class CommentFactory < JIRA::BaseFactory # :nodoc:

data/lib/jira/resource/component.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module JIRA
   module Resource
     class ComponentFactory < JIRA::BaseFactory # :nodoc:

data/lib/jira/resource/createmeta.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module JIRA
   module Resource
     class CreatemetaFactory < JIRA::BaseFactory # :nodoc:
@@ -36,7 +38,7 @@ module JIRA
 
         json = parse_json(response.body)
         json['projects'].map do |attrs|
-          new(client, attrs: attrs)
+          new(client, attrs:)
         end
       end
     end

data/lib/jira/resource/field.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module JIRA
   module Resource
     class FieldFactory < JIRA::BaseFactory # :nodoc:
@@ -19,43 +21,42 @@ module JIRA
 
       def self.map_fields(client)
         field_map = {}
-        field_map_reverse = {}
         fields = client.Field.all
 
         # two pass approach, so that a custom field with the same name
         # as a system field can't take precedence
         fields.each do |f|
           next if f.custom
+
           name = safe_name(f.name)
-          field_map_reverse[f.id] = [f.name, name] # capture both the official name, and the mapped name
           field_map[name] = f.id
         end
 
-        fields.each do |f|
+        fields.each do |f| # rubocop:disable Style/CombinableLoops
           next unless f.custom
+
           name = if field_map.key? f.name
                    renamed = safer_name(f.name, f.id)
                    warn "Duplicate Field name #{f.name} #{f.id} - renaming as #{renamed}"
                    renamed
                  else
                    safe_name(f.name)
-          end
-          field_map_reverse[f.id] = [f.name, name] # capture both the official name, and the mapped name
+                 end
           field_map[name] = f.id
         end
 
-        client.cache.field_map_reverse = field_map_reverse # not sure where this will be used yet, but sure to be useful
-        client.cache.field_map = field_map
+        client.field_map_cache = field_map
       end
 
       def self.field_map(client)
-        client.cache.field_map
+        client.field_map_cache
       end
 
       def self.name_to_id(client, field_name)
         field_name = field_name.to_s
-        return field_name unless client.cache.field_map && client.cache.field_map[field_name]
-        client.cache.field_map[field_name]
+        return field_name unless client.field_map_cache && client.field_map_cache[field_name]
+
+        client.field_map_cache[field_name]
       end
 
       def respond_to?(method_name, _include_all = false)
@@ -66,7 +67,7 @@ module JIRA
         end
       end
 
-      def method_missing(method_name, *args, &block)
+      def method_missing(method_name, *args, &)
         if attrs.key?(method_name.to_s)
           attrs[method_name.to_s]
         else
@@ -74,7 +75,7 @@ module JIRA
           if attrs.key?(official_name)
             attrs[official_name]
           else
-            super(method_name, *args, &block)
+            super
           end
         end
       end

data/lib/jira/resource/filter.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module JIRA
   module Resource
     class FilterFactory < JIRA::BaseFactory # :nodoc:

data/lib/jira/resource/issue.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'cgi'
 require 'json'
 
@@ -6,46 +8,59 @@ module JIRA
     class IssueFactory < JIRA::BaseFactory # :nodoc:
     end
 
+    # This class provides the Issue object <-> REST mapping for JIRA::Resource::Issue derived class,
+    # i.e. the Create, Retrieve, Update, Delete lifecycle methods.
+    #
+    # == Lifecycle methods
+    #
+    # === Retrieving all issues
+    #
+    #   client.Issue.all
+    #
+    # === Retrieving a single issue
+    #
+    #   options = { expand: 'editmeta' }
+    #   issue = client.Issue.find("SUP-3000", options)
+    #
+    # === Creating a new issue
+    #
+    #   issue = client.Issue.build(fields: { summary: 'New issue', project: { key: 'SUP' }, issuetype: { name: 'Bug' } })
+    #   issue.save
+    #
+    # === Updating an issue
+    #
+    #   issue = client.Issue.find("SUP-3000")
+    #   issue.save(fields: { summary: 'Updated issue' })
+    #
+    # === Deleting an issue
+    #
+    #   issue = client.Issue.find("SUP-3000")
+    #   issue.delete
+    #
     class Issue < JIRA::Base
-      has_one :reporter,  class: JIRA::Resource::User,
-                          nested_under: 'fields'
-      has_one :assignee,  class: JIRA::Resource::User,
-                          nested_under: 'fields'
-      has_one :project,   nested_under: 'fields'
-
+      has_one :reporter, class: JIRA::Resource::User, nested_under: 'fields'
+      has_one :assignee, class: JIRA::Resource::User, nested_under: 'fields'
+      has_one :project, nested_under: 'fields'
       has_one :issuetype, nested_under: 'fields'
-
-      has_one :priority,  nested_under: 'fields'
-
-      has_one :status,    nested_under: 'fields'
-
+      has_one :priority, nested_under: 'fields'
+      has_one :status, nested_under: 'fields'
+      has_one :resolution, nested_under: 'fields'
       has_many :transitions
-
       has_many :components, nested_under: 'fields'
-
       has_many :comments, nested_under: %w[fields comment]
-
-      has_many :attachments, nested_under: 'fields',
-                             attribute_key: 'attachment'
-
-      has_many :versions,    nested_under: 'fields'
-      has_many :fixVersions, class: JIRA::Resource::Version,
-                             nested_under: 'fields'
-
+      has_many :attachments, nested_under: 'fields', attribute_key: 'attachment'
+      has_many :versions, nested_under: 'fields'
+      has_many :fixVersions, class: JIRA::Resource::Version, nested_under: 'fields'
       has_many :worklogs, nested_under: %w[fields worklog]
-      has_one :sprint, class: JIRA::Resource::Sprint,
-                       nested_under: 'fields'
-
-      has_many :closed_sprints, class: JIRA::Resource::Sprint,
-                                nested_under: 'fields', attribute_key: 'closedSprints'
-
+      has_one :sprint, class: JIRA::Resource::Sprint, nested_under: 'fields'
+      has_many :closed_sprints, class: JIRA::Resource::Sprint, nested_under: 'fields', attribute_key: 'closedSprints'
       has_many :issuelinks, nested_under: 'fields'
-
       has_many :remotelink, class: JIRA::Resource::Remotelink
+      has_many :watchers, attribute_key: 'watches', nested_under: %w[fields watches]
 
-      has_many :watchers,   attribute_key: 'watches',
-                            nested_under: %w[fields watches]
-
+      # Get collection of issues.
+      # @param client [JIRA::Client]
+      # @return [Array<JIRA::Resource::Issue>]
       def self.all(client)
         start_at = 0
         max_results = 1000
@@ -59,6 +74,7 @@ module JIRA
             result.push(client.Issue.build(issue))
           end
           break if json['issues'].empty?
+
           start_at += json['issues'].size
         end
         result
@@ -67,10 +83,14 @@ module JIRA
       def self.jql(client, jql, options = { fields: nil, start_at: nil, max_results: nil, expand: nil, validate_query: true })
         url = client.options[:rest_base_path] + "/search?jql=#{CGI.escape(jql)}"
 
-        url << "&fields=#{options[:fields].map { |value| CGI.escape(client.Field.name_to_id(value)) }.join(',')}" if options[:fields]
+        if options[:fields]
+          url << "&fields=#{options[:fields].map do |value|
+                              CGI.escape(client.Field.name_to_id(value))
+                            end.join(',')}"
+        end
         url << "&startAt=#{CGI.escape(options[:start_at].to_s)}" if options[:start_at]
         url << "&maxResults=#{CGI.escape(options[:max_results].to_s)}" if options[:max_results]
-        url << '&validateQuery=false' if options[:validate_query] === false
+        url << '&validateQuery=false' if options[:validate_query] === false # rubocop:disable Style/CaseEquality
 
         if options[:expand]
           options[:expand] = [options[:expand]] if options[:expand].is_a?(String)
@@ -79,9 +99,8 @@ module JIRA
 
         response = client.get(url)
         json = parse_json(response.body)
-        if options[:max_results] && (options[:max_results] == 0)
-          return json['total']
-        end
+        return json['total'] if options[:max_results]&.zero?
+
         json['issues'].map do |issue|
           client.Issue.build(issue)
         end
@@ -90,16 +109,24 @@ module JIRA
       # Fetches the attributes for the specified resource from JIRA unless
       # the resource is already expanded and the optional force reload flag
       # is not set
+      # @param [Boolean] reload
+      # @param [Hash] query_params
+      # @option query_params [String] :fields
+      # @option query_params [String] :expand
+      # @option query_params [Integer] :startAt
+      # @option query_params [Integer] :maxResults
+      # @return [void]
       def fetch(reload = false, query_params = {})
         return if expanded? && !reload
+
         response = client.get(url_with_query_params(url, query_params))
         set_attrs_from_response(response)
-        if @attrs && @attrs['fields'] && @attrs['fields']['worklog'] && (@attrs['fields']['worklog']['total'] > @attrs['fields']['worklog']['maxResults'])
+        if @attrs && @attrs['fields'] &&
+           @attrs['fields']['worklog'] &&
+           (@attrs['fields']['worklog']['total'] > @attrs['fields']['worklog']['maxResults'])
           worklog_url = client.options[:rest_base_path] + "/#{self.class.endpoint_name}/#{id}/worklog"
           response = client.get(worklog_url)
-          unless response.body.nil? || (response.body.length < 2)
-            set_attrs({ 'fields' => { 'worklog' => self.class.parse_json(response.body) } }, false)
-          end
+          set_attrs({ 'fields' => { 'worklog' => self.class.parse_json(response.body) } }, false) unless response.body.nil? || (response.body.length < 2)
         end
         @expanded = true
       end
@@ -112,15 +139,19 @@ module JIRA
         json['fields']
       end
 
+      # @private
       def respond_to?(method_name, _include_all = false)
-        if attrs.key?('fields') && [method_name.to_s, client.Field.name_to_id(method_name)].any? { |k| attrs['fields'].key?(k) }
+        if attrs.key?('fields') && [method_name.to_s, client.Field.name_to_id(method_name)].any? do |k|
+             attrs['fields'].key?(k)
+           end
           true
         else
           super(method_name)
         end
       end
 
-      def method_missing(method_name, *args, &block)
+      # @private
+      def method_missing(method_name, *args, &)
         if attrs.key?('fields')
           if attrs['fields'].key?(method_name.to_s)
             attrs['fields'][method_name.to_s]
@@ -129,13 +160,33 @@ module JIRA
             if attrs['fields'].key?(official_name)
               attrs['fields'][official_name]
             else
-              super(method_name, *args, &block)
+              super
             end
           end
         else
-          super(method_name, *args, &block)
+          super
         end
       end
+
+      # @!method self.find(client, key, options = {})
+      #   Gets/fetches an issue from JIRA.
+      #
+      #   Note: attachments are not fetched by default.
+      #
+      #   @param [JIRA::Client] client
+      #   @param [String] key the key of the issue to find
+      #   @param [Hash] options the options to find the issue with
+      #   @option options [String] :fields the fields to include in the response
+      #   @return [JIRA::Resource::Issue] the found issue
+      #   @example Find an issue
+      #   JIRA::Resource::Issue.find(client, "SUP-3000", { fields: %w[summary description attachment created ] } )
+      #
+      # @!method self.build(attrs = {})
+      #   Constructs a new issue object.
+      #   @param [Hash] attrs the attributes to initialize the issue with
+      #   @return [JIRA::Resource::Issue] the new issue
+      #
+      # .
     end
   end
 end

data/lib/jira/resource/issue_picker_suggestions.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module JIRA
   module Resource
     class IssuePickerSuggestionsFactory < JIRA::BaseFactory # :nodoc:
@@ -6,7 +8,8 @@ module JIRA
     class IssuePickerSuggestions < JIRA::Base
       has_many :sections, class: JIRA::Resource::IssuePickerSuggestionsIssue
 
-      def self.all(client, query = '', options = { current_jql: nil, current_issue_key: nil, current_project_id: nil, show_sub_tasks: nil, show_sub_tasks_parent: nil })
+      def self.all(client, query = '', options = { current_jql: nil, current_issue_key: nil, current_project_id: nil,
+                                                   show_sub_tasks: nil, show_sub_tasks_parent: nil })
         url = client.options[:rest_base_path] + "/issue/picker?query=#{CGI.escape(query)}"
 
         url << "&currentJQL=#{CGI.escape(options[:current_jql])}" if options[:current_jql]

data/lib/jira/resource/issue_picker_suggestions_issue.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module JIRA
   module Resource
     class IssuePickerSuggestionsIssueFactory < JIRA::BaseFactory # :nodoc:

data/lib/jira/resource/issuelink.rb

@@ -1,11 +1,14 @@
+# frozen_string_literal: true
+
 module JIRA
   module Resource
     class IssuelinkFactory < JIRA::BaseFactory # :nodoc:
     end
 
-    # Because of circular dependency Issue->IssueLink->Issue
-    # we have to declare JIRA::Resource::Issue class.
-    class Issue < JIRA::Base; end
+    class Issue < JIRA::Base
+      # Because of circular dependency Issue->IssueLink->Issue
+      # we have to declare JIRA::Resource::Issue class.
+    end
 
     class Issuelink < JIRA::Base
       has_one :type, class: JIRA::Resource::Issuelinktype

data/lib/jira/resource/issuelinktype.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module JIRA
   module Resource
     class IssuelinktypeFactory < JIRA::BaseFactory # :nodoc:

data/lib/jira/resource/issuetype.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module JIRA
   module Resource
     class IssuetypeFactory < JIRA::BaseFactory # :nodoc:

data/lib/jira/resource/priority.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module JIRA
   module Resource
     class PriorityFactory < JIRA::BaseFactory # :nodoc:

data/lib/jira/resource/project.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module JIRA
   module Resource
     class ProjectFactory < JIRA::BaseFactory # :nodoc:
@@ -15,7 +17,7 @@ module JIRA
 
       # Returns all the issues for this project
       def issues(options = {})
-        search_url = client.options[:rest_base_path] + '/search'
+        search_url = "#{client.options[:rest_base_path]}/search"
         query_params = { jql: "project=\"#{key}\"" }
         query_params.update Base.query_params_for_search(options)
         response = client.get(url_with_query_params(search_url, query_params))
@@ -26,7 +28,7 @@ module JIRA
       end
 
       def users(start_at: nil, max_results: nil)
-        users_url = client.options[:rest_base_path] + '/user/assignable/search'
+        users_url = "#{client.options[:rest_base_path]}/user/assignable/search"
         query_params = { project: key_value }
         query_params['startAt'] = start_at if start_at
         query_params['maxResults'] = max_results if max_results

data/lib/jira/resource/rapidview.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'cgi'
 
 module JIRA
@@ -7,7 +9,7 @@ module JIRA
 
     class RapidView < JIRA::Base
       def self.all(client)
-        response = client.get(path_base(client) + '/rapidview')
+        response = client.get("#{path_base(client)}/rapidview")
         json = parse_json(response.body)
         json['views'].map do |view|
           client.RapidView.build(view)
@@ -44,7 +46,7 @@ module JIRA
 
       def sprints(options = {})
         params = { includeHistoricSprints: options.fetch(:include_historic, false),
-                   includeFutureSprints:   options.fetch(:include_future, false) }
+                   includeFutureSprints: options.fetch(:include_future, false) }
         response = client.get(path_base(client) + "/sprintquery/#{id}?#{params.to_query}")
         json = self.class.parse_json(response.body)
         json['sprints'].map do |sprint|
@@ -56,7 +58,7 @@ module JIRA
       private
 
       def self.path_base(client)
-        client.options[:context_path] + '/rest/greenhopper/1.0'
+        "#{client.options[:context_path]}/rest/greenhopper/1.0"
       end
 
       def path_base(client)

data/lib/jira/resource/remotelink.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module JIRA
   module Resource
     class RemotelinkFactory < JIRA::BaseFactory # :nodoc:

data/lib/jira/resource/resolution.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module JIRA
   module Resource
     class ResolutionFactory < JIRA::BaseFactory # :nodoc:

data/lib/jira/resource/serverinfo.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module JIRA
   module Resource
     class ServerInfoFactory < JIRA::BaseFactory # :nodoc: