feat: New labels API (#577)

* Add new labels API + docs

* Add changelog

Author: bbugh

__tests__/unit/actions/labels.test.js

@@ -2,6 +2,76 @@ const Labels = require('../../../lib/actions/labels')
 const Helper = require('../../../__fixtures__/unit/helper')
 const UnSupportedSettingError = require('../../../lib/errors/unSupportedSettingError')
 
+test('check that replace replaces existing labels', async () => {
+  const labels = new Labels()
+  const context = createMockContext(['drop_label'])
+
+  const settings = {
+    replace: ['work in progress', 'development']
+  }
+
+  await labels.afterValidate(context, settings)
+  expect(context.octokit.issues.setLabels.mock.calls.length).toBe(1)
+  expect(context.octokit.issues.setLabels.mock.calls[0][0].labels).toStrictEqual({ labels: settings.replace })
+})
+
+test('check that add appends to existing labels', async () => {
+  const labels = new Labels()
+  const context = createMockContext(['another label', 'test label'])
+
+  const settings = {
+    add: ['production', 'deploy']
+  }
+
+  await labels.afterValidate(context, settings)
+  expect(context.octokit.issues.setLabels.mock.calls.length).toBe(1)
+  expect(context.octokit.issues.setLabels.mock.calls[0][0].labels).toStrictEqual({ labels: ['another label', 'test label', 'production', 'deploy'] })
+})
+
+test('check that delete removes from existing labels', async () => {
+  const labels = new Labels()
+  const context = createMockContext(['another label', 'test label', 'delete me', 'delete this too'])
+
+  const settings = {
+    delete: ['delete me', 'delete this too']
+  }
+
+  await labels.afterValidate(context, settings)
+  expect(context.octokit.issues.setLabels.mock.calls.length).toBe(1)
+  expect(context.octokit.issues.setLabels.mock.calls[0][0].labels).toStrictEqual({ labels: ['another label', 'test label'] })
+})
+
+test('check the order of replace, add, delete', async () => {
+  const labels = new Labels()
+  const context = createMockContext(['original label', 'another label'])
+
+  // order of operations is replace, then add, then delete
+  const settings = {
+    delete: ['not present', 'more adds'],
+    add: ['addition', 'more adds'],
+    replace: ['test present', 'not present']
+  }
+
+  await labels.afterValidate(context, settings)
+  expect(context.octokit.issues.setLabels.mock.calls.length).toBe(1)
+  expect(context.octokit.issues.setLabels.mock.calls[0][0].labels).toStrictEqual({ labels: ['test present', 'addition'] })
+})
+
+test('check that settings can be a single value', async () => {
+  const labels = new Labels()
+  const context = createMockContext(['original label', 'another label', 'delete me'])
+
+  const settings = {
+    delete: 'deletion',
+    add: 'addition',
+    replace: 'replace'
+  }
+
+  await labels.afterValidate(context, settings)
+  expect(context.octokit.issues.setLabels.mock.calls.length).toBe(1)
+  expect(context.octokit.issues.setLabels.mock.calls[0][0].labels).toStrictEqual({ labels: ['replace', 'addition'] })
+})
+
 test('check that unknown mode throw errors', async () => {
   const labels = new Labels()
   const context = Helper.mockContext()

docs/actions/labels.rst

@@ -1,6 +1,54 @@
 Labels
 ^^^^^^^^
 
+You can add, remove, and delete labels with one action.
+
+.. warning::
+    Using multiple ``do: labels`` in the same operation is not idempotent.
+    Use only one ``labels`` action per block for accurate labeling.
+
+You can add new labels, preserving existing ones
+
+::
+
+    - do: labels
+      add: 'Ready for Review'
+
+You can delete existing labels
+
+::
+
+    - do: labels
+      delete: [ 'Ready for Review', 'Triage' ]
+
+You can replace all current labels with new ones
+
+::
+
+    - do: labels
+      replace: [ 'Triage', 'Needs Deploy' ]
+
+You can also use any combination of these options. They can be listed in any
+order, but the action is always evaluated in the order of ``replace`` → ``add``
+→ ``delete``.
+
+::
+
+    - do: labels
+      replace: [ 'New Task', 'Not Useful' ]
+      add: [ 'Work in Progress', 'Needs Deploy' ]
+      delete: 'Not Useful'
+
+    # result: [ 'New Task', 'Work in Progress', 'Needs Deploy' ]
+
+
+``labels`` and ``mode``
+"""""""""""""""""""""""
+
+.. warning::
+    Using ``labels`` with ``mode`` is deprecated and will be removed in v3.
+    Use the ``add``, ``replace``, and ``delete`` options above for labeling.
+
 You can also add a set of the labels on an item
 
 ::

docs/changelog.rst

@@ -1,5 +1,6 @@
 CHANGELOG
 =====================================
+| August 10, 2021 : feat: New labels API `#577 <https://github.com/mergeability/mergeable/pull/577>`_
 | August 6, 2021 : feat: Add team assignment to request_review action `#574 <https://github.com/mergeability/mergeable/pull/574>`_
 | August 6, 2021 : feat: Support must_include and must_exclude regex as an array `#575 <https://github.com/mergeability/mergeable/pull/575>`_
 | July 19, 2021 : feat: Add ignore_drafts option to ignore drafts in stale validator `#565 <https://github.com/mergeability/mergeable/issues/565>`_

lib/actions/labels.js

@@ -6,6 +6,9 @@ const matchesPatterns = (label, patterns) => (
   patterns.some((pattern) => minimatch(label, pattern))
 )
 
+/**
+ * @deprecated
+ */
 const deleteLabels = async (context, issueNumber, labels, actionObj) => {
   const currentLabels = await actionObj.githubAPI.listLabelsOnIssue(context, issueNumber)
   // We get the current labels and filter out anything that matches
@@ -30,6 +33,30 @@ class Labels extends Action {
   async afterValidate (context, settings, name, results) {
     const items = this.getActionables(context, results)
 
+    if (settings.replace || settings.add || settings.delete) {
+      return Promise.all(
+        items.map(async issue => {
+          let labels
+
+          if (settings.replace) {
+            labels = [].concat(settings.replace)
+          } else {
+            labels = await this.githubAPI.listLabelsOnIssue(context, issue.number)
+          }
+
+          if (settings.add) {
+            labels = labels.concat(settings.add)
+          }
+
+          if (settings.delete) {
+            labels = labels.filter(label => !matchesPatterns(label, [].concat(settings.delete)))
+          }
+
+          return this.githubAPI.setLabels(context, issue.number, labels)
+        })
+      )
+    }
+
     const actions = {
       add: this.githubAPI.addLabels,
       delete: deleteLabels,