Enable adding feature categories to controllers

This allows us to specify a feature category on controller
actions.

To specify a feature category can be specified on an entire controller
using:

  feature_category :source_code_management

The feature category can be scoped to a list of actions using the
`only` argument, actions can be excluded using the `except` argument.

  feature_category :source_code_management, only: [:create, :update]
  feature_category :source_code_management, except: [:metrics_reports]

`except` and `only` arguments can not be combined. When specifying
`unless` all other actions will get the category assigned.

The assignment can also be scoped using `if` and `unless` procs:

  feature_category :source_code_management,
                   unless: -> (action) { action.include?("reports") }
                   if: -> (action) { action.include?("widget") }

In this case, both procs need to be satisfied for the action to get
the category assigned.

The `spec/controllers/every_controller_spec.rb` will iterate over all
defined routes, and check the controller to see if a category is
assigned to all actions. The spec also validates if the used feature
categories are known. And if the actions used in `only` and `except`
configuration still exist as routes.

app/controllers/application_controller.rb

@@ -22,6 +22,7 @@ class ApplicationController < ActionController::Base
   include Impersonation
   include Gitlab::Logging::CloudflareHelper
   include Gitlab::Utils::StrongMemoize
+  include ControllerWithFeatureCategory
 
   before_action :authenticate_user!, except: [:route_not_found]
   before_action :enforce_terms!, if: :should_enforce_terms?

app/controllers/concerns/controller_with_feature_category.rb

+# frozen_string_literal: true
+
+module ControllerWithFeatureCategory
+  extend ActiveSupport::Concern
+  include Gitlab::ClassAttributes
+
+  class_methods do
+    def feature_category(category, config = {})
+      validate_config!(config)
+
+      category_config = Config.new(category, config[:only], config[:except], config[:if], config[:unless])
+      # Add the config to the beginning. That way, the last defined one takes precedence.
+      feature_category_configuration.unshift(category_config)
+    end
+
+    def feature_category_for_action(action)
+      category_config = feature_category_configuration.find { |config| config.matches?(action) }
+
+      category_config&.category || superclass_feature_category_for_action(action)
+    end
+
+    private
+
+    def validate_config!(config)
+      invalid_keys = config.keys - [:only, :except, :if, :unless]
+      if invalid_keys.any?
+        raise ArgumentError, "unknown arguments: #{invalid_keys} "
+      end
+
+      if config.key?(:only) && config.key?(:except)
+        raise ArgumentError, "cannot configure both `only` and `except`"
+      end
+    end
+
+    def feature_category_configuration
+      class_attributes[:feature_category_config] ||= []
+    end
+
+    def superclass_feature_category_for_action(action)
+      return unless superclass.respond_to?(:feature_category_for_action)
+
+      superclass.feature_category_for_action(action)
+    end
+  end
+end

app/controllers/concerns/controller_with_feature_category/config.rb

+# frozen_string_literal: true
+
+module ControllerWithFeatureCategory
+  class Config
+    attr_reader :category
+
+    def initialize(category, only, except, if_proc, unless_proc)
+      @category = category.to_sym
+      @only, @except = only&.map(&:to_s), except&.map(&:to_s)
+      @if_proc, @unless_proc = if_proc, unless_proc
+    end
+
+    def matches?(action)
+      included?(action) && !excluded?(action) &&
+        if_proc?(action) && !unless_proc?(action)
+    end
+
+    private
+
+    attr_reader :only, :except, :if_proc, :unless_proc
+
+    def if_proc?(action)
+      if_proc.nil? || if_proc.call(action)
+    end
+
+    def unless_proc?(action)
+      unless_proc.present? && unless_proc.call(action)
+    end
+
+    def included?(action)
+      only.nil? || only.include?(action)
+    end
+
+    def excluded?(action)
+      except.present? && except.include?(action)
+    end
+  end
+end

app/controllers/projects/merge_requests_controller.rb

@@ -45,6 +45,13 @@ class Projects::MergeRequestsController < Projects::MergeRequests::ApplicationCo
 
   around_action :allow_gitaly_ref_name_caching, only: [:index, :show, :discussions]
 
+  feature_category :source_code_management,
+                   unless: -> (action) { action.ends_with?("_reports") }
+  feature_category :code_testing,
+                   only: [:test_reports, :coverage_reports, :terraform_reports]
+  feature_category :accessibility_testing,
+                   only: [:accessibility_reports]
+
   def index
     @merge_requests = @issuables
 

