gitlab_quality-test_tooling 3.21.0 → 3.21.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6fa78c58b83ed94504f42df7a78f5bdbddea78f9466134618b6c9b34fa99d679
-  data.tar.gz: bb3b04f2dee89712fd561a944de2d397db62867351f562ac0b0e7cac721424d2
+  metadata.gz: cbd765eef13187839210bb0dde07988168415170236b8734d3faf396ce95b9a9
+  data.tar.gz: '0877e97fd029bdb06028dad82aeae1a15f18b73e3f8ad2ad9c0448819335ca71'
 SHA512:
-  metadata.gz: d969c70fbf9efb0aac4020367999aca505d226125a63daeaa8dc6f5ad409f84d8f9bc6a411ada6c9aa5c91627ef8bec768a165bcf4258df0e7e65426d63776c3
-  data.tar.gz: d3329d8d499320cd0fdad6a8a2c9ea669d7310b1076aa5c8130e3c4b79e6f12e2fc2a32ecaa0a11f057860f8c8f82db9551120f5f0b5ce28f9a1898597a74842
+  metadata.gz: f242e07dbdefd766fd8f2bec91b779c93bf68f91a913314982b8e3053db99704fa0330cb31dadeb8829c570f43b7f2f04c52265fcdd75cc1beb60f1486096554
+  data.tar.gz: b6cd28e7ad33b233fb6f7c68db39ade7b72118913eac8e3b3281e018d59a9e9e5ca99b50a7730d28f189b5a2517c2c933e254d15f7a50cff6800476346aa4b37

data/AGENTS.md

@@ -75,6 +75,13 @@ Reference: https://docs.gitlab.com/ee/development/changelog.html
 - **CodeCoverage** — Coverage analysis and responsibility patterns
 - **ClickHouse::Client** — HTTP query/insert client for ClickHouse, used by the code coverage subsystem
 
+## Code Comments
+
+Comments carry the non-obvious why, not what the code already says. Keep them
+short. A header block that restates the query or narrates each column gets
+trimmed to the design decisions a reader can't infer from the code. This
+applies to AI-generated comments too: trim before committing.
+
 ## Review Guidance
 
 - `RelateFailureIssue#trigger_duo_analysis` deliberately rescues all `StandardError` (best-effort): a Duo/API failure must never block failure-issue creation. Preserve the broad rescue — don't narrow or remove it.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    gitlab_quality-test_tooling (3.21.0)
+    gitlab_quality-test_tooling (3.21.1)
       activesupport (>= 7.0)
       amatch (~> 0.4.1)
       fog-google (~> 1.24, >= 1.24.1)

data/lib/gitlab_quality/test_tooling/code_coverage/click_house/test_health_risk_aggregation.sql

@@ -1,52 +1,28 @@
--- Daily aggregation of per-test coverage data into per-group risk summary.
+-- Daily aggregation of per-test coverage into per-group risk rows: one
+-- (snapshot_date, group, stage, section) row inserted into
+-- code_coverage.test_health_risk_per_group.
 --
--- Reads the bitmap line sets from `code_coverage.test_coverage_per_file`,
--- joins per-test quarantine and flaky status from `test_metrics`, then
--- computes for each source file:
---   quarantined_union        = union of line sets covered by *quarantined* tests
---   flaky_union              = union of line sets covered by *flaky* tests
---   quarantined_or_flaky_union = union of line sets covered by *quarantined OR flaky* tests
---   healthy_union            = union of line sets covered by tests that are neither
+-- "At risk" lines are covered only by quarantined/flaky tests. The healthy
+-- baseline excludes flaky tests by design: a flaky test isn't a reliable
+-- safety net, so its lines shouldn't offset quarantine-only risk.
 --
