Merge pull request #7378 from alphagov/CM-618-develop-smart-answers-spike

(CM-618) Develop smart answers spike

Author: pezholio

Gemfile

@@ -6,6 +6,7 @@ gem "rails", "8.0.3"
 
 gem "ast"
 gem "bootsnap", require: false
+gem "content_block_tools"
 gem "dartsass-rails"
 gem "erb_lint"
 gem "gds-api-adapters"

Gemfile.lock

@@ -111,6 +111,12 @@ GEM
     coderay (1.1.3)
     concurrent-ruby (1.3.5)
     connection_pool (2.5.4)
+    content_block_tools (1.6.1)
+      actionview (>= 6, < 8.1.2)
+      gds-api-adapters (~> 101.0.0)
+      govspeak (>= 10.6.3)
+      rails (>= 6, < 8.1.2)
+      view_component (~> 4)
     crack (1.0.1)
       bigdecimal
       rexml
@@ -658,6 +664,9 @@ GEM
     unicode-emoji (4.0.4)
     uri (1.1.1)
     useragent (0.16.11)
+    view_component (4.1.0)
+      activesupport (>= 7.1.0, < 8.2)
+      concurrent-ruby (~> 1)
     webmock (3.26.1)
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
@@ -684,6 +693,7 @@ DEPENDENCIES
   binding_of_caller
   bootsnap
   byebug
+  content_block_tools
   dartsass-rails
   erb_lint
   gds-api-adapters

app/presenters/content_item_presenter.rb

@@ -25,7 +25,8 @@ def payload
       routes: [
         { type: "prefix", path: base_path },
       ],
-    }
+      links:,
+    }.compact
   end
 
 private
@@ -37,4 +38,12 @@ def start_node_presenter
   def base_path
     "/#{flow.name}"
   end
+
+  def links
+    embed_content_ids.any? ? { embed: embed_content_ids } : nil
+  end
+
+  def embed_content_ids
+    @embed_content_ids ||= ContentBlockDetector.new(flow).content_blocks.map(&:content_id).uniq
+  end
 end

app/services/content_block_detector.rb

@@ -0,0 +1,98 @@
+# Detects and extracts content blocks from Smart Answer flows and their associated files.
+#
+# This class analyzes a flow's Ruby source files, calculator files, and ERB templates
+# to find embedded content block references and returns the corresponding ContentBlock objects.
+class ContentBlockDetector
+  # Regular expression pattern to match calculator class names in the format
+  # SmartAnswer::Calculators::CalculatorName
+  CALCULATOR_PATTERN = /SmartAnswer::Calculators::[a-zA-Z]+/
+
+  attr_reader :flow
+
+  # Initializes a new ContentBlockDetector
+  #
+  # @param flow [Object] The Smart Answer flow object to analyze for content blocks
+  def initialize(flow)
+    @flow = flow
+  end
+
+  # Finds and returns all unique content blocks referenced in the flow
+  #
+  # Searches through all flow-related files (flow class, calculators, and templates)
+  # to find content block references, extracts their embed codes, and converts them
+  # to ContentBlock objects.
+  #
+  # @return [Array<ContentBlockTools::ContentBlock>] Array of unique content blocks found
+  def content_blocks
+    references = ContentBlockTools::ContentBlockReference.find_all_in_document(flow_content)
+    embed_codes = references.map(&:embed_code).uniq
+    embed_codes.map do |embed_code|
+      ContentBlockTools::ContentBlock.from_embed_code(embed_code)
+    end
+  end
+
+  # Returns the file path of the flow's main Ruby class file
+  #
+  # Uses memoization to cache the result after first lookup
+  #
+  # @return [String] File path to the flow's Ruby class definition
+  def flow_filename
+    @flow_filename ||= Object.const_source_location(flow.class.to_s)[0]
+  end
+
+  # Extracts and returns all calculator classes referenced in the flow file
+  #
+  # Scans the flow's source file for calculator class names matching the
+  # CALCULATOR_PATTERN and constantizes them into actual class objects.
+  # Uses memoization to cache the result.
+  #
+  # @return [Array<Class>] Array of calculator class objects
+  def calculators
+    @calculators ||= File.read(flow_filename)
+                         .scan(CALCULATOR_PATTERN)
+                         .map(&:constantize)
+  end
+
+  # Returns file paths for all calculator classes used by the flow
+  #
+  # @return [Array<String>] Array of file paths to calculator class files
+  def calculator_filenames
+    calculators.map do |calculator|
+      Object.const_source_location(calculator.to_s)[0]
+    end
+  end
+
+  # Returns all ERB template file paths associated with the flow
+  #
+  # Searches for all .erb files in the flow's template directory,
+  # which follows the naming convention: app/flows/[flow_name]_flow/**/*.erb
+  #
+  # @return [Array<String>] Array of ERB template file paths
+  def template_filenames
+    Dir.glob(File.join("app", "flows", "#{flow.name.underscore}_flow", "**", "*.erb"))
+  end
+
+  # Reads and concatenates the content of all flow-related files
+  #
+  # @return [String] Combined content of all flow files
+  def flow_content
+    files.map { |file|
+      File.read(file)
+    }.join
+  end
+
+private
+
+  # Returns an array of all file paths associated with the flow
+  #
+  # Includes the main flow file, calculator files, and all ERB templates
+  #
+  # @return [Array<String>] Array of file paths
+  def files
+    [
+      flow_filename,
+      *calculator_filenames,
+      *template_filenames,
+    ]
+  end
+end