ee/app/controllers/ee/projects/merge_requests_controller.rb

@@ -19,6 +19,14 @@ module EE
         before_action :authorize_read_pipeline!, only: [:container_scanning_reports, :dependency_scanning_reports,
                                                         :license_scanning_reports,
                                                         :sast_reports, :secret_detection_reports, :dast_reports, :metrics_reports]
+
+        feature_category :container_scanning, only: [:container_scanning_reports]
+        feature_category :dependency_scanning, only: [:dependency_scanning_reports]
+        feature_category :license_compliance, only: [:license_scanning_reports]
+        feature_category :static_application_security_testing, only: [:sast_reports]
+        feature_category :secret_detection, only: [:secret_detection_reports]
+        feature_category :dynamic_application_security_testing, only: [:dast_reports]
+        feature_category :metrics, only: [:metrics_reports]
       end
 
       def approve

spec/controllers/concerns/controller_with_feature_category/config_spec.rb

+# frozen_string_literal: true
+
+require "fast_spec_helper"
+require "rspec-parameterized"
+require_relative "../../../../app/controllers/concerns/controller_with_feature_category/config"
+
+RSpec.describe ControllerWithFeatureCategory::Config do
+  describe "#matches?" do
+    using RSpec::Parameterized::TableSyntax
+
+    where(:only_actions, :except_actions, :if_proc, :unless_proc, :test_action, :expected) do
+      nil         | nil         | nil   | nil   | "action"   | true
+      [:included] | nil         | nil   | nil   | "action"   | false
+      [:included] | nil         | nil   | nil   | "included" | true
+      nil         | [:excluded] | nil   | nil   | "excluded" | false
+      nil         | nil         | true  | nil   | "action"   | true
+      [:included] | nil         | true  | nil   | "action"   | false
+      [:included] | nil         | true  | nil   | "included" | true
+      nil         | [:excluded] | true  | nil   | "excluded" | false
+      nil         | nil         | false | nil   | "action"   | false
+      [:included] | nil         | false | nil   | "action"   | false
+      [:included] | nil         | false | nil   | "included" | false
+      nil         | [:excluded] | false | nil   | "excluded" | false
+      nil         | nil         | nil   | true  | "action"   | false
+      [:included] | nil         | nil   | true  | "action"   | false
+      [:included] | nil         | nil   | true  | "included" | false
+      nil         | [:excluded] | nil   | true  | "excluded" | false
+      nil         | nil         | nil   | false | "action"   | true
+      [:included] | nil         | nil   | false | "action"   | false
+      [:included] | nil         | nil   | false | "included" | true
+      nil         | [:excluded] | nil   | false | "excluded" | false
+      nil         | nil         | true  | false | "action"   | true
+      [:included] | nil         | true  | false | "action"   | false
+      [:included] | nil         | true  | false | "included" | true
+      nil         | [:excluded] | true  | false | "excluded" | false
+      nil         | nil         | false | true  | "action"   | false
+      [:included] | nil         | false | true  | "action"   | false
+      [:included] | nil         | false | true  | "included" | false
+      nil         | [:excluded] | false | true  | "excluded" | false
+    end
+
+    with_them do
+      let(:config) do
+        if_to_proc = if_proc.nil? ? nil : -> (_) { if_proc }
+        unless_to_proc = unless_proc.nil? ? nil : -> (_) { unless_proc }
+
+        described_class.new(:category, only_actions, except_actions, if_to_proc, unless_to_proc)
+      end
+
+      specify { expect(config.matches?(test_action)).to be(expected) }
+    end
+  end
+end

spec/controllers/concerns/controller_with_feature_category_spec.rb

