ThrowTheSwitch
diff --git a/‎docs/mkdocs/plugins/gcov/gcovr.md‎
Lines changed: 8 additions & 4 deletions b/‎docs/mkdocs/plugins/gcov/gcovr.md‎
Lines changed: 8 additions & 4 deletions
diff --git a/‎docs/mkdocs/reference/gcov-plugin.md‎
Lines changed: 9 additions & 4 deletions b/‎docs/mkdocs/reference/gcov-plugin.md‎
Lines changed: 9 additions & 4 deletions
diff --git a/‎plugins/gcov/lib/gcov.rb‎
Lines changed: 47 additions & 22 deletions b/‎plugins/gcov/lib/gcov.rb‎
Lines changed: 47 additions & 22 deletions
diff --git a/‎plugins/gcov/lib/gcov_constants.rb‎
Lines changed: 1 addition & 0 deletions b/‎plugins/gcov/lib/gcov_constants.rb‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎plugins/gcov/lib/gcov_reportinator.rb‎
Lines changed: 65 additions & 0 deletions b/‎plugins/gcov/lib/gcov_reportinator.rb‎
Lines changed: 65 additions & 0 deletions
diff --git a/‎plugins/gcov/lib/gcov_types.rb‎
Lines changed: 62 additions & 1 deletion b/‎plugins/gcov/lib/gcov_types.rb‎
Lines changed: 62 additions & 1 deletion
@@ -131,7 +131,7 @@ Report the decision coverage. For HTML, JSON, and the summary report.
 
 Implied automatically whenever `:fail_under_decision` is set.
 
-**Requires:** `gcovr` 6.0 or higher
+**Requires:** `gcovr` 5.1 or higher
 
 ---
 
@@ -166,21 +166,25 @@ Select the source file character encoding. (`gcovr --source-encoding`)
 ### `:branches`
 
 Report the branch coverage instead of the line coverage. Applies to the text
-report only. (`gcovr --branches`)
+report only. Uses `gcovr --txt-metric branch` on `gcovr` 7.0+ (`--branches` is
+deprecated as of 7.0, though still functional); `gcovr --branches` below it.
 
 ---
 
 ### `:sort_uncovered`
 
 Sort entries by increasing number of uncovered lines. Applies to text and HTML
-reports. (`gcovr --sort-uncovered`)
+reports. Uses `gcovr --sort uncovered-number` on `gcovr` 7.0+ (`--sort-uncovered`
+is deprecated as of 7.0, though still functional); `gcovr --sort-uncovered` below it.
 
 ---
 
 ### `:sort_percentage`
 
 Sort entries by increasing percentage of uncovered lines. Applies to text and
-HTML reports. (`gcovr --sort-percentage`)
+HTML reports. Uses `gcovr --sort uncovered-percent` on `gcovr` 7.0+
+(`--sort-percentage` is deprecated as of 7.0, though still functional);
+`gcovr --sort-percentage` below it.
 
 ---
 
 
@@ -230,7 +230,7 @@ Report the decision coverage. For HTML, JSON, and the summary report.
 
 Implied automatically whenever `:fail_under_decision` is set.
 
-**Requires:** `gcovr` 6.0 or higher
+**Requires:** `gcovr` 5.1 or higher
 
 ---
 
@@ -263,21 +263,26 @@ Source file character encoding. (`gcovr --source-encoding`)
 ### `:branches`
 
 Report branch coverage instead of line coverage. Applies to text reports only.
-(`gcovr --branches`)
+Uses `gcovr --txt-metric branch` on `gcovr` 7.0+ (`--branches` is deprecated as
+of 7.0, though still functional); `gcovr --branches` below it.
 
 ---
 
 ### `:sort_uncovered`
 
 Sort report entries by increasing number of uncovered lines. Applies to text
-and HTML reports. (`gcovr --sort-uncovered`)
+and HTML reports. Uses `gcovr --sort uncovered-number` on `gcovr` 7.0+
+(`--sort-uncovered` is deprecated as of 7.0, though still functional);
+`gcovr --sort-uncovered` below it.
 
 ---
 
 ### `:sort_percentage`
 
 Sort report entries by increasing percentage of uncovered lines. Applies to
-text and HTML reports. (`gcovr --sort-percentage`)
+text and HTML reports. Uses `gcovr --sort uncovered-percent` on `gcovr` 7.0+
+(`--sort-percentage` is deprecated as of 7.0, though still functional);
+`gcovr --sort-percentage` below it.
 
 ---
 
 
