Implementation/COMMS-1046: Labels in the work package schema and labels-by-workspace API

app/models/label.rb

@@ -32,8 +32,24 @@ class Label < ApplicationRecord
   belongs_to :author, class_name: "User"
   has_many :labelings, dependent: :delete_all
 
+  USAGE_COUNT_SQL = "(SELECT COUNT(*) FROM labelings WHERE labelings.label_id = labels.id)"
+
   scope :with_usage_count, -> {
-    select("labels.*, (SELECT COUNT(*) FROM labelings WHERE labelings.label_id = labels.id) AS usage_count")
+    select("labels.*, #{USAGE_COUNT_SQL} AS usage_count")
+  }
+
+  scope :ordered_by_relevance_for, ->(project) {
+    used_in_project = Labeling
+                        .where(labelable_type: WorkPackage.name)
+                        .where("labelings.label_id = labels.id")
+                        .joins("INNER JOIN work_packages ON work_packages.id = labelings.labelable_id")
+                        .where(work_packages: { project_id: project })
+                        .arel
+                        .exists
+
+    reorder(used_in_project.desc)
+      .order(Arel.sql("#{USAGE_COUNT_SQL} DESC"))
+      .order("LOWER(labels.name) ASC")
   }
 
   normalizes :name, with: -> { it.squish }

app/models/type/attribute_groups.rb

@@ -50,6 +50,7 @@ module Type::AttributeGroups
         remaining_time: :estimates_and_progress,
         percentage_done: :estimates_and_progress,
         priority: :details,
+        labels: :details,
         # `:excluded` is not a "real" group. It's meant to exclude built in fields from the form
         observed_in_versions: :excluded
       }

app/models/type/attributes.rb

@@ -86,7 +86,8 @@ def all_work_package_form_attributes(merge_date: false)
       OpenProject::Cache.fetch_request_cached("all_work_package_form_attributes",
                                               *wp_cf_cache_parts,
                                               EXCLUDED.length,
-                                              merge_date) do
+                                              merge_date,
+                                              OpenProject::FeatureDecisions.work_package_labels_active?) do
         calculate_all_work_package_form_attributes(merge_date)
       end
     end
@@ -139,6 +140,10 @@ def skipped_attribute?(key, definition)
       # We always want to include the priority even if its required
       return false if key == "priority"
 
+      # Remove once the work_package_labels feature flag is removed; show_if
+      # on the schema representer property is never evaluated here.
+      return true if key == "labels" && !OpenProject::FeatureDecisions.work_package_labels_active?
+
       EXCLUDED.include?(key) || definition[:required]
     end
 

app/models/work_package/exports/formatters/labels.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+#-- copyright
+# OpenProject is an open source project management software.
+# Copyright (C) the OpenProject GmbH
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License version 3.
+#
+# OpenProject is a fork of ChiliProject, which is a fork of Redmine. The copyright follows:
+# Copyright (C) 2006-2013 Jean-Philippe Lang
+# Copyright (C) 2010-2013 the ChiliProject Team
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+#
+# See COPYRIGHT and LICENSE files for more details.
+#++
+
+module WorkPackage::Exports
+  module Formatters
+    class Labels < ::Exports::Formatters::Default
+      def self.apply?(attribute, _export_format)
+        attribute.to_sym == :labels
+      end
+
+      def retrieve_value(object)
+        object.labels.map(&:name)
+      end
+    end
+  end
+end

config/initializers/export_formats.rb

@@ -49,6 +49,7 @@
       formatter WorkPackage, WorkPackage::Exports::Formatters::XLS::DoneRatio
       formatter WorkPackage, WorkPackage::Exports::Formatters::PDF::Hours
       formatter WorkPackage, WorkPackage::Exports::Formatters::Id
+      formatter WorkPackage, WorkPackage::Exports::Formatters::Labels
       formatter WorkPackage, WorkPackage::Exports::Formatters::ProjectPhase
       formatter WorkPackage, WorkPackage::Exports::Formatters::SpentUnits
       formatter WorkPackage, WorkPackage::Exports::Formatters::TargetVersions

docs/api/apiv3/openapi-spec.yml

@@ -665,6 +665,8 @@ paths:
     "$ref": "./paths/workspace_work_packages_form.yml"
   "/api/v3/workspaces/{id}/versions":
     "$ref": "./paths/workspace_versions.yml"
+  "/api/v3/workspaces/{id}/labels":
+    "$ref": "./paths/workspace_labels.yml"
   "/api/v3/workspaces/schema":
     "$ref": "./paths/workspaces_schema.yml"
 

docs/api/apiv3/paths/workspace_labels.yml

