pull_requests.rb

# frozen_string_literal: true

module Octokit
  class Client
    # Methods for the Pull Requests API
    #
    # @see https://developer.github.com/v3/pulls/
    module PullRequests
      # List pull requests for a repository
      #
      # @overload pull_requests(repo, options)
      #   @param repo [Integer, String, Hash, Repository] A GitHub repository
      #   @param options [Hash] Method options
      #   @option options [String] :state `open` or `closed` or `all`.
      # @return [Array<Sawyer::Resource>] Array of pulls
      # @see https://developer.github.com/v3/pulls/#list-pull-requests
      # @example
      #   Octokit.pull_requests('rails/rails', :state => 'closed')
      def pull_requests(repo, options = {})
        paginate "#{Repository.path repo}/pulls", options
      end
      alias pulls pull_requests

      # Get a pull request
      #
      # @see https://developer.github.com/v3/pulls/#get-a-single-pull-request
      # @param repo [Integer, String, Hash, Repository] A GitHub repository
      # @param number [Integer] Number of the pull request to fetch
      # @return [Sawyer::Resource] Pull request info
      # @example
      #   Octokit.pull_request('rails/rails', 42, :state => 'closed')
      def pull_request(repo, number, options = {})
        get "#{Repository.path repo}/pulls/#{number}", options
      end
      alias pull pull_request

      # Create a pull request
      #
      # @see https://developer.github.com/v3/pulls/#create-a-pull-request
      # @param repo [Integer, String, Hash, Repository] A GitHub repository
      # @param base [String] The branch (or git ref) you want your changes
      #                      pulled into. This should be an existing branch on the current
      #                      repository. You cannot submit a pull request to one repo that requests
      #                      a merge to a base of another repo.
      # @param head [String] The branch (or git ref) where your changes are implemented.
      # @param title [String] Title for the pull request
      # @param body [String] The body for the pull request (optional). Supports GFM.
      # @return [Sawyer::Resource] The newly created pull request
      # @example
      #   @client.create_pull_request("octokit/octokit.rb", "master", "feature-branch",
      #     "Pull Request title", "Pull Request body")
      def create_pull_request(repo, base, head, title, body = nil, options = {})
        pull = {
          base: base,
          head: head,
          title: title
        }
        pull[:body] = body unless body.nil?
        post "#{Repository.path repo}/pulls", options.merge(pull)
      end

      # Create a pull request from existing issue
      #
      # @see https://developer.github.com/v3/pulls/#alternative-input
      # @param repo [Integer, String, Hash, Repository] A GitHub repository
      # @param base [String] The branch (or git ref) you want your changes
      #                      pulled into. This should be an existing branch on the current
      #                      repository. You cannot submit a pull request to one repo that requests
      #                      a merge to a base of another repo.
      # @param head [String] The branch (or git ref) where your changes are implemented.
      # @param issue [Integer] Number of Issue on which to base this pull request
      # @return [Sawyer::Resource] The newly created pull request
      def create_pull_request_for_issue(repo, base, head, issue, options = {})
        pull = {
          base: base,
          head: head,
          issue: issue
        }
        post "#{Repository.path repo}/pulls", options.merge(pull)
      end

      # Update a pull request
      # @overload update_pull_request(repo, number, title=nil, body=nil, state=nil, options = {})
      #   @deprecated
      #   @param repo [Integer, String, Hash, Repository] A GitHub repository.
      #   @param number [Integer] Number of pull request to update.
      #   @param title [String] Title for the pull request.
      #   @param body [String] Body content for pull request. Supports GFM.
      #   @param state [String] State of the pull request. `open` or `closed`.
      # @overload update_pull_request(repo, number,  options = {})
      #   @param repo [Integer, String, Hash, Repository] A GitHub repository.
      #   @param number [Integer] Number of pull request to update.
      #   @option options [String] :title Title for the pull request.
      #   @option options [String] :body Body for the pull request.
      #   @option options [String] :state State for the pull request.
      # @return [Sawyer::Resource] Hash representing updated pull request.
      # @see https://developer.github.com/v3/pulls/#update-a-pull-request
      # @example
      #   @client.update_pull_request('octokit/octokit.rb', 67, 'new title', 'updated body', 'closed')
      # @example Passing nil for optional attributes to update specific attributes.
      #   @client.update_pull_request('octokit/octokit.rb', 67, nil, nil, 'open')
      # @example Empty body by passing empty string
      #   @client.update_pull_request('octokit/octokit.rb', 67, nil, '')
      def update_pull_request(*args)
        arguments = Octokit::Arguments.new(args)
        repo = arguments.shift
        number = arguments.shift
        patch "#{Repository.path repo}/pulls/#{number}", arguments.options
      end

      # Close a pull request
      #
      # @param repo [Integer, String, Hash, Repository] A GitHub repository.
      # @param number [Integer] Number of pull request to update.
      # @return [Sawyer::Resource] Hash representing updated pull request.
      # @see https://developer.github.com/v3/pulls/#update-a-pull-request
      # @example
      #   @client.close_pull_request('octokit/octokit.rb', 67)
      def close_pull_request(repo, number, options = {})
        options.merge! state: 'closed'
        update_pull_request(repo, number, options)
      end

      # List commits on a pull request
      #
      # @see https://developer.github.com/v3/pulls/#list-commits-on-a-pull-request
      # @param repo [Integer, String, Hash, Repository] A GitHub repository
      # @param number [Integer] Number of pull request
      # @return [Array<Sawyer::Resource>] List of commits
      def pull_request_commits(repo, number, options = {})
        paginate "#{Repository.path repo}/pulls/#{number}/commits", options
      end
      alias pull_commits pull_request_commits

      # List pull request comments for a repository
      #
      # By default, Review Comments are ordered by ascending ID.
      #
      # @param repo [Integer, String, Repository, Hash] A GitHub repository
      # @param options [Hash] Optional parameters
      # @option options [String] :sort created or updated
      # @option options [String] :direction asc or desc. Ignored without sort
      #   parameter.
      # @option options [String] :since Timestamp in ISO 8601
      #   format: YYYY-MM-DDTHH:MM:SSZ
      #
      # @return [Array] List of pull request review comments.
      #
      # @see https://developer.github.com/v3/pulls/comments/#list-comments-in-a-repository
      #
      # @example Get the pull request review comments in the octokit repository
      #   @client.issues_comments("octokit/octokit.rb")
      #
      # @example Get review comments, sort by updated asc since a time
      #   @client.pull_requests_comments("octokit/octokit.rb", {
      #     :sort => 'updated',
      #     :direction => 'asc',
      #     :since => '2010-05-04T23:45:02Z'
      #   })
      def pull_requests_comments(repo, options = {})
        paginate("#{Repository.path repo}/pulls/comments", options)
      end
      alias pulls_comments   pull_requests_comments
      alias reviews_comments pull_requests_comments

      # List comments on a pull request
      #
      # @see https://developer.github.com/v3/pulls/comments/#list-comments-on-a-pull-request
      # @param repo [Integer, String, Hash, Repository] A GitHub repository
      # @param number [Integer] Number of pull request
      # @return [Array<Sawyer::Resource>] List of comments
      def pull_request_comments(repo, number, options = {})
        # return the comments for a pull request
        paginate("#{Repository.path repo}/pulls/#{number}/comments", options)
      end
      alias pull_comments   pull_request_comments
      alias review_comments pull_request_comments

      # Get a pull request comment
      #
      # @param repo [Integer, String, Hash, Repository] A GitHub repository
      # @param comment_id [Integer] Id of comment to get
      # @return [Sawyer::Resource] Hash representing the comment
      # @see https://developer.github.com/v3/pulls/comments/#get-a-single-comment
      # @example
      #   @client.pull_request_comment("pengwynn/octkit", 1903950)
      def pull_request_comment(repo, comment_id, options = {})
        get "#{Repository.path repo}/pulls/comments/#{comment_id}", options
      end
      alias pull_comment   pull_request_comment
      alias review_comment pull_request_comment

      # Create a pull request comment
      #
      # @param repo [Integer, String, Hash, Repository] A GitHub repository
      # @param pull_id [Integer] Pull request id
      # @param body [String] Comment content
      # @param commit_id [String] Sha of the commit to comment on.
      # @param path [String] Relative path of the file to comment on.
      # @param line [Integer] Line index in the diff to comment on.
      #                       For a multi-line comment, the last line of the range
      #                       and specify 'start_line' in the 'options'.
      # @return [Sawyer::Resource] Hash representing the new comment
      # @deprecated The position will be deprecated in the next major version. Please refer to the details below.
      # @see https://developer.github.com/v3/pulls/comments/#create-a-comment
      # @example
      #   @client.create_pull_request_comment("octokit/octokit.rb", 163, ":shipit:",
      #     "2d3201e4440903d8b04a5487842053ca4883e5f0", "lib/octokit/request.rb", 47)
      def create_pull_request_comment(repo, pull_id, body, commit_id, path, line, options = {})
        options.merge!({
                         body: body,
                         commit_id: commit_id,
                         path: path,
                         line: line
                       })
        post "#{Repository.path repo}/pulls/#{pull_id}/comments", options
      end
      alias create_pull_comment create_pull_request_comment
      alias create_view_comment create_pull_request_comment

      # Create reply to a pull request comment
      #
      # @param repo [Integer, String, Hash, Repository] A GitHub repository
      # @param pull_id [Integer] Pull request id
      # @param body [String] Comment contents
      # @param comment_id [Integer] Comment id to reply to
      # @return [Sawyer::Resource] Hash representing new comment
      # @see https://developer.github.com/v3/pulls/comments/#create-a-comment
      # @example
      #   @client.create_pull_request_comment_reply("octokit/octokit.rb", 163, "done.", 1903950)
      def create_pull_request_comment_reply(repo, pull_id, body, comment_id, options = {})
        options.merge!({
                         body: body,
                         in_reply_to: comment_id
                       })
        post "#{Repository.path repo}/pulls/#{pull_id}/comments", options
      end
      alias create_pull_reply   create_pull_request_comment_reply
      alias create_review_reply create_pull_request_comment_reply

      # Update pull request comment
      #
      # @param repo [Integer, String, Hash, Repository] A GitHub repository
      # @param comment_id [Integer] Id of the comment to update
      # @param body [String] Updated comment content
      # @return [Sawyer::Resource] Hash representing the updated comment
      # @see https://developer.github.com/v3/pulls/comments/#edit-a-comment
      # @example
      #   @client.update_pull_request_comment("octokit/octokit.rb", 1903950, ":shipit:")
      def update_pull_request_comment(repo, comment_id, body, options = {})
        options.merge! body: body
        patch("#{Repository.path repo}/pulls/comments/#{comment_id}", options)
      end
      alias update_pull_comment   update_pull_request_comment
      alias update_review_comment update_pull_request_comment

      # Delete pull request comment
      #
      # @param repo [Integer, String, Hash, Repository] A GitHub repository
      # @param comment_id [Integer] Id of the comment to delete
      # @return [Boolean] True if deleted, false otherwise
      # @see https://developer.github.com/v3/pulls/comments/#delete-a-comment
      # @example
      #   @client.delete_pull_request_comment("octokit/octokit.rb", 1902707)
      def delete_pull_request_comment(repo, comment_id, options = {})
        boolean_from_response(:delete, "#{Repository.path repo}/pulls/comments/#{comment_id}", options)
      end
      alias delete_pull_comment   delete_pull_request_comment
      alias delete_review_comment delete_pull_request_comment

      # List files on a pull request
      #
      # @see https://developer.github.com/v3/pulls/#list-pull-requests-files
      # @param repo [Integer, String, Hash, Repository] A GitHub repository
      # @param number [Integer] Number of pull request
      # @return [Array<Sawyer::Resource>] List of files
      def pull_request_files(repo, number, options = {})
        paginate "#{Repository.path repo}/pulls/#{number}/files", options
      end
      alias pull_files pull_request_files

      # Update a pull request branch
      #
      # @see https://developer.github.com/v3/pulls/#update-a-pull-request-branch
      # @param repo [Integer, String, Hash, Repository] A GitHub repository
      # @param number [Integer] Number of pull request
      # @param options [Hash] Optional parameters (e.g. expected_head_sha)
      # @return [Boolean] True if the pull request branch has been updated
      def update_pull_request_branch(repo, number, options = {})
        boolean_from_response(:put, "#{Repository.path repo}/pulls/#{number}/update-branch", options)
      end

      # Merge a pull request
      #
      # @see https://developer.github.com/v3/pulls/#merge-a-pull-request-merge-button
      # @param repo [Integer, String, Hash, Repository] A GitHub repository
      # @param number [Integer] Number of pull request
      # @param commit_message [String] Optional commit message for the merge commit
      # @return [Array<Sawyer::Resource>] Merge commit info if successful
      def merge_pull_request(repo, number, commit_message = '', options = {})
        put "#{Repository.path repo}/pulls/#{number}/merge", options.merge({ commit_message: commit_message })
      end

      # Check pull request merge status
      #
      # @see https://developer.github.com/v3/pulls/#get-if-a-pull-request-has-been-merged
      # @param repo [Integer, String, Hash, Repository] A GitHub repository
      # @param number [Integer] Number of pull request
      # @return [Boolean] True if the pull request has been merged
      def pull_merged?(repo, number, options = {})
        boolean_from_response :get, "#{Repository.path repo}/pulls/#{number}/merge", options
      end
      alias pull_request_merged? pull_merged?
    end
  end
end