@@ -16,7 +16,21 @@
 require 'reportgenerator_reportinator'
 
 class Gcov < Plugin
-  
+
+  include ToolVersionGating
+
+  # Checked lazily (see validate_mcdc_gcc_version!, called from the gcov-context build
+  # hooks below) rather than here in setup(), which runs for every build this plugin is
+  # merely *enabled* for -- not only real `gcov:` builds. Shelling out to `gcc --version`
+  # here would make GCC-version validation (and a build-breaking exception on too-old a
+  # GCC) fire even for builds that never touch :mcdc at all, e.g. plain `test:all`.
+  MCDC_GCC_VERSION_GATE = {
+    :mcdc => {
+      min: [14, 0],
+      message: ":gcov ↳ :mcdc ➡️ Modified condition/decision coverage requires GCC %{req} or higher (found %{found})"
+    }
+  }.freeze
+
   # `Plugin` setup()
   def setup
     @result_list = []
@@ -80,16 +94,9 @@ def setup
 
     @mutex = Mutex.new()
 
-    # Validate MC/DC configuration against GCC version (only incurs gcc --version when :mcdc: TRUE)
-    if @project_config[:gcov_mcdc]
-      gcc_version = get_gcc_version()
-      if gcc_version.major < 14
-        raise CeedlingException.new(
-          ":gcov ↳ :mcdc ➡️ Modified condition/decision coverage requires GCC 14 or higher " \
-          "(found #{gcc_version.major}.#{gcc_version.minor})"
-        )
-      end
-    end
+    # See validate_mcdc_gcc_version! and MCDC_GCC_VERSION_GATE above for why this isn't
+    # checked eagerly here.
+    @mcdc_gcc_checked = false
   end
 
   # Called within class and also externally by plugin Rakefile
@@ -138,6 +145,8 @@ def process_untested_sources(sources:, guidance: true)
       @loginator.log_list( untested_sources.sort, header, Verbosity::COMPLAIN, LogLabels::WARNING )
 
     when GCOV_UNTESTED_SOURCES_COMPILE
+      validate_mcdc_gcc_version!
+
       msg = 'Processing Untested Sources'
       msg = @reportinator.generate_heading( @loginator.decorate( msg, LogLabels::RUN ) )
       @loginator.log( msg )
@@ -241,6 +250,8 @@ def pre_test_compile_register(arg_hash)
     return unless arg_hash[:context] == GCOV_SYM
     return if EXTENSION_ASSEMBLY.match?(arg_hash[:source])
 
+    validate_mcdc_gcc_version!
+
     arg_hash[:tool] = TOOLS_GCOV_COMPILER
     arg_hash[:flags] += ['-fcondition-coverage'] if @project_config[:gcov_mcdc]
 
@@ -270,6 +281,8 @@ def pre_compile_execute(arg_hash)
   def pre_test_link_register(arg_hash)
     return unless arg_hash[:context] == GCOV_SYM
 
+    validate_mcdc_gcc_version!
+
     @cli_gcov_task = true
     arg_hash[:tool] = TOOLS_GCOV_LINKER
     arg_hash[:flags] += ['-fcondition-coverage'] if @project_config[:gcov_mcdc]
@@ -453,23 +466,35 @@ def build_reportinators(config)
     return reportinators
   end
 
-  def get_gcc_version()
-    command = @tool_executor.build_command_line( TOOLS_GCOV_GCC_VERSION, [])
+  # Lazily validates :mcdc against the installed GCC version -- called from every
+  # gcov-context build hook that could otherwise emit -fcondition-coverage (compile,
+  # untested-source compile, link), memoized so `gcc --version` runs at most once
+  # regardless of how many source files or hooks fire before it. See MCDC_GCC_VERSION_GATE
+  # above for why this isn't checked eagerly in setup().
+  def validate_mcdc_gcc_version!
+    return if @mcdc_gcc_checked
+    @mcdc_gcc_checked = true
+    return unless @project_config[:gcov_mcdc]
+
+    enforce_version_gates!(
+      { mcdc: @project_config[:gcov_mcdc] },
+      get_gcc_version(),
+      MCDC_GCC_VERSION_GATE
+    )
+  end
 
+  # Get the GCC version number as a ToolVersion struct.
+  def get_gcc_version()
     @loginator.lazy( Verbosity::OBNOXIOUS ) do
       @reportinator.generate_progress("Collecting GCC version for conditional feature handling")
     end
 
