Add additional helpful section for frozen objects

Augument runtime errors with additional information that explains why an object might be frozen, and how frozen resource properties are a good thing.

Fixes #3734, for [accepted RFC 55](https://github.com/chef/chef-rfc/pull/135).

2 files changed, 42 insertions, 0 deletions

diff --git a/lib/chef/formatters/error_inspectors/compile_error_inspector.rb b/lib/chef/formatters/error_inspectors/compile_error_inspector.rb
index d64d5e7b01..fe418ed485 100644
--- a/lib/chef/formatters/error_inspectors/compile_error_inspector.rb
+++ b/lib/chef/formatters/error_inspectors/compile_error_inspector.rb
@@ -44,6 +44,18 @@ class Chef
             error_description.section("Cookbook Trace:", traceback)
             error_description.section("Relevant File Content:", context)
           end
+
+          if exception_message_modifying_frozen?
+            msg = <<-MESSAGE
+            Chef calls the freeze method on certain ruby objects to prevent
+            pollution across multiple instances. Specifically, resource
+            properties have frozen default values to avoid modifying the
+            property for all instances of a resource. Try modifying the
+            particular instance variable or using an instance accessor instead.
+            MESSAGE
+
+            error_description.section("Additional information:", msg.gsub(/^ {6}/, ''))
+          end
         end
 
         def context
@@ -111,6 +123,10 @@ class Chef
             end
         end
 
+        def exception_message_modifying_frozen?
+          exception.message.include?("can't modify frozen")
+        end
+
       end
 
     end
diff --git a/spec/unit/formatters/error_inspectors/compile_error_inspector_spec.rb b/spec/unit/formatters/error_inspectors/compile_error_inspector_spec.rb
index 5f95beb259..3c8d5dfa29 100644
--- a/spec/unit/formatters/error_inspectors/compile_error_inspector_spec.rb
+++ b/spec/unit/formatters/error_inspectors/compile_error_inspector_spec.rb
@@ -110,6 +110,32 @@ describe Chef::Formatters::ErrorInspectors::CompileErrorInspector do
       end
     end
 
+    context "when the error is a RuntimeError about frozen object" do
+      let(:exception) do
+        e = RuntimeError.new("can't modify frozen Array")
+        e.set_backtrace(trace)
+        e
+      end
+
+      let(:path_to_failed_file) { "/tmp/kitchen/cache/cookbooks/foo/recipes/default.rb" }
+
+      let(:trace) do
+        [
+          "/tmp/kitchen/cache/cookbooks/foo/recipes/default.rb:2:in `block in from_file'",
+          "/tmp/kitchen/cache/cookbooks/foo/recipes/default.rb:1:in `from_file'"
+        ]
+      end
+
+      describe "when explaining a runtime error in the compile phase" do
+        it "correctly detects RuntimeError for frozen objects" do
+          expect(inspector.exception_message_modifying_frozen?).to be(true)
+        end
+
+        # could also test for description.section to be called, but would have
+        # to adjust every other test to begin using a test double for description
+      end
+    end
+
     context "when the error does not contain any lines from cookbooks" do
 
       let(:trace) do