ceedling 1.0.1 → 1.1.1

data/plugins/gcov/lib/gcovr_reportinator.rb

@@ -1,22 +1,31 @@
 # =========================================================================
 #   Ceedling - Test-Centered Build System for C
 #   ThrowTheSwitch.org
-#   Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
 #   SPDX-License-Identifier: MIT
 # =========================================================================
 
-require 'reportinator_helper'
 require 'ceedling/exceptions'
 require 'ceedling/constants'
+require 'gcov_types'
+require 'gcov_reportinator'
 
-class GcovrReportinator
+class GcovrReportinator < GcovReportinator
+
+  NAME = 'Gcovr'
+
+  def name; NAME; end
 
   attr_reader :artifacts_path
 
-  def initialize(system_objects)
+  GCOVR_SETTING_PREFIX = "gcov_gcovr"
+
+  def initialize(system_objects, config)
+    super(config)
+
     @artifacts_path = GCOV_GCOVR_ARTIFACTS_PATH
+    @summary        = ''
     @ceedling = system_objects
-    @reportinator_helper = ReportinatorHelper.new(system_objects)
 
     # Validate the gcovr tool since it's used to generate reports
     @ceedling[:tool_validator].validate(
@@ -28,108 +37,60 @@ class GcovrReportinator
     @loginator = @ceedling[:loginator]
     @reportinator = @ceedling[:reportinator]
     @tool_executor = @ceedling[:tool_executor]
+    @configurator = @ceedling[:configurator]
+
+    check_config_options()
+
+    @gcovr_version = get_gcovr_version()
+
+    # MC/DC reporting requires gcovr 8+
+    if @configurator.gcov_mcdc && !min_version?( @gcovr_version, 8, 0 )
+      raise CeedlingException.new(
+        ":gcov ↳ :mcdc ➡️ Modified condition/decision coverage reporting requires gcovr 8 or higher " \
+        "(found #{@gcovr_version.major}.#{@gcovr_version.minor})"
+      )
+    end
   end
 
   # Generate the gcovr report(s) specified in the options.
+  # Sets @summary when :print_summary is enabled; Gcov#generate_coverage_reports logs it.
   def generate_reports(opts)
-    # Get the gcovr version number.
-    gcovr_version = get_gcovr_version()
-
-    # Get gcovr options from project configuration options
-    gcovr_opts = get_gcovr_opts(opts)
-
-    # Extract exception_on_fail setting
+    gcovr_opts        = collect_gcovr_opts(opts)
     exception_on_fail = !!gcovr_opts[:exception_on_fail]
+    args_common       = args_builder_common(gcovr_opts, @gcovr_version)
 
-    # Build the common gcovr arguments.
-    args_common = args_builder_common( gcovr_opts, gcovr_version )
-
-    msg = @reportinator.generate_heading( "Running Gcovr Coverage Reports" )
-    @loginator.log( msg )
+    @loginator.log(@reportinator.generate_heading("Running Gcovr Coverage Reports"))
 
-    # gcovr version 4.2 and later supports generating multiple reports with a single call.
-    if min_version?( gcovr_version, 4, 2 )
-      reports = []
-
-      args = args_common
-
-      args += (_args = args_builder_cobertura(opts, false))
-      reports << "Cobertura XML" if not _args.empty?
-
-      args += (_args = args_builder_sonarqube(opts, false))
-      reports << "SonarQube" if not _args.empty?
-      
-      args += (_args = args_builder_json(opts, true))
-      reports << "JSON" if not _args.empty?
-      
-      # As of gcovr version 4.2, the --html argument must appear last.
-      args += (_args = args_builder_html(opts, false))
-      reports << "HTML" if not _args.empty?
-      
-      reports.each do |report|
-        msg = @reportinator.generate_progress("Generating #{report} coverage report in '#{GCOV_GCOVR_ARTIFACTS_PATH}'")
-        @loginator.log( msg )
-      end
-
-      # Generate the report(s).
-      # only if one of the previous done checks for:
-      #
-      # - args_builder_cobertura
-      # - args_builder_sonarqube
-      # - args_builder_json
-      # - args_builder_html
-      #
-      # updated the args variable. In other case, no need to run GCOVR for current setup.
-      if !(args == args_common)
-        run( gcovr_opts, args, exception_on_fail )
-      end
-
-    # gcovr version 4.1 and earlier supports HTML and Cobertura XML reports.
-    # It does not support SonarQube and JSON reports.
-    # Reports must also be generated separately.
+    # gcovr 4.2+ can produce all report formats in one invocation;
+    # earlier versions require a separate call for each format.
+    if min_version?(@gcovr_version, 4, 2)
+      generate_reports_modern(gcovr_opts, args_common, exception_on_fail, opts)
     else
-      args_cobertura = args_builder_cobertura(opts, true)
-      args_html = args_builder_html(opts, true)
-
-      if args_html.length > 0
-        msg = @reportinator.generate_progress("Generating an HTML coverage report in '#{GCOV_GCOVR_ARTIFACTS_PATH}'")
-        @loginator.log( msg )
-
-        # Generate the HTML report.
-        run( gcovr_opts, (args_common + args_html), exception_on_fail )
-      end
-
-      if args_cobertura.length > 0
-        msg = @reportinator.generate_progress("Generating an Cobertura XML coverage report in '#{GCOV_GCOVR_ARTIFACTS_PATH}'")
-        @loginator.log( msg )
-
-        # Generate the Cobertura XML report.
-        run( gcovr_opts, (args_common + args_cobertura), exception_on_fail )
-      end
-    end
-
-    # Determine if the gcovr text report is enabled. Defaults to disabled.
-    if report_enabled?(opts, ReportTypes::TEXT)
-      generate_text_report( opts, args_common, exception_on_fail )
+      generate_reports_legacy(gcovr_opts, args_common, exception_on_fail, opts)
     end
 
-    # White space log line
-    @loginator.log( '' )
+    # Text report is always a standalone gcovr invocation regardless of version.
+    generate_text_report(opts, args_common, exception_on_fail) if report_enabled?(opts, ReportTypes::TEXT)
   end
 
   ### Private ###
 
   private
 
-  GCOVR_SETTING_PREFIX = "gcov_gcovr"
-
   # Build the gcovr report generation common arguments.
+  # --root and --exclude are passed as positional args ${1} and ${2} to the tool executor
+  # and are not included in the string returned by this method.
   def args_builder_common(gcovr_opts, gcovr_version)
     args = ""
-    args += "--root \"#{gcovr_opts[:report_root]}\" " unless gcovr_opts[:report_root].nil?
-    args += "--config \"#{gcovr_opts[:config_file]}\" " unless gcovr_opts[:config_file].nil?
+    args += "--config \"#{gcovr_opts[:config_file]}\" " if config_file_in_use?(gcovr_opts)
+
+    # When a config file is provided, defer all other options to it.
+    # This prevents Ceedling from overriding config file values with its CLI arguments.
+    # --root (${1}) is always passed; --exclude (${2}) is nil when a config file is present,
+    # so the tool executor omits those flags and the config file governs exclusions.
+    return args if config_file_in_use?(gcovr_opts)
+
     args += "--filter \"#{gcovr_opts[:report_include]}\" " unless gcovr_opts[:report_include].nil?
-    args += "--exclude \"#{gcovr_opts[:report_exclude]}\" " unless gcovr_opts[:report_exclude].nil?
     args += "--gcov-filter \"#{gcovr_opts[:gcov_filter]}\" " unless gcovr_opts[:gcov_filter].nil?
     args += "--gcov-exclude \"#{gcovr_opts[:gcov_exclude]}\" " unless gcovr_opts[:gcov_exclude].nil?
     args += "--exclude-directories \"#{gcovr_opts[:exclude_directories]}\" " unless gcovr_opts[:exclude_directories].nil?
@@ -165,9 +126,9 @@ class GcovrReportinator
       # Value sanity checks for :fail_under_* settings
       if opt.to_s =~ /fail_/
         if not value.is_a? Integer
-          raise CeedlingException.new(":gcov ↳ :gcovr ↳ :#{opt} => '#{value}' must be an integer")
+          raise CeedlingException.new(":gcov ↳ :gcovr ↳ :#{opt} ➡️ '#{value}' must be an integer")
         elsif (value < 0) || (value > 100)
-          raise CeedlingException.new(":gcov ↳ :gcovr ↳ :#{opt} => '#{value}' must be an integer percentage 0 – 100")
+          raise CeedlingException.new(":gcov ↳ :gcovr ↳ :#{opt} ➡️ '#{value}' must be an integer percentage 0 – 100")
         end
       end
       
@@ -181,7 +142,7 @@ class GcovrReportinator
 
   # Build the gcovr Cobertura XML report generation arguments.
   def args_builder_cobertura(opts, use_output_option=false)
-    gcovr_opts = get_gcovr_opts(opts)
+    gcovr_opts = collect_gcovr_opts(opts)
     args = ""
 
     # Determine if the Cobertura XML report is enabled. Defaults to disabled.
@@ -192,7 +153,7 @@ class GcovrReportinator
         artifacts_file_cobertura = File.join(GCOV_GCOVR_ARTIFACTS_PATH, gcovr_opts[:cobertura_artifact_filename])
       end
 
-      args += "--xml-pretty " if gcovr_opts[:cobertura_pretty]
+      args += "--xml-pretty " if gcovr_opts[:cobertura_pretty] && !config_file_in_use?(gcovr_opts)
       args += "--xml #{use_output_option ? "--output " : ""} \"#{artifacts_file_cobertura}\" "
     end
 
@@ -202,7 +163,7 @@ class GcovrReportinator
 
   # Build the gcovr SonarQube report generation arguments.
   def args_builder_sonarqube(opts, use_output_option=false)
-    gcovr_opts = get_gcovr_opts(opts)
+    gcovr_opts = collect_gcovr_opts(opts)
     args = ""
 
     # Determine if the gcovr SonarQube XML report is enabled. Defaults to disabled.
@@ -222,7 +183,7 @@ class GcovrReportinator
 
   # Build the gcovr JSON report generation arguments.
   def args_builder_json(opts, use_output_option=false)
-    gcovr_opts = get_gcovr_opts( opts )
+    gcovr_opts = collect_gcovr_opts( opts )
     args = ""
 
     # Determine if the gcovr JSON report is enabled. Defaults to disabled.
@@ -233,7 +194,7 @@ class GcovrReportinator
         artifacts_file_json = File.join(GCOV_GCOVR_ARTIFACTS_PATH, gcovr_opts[:json_artifact_filename])
       end
 
-      args += "--json-pretty " if gcovr_opts[:json_pretty]
+      args += "--json-pretty " if gcovr_opts[:json_pretty] && !config_file_in_use?(gcovr_opts)
       # Note: In gcovr 4.2, the JSON report is output only when the --output option is specified.
       # Hopefully we can remove --output after a future gcovr release.
       args += "--json #{use_output_option ? "--output " : ""} \"#{artifacts_file_json}\" "
@@ -245,7 +206,7 @@ class GcovrReportinator
 
   # Build the gcovr HTML report generation arguments.
   def args_builder_html(opts, use_output_option=false)
-    gcovr_opts = get_gcovr_opts(opts)
+    gcovr_opts = collect_gcovr_opts(opts)
     args = ""
 
     # Determine if the gcovr HTML report is enabled.
@@ -262,12 +223,17 @@ class GcovrReportinator
       is_html_report_type_detailed = (opts[:gcov_html_report_type].is_a? String) && (opts[:gcov_html_report_type].casecmp("detailed") == 0)
 
       args += "--html-details " if is_html_report_type_detailed || report_enabled?(opts, ReportTypes::HTML_DETAILED)
-      args += "--html-title \"#{gcovr_opts[:html_title]}\" " unless gcovr_opts[:html_title].nil?
-      args += "--html-absolute-paths " if !(gcovr_opts[:html_absolute_paths].nil?) && gcovr_opts[:html_absolute_paths]
-      args += "--html-encoding \"#{gcovr_opts[:html_encoding]}\" " unless gcovr_opts[:html_encoding].nil?
 
-      [:html_medium_threshold, :html_high_threshold].each do |opt|
-        args += "--#{opt.to_s.gsub('_','-')} #{gcovr_opts[opt]} " unless gcovr_opts[opt].nil?
+      # These options duplicate settings a gcovr configuration file would provide, so they're
+      # withheld when :config_file is set to avoid silently overriding the file's values.
+      if !config_file_in_use?(gcovr_opts)
+        args += "--html-title \"#{gcovr_opts[:html_title]}\" " unless gcovr_opts[:html_title].nil?
+        args += "--html-absolute-paths " if !(gcovr_opts[:html_absolute_paths].nil?) && gcovr_opts[:html_absolute_paths]
+        args += "--html-encoding \"#{gcovr_opts[:html_encoding]}\" " unless gcovr_opts[:html_encoding].nil?
+
+        [:html_medium_threshold, :html_high_threshold].each do |opt|
+          args += "--#{opt.to_s.gsub('_','-')} #{gcovr_opts[opt]} " unless gcovr_opts[opt].nil?
+        end
       end
 
       # The following option must be appended last for gcovr version <= 4.2 to properly work.
@@ -278,9 +244,10 @@ class GcovrReportinator
   end
 
 
-  # Generate a gcovr text report
+  # Generate a gcovr text report.
+  # @summary is set by run_gcovr when :print_summary is enabled.
   def generate_text_report(opts, args_common, boom)
-    gcovr_opts = get_gcovr_opts(opts)
+    gcovr_opts = collect_gcovr_opts(opts)
     args_text = ""
     message_text = "Generating a text coverage report"
 
@@ -293,80 +260,258 @@ class GcovrReportinator
     msg = @reportinator.generate_progress(message_text)
     @loginator.log(msg, Verbosity::NORMAL)
 
-    # Generate the text report
-    run( gcovr_opts, (args_common + args_text), boom )
+    run_gcovr( gcovr_opts, (args_common + args_text), boom )
+  end
+
+
+  # gcovr 4.2+ supports all output formats in a single invocation.
+  # Accumulate per-format args and track which formats are active for progress logging.
+  # As required by gcovr 4.2, --html arguments must be appended last.
+  # @summary is set by run_gcovr when :print_summary is enabled.
+  def generate_reports_modern(gcovr_opts, args_common, exception_on_fail, opts)
+    reports = []
+    args    = args_common
+
+    args += (_args = args_builder_cobertura(opts, false))
+    reports << "Cobertura XML" unless _args.empty?
+
+    args += (_args = args_builder_sonarqube(opts, false))
+    reports << "SonarQube" unless _args.empty?
+
+    args += (_args = args_builder_json(opts, true))
+    reports << "JSON" unless _args.empty?
+
+    # --html must be last (gcovr 4.2 requirement)
+    args += (_args = args_builder_html(opts, false))
+    reports << "HTML" unless _args.empty?
+
+    reports.each do |report|
+      @loginator.log(
+        @reportinator.generate_progress("Generating #{report} coverage report in '#{GCOV_GCOVR_ARTIFACTS_PATH}/'"),
+        Verbosity::NORMAL, LogLabels::NOTICE
+      )
+    end
+
+    # Skip the gcovr call entirely when no format added arguments.
+    return if args == args_common
+
+    run_gcovr(gcovr_opts, args, exception_on_fail)
+  end
+
+
+  # gcovr 4.1 and earlier support only HTML and Cobertura XML, and each must be
+  # generated with a separate gcovr call. SonarQube and JSON are unavailable.
+  # @summary is set by run_gcovr when :print_summary is enabled.
+  def generate_reports_legacy(gcovr_opts, args_common, exception_on_fail, opts)
+    args_html      = args_builder_html(opts, true)
+    args_cobertura = args_builder_cobertura(opts, true)
+
+    if args_html.length > 0
+      @loginator.log(
+        @reportinator.generate_progress("Generating an HTML coverage report in '#{GCOV_GCOVR_ARTIFACTS_PATH}'")
+      )
+      run_gcovr(gcovr_opts, args_common + args_html, exception_on_fail)
+    end
+
+    if args_cobertura.length > 0
+      @loginator.log(
+        @reportinator.generate_progress("Generating a Cobertura XML coverage report in '#{GCOV_GCOVR_ARTIFACTS_PATH}'")
+      )
+      run_gcovr(gcovr_opts, args_common + args_cobertura, exception_on_fail)
+    end
+  end
+
+
+  # gcovr options silently ignored whenever :config_file is set (dropped by args_builder_common's
+  # early return, or gated in args_builder_cobertura/json/html) -- in that case all such
+  # configuration must come from the gcovr configuration file itself.
+  IGNORED_WHEN_CONFIG_FILE_SET = [
+    :report_include, :report_exclude, :gcov_filter, :gcov_exclude, :exclude_directories,
+    :branches, :sort_uncovered, :sort_percentage, :print_summary, :gcov_executable,
+    :exclude_unreachable_branches, :exclude_throw_branches, :use_gcov_files, :gcov_ignore_parse_errors,
+    :keep, :delete, :threads, :merge_mode_function,
+    :fail_under_line, :fail_under_branch, :fail_under_decision, :fail_under_function,
+    :source_encoding, :object_directory,
+    :cobertura_pretty, :json_pretty,
+    :html_title, :html_absolute_paths, :html_encoding, :html_medium_threshold, :html_high_threshold
+  ].freeze
+
+  # True when a gcovr configuration file is in use, meaning Ceedling must defer to it and
+  # withhold any option that would silently override its settings.
+  def config_file_in_use?(gcovr_opts)
+    !gcovr_opts[:config_file].nil?
+  end
+
+
+  # Validate the gcovr plugin configuration for known-bad combinations.
+  def check_config_options
+    gcovr_opts = @config[GCOVR_SETTING_PREFIX.to_sym] || {}
+    return unless config_file_in_use?(gcovr_opts)
+
+    ignored = IGNORED_WHEN_CONFIG_FILE_SET.select { |key| !gcovr_opts[key].nil? }
+    return if ignored.empty?
+
+    list = ignored.map { |key| ":#{key}" }.join(', ')
+    msg = ":gcov ↳ :gcovr ↳ :config_file is set, so the following options are ignored: #{list}. " \
+          "Provide equivalent settings directly in your gcovr configuration file instead."
+    @loginator.log( msg, Verbosity::COMPLAIN )
   end
 
 
   # Get the gcovr options from the project options.
-  def get_gcovr_opts(opts)
-    return opts[GCOVR_SETTING_PREFIX.to_sym]
+  def collect_gcovr_opts(opts)
+    # dup prevents repeated calls from accumulating mutations on the shared opts hash.
+    # Each args_builder_* method calls this independently, so without dup every call
+    # would see the already-mutated :report_exclude from the previous call and nest it.
+    _opts = opts[GCOVR_SETTING_PREFIX.to_sym].dup
+
+    if config_file_in_use?(_opts)
+      # A gcovr config file is authoritative; CLI args override it, so injecting
+      # auto-excludes would silently defeat the config file. Force an empty array
+      # (not nil) so the tool executor omits the --exclude flag entirely.
+      _opts[:report_exclude] = []
+    else
+      # Build array of --exclude patterns: user-provided value (if any) + internally-generated per-file patterns.
+      # Splat via *Array() handles both a user-supplied string and a user-supplied array
+      # without introducing a nested element into the exclusions list.
+      excludes = build_report_exclusions()
+      excludes.unshift( *Array(_opts[:report_exclude]) ) if _opts[:report_exclude]
+      _opts[:report_exclude] = excludes unless excludes.empty?
+    end
+
+    _opts[:mcdc] = true if opts[:gcov_mcdc]
+
+    return _opts
   end
 
 
-  # Run gcovr with the given arguments
-  def run(opts, args, boom)
-    command = @tool_executor.build_command_line(TOOLS_GCOV_GCOVR_REPORT, [], args)
+  # Build a combined Python regex for gcovr's `--exclude` flag covering all
+  # non-production file categories: test files, support files, and generated/framework files.
+  def build_report_exclusions
+    data = build_exclusion_data
+    patterns = []
+
+    data[:test_paths].each do |path|
+      # Test files (e.g. test_foo.c)
+      patterns << ".*#{path}.*/#{data[:test_prefix]}.+\\#{data[:src_extension]}$"
+    end
+
+    # Support files (e.g. helpers, stubs, fixtures) — never production source
+    data[:support_paths].each do |path|
+      patterns << ".*#{path}/.+\\#{data[:src_extension]}$"
+    end
+
+    # Any generated files for tests or vendored framework C source files below the root of the build directory
+    patterns << ".*#{data[:build_root]}/.+\\#{EXTENSION_CORE_SOURCE}$"
+
+    return patterns
+  end
+
+
+  # Runs gcovr with the given arguments.
+  # Responsibilities:
+  #  - Builds and executes the gcovr command
+  #  - Prints raw shell output (success and failure)
+  #  - Saves --print-summary output to @summary; Gcov#generate_coverage_reports logs it
+  #  - Delegates exit-code interpretation to gcovr_exec_exception?
+  #  - Returns shell_result on success or non-fatal exception; raises on fatal exception
+  # gcovr_opts[:report_root] → ${1} (--root); gcovr_opts[:report_exclude] → ${2} (--exclude, array).
+  def run_gcovr(gcovr_opts, args, boom)
+    command = @tool_executor.build_command_line(
+      TOOLS_GCOV_GCOVR_REPORT, [],
+      gcovr_opts[:report_root],    # ${1} --root
+      gcovr_opts[:report_exclude], # ${2} --exclude (array; expanded to one flag per entry)
+      args                         # ${3} remaining optional arguments
+    )
 
     shell_result = nil
+    exception    = nil
 
     begin
       shell_result = @tool_executor.exec( command )
     rescue ShellException => ex
-      result = ex.shell_result
-      @reportinator_helper.print_shell_result( result )
-      raise(ex) if gcovr_exec_exception?( opts, result[:exit_code], boom )
+      exception    = ex
+      shell_result = ex.shell_result
     end
 
-    @reportinator_helper.print_shell_result( shell_result )
+    print_shell_exec_time( shell_result )
+    @summary = extract_gcovr_summary( shell_result[:stdout] ) if gcovr_opts[:print_summary]
+
+    raise( exception ) if exception && gcovr_exec_exception?( gcovr_opts, shell_result[:exit_code], boom, shell_result )
+    return shell_result
   end
 
 
-  # Get the gcovr version number as components
-  # Return {:major, :minor}
-  def get_gcovr_version()
-    major = 0
-    minor = 0
+  # Returns the error message text from gcovr stderr, or nil if none found.
+  # Matches lines beginning with "error" or "(ERROR)" and extracts the trailing message.
+  def extract_gcovr_error_message(shell_result)
+    return nil if shell_result.nil?
+
+    stderr = shell_result[:stderr]
+    return nil if stderr.nil? || stderr.empty?
+
+    stderr.each_line do |line|
+      match = line.match( /^\(?error\S*\s+(.+)/i )
+      return match[1].strip.capitalize if match
+    end
+
+    nil
+  end
+
 
-    command = @tool_executor.build_command_line(TOOLS_GCOV_GCOVR_REPORT, [], "--version")
+  # Extract the last contiguous block of lines containing '%' from gcovr stdout.
+  # gcovr --print-summary emits lines like "lines: 69.6% (80 out of 115)" — this
+  # locates that block generically without depending on exact line labels.
+  def extract_gcovr_summary(output)
+    return '' if output.nil? || output.empty?
 
-    msg = @reportinator.generate_progress("Collecting gcovr version for conditional feature handling")
-    @loginator.log( msg, Verbosity::OBNOXIOUS )
+    lines = output.lines
+    last_pct_idx = lines.rindex { |l| l.include?('%') }
+    return '' if last_pct_idx.nil?
+
+    first_pct_idx = last_pct_idx
+    first_pct_idx -= 1 while first_pct_idx > 0 && lines[first_pct_idx - 1].include?('%')
+
+    lines[first_pct_idx..last_pct_idx].join('')
+  end
+
+
+  # Get the gcovr version number as GcovToolVersion struct
+  def get_gcovr_version()
+    command = @tool_executor.build_command_line( TOOLS_GCOV_GCOVR_VERSION, [] )
+
+    @loginator.lazy( Verbosity::OBNOXIOUS ) do
+      @reportinator.generate_progress("Collecting gcovr version for conditional feature handling")
+    end
 
     shell_result = @tool_executor.exec( command )
-    version_number_match_data = shell_result[:output].match(/gcovr ([0-9]+)\.([0-9]+)/)
+    version_match = shell_result[:output].match(/gcovr (\d+)\.(\d+)/)
 
-    if !(version_number_match_data.nil?) && !(version_number_match_data[1].nil?) && !(version_number_match_data[2].nil?)
-        major = version_number_match_data[1].to_i
-        minor = version_number_match_data[2].to_i
-    else
+    if version_match.nil? || version_match[1].nil? || version_match[2].nil?
       raise CeedlingException.new( "Could not collect `gcovr` version from its command line" )
     end
 
-    return {:major => major, :minor => minor}
+    return GcovToolVersion.new( version_match[1].to_i, version_match[2].to_i )
   end
 
 
-  # Process version hash from `get_gcovr_version()`
+  # Process GcovToolVersion struct from `get_gcovr_version()`
   def min_version?(version, major, minor)
-    # Meet minimum requirement if major version is greater than minimum major threshold
-    return true if version[:major] > major
-
-    # Meet minimum requirement only if greater than or equal to minor version for the same major version
-    return true if version[:major] == major and version[:minor] >= minor
-
-    # Version is less than major.minor
+    return true if version.major > major
+    return true if version.major == major && version.minor >= minor
     return false
   end
 
 
-  # Output to console a human-friendly message on certain coverage failure exit codes
+  # Output to console a human-friendly message on certain coverage failure exit codes.
+  # Prefers the actual gcovr error text from stderr; falls back to descriptive strings.
   # Perform the logic on whether to raise an exception
-  def gcovr_exec_exception?(opts, exitcode, boom)
+  def gcovr_exec_exception?(opts, exitcode, boom, shell_result=nil)
 
     # Special handling of exit code 2 with --fail-under-line
-    if ((exitcode & 2) == 2) and !opts[:gcovr][:fail_under_line].nil?
-      msg = "Line coverage is less than the configured gcovr minimum of #{opts[:gcovr][:fail_under_line]}%"
+    if ((exitcode & 2) == 2) and !opts[:fail_under_line].nil?
+      fallback = "Line coverage is less than the configured minimum of #{opts[:fail_under_line]}%"
+      msg = "Gcovr ⏩️ #{extract_gcovr_error_message( shell_result ) || fallback}"
       if boom
         raise CeedlingException.new(msg)
       else
@@ -377,8 +522,9 @@ class GcovrReportinator
     end
 
     # Special handling of exit code 4 with --fail-under-branch
-    if ((exitcode & 4) == 4) and !opts[:gcovr][:fail_under_branch].nil?
-      msg = "Branch coverage is less than the configured gcovr minimum of #{opts[:gcovr][:fail_under_branch]}%"
+    if ((exitcode & 4) == 4) and !opts[:fail_under_branch].nil?
+      fallback = "Branch coverage is less than the configured minimum of #{opts[:fail_under_branch]}%"
+      msg = "Gcovr ⏩️ #{extract_gcovr_error_message( shell_result ) || fallback}"
       if boom
         raise CeedlingException.new(msg)
       else
@@ -389,8 +535,9 @@ class GcovrReportinator
     end
 
     # Special handling of exit code 8 with --fail-under-decision
-    if ((exitcode & 8) == 8) and !opts[:gcovr][:fail_under_decision].nil?
-      msg = "Decision coverage is less than the configured gcovr minimum of #{opts[:gcovr][:fail_under_decision]}%"
+    if ((exitcode & 8) == 8) and !opts[:fail_under_decision].nil?
+      fallback = "Decision coverage is less than the configured minimum of #{opts[:fail_under_decision]}%"
+      msg = "Gcovr ⏩️ #{extract_gcovr_error_message( shell_result ) || fallback}"
       if boom
         raise CeedlingException.new(msg)
       else
@@ -401,8 +548,9 @@ class GcovrReportinator
     end
 
     # Special handling of exit code 16 with --fail-under-function
-    if ((exitcode & 16) == 16) and !opts[:gcovr][:fail_under_function].nil?
-      msg = "Function coverage is less than the configured gcovr minimum of #{opts[:gcovr][:fail_under_function]}%"
+    if ((exitcode & 16) == 16) and !opts[:fail_under_function].nil?
+      fallback = "Function coverage is less than the configured minimum of #{opts[:fail_under_function]}%"
+      msg = "Gcovr ⏩️ #{extract_gcovr_error_message( shell_result ) || fallback}"
       if boom
         raise CeedlingException.new(msg)
       else