@@ -0,0 +1,63 @@
+# /api/v3/workspaces/{id}/labels
+---
+get:
+  parameters:
+  - description: ID of the workspace whose labels will be listed
+    example: 1
+    in: path
+    name: id
+    required: true
+    schema:
+      type: integer
+  - name: filters
+    description: |-
+      JSON specifying filter conditions.
+      Currently supported filters are:
+
+      + name: filters labels by name, with the operators `~` (contains), `!~` (does not contain) and `**` (all)
+    example: '[{ "name": { "operator": "~", "values": ["bug"] } }]'
+    in: query
+    required: false
+    schema:
+      type: string
+  responses:
+    '200':
+      content:
+        application/hal+json:
+          examples:
+            'simple label collection':
+              $ref: "../components/examples/label_collection.yml"
+          schema:
+            "$ref": "../components/schemas/label_collection_model.yml"
+      description: OK
+      headers: {}
+    '400':
+      $ref: "../components/responses/invalid_query.yml"
+    '404':
+      content:
+        application/hal+json:
+          schema:
+            $ref: "../components/schemas/error_response.yml"
+          examples:
+            response:
+              value:
+                _type: Error
+                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
+                message: The specified workspace does not exist.
+      description: |-
+        Returned if the workspace does not exist or the client does not have sufficient permissions
+        to see it.
+
+        **Required permission:** view work packages (on given workspace)
+
+        *Note: A client without sufficient permissions shall not be able to test for the existence of a workspace.
+        That's why a 404 is returned here, even if a 403 might be more appropriate.*
+      headers: {}
+  tags:
+  - Labels
+  description: |-
+    Returns a paginated collection of all labels, ordered by relevance for the given workspace:
+    labels already used on work packages of the workspace come first, followed by the remaining labels.
+    Within each group, labels are ordered by how often they are used overall and then by name.
+  operationId: List_labels_by_workspace
+  summary: List labels by workspace

lib/api/v3/labels/labels_by_workspace_api.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+#-- copyright
+# OpenProject is an open source project management software.
+# Copyright (C) the OpenProject GmbH
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License version 3.
+#
+# OpenProject is a fork of ChiliProject, which is a fork of Redmine. The copyright follows:
+# Copyright (C) 2006-2013 Jean-Philippe Lang
+# Copyright (C) 2010-2013 the ChiliProject Team
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+#
+# See COPYRIGHT and LICENSE files for more details.
+#++
+
+module API
+  module V3
+    module Labels
+      class LabelsByWorkspaceAPI < ::API::OpenProjectAPI
+        resources :labels do
+          after_validation do
+            raise API::Errors::NotFound unless OpenProject::FeatureDecisions.work_package_labels_active?
+
+            authorize_in_project(:view_work_packages, project: @project)
+          end
+
+          get &::API::V3::Utilities::Endpoints::Index.new(model: Label,
+                                                          scope: -> { Label.ordered_by_relevance_for(@project) },
+                                                          self_path: -> { api_v3_paths.labels_by_workspace(@project.id) })
+                                                     .mount
+        end
+      end
+    end
+  end
+end

lib/api/v3/utilities/path_helper.rb

@@ -656,6 +656,10 @@ def self.views_type(type)
           index :label
           show :label
 
+          def self.labels_by_workspace(workspace_id)
+            "#{workspace(workspace_id)}/labels"
+          end
+
           def self.versions_available_projects
             "#{versions}/available_projects"
           end

lib/api/v3/work_packages/eager_loading/checksum.rb

@@ -56,24 +56,32 @@ def fetch_checksums_for(work_packages)
 
             protected
 
-            # Versions are a has_many, which would multiply rows in the
-            # left_joins/pluck above, so they enter as an aggregated subquery.
-            # A version can attach under more than one kind, so the kind is part
-            # of the value and of the order.
+            # Versions and labels are has_many and enter as aggregated subqueries;
+            # joining them in the pluck above would multiply the rows. A version
+            # can attach under more than one kind, so the kind is part of the
+            # value and of the order.
             VERSIONS_CHECKSUM_SQL = <<~SQL.squish
               (SELECT COALESCE(STRING_AGG(CONCAT(wpv.kind, v.id, v.updated_at), ',' ORDER BY wpv.kind, v.id), '')
                  FROM work_package_versions wpv
                  INNER JOIN versions v ON v.id = wpv.version_id
                 WHERE wpv.work_package_id = work_packages.id)
             SQL
 