-    shell_result = @tool_executor.exec( command )
-
     # First line of gcc --version: "gcc[.exe] (...platform info...) major.minor.patch"
-    version_match = shell_result[:output].match(/^gcc(?:#{Regexp.escape(EXTENSION_WIN_EXE)})?\s+.*\s+(\d+)\.(\d+)\.\d+/)
-
-    if version_match.nil? || version_match[1].nil? || version_match[2].nil?
-      raise CeedlingException.new("Could not collect `gcc` version from its command line")
-    end
-
-    return GcovToolVersion.new( version_match[1].to_i, version_match[2].to_i )
+    detect_tool_version(
+      TOOLS_GCOV_GCC_VERSION,
+      /^gcc(?:#{Regexp.escape(EXTENSION_WIN_EXE)})?\s+.*\s+(\d+)\.(\d+)\.\d+/,
+      tool_label: 'gcc'
+    )
   end
 
 end
 
@@ -28,6 +28,7 @@
 GCOV_GCOVR_ARTIFACTS_FILE_COBERTURA   = File.join(GCOV_GCOVR_ARTIFACTS_PATH, "GcovCoverageCobertura.xml")
 GCOV_GCOVR_ARTIFACTS_FILE_SONARQUBE   = File.join(GCOV_GCOVR_ARTIFACTS_PATH, "GcovCoverageSonarQube.xml")
 GCOV_GCOVR_ARTIFACTS_FILE_JSON        = File.join(GCOV_GCOVR_ARTIFACTS_PATH, "GcovCoverage.json")
+GCOV_GCOVR_DEFAULT_TEXT_ARTIFACT_FILENAME = "coverage.txt".freeze
 
 # Report Creation Utilities
 GCOV_UTILITY_NAME_GCOVR = "gcovr"
 
@@ -5,6 +5,9 @@
 #   SPDX-License-Identifier: MIT
 # =========================================================================
 
+require 'ceedling/exceptions'
+require 'gcov_types'
+
 # Abstract base class that formalises the gcov reportinator interface.
 #
 # Subclasses must:
@@ -13,13 +16,16 @@
 #     and expose it via attr_reader.
 #   - Set @configurator in initialize to access build_exclusion_data().
 #   - Set @loginator in initialize to access print_shell_exec_time().
+#   - Set @tool_executor in initialize to use ToolVersionGating's detect_tool_version().
 #   - Initialize @summary = '' and set it during generate_reports() when the
 #     tool produces a coverage summary (e.g. gcovr --print-summary output).
 #     Gcov#generate_coverage_reports reads summary() and is the sole logging site.
 #   - Implement generate_reports(opts) as a void orchestrator.
 #
 class GcovReportinator
 
+  include ToolVersionGating
+
   def initialize(config)
     @config = config
   end
@@ -64,4 +70,63 @@ def build_exclusion_data
     }
   end
 
+
+  # Shared "escape hatch" handling for arbitrary user-supplied CLI arguments, applied
+  # even when a config/report file is otherwise in full control -- both GcovrReportinator's
+  # :custom_args and ReportGeneratorReportinator's :custom_args use this identical pattern.
+  def build_custom_args(custom_args)
+    return "" if custom_args.nil?
+
+    custom_args.each_with_object(String.new) do |custom_arg, args|
+      args << "\"#{custom_arg}\" " unless custom_arg.nil? || custom_arg.empty?
+    end
+  end
+
+
+  # Generic CLI-argument builder driven by a declarative table, so each reportinator's
+  # own option-to-flag mapping reads as plain data rather than repeated ad hoc string
+  # concatenation. table: { option_symbol => spec }, where spec is:
+  #   :flag        - the CLI flag text, or a Proc(version) -> String for a flag whose
+  #                   name itself depends on the tool version (e.g. a deprecated/renamed flag).
+  #   :type        - :boolean (flag alone), :value (flag + one quoted value by default),
+  #                   :inline_value (flag and value quoted together as a single CLI token,
+  #                   ReportGenerator's `-key:value` style, vs. gcovr's `--flag "value"`),
+  #                   :list (flag repeated once per array entry), :integer (flag + value,
+  #                   only if the configured value is an Integer), or :integer_percent
+  #                   (as :integer, plus a 1-100 range check raising CeedlingException).
+  #   :quote       - set false to emit a :value/:list entry's value unquoted.
+  #   :min_version - [major, minor]; entry is silently omitted below this version
+  #                   (distinct from VERSION_GATES-style checks, which raise instead).
+  def build_args_from_table(opts, table, version: nil, component_prefix: '')
+    table.each_with_object(String.new) do |(option, spec), args|
+      value = opts[option]
+      next if value.nil? || value == false
+      next if spec[:min_version] && !min_version?(version, *spec[:min_version])
+
+      flag = spec[:flag].respond_to?(:call) ? spec[:flag].call(version) : spec[:flag]
+      quote = spec[:quote] != false
+
+      case spec[:type]
+      when :boolean
+        args << "#{flag} "
+      when :value
+        args << "#{flag} #{quote ? "\"#{value}\"" : value} "
+      when :inline_value
+        args << "\"#{flag}#{value}\" "
+      when :list
+        Array(value).each { |v| args << "#{flag} #{quote ? "\"#{v}\"" : v} " }
+      when :integer
+        args << "#{flag} #{value} " if value.is_a?(Integer)
+      when :integer_percent
+        unless value.is_a?(Integer)
+          raise CeedlingException.new("#{component_prefix} ↳ :#{option} ➡️ '#{value}' must be an integer")
+        end
+        unless (1..100).cover?(value)
+          raise CeedlingException.new("#{component_prefix} ↳ :#{option} ➡️ '#{value}' must be an integer percentage 1 – 100")
+        end
+        args << "#{flag} #{value} "
+      end
+    end
+  end
+
 end
@@ -5,4 +5,65 @@
 #   SPDX-License-Identifier: MIT
 # =========================================================================
 
-GcovToolVersion = Struct.new(:major, :minor)
+require 'ceedling/exceptions'
+
+# major.minor version of any tool this plugin shells out to (gcovr, gcc) --
+# generic so gcc-version and gcovr-version checks share one comparable type
+# instead of each plugin file inventing its own.
+ToolVersion = Struct.new(:major, :minor)
+
+# Generic version detection + gating, mixed into any class that shells out to
+# a tool whose available features depend on its version (GcovReportinator's
+# gcovr/ReportGenerator subclasses, Gcov's own gcc check). One mechanic here;
+# each includer supplies its own version-tool config, output pattern, and
+# declarative gate table rather than hand-rolling comparison/raise boilerplate
+# per gated option. Requires the includer to have set @tool_executor.
+module ToolVersionGating
+
+  # True when version is at least major.minor. Defined at both module- and instance-level
+  # (the instance method just delegates) so a declarative table built at class-definition
+  # time -- outside any includer instance's context, e.g. a Proc picking a version-dependent
+  # flag name -- can still call it as ToolVersionGating.min_version?(...).
+  def self.min_version?(version, major, minor)
+    return true if version.major > major
+    return true if version.major == major && version.minor >= minor
+    return false
+  end
+
+  def min_version?(version, major, minor)
+    ToolVersionGating.min_version?(version, major, minor)
+  end
+
+  # Run a `--version`-style tool invocation and parse a ToolVersion from its output.
+  # tool_config: a ToolExecutor tool-config hash needing no positional substitutions.
+  # pattern: a Regexp whose first two capture groups are (major, minor).
+  def detect_tool_version(tool_config, pattern, tool_label:)
+    command = @tool_executor.build_command_line( tool_config, [] )
+    shell_result = @tool_executor.exec( command )
+    version_match = shell_result[:output].match( pattern )
+
+    if version_match.nil? || version_match[1].nil? || version_match[2].nil?
+      raise CeedlingException.new( "Could not collect `#{tool_label}` version from its command line" )
+    end
+
+    ToolVersion.new( version_match[1].to_i, version_match[2].to_i )
+  end
+
+  # Raise one CeedlingException listing every configured option in gate_table whose
+  # value is set but whose required minimum version exceeds the detected version.
+  # gate_table: { option_symbol => { min: [major, minor], message: "... %{req} ... %{found} ..." } }.
+  # opts: any hash the option symbols can be looked up in -- callers may merge values
+  # from more than one config namespace (e.g. gcov.rb's :mcdc lives directly under
+  # :gcov, not under :gcov ↳ :gcovr like GcovrReportinator's own gated options).
+  def enforce_version_gates!(opts, version, gate_table)
+    violations = gate_table.filter_map do |option, gate|
+      next if opts[option].nil? || opts[option] == false
+      next if min_version?( version, *gate[:min] )
+
+      gate[:message] % { req: gate[:min].join('.'), found: "#{version.major}.#{version.minor}" }
+    end
+
+    raise CeedlingException.new( violations.join("\n") ) unless violations.empty?
+  end
+
+end