docs/tasks/using-content-blocks.md

@@ -0,0 +1,40 @@
+# Using content blocks in Smart Answers
+
+You can use content blocks from the [Content Block Manager](https://content-block-manager.publishing.service.gov.uk) in Smart Answers.  
+This lets you reuse content across multiple Smart Answers, which will automatically update when the content block is updated.
+
+## Content block embed codes
+
+A content block embed code is a short snippet used to embed a content block. It looks like this:
+
+```
+{{embed:content_block_contact:information-commissioners-office}}
+````
+
+## Using an embed code in a Smart Answer
+
+You can use embed codes in a Smart Answer’s Flow, Calculator or view.  
+
+To fetch a content block using an embed code, call the [`ContentBlockTools::ContentBlock.from_embed_code` method](https://github.com/alphagov/govuk_content_block_tools/blob/69f06ce51513e47f2cc2925b933a0de09249a516/lib/content_block_tools/content_block.rb#L69):
+
+```ruby
+block = ContentBlockTools::ContentBlock.from_embed_code("{{embed:content_block_contact:information-commissioners-office}}")
+````
+
+You can then use the [`render` method](https://github.com/alphagov/govuk_content_block_tools/blob/69f06ce51513e47f2cc2925b933a0de09249a516/lib/content_block_tools/content_block.rb#L93) to return the content block as an HTML string:
+
+```ruby
+block.render #=> "<div class=\"content-block content-block--contact\" ..."
+```
+
+## Publishing a Smart Answer that uses content blocks
+
+After adding a content block to a Smart Answer, you must [republish the Smart Answer](https://github.com/alphagov/smart-answers/blob/main/docs/tasks/publishing.md).
+This ensures the Smart Answer is shown as dependent content in Content Block Manager. It also allows changes to the content block to be previewed in the context of the Smart Answer.
+
+This process uses the [`ContentBlockDetector` class](https://github.com/alphagov/smart-answers/blob/main/app/services/content_block_detector.rb) to detect embedded content blocks and send them to the Publishing API as links.
+
+## Limitations
+
+Because the Content Block Manager’s preview service finds and replaces content blocks within pages, it’s not yet possible to use content blocks in Calculations.
+We plan to address this in the future.

test/unit/content_item_presenter_test.rb

@@ -28,5 +28,35 @@ class ContentItemPresenterPresenterTest < ActiveSupport::TestCase
       assert_equal "The Gorge of Eternal Peril!!!", payload[:description]
       assert_match %r{He who would cross the Bridge of Death}, payload.dig(:details, :hidden_search_terms, 0)
     end
+
+    context "when the ContentBlockDetector finds associated content blocks" do
+      setup do
+        @content_id = SecureRandom.uuid
+        content_block_1 = stub("content_block", content_id: @content_id)
+        content_block_2 = stub("content_block", content_id: @content_id)
+
+        detector = stub("detector", content_blocks: [content_block_1, content_block_2])
+        ContentBlockDetector.expects(:new).with(@flow).returns(detector)
+      end
+
+      should "include an array of unique content IDs in the payload" do
+        payload = ContentItemPresenter.new(@flow).payload
+
+        assert_equal [@content_id], payload[:links][:embed]
+      end
+    end
+
+    context "when the ContentBlockDetector does not find associated content blocks" do
+      setup do
+        detector = stub("detector", content_blocks: [])
+        ContentBlockDetector.expects(:new).with(@flow).returns(detector)
+      end
+
+      should "not include any links" do
+        payload = ContentItemPresenter.new(@flow).payload
+
+        assert_nil payload[:links]
+      end
+    end
   end
 end

test/unit/services/content_block_detector_test.rb

@@ -0,0 +1,104 @@
+require "test_helper"
+
+class ContentBlockDetectorTest < ActiveSupport::TestCase
+  setup do
+    @flow = mock("flow")
+    @flow.stubs(:name).returns("example")
+    @flow_class = mock("flow_class")
+    @flow_class.stubs(:to_s).returns("ExampleFlow")
+    @flow.stubs(:class).returns(@flow_class)
+
+    @flow_file = "/path/to/flow.rb"
+    @template_file = "/path/to/template.erb"
+    @calculator_file = "/path/to/calculator.rb"
+
+    @detector = ContentBlockDetector.new(@flow)
+  end
+
+  context "#flow_filename" do
+    should "return the filename for the flow" do
+      Object.expects(:const_source_location).with(@flow_class.to_s).returns([@flow_file])
+
+      assert_equal @flow_file, @detector.flow_filename
+    end
+  end
+
+  context "#calculators" do
+    should "return the filename for the template" do
+      flow_content = "FLOW CONTENT"
+      calculator = stub("calculator", constantize: "calculator_constantized")
+
+      @detector.stubs(:flow_filename).returns(@flow_file)
+      File.expects(:read).with(@flow_file).returns(flow_content)
+      flow_content.expects(:scan)
+                  .with(ContentBlockDetector::CALCULATOR_PATTERN)
+                  .returns([calculator])
+
+      assert_equal [calculator.constantize], @detector.calculators
+    end
+  end
+
+  context "#calculator_filenames" do
+    should "return the filename for the calculators" do
+      calculator = stub("calculator")
+
+      @detector.stubs(:calculators).returns([calculator])
+      Object.stubs(:const_source_location)
+            .with(calculator.to_s)
+            .returns([@calculator_file])
+
+      assert_equal [@calculator_file], @detector.calculator_filenames
+    end
+  end
+
+  context "#template_filenames" do
+    should "return the filename for the templates" do
+      glob = File.join("app", "flows", "#{@flow.name.underscore}_flow", "**", "*.erb")
+      Dir.expects(:glob).with(glob)
+         .returns([@template_file])
+
+      assert_equal [@template_file], @detector.template_filenames
+    end
+  end
+
+  context "#flow_content" do
+    should "return the content for the flow's files" do
+      @detector.stubs(:flow_filename).returns(@flow_file)
+      @detector.stubs(:calculator_filenames).returns(@calculator_file)
+      @detector.stubs(:template_filenames).returns(@template_file)
+
+      flow_content = "FLOW CONTENT"
+      calculator_content = "CALCULATOR CONTENT"
+      template_content = "TEMPLATE CONTENT"
+
+      File.expects(:read).with(@flow_file).returns(flow_content)
+      File.expects(:read).with(@calculator_file).returns(calculator_content)
+      File.expects(:read).with(@template_file).returns(template_content)
+
+      expected_content = [flow_content, calculator_content, template_content].join
+
+      assert_equal expected_content, @detector.flow_content
+    end
+  end
+
+  context "#content_blocks" do
+    should "return unique content blocks from flow content" do
+      flow_content = "FLOW CONTENT"
+
+      @detector.stubs(:flow_content).returns(flow_content)
+
+      reference = stub("reference", embed_code: "EMBED CODE")
+      content_block = stub("content_block")
+
+      ContentBlockTools::ContentBlockReference.stubs(:find_all_in_document)
+                                              .with(flow_content)
+                                              .returns([reference])
+
+      ContentBlockTools::ContentBlock.stubs(:from_embed_code)
+                                     .with(reference.embed_code)
+                                     .returns(content_block)
+
+      assert_equal [content_block], @detector.content_blocks
+    end
+  end
+end