DEV: add topic_query_suggested_options modifier (#20893)

Add a modifier that will allow us to tune the results returned by suggested.

At the moment the modifier allows us to toggle including random results.
This was created for the discourse-ai module. It needs to switch off random
results when it returns related topics.

Longer term we can use it to toggle unread/new and other aspects.

This also demonstrates how to test the contract when adding modifiers.

lib/topic_view.rb

@@ -605,7 +605,16 @@ class TopicView
 
   def suggested_topics
     if @include_suggested
-      @suggested_topics ||= TopicQuery.new(@user).list_suggested_for(topic, pm_params: pm_params)
+      @suggested_topics ||=
+        begin
+          kwargs =
+            DiscoursePluginRegistry.apply_modifier(
+              :topic_view_suggested_topics_options,
+              { include_random: true, pm_params: pm_params },
+              self,
+            )
+          TopicQuery.new(@user).list_suggested_for(topic, **kwargs)
+        end
     else
       nil
     end

spec/lib/topic_view_spec.rb

@@ -1091,4 +1091,30 @@ RSpec.describe TopicView do
       end
     end
   end
+
+  describe "with topic_view_suggested_topics_options modifier" do
+    let!(:topic1) { Fabricate(:topic) }
+    let!(:topic2) { Fabricate(:topic) }
+
+    after { DiscoursePluginRegistry.clear_modifiers! }
+
+    it "allows disabling of random suggested" do
+      topic_view = TopicView.new(topic1)
+
+      Plugin::Instance
+        .new
+        .register_modifier(
+          :topic_view_suggested_topics_options,
+        ) do |suggested_options, inner_topic_view|
+          expect(inner_topic_view).to eq(topic_view)
+          suggested_options.merge(include_random: false)
+        end
+
+      expect(topic_view.suggested_topics.topics.count).to eq(0)
+
+      DiscoursePluginRegistry.clear_modifiers!
+
+      expect(TopicView.new(topic1).suggested_topics.topics.count).to be > 0
+    end
+  end
 end