(MODULES-11831) Add SimpleCov coverage gate with baseline mode

Sync a coverage gate to all modules via `pdk update`:

* moduleroot/.github/workflows/coverage.yml.erb - thin caller that
  delegates to puppetlabs/cat-github-actions module_coverage.yml,
  passing threshold and baseline_mode from .sync.yml.
* moduleroot/spec/spec_helper.rb.erb - SimpleCov hook that starts before
  any application code loads. Gated behind the COVERAGE env var and the
  `simplecov` config flag, so local `rake spec` runs are unaffected and
  there is no double-load or json/json_pure conflict.
* config_defaults.yml - add `simplecov: true`, a managed coverage.yml
  entry (threshold 80, baseline_mode true), and the simplecov /
  simplecov-lcov gems. baseline_mode with no `.coverage_baseline` file is
  a no-op gate, so the rollout is non-breaking.
* README.md - document the new keys and the two coverage modes.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: imaqsood

README.md

@@ -200,6 +200,17 @@ release_schedule:
 
 In this example the automated release prep workflow is triggered every Saturday at 3 am.
 
+### .github/workflows/coverage.yml
+
+> The coverage workflow enforces Ruby unit-test coverage on pull requests. It runs `bundle exec rake spec` with [SimpleCov](https://github.com/simplecov-ruby/simplecov) enabled (driven by the `simplecov` key on `spec/spec_helper.rb`), uploads the LCOV report as a build artifact, and posts the coverage result as a PR comment. It delegates to the reusable `puppetlabs/cat-github-actions/.github/workflows/module_coverage.yml` workflow. The gate runs in one of two modes:
+
+| Key            | Description   |
+| :------------- |:--------------|
+|threshold|In absolute mode, the minimum line coverage percentage required for the build to pass. Defaults to `80`.|
+|baseline_mode|When `true` (the default), the build gates against a `.coverage_baseline` file in the repo root instead of `threshold`: it fails only if coverage drops below the recorded baseline, and stays green (suggesting a new baseline) when coverage rises. When no `.coverage_baseline` file exists the baseline is `0`, so the gate is a no-op and rollout is non-breaking. Set to `false` to gate against `threshold` instead.|
+
+To start ratcheting coverage in baseline mode, commit a `.coverage_baseline` file containing the current line coverage percentage (for example `82.5`). To switch a module to a fixed target, set `baseline_mode: false` and tune `threshold` in `.sync.yml`. To opt a module out entirely, set both `simplecov: false` (on `spec/spec_helper.rb`) and `unmanaged: true` on `.github/workflows/coverage.yml`.
+
 ### .pdkignore
 
 >A .pdkignore file in your repo allows you to specify files to ignore when building a module package with `pdk build`.
@@ -323,6 +334,7 @@ is_pe: false
 |strict_variables| Defines the [Puppet Strict Variables configuration parameter](https://puppet.com/docs/puppet/5.4/configuration.html#strict_variables). Defaults to `true` however due to `puppetlabs_spec_helper` forced override (https://github.com/puppetlabs/puppetlabs_spec_helper/blob/070ecb79a63cb8fa10f46532c413c055e2697682/lib/puppetlabs_spec_helper/module_spec_helper.rb#L71). Set to `false` to align with true default or with `STRICT_VARIABLES=no` environment setting.|
 |coverage_report|Enable [rspec-puppet coverage reports](https://rspec-puppet.com/documentation/coverage/). Defaults to `false`|
 |minimum_code_coverage_percentage|The desired code coverage percentage required for tests to pass. Defaults to `0`|
+|simplecov|Enables the [SimpleCov](https://github.com/simplecov-ruby/simplecov) hook used by the coverage workflow to measure Ruby line coverage of `lib/`. The hook only activates when the `COVERAGE` environment variable is set to `yes` (the coverage workflow sets this), so local `rake spec` runs are unaffected. Defaults to `true`. This is separate from `coverage_report`, which measures Puppet resource coverage.|
 
 ## Further Notes
 

config_defaults.yml

@@ -555,8 +555,12 @@ Gemfile:
         version: '= 3.12.1'
       - gem: 'pry'
         version: '~> 0.10'
+      - gem: 'simplecov'
+        version: '~> 0.22'
       - gem: 'simplecov-console'
         version: '~> 0.9'
+      - gem: 'simplecov-lcov'
+        version: '~> 0.8'
       - gem: 'puppet-debugger'
         version: '~> 1.6'
       - gem: 'rubocop'
@@ -615,6 +619,16 @@ spec/spec_helper.rb:
   mock_with: ":rspec"
   strict_level: ":warning"
   strict_variables: true
+  # Enables the SimpleCov hook used by the coverage workflow. Active only when
+  # the COVERAGE env var is set, so local `rake spec` runs are unaffected.
+  simplecov: true
+# The coverage workflow is managed (not unmanaged) so `pdk update` rolls it out
+# to every module. baseline_mode with no `.coverage_baseline` file is a no-op
+# gate (baseline 0), so deploying it is non-breaking; commit a baseline to start
+# ratcheting, or set `baseline_mode: false` to gate against `threshold`.
+.github/workflows/coverage.yml:
+  threshold: 80
+  baseline_mode: true
 .github/workflows/ci.yml:
   unmanaged: true
 .github/workflows/nightly.yml:

moduleroot/.github/workflows/coverage.yml.erb

@@ -0,0 +1,23 @@
+<% coverage = @configs['.github/workflows/coverage.yml'] || {} -%>
+name: "coverage"
+
+on:
+  pull_request:
+    branches:
+      - "main"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pull-requests: write
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  Coverage:
+    uses: "puppetlabs/cat-github-actions/.github/workflows/module_coverage.yml@main"
+    with:
+      threshold: <%= coverage['threshold'] || 80 %>
+      baseline_mode: <%= coverage['baseline_mode'] ? true : false %>

moduleroot/spec/spec_helper.rb.erb

@@ -1,5 +1,31 @@
 # frozen_string_literal: true
 
+<%- if @configs['simplecov'] -%>
+# SimpleCov must start before any application code is required so that every
+# line is tracked. Gated behind the COVERAGE env var so local `rake spec` runs
+# are unaffected; the coverage workflow sets COVERAGE=yes.
+if ENV['COVERAGE'] == 'yes'
+  require 'simplecov'
+  require 'simplecov-lcov'
+
+  SimpleCov::Formatter::LcovFormatter.config do |config|
+    config.report_with_single_file = true
+  end
+  SimpleCov.formatters = SimpleCov::Formatter::MultiFormatter.new(
+    [
+      SimpleCov::Formatter::SimpleFormatter,
+      SimpleCov::Formatter::LcovFormatter,
+    ],
+  )
+  SimpleCov.start do
+    track_files 'lib/**/*.rb'
+    add_filter '/spec/'
+    add_filter '/vendor/'
+    add_filter '/.vendor/'
+  end
+end
+
+<%- end -%>
 <%- if @configs['mock_with'] -%>
 RSpec.configure do |c|
   c.mock_with <%= @configs['mock_with'] %>