Get the `merge-base` of 2 refs trough the API

This adds an endpoint to get the common ancestor of 2 refs from the API.

changelogs/unreleased/bvl-merge-base-api.yml

+---
+title: Get the `merge-base` of 2 refs trough the API
+merge_request: 20929
+author:
+type: added

doc/api/repositories.md

@@ -204,3 +204,39 @@ Response:
   "deletions": 244
 }]
 ```
+
+## Merge Base
+
+Get the common ancestor for 2 refs.
+
+```
+GET /projects/:id/repository/merge_base
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
+| `refs` | array | yes | The refs to find the common ancestor of, for now only 2 refs are supported |
+
+```bash
+curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/repository/merge_base?refs[]=304d257dcb821665ab5110318fc58a007bd104ed&refs[]=0031876facac3f2b2702a0e53a26e89939a42209"
+```
+
+Example response:
+
+```json
+{
+	"id": "1a0b36b3cdad1d2ee32457c102a8c0b7056fa863",
+	"short_id": "1a0b36b3",
+	"title": "Initial commit",
+	"created_at": "2014-02-27T08:03:18.000Z",
+	"parent_ids": [],
+	"message": "Initial commit\n",
+	"author_name": "Dmitriy Zaporozhets",
+	"author_email": "dmitriy.zaporozhets@gmail.com",
+	"authored_date": "2014-02-27T08:03:18.000Z",
+	"committer_name": "Dmitriy Zaporozhets",
+	"committer_email": "dmitriy.zaporozhets@gmail.com",
+	"committed_date": "2014-02-27T08:03:18.000Z"
+}
+```

lib/api/repositories.rb

@@ -123,6 +123,41 @@ module API
           not_found!
         end
       end
+
+      desc 'Get the common ancestor between commits' do
+        success Entities::Commit
+      end
+      params do
+        # For now we just support 2 refs passed, but `merge-base` supports
+        # multiple defining this as an Array instead of 2 separate params will
+        # make sure we don't need to deprecate this API in favor of one
+        # supporting multiple commits when this functionality gets added to
+        # Gitaly
+        requires :refs, type: Array[String]
+      end
+      get ':id/repository/merge_base' do
+        refs = params[:refs]
+
+        unless refs.size == 2
+          render_api_error!('Provide exactly 2 refs', 400)
+        end
+
+        commits = user_project.repository.commits_by(oids: refs)
+        unknown_refs = Hash[refs.zip(commits)]
+                         .select { |ref, commit| commit.nil? }.keys
+
+        if unknown_refs.any?
+          ref_noun = 'ref'.pluralize(unknown_refs.size)
+          message = "Could not find #{ref_noun}: #{unknown_refs.join(', ')}"
+          render_api_error!(message, 400)
+        end
+
+        if merge_base = user_project.repository.merge_base(*commits)
+          present user_project.commit_by(oid: merge_base), with: Entities::Commit
+        else
+          not_found!("Merge Base")
+        end
+      end
     end
   end
 end

spec/requests/api/repositories_spec.rb

@@ -465,4 +465,77 @@ describe API::Repositories do
       end
     end
   end
+
+  describe 'GET :id/repository/merge_base' do
+    let(:refs) do
+      %w(304d257dcb821665ab5110318fc58a007bd104ed 0031876facac3f2b2702a0e53a26e89939a42209)
+    end
+
+    subject(:request) do
+      get(api("/projects/#{project.id}/repository/merge_base", current_user), refs: refs)
+    end
+
+    shared_examples 'merge base' do
+      it 'returns the common ancestor' do
+        request
+
+        expect(response).to have_gitlab_http_status(:success)
+        expect(json_response['id']).to be_present
+      end
+    end
+
+    context 'when unauthenticated', 'and project is public' do
+      it_behaves_like 'merge base' do
+        let(:project) { create(:project, :public, :repository) }
+        let(:current_user) { nil }
+      end
+    end
+
+    context 'when unauthenticated', 'and project is private' do
+      it_behaves_like '404 response' do
+        let(:current_user) { nil }
+        let(:message) { '404 Project Not Found' }
+      end
+    end
+
+    context 'when authenticated', 'as a developer' do
+      it_behaves_like 'merge base' do
+        let(:current_user) { user }
+      end
+    end
+
+    context 'when authenticated', 'as a guest' do
+      it_behaves_like '403 response' do
+        let(:current_user) { guest }
+      end
+    end
+
+    context 'when passing refs that do not exist' do
+      it_behaves_like '400 response' do
+        let(:refs) { %w(304d257dcb821665ab5110318fc58a007bd104ed missing) }
+        let(:current_user) { user }
+        let(:message) { 'Could not find ref: missing' }
+      end
+    end
+
+    context 'when passing refs that do not have a merge base' do
+      it_behaves_like '404 response' do
+        let(:refs) { ['304d257dcb821665ab5110318fc58a007bd104ed', TestEnv::BRANCH_SHA['orphaned-branch']] }
+        let(:current_user) { user }
+        let(:message) { '404 Merge Base Not Found' }
+      end
+    end
+
+    context 'when not enough refs are passed' do
+      let(:refs) { %w(only-one) }
+      let(:current_user) { user }
+
+      it 'renders a bad request error' do
+        request
+
+        expect(response).to have_gitlab_http_status(:bad_request)
+        expect(json_response['message']).to eq('Provide exactly 2 refs')
+      end
+    end
+  end
 end