+# frozen_string_literal: true
+
+require 'fast_spec_helper'
+require_relative "../../../app/controllers/concerns/controller_with_feature_category"
+require_relative "../../../app/controllers/concerns/controller_with_feature_category/config"
+
+RSpec.describe ControllerWithFeatureCategory do
+  describe ".feature_category_for_action" do
+    let(:base_controller) do
+      Class.new do
+        include ControllerWithFeatureCategory
+      end
+    end
+
+    let(:controller) do
+      Class.new(base_controller) do
+        feature_category :baz
+        feature_category :foo, except: %w(update edit)
+        feature_category :bar, only: %w(index show)
+        feature_category :quux, only: %w(destroy)
+        feature_category :quuz, only: %w(destroy)
+      end
+    end
+
+    let(:subclass) do
+      Class.new(controller) do
+        feature_category :qux, only: %w(index)
+      end
+    end
+
+    it "is nil when nothing was defined" do
+      expect(base_controller.feature_category_for_action("hello")).to be_nil
+    end
+
+    it "returns the expected category", :aggregate_failures do
+      expect(controller.feature_category_for_action("update")).to eq(:baz)
+      expect(controller.feature_category_for_action("hello")).to eq(:foo)
+      expect(controller.feature_category_for_action("index")).to eq(:bar)
+    end
+
+    it "returns the closest match for categories defined in subclasses" do
+      expect(subclass.feature_category_for_action("index")).to eq(:qux)
+      expect(subclass.feature_category_for_action("show")).to eq(:bar)
+    end
+
+    it "returns the last defined feature category when multiple match" do
+      expect(controller.feature_category_for_action("destroy")).to eq(:quuz)
+    end
+
+    it "raises an error when using including and excluding the same action" do
+      expect do
+        Class.new(base_controller) do
+          feature_category :hello, only: [:world], except: [:world]
+        end
+      end.to raise_error(%r(cannot configure both `only` and `except`))
+    end
+
+    it "raises an error when using unknown arguments" do
+      expect do
+        Class.new(base_controller) do
+          feature_category :hello, hello: :world
+        end
+      end.to raise_error(%r(unknown arguments))
+    end
+  end
+end

spec/controllers/every_controller_spec.rb

+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe "Every controller" do
+  context "feature categories" do
+    let_it_be(:feature_categories) do
+      YAML.load_file(Rails.root.join('config', 'feature_categories.yml')).map(&:to_sym).to_set
+    end
+
+    let_it_be(:controller_actions) do
+      # This will return tuples of all controller actions defined in the routes
+      # Only for controllers inheriting ApplicationController
+      # Excluding controllers from gems (OAuth, Sidekiq)
+      Rails.application.routes.routes
+        .map { |route| route.required_defaults.presence }
+        .compact
+        .select { |route| route[:controller].present? && route[:action].present? }
+        .map { |route| [constantize_controller(route[:controller]), route[:action]] }
+        .reject { |route| route.first.nil? || !route.first.include?(ControllerWithFeatureCategory) }
+    end
+
+    let_it_be(:routes_without_category) do
+      controller_actions.map do |controller, action|
+        "#{controller}##{action}" unless controller.feature_category_for_action(action)
+      end.compact
+    end
+
+    it "has feature categories" do
+      pending("We'll work on defining categories for all controllers: "\
+              "https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/463")
+
+      expect(routes_without_category).to be_empty, "#{routes_without_category.first(10)} did not have a category"
+    end
+
+    it "completed controllers don't get new routes without categories" do
+      completed_controllers = [Projects::MergeRequestsController].map(&:to_s)
+
+      newly_introduced_missing_category = routes_without_category.select do |route|
+        completed_controllers.any? { |controller| route.start_with?(controller) }
+      end
+
+      expect(newly_introduced_missing_category).to be_empty
+    end
+
+    it "recognizes the feature categories" do
+      routes_unknown_category = controller_actions.map do |controller, action|
+        used_category = controller.feature_category_for_action(action)
+        next unless used_category
+        next if used_category == :not_owned
+
+        ["#{controller}##{action}", used_category] unless feature_categories.include?(used_category)
+      end.compact
+
+      expect(routes_unknown_category).to be_empty, "#{routes_unknown_category.first(10)} had an unknown category"
+    end
+
+    it "doesn't define or exclude categories on removed actions", :aggregate_failures do
+      controller_actions.group_by(&:first).each do |controller, controller_action|
+        existing_actions = controller_action.map(&:last)
+        used_actions = actions_defined_in_feature_category_config(controller)
+        non_existing_used_actions = used_actions - existing_actions
+
+        expect(non_existing_used_actions).to be_empty,
+                                             "#{controller} used #{non_existing_used_actions} to define feature category, but the route does not exist"
+      end
+    end
+  end
+
+  def constantize_controller(name)
+    "#{name.camelize}Controller".constantize
+  rescue NameError
+    nil # some controllers, like the omniauth ones are dynamic
+  end
+
+  def actions_defined_in_feature_category_config(controller)
+    feature_category_configs = controller.send(:class_attributes)[:feature_category_config]
+    feature_category_configs.map do |config|
+      Array(config.send(:only)) + Array(config.send(:except))
+    end.flatten.uniq.map(&:to_s)
+  end
+end