+            LABELS_CHECKSUM_SQL = <<~SQL.squish
+              (SELECT COALESCE(STRING_AGG(CONCAT(l.id, l.updated_at), ',' ORDER BY l.id), '')
+                 FROM labelings lg
+                 INNER JOIN labels l ON l.id = lg.label_id
+                WHERE lg.labelable_type = '#{WorkPackage.polymorphic_name}' AND lg.labelable_id = work_packages.id)
+            SQL
+
             def md5_concat
               md5_parts = checksum_associations.flat_map do |association_name|
                 table_name = md5_checksum_table_name(association_name)
 
                 %W[#{table_name}.id #{table_name}.updated_at]
               end
               md5_parts << VERSIONS_CHECKSUM_SQL
+              md5_parts << LABELS_CHECKSUM_SQL
 
               <<-SQL
                 MD5(CONCAT(#{md5_parts.join(', ')}))

lib/api/v3/work_packages/schema/work_package_schema_representer.rb

@@ -42,7 +42,8 @@ class WorkPackageSchemaRepresenter < ::API::Decorators::SchemaRepresenter
                              dependencies: -> {
                                all_permissions_granted_to_user_under_project +
                                  [Setting.work_package_done_ratio,
-                                  Setting::WorkPackageMultipleVersions.active?]
+                                  Setting::WorkPackageMultipleVersions.active?,
+                                  OpenProject::FeatureDecisions.work_package_labels_active?]
                              }
 
           custom_field_injector type: :schema_representer
@@ -279,6 +280,12 @@ def initialize(schema, self_link:, **context)
                                    required: false,
                                    href_callback: ->(*) { assignee_user_autocompleter }
 
+          schema_with_allowed_link :labels,
+                                   type: "[]Label",
+                                   required: false,
+                                   show_if: ->(*) { OpenProject::FeatureDecisions.work_package_labels_active? },
+                                   href_callback: ->(*) { labels_autocompleter }
+
           schema_with_allowed_collection :type,
                                          value_representer: Types::TypeRepresenter,
                                          link_factory: ->(type) {
@@ -460,6 +467,12 @@ def all_permissions_granted_to_user_under_project
               .sort
           end
 
+          def labels_autocompleter
+            project_id = represented.work_package&.project_id
+
+            api_v3_paths.labels_by_workspace(project_id) if project_id
+          end
+
           def assignee_user_autocompleter
             work_package = represented.work_package
 

lib/api/v3/workspaces/nested_apis.rb

@@ -37,6 +37,7 @@ class NestedApis < ::API::OpenProjectAPI
         mount API::V3::WorkPackages::WorkPackagesByWorkspaceAPI
         mount API::V3::Categories::CategoriesByWorkspaceAPI
         mount API::V3::Versions::VersionsByProjectAPI
+        mount API::V3::Labels::LabelsByWorkspaceAPI
         mount API::V3::Queries::QueriesByWorkspaceAPI
         mount API::V3::Favorites::FavoriteActionsAPI, with: { favorite_object_getter: ->(*) { @project } }
       end

spec/lib/api/v3/utilities/path_helper_spec.rb

@@ -491,6 +491,12 @@
       it_behaves_like "api v3 path", "/versions/available_projects"
     end
 
+    describe "#labels_by_workspace" do
+      subject { helper.labels_by_workspace 42 }
+
+      it_behaves_like "api v3 path", "/workspaces/42/labels"
+    end
+
     describe "#versions_by_project" do
       subject { helper.versions_by_project 42 }
 

spec/lib/api/v3/work_packages/eager_loading/cache_checksum_integration_spec.rb

@@ -231,5 +231,61 @@
       expect(new_checksum)
         .not_to eql orig_checksum
     end
+
+    it "produces a different checksum when a label is added to the work package" do
+      label = create(:label)
+
+      create(:labeling, labelable: work_package, label:)
+
+      expect(new_checksum)
+        .not_to eql orig_checksum
+    end
+
+    it "produces a different checksum when a label is removed from the work package" do
+      label = create(:label)
+      labeling = create(:labeling, labelable: work_package, label:)
+
+      previous_checksum = EagerLoadingMockWrapper
+        .wrap(described_class, [work_package])
+        .first
+        .cache_checksum
+
+      labeling.destroy!
+
+      expect(new_checksum)
+        .not_to eql previous_checksum
+    end
+
+    it "produces a different checksum when an assigned label is renamed" do
+      label = create(:label)
+      create(:labeling, labelable: work_package, label:)
+
+      previous_checksum = EagerLoadingMockWrapper
+        .wrap(described_class, [work_package])
+        .first
+        .cache_checksum
+
+      label.update_attribute(:name, "Renamed label #{label.id}")
+
+      expect(new_checksum)
+        .not_to eql previous_checksum
+    end
+
+    it "produces the same checksum when a label not assigned to the work package changes" do
+      assigned_label = create(:label)
+      create(:labeling, labelable: work_package, label: assigned_label)
+      unassigned_label = create(:label)
+      create(:labeling, labelable: create(:work_package, project:), label: unassigned_label)
+
+      previous_checksum = EagerLoadingMockWrapper
+        .wrap(described_class, [work_package])
+        .first
+        .cache_checksum
+
+      unassigned_label.update_attribute(:name, "Renamed label #{unassigned_label.id}")
+
+      expect(new_checksum)
+        .to eql previous_checksum
+    end
   end
 end