--- The "at risk" line counts are:
---   at_risk_lines_quarantine = lines uniquely covered by quarantined tests
---                              (not covered by any healthy test)
---   at_risk_lines_flaky      = lines uniquely covered by flaky tests
---   at_risk_lines_combined   = lines uniquely covered by quarantined OR flaky
+-- Parameters use `{name}` braces, substituted as literal text by gsub in
+-- TestHealthRiskAggregator#build_sql after validation. A typoed placeholder
+-- silently survives gsub, so match the names exactly.
+--   {snapshot_date}  date stamp for this run
+--   {coverage_start} day of the most recent full per-test capture
+--   {risk_window}    quarantine/flaky lookback, default '30 DAY'
 --
--- Healthy union excludes flaky tests too, by design: a flaky test isn't a
--- reliable coverage safety net, so its lines shouldn't count toward the
--- baseline against which quarantine-only risk is measured.
+-- The INSERT is unconditional. Idempotency comes from the target table's
+-- ReplacingMergeTree(version) engine keyed by the row tuple: re-runs and
+-- overlapping cross-run inserts replace rather than duplicate, latest wins.
 --
--- Result: one row per (snapshot_date, group, stage, section) tuple inserted
--- into `code_coverage.test_health_risk_per_group`.
---
--- Parameter substitution: this template uses `{name}` braces (not %{name} or
--- :name). They're replaced by literal text via `gsub` in
--- TestHealthRiskAggregator#build_sql, after each parameter passes a regex
--- check. A typoed placeholder name will silently fall through gsub as a
--- literal — match the names exactly.
---
---   {snapshot_date}     : the date stamp for this run, e.g. '2026-05-07'
---   {coverage_window}   : interval to look back for fresh per-test rows,
---                         default '2 DAY' (see Resilience note below)
---   {risk_window}       : interval to consider quarantine/flaky status from
---                         the test_metrics summaries, default '30 DAY'
-
--- Idempotency: this INSERT is unconditional. The target table must use
--- SharedReplacingMergeTree(version) (or ReplacingMergeTree on non-Cloud
--- ClickHouse; Cloud silently rewrites to Shared...) keyed by
--- (snapshot_date, group, stage, section), with
--- `version UInt64 MATERIALIZED toUnixTimestamp64Milli(now64(3))`, so re-running
--- for the same snapshot_date produces a higher version that replaces the
--- previous row on merge. Without that engine, re-runs would duplicate rows.
---
--- Resilience: `{coverage_window}` defaults to 2 DAY (see
--- TestHealthRiskAggregator::DEFAULT_COVERAGE_WINDOW). One missed nightly
--- run is recovered on the next night because the aggregation still sees
--- the previous day's per-test rows. Cross-run race: if two jobs land
--- inserts overlapping with the aggregation, the later aggregation wins
--- because of the version-based replacement.
+-- Per-test capture is sparse between full sweeps (roughly weekly), so a
+-- fixed trailing window would flap. {coverage_start} anchors the universe at
+-- the last day that cleared the full-capture floor (#find_coverage_start);
+-- when no day qualifies within the lookback, nothing is written and the
+-- previous snapshot carries forward. FINAL on the source keeps the latest
+-- version per (test_file, source_file), so the wide span never double-counts.
 INSERT INTO code_coverage.test_health_risk_per_group
 WITH
   quarantine_status AS (
@@ -109,7 +85,7 @@ WITH
     LEFT JOIN quarantine_status qs ON qs.test_file = tc.test_file
     LEFT JOIN flaky_status      fs ON fs.test_file = tc.test_file
     LEFT JOIN test_ownership own ON own.file_path = tc.test_file
-    WHERE tc.timestamp >= now() - INTERVAL {coverage_window}
+    WHERE tc.timestamp >= toDate('{coverage_start}')
   ),
   per_file AS (
     SELECT

data/lib/gitlab_quality/test_tooling/code_coverage/click_house/test_health_risk_aggregator.rb

@@ -19,14 +19,25 @@ module GitlabQuality
 
           SQL_FILE = File.expand_path('test_health_risk_aggregation.sql', __dir__)
 
-          # 2 DAY rather than 1 DAY makes the aggregation self-healing across
-          # a single missed nightly run: if last night's export failed, this
-          # night's run still sees yesterday's per-test rows and produces a
-          # current snapshot. ReplacingMergeTree FINAL on the source table
-          # ensures we read only the latest version per (test_file, source_file).
-          # ClickHouse accepts both '2 DAY' and '2 DAYS'; we use the singular
-          # form for consistency with `30 DAY` below.
-          DEFAULT_COVERAGE_WINDOW = '2 DAY'
+          # Per-test capture is sparse between full captures (a full sweep of
+          # the suite lands roughly weekly; weekdays contribute only a small
+          # delta), so the coverage universe anchors at the most recent day
+          # whose capture volume clears this floor instead of a fixed trailing
+          # interval. Counted in distinct test files, because the weekend
+          # sweep enumerates the whole suite by test file: full sweeps land
+          # 22-27k test files, a single sweep bucket ~13k, and delta days at
+          # most ~16k even at their historical worst. Source files would not
+          # separate the cases: a few thousand tests already touch tens of
+          # thousands of source files through app boot, so a healthy delta
+          # day could pass a source-file floor and anchor the window at a
+          # partial capture.
+          DEFAULT_FULL_CAPTURE_FLOOR = 18_000
+          # Far enough back to bridge two missed weekly full captures before
+          # giving up, and well inside the source table's 90-day TTL. When no
+          # day within the lookback clears the floor, the run writes nothing
+          # so the previous snapshot carries forward rather than publishing a
+          # denominator built from sparse data.
+          DEFAULT_ANCHOR_LOOKBACK = '21 DAY'
           DEFAULT_RISK_WINDOW = '30 DAY'
 
           # `snapshot_date` is YYYY-MM-DD; intervals are `<integer> <unit>`
@@ -36,35 +47,38 @@ module GitlabQuality
 
           def initialize(
             url:, database:, username: nil, password: nil, logger: nil,
-            coverage_window: DEFAULT_COVERAGE_WINDOW, risk_window: DEFAULT_RISK_WINDOW)
+            full_capture_floor: DEFAULT_FULL_CAPTURE_FLOOR, anchor_lookback: DEFAULT_ANCHOR_LOOKBACK,
+            risk_window: DEFAULT_RISK_WINDOW)
             @url = url
             @database = database
             @username = username
             @password = password
             @logger = logger || ::Logger.new($stdout, level: 1)
-            @coverage_window = coverage_window
+            @full_capture_floor = full_capture_floor
+            @anchor_lookback = anchor_lookback
             @risk_window = risk_window
           end
 
           # @param snapshot_date [Date, String] date stamp for this run; defaults to today.
           # @return [void]
           def run(snapshot_date: Date.today) # rubocop:disable Metrics/AbcSize
-            sql = build_sql(snapshot_date: snapshot_date)
-            logger.info(
-              "#{LOG_PREFIX} Running test_health_risk aggregation snapshot_date=#{snapshot_date} " \
-                "coverage_window=#{coverage_window} risk_window=#{risk_window}"
-            )
-            client.query(sql, format: "TabSeparated")
-            inserted = fetch_row_count(snapshot_date)
-            if inserted.is_a?(Integer) && inserted.zero?
+            date = validate_date(snapshot_date)
+            coverage_start = find_coverage_start
+            if coverage_start.nil?
               logger.warn(
-                "#{LOG_PREFIX} Aggregation wrote 0 rows for snapshot_date=#{snapshot_date}. " \
-                  "This is valid if no per-test data is in the coverage_window, but worth checking " \
-                  "test_coverage_per_file directly if a recent export ran."
+                "#{LOG_PREFIX} No day within #{anchor_lookback} captured >= #{full_capture_floor} " \
+                  "distinct test files; skipping snapshot for #{date} so the previous row carries forward."
               )
-            else
-              logger.info("#{LOG_PREFIX} Aggregation wrote #{inserted} rows for snapshot_date=#{snapshot_date}")
+              return
             end
+
+            sql = build_sql(snapshot_date: date, coverage_start: coverage_start)
+            logger.info(
+              "#{LOG_PREFIX} Running test_health_risk aggregation snapshot_date=#{date} " \
+                "coverage_start=#{coverage_start} risk_window=#{risk_window}"
+            )
+            client.query(sql, format: "TabSeparated")
+            report_row_count(date)
           rescue StandardError => e
             logger.error("#{LOG_PREFIX} Aggregation failed for #{snapshot_date}: #{e.message}")
             raise
@@ -72,24 +86,62 @@ module GitlabQuality
 
           private
 
-          attr_reader :url, :database, :username, :password, :logger, :coverage_window, :risk_window
+          attr_reader :url, :database, :username, :password, :logger,
+            :full_capture_floor, :anchor_lookback, :risk_window
+
+          # Most recent day whose capture volume looks like a full sweep of the
+          # suite. maxOrNull (rather than max) distinguishes "no qualifying day"
+          # from a real date when the subquery comes back empty.
+          def find_coverage_start
+            sql = <<~SQL
+              SELECT maxOrNull(day) AS coverage_start
+              FROM (
+                SELECT toDate(timestamp) AS day
+                FROM code_coverage.test_coverage_per_file
+                WHERE timestamp >= now() - INTERVAL #{validate_interval(anchor_lookback)}
+                GROUP BY day
+                HAVING uniqExact(test_file) >= #{validate_positive_integer(full_capture_floor)}
+              )
+            SQL
+            anchor = client.query(sql, format: "JSONCompact")&.dig('data', 0, 0)
+            anchor.nil? ? nil : validate_date(anchor, 'coverage_start')
+          end
+
+          def report_row_count(date)
+            inserted = fetch_row_count(date)
+            if inserted.is_a?(Integer) && inserted.zero?
+              logger.warn(
+                "#{LOG_PREFIX} Aggregation wrote 0 rows for snapshot_date=#{date}. " \
+                  "This is valid if no per-test data landed since the coverage anchor, but worth " \
+                  "checking test_coverage_per_file directly if a recent export ran."
+              )
+            else
+              logger.info("#{LOG_PREFIX} Aggregation wrote #{inserted} rows for snapshot_date=#{date}")
+            end
+          end
 
-          def build_sql(snapshot_date:)
+          def build_sql(snapshot_date:, coverage_start:)
             template = File.read(SQL_FILE)
             template
               .gsub('{snapshot_date}', validate_date(snapshot_date))
-              .gsub('{coverage_window}', validate_interval(coverage_window))
+              .gsub('{coverage_start}', coverage_start)
               .gsub('{risk_window}', validate_interval(risk_window))
           end
 
           # DateTime/Time `to_s` includes the time portion and is rejected.
-          def validate_date(value)
+          def validate_date(value, name = 'snapshot_date')
             str = value.to_s
-            raise ArgumentError, "Invalid snapshot_date: #{value.inspect}" unless DATE_PATTERN.match?(str)
+            raise ArgumentError, "Invalid #{name}: #{value.inspect}" unless DATE_PATTERN.match?(str)
 
             str
           end
 
+          def validate_positive_integer(value)
+            raise ArgumentError, "Invalid full_capture_floor: #{value.inspect}" unless value.is_a?(Integer) && value.positive?
+
+            value.to_s
+          end
+
           def validate_interval(value)
             raise ArgumentError, "Invalid interval expression: #{value.inspect}" unless INTERVAL_PATTERN.match?(value.to_s)
 

data/lib/gitlab_quality/test_tooling/version.rb

@@ -2,6 +2,6 @@
 
 module GitlabQuality
   module TestTooling
-    VERSION = "3.21.0"
+    VERSION = "3.21.1"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gitlab_quality-test_tooling
 version: !ruby/object:Gem::Version
-  version: 3.21.0
+  version: 3.21.1
 platform: ruby
 authors:
 - GitLab Quality
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-14 00:00:00.000000000 Z
+date: 2026-08-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: climate_control