feat: Add ignored columns reporting

This commit introduces a new feature that provides reporting
of ignored columns when the corresponding option is enabled.

A new option, `report_ignored_columns`, has been added to the
`Sheetah::Template` initialization. It works in conjunction
with the existing `ignore_unspecified_columns` option, which
must also be enabled for the reporting to take effect.

Author: Morgan Jézéquel

lib/sheetah/headers.rb

@@ -72,6 +72,8 @@ def add_ensure_column_is_specified(header, column)
         @messenger.error("invalid_header", header.value)
       end
 
+      @messenger.warn("ignored_column", header.value) if @specification.report_ignored_columns?
+
       false
     end
 

lib/sheetah/specification.rb

@@ -13,9 +13,10 @@ class MutablePatternError < Errors::SpecError
     class DuplicatedPatternError < Errors::SpecError
     end
 
-    def initialize(ignore_unspecified_columns: false)
+    def initialize(ignore_unspecified_columns: false, report_ignored_columns: false)
       @column_by_pattern = {}
       @ignore_unspecified_columns = ignore_unspecified_columns
+      @report_ignored_columns = report_ignored_columns
     end
 
     def set(pattern, column)
@@ -56,6 +57,10 @@ def ignore_unspecified_columns?
       @ignore_unspecified_columns
     end
 
+    def report_ignored_columns?
+      @report_ignored_columns
+    end
+
     def freeze
       @column_by_pattern.freeze
       super

lib/sheetah/template.rb

@@ -26,13 +26,17 @@ module Sheetah
   # specification, and composite attributes will produce as many columns as
   # required by the number of scalar values they hold.
   class Template
-    def initialize(attributes:, ignore_unspecified_columns: false)
+    def initialize(attributes:, ignore_unspecified_columns: false, report_ignored_columns: false)
       @attributes = build_attributes(attributes)
       @ignore_unspecified_columns = ignore_unspecified_columns
+      @report_ignored_columns = ignore_unspecified_columns && report_ignored_columns
     end
 
     def apply(config)
-      specification = Specification.new(ignore_unspecified_columns: @ignore_unspecified_columns)
+      specification = Specification.new(
+        ignore_unspecified_columns: @ignore_unspecified_columns,
+        report_ignored_columns: @report_ignored_columns
+      )
 
       @attributes.each do |attribute|
         attribute.each_column(config) do |column|

spec/sheetah/headers_spec.rb

@@ -11,7 +11,8 @@
     instance_double(
       Sheetah::Specification,
       required_columns: [],
-      ignore_unspecified_columns?: false
+      ignore_unspecified_columns?: false,
+      report_ignored_columns?: false
     )
   end
 
@@ -106,6 +107,31 @@ def stub_specification(column_by_header)
           ]
         )
       end
+
+      context "when the ignored columns reporting is enabled" do
+        let(:specification) do
+          instance_double(
+            Sheetah::Specification,
+            required_columns: [],
+            ignore_unspecified_columns?: true,
+            report_ignored_columns?: true
+          )
+        end
+
+        it "messages a warning" do
+          expect(messenger.messages).to eq(
+            [
+              Sheetah::Messaging::Message.new(
+                severity: "WARN",
+                code: "ignored_column",
+                code_data: sheet_headers[4].value,
+                scope: "COL",
+                scope_data: { col: sheet_headers[4].col }
+              ),
+            ]
+          )
+        end
+      end
     end
 
     context "when there is a duplicate" do

spec/sheetah_spec.rb

@@ -137,6 +137,32 @@ def process_to_a(*args, **opts)
           Success(foo: "dlrow", bar: [nil, nil, "foo@bar.baz", nil, Float])
         )
       end
+
+      context "when the reporting is enabled" do
+        before { template_opts[:report_ignored_columns] = true }
+
+        it "messages the ignored columns" do # rubocop:disable RSpec/ExampleLength
+          expect(process(input) {}).to have_attributes(
+            result: Success(),
+            messages: contain_exactly(
+              have_attributes(
+                code: "ignored_column",
+                code_data: "oof",
+                scope: Sheetah::Messaging::SCOPES::COL,
+                scope_data: { col: "C" },
+                severity: Sheetah::Messaging::SEVERITIES::WARN
+              ),
+              have_attributes(
+                code: "ignored_column",
+                code_data: "rab",
+                scope: Sheetah::Messaging::SCOPES::COL,
+                scope_data: { col: "F" },
+                severity: Sheetah::Messaging::SEVERITIES::WARN
+              )
+            )
+          )
+        end
+      end
     end
 
     context "when the template doesn't allow it" do