sequra-style 1.17.0 → 1.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e247920824c3d061c6385b8c29a20843d4b1ee27fbca2d6fa3a498f7b4ff6833
-  data.tar.gz: 66fbba9730edfbc25eb5224438bfff22bba38d72399169fcab016633f23fe049
+  metadata.gz: 47e2880848be7928ef68435e320055b4d2003f4b321d172094fa77f123f5139e
+  data.tar.gz: d8ef008a1b7ba0477c45a19d52eb965d86a994fe5c7c203c67ecc2941f2ac798
 SHA512:
-  metadata.gz: 20d6f4326a2b796cae26c3cb7457e80613f9ddd85704cf028d8a8307602293c77d67c22942974e7b3242d7bcfe5f7113dbb9760c6c5704785910e6b54f84fb9f
-  data.tar.gz: e36aa35cf7d5158c17d83f974fe9ac36f5d0e447521eebdeed4f6f4d8d49aec244af1e97b80ea63e9e8001c4b98c354ac7b095791d66240dfe85fdd6faa157b2
+  metadata.gz: 19d7b3760cf692ed282a02b99416f5d3e6f9fc288a8f5ecf8086e40459215f8665c27fc90f336183e42dcc37823668364a9d8503fa8a462b3afc5ad0d68885cb
+  data.tar.gz: 17bd16a9f9499060f4ee8e986c0f7a12e32a5a1f5d28ba494b9b5ca2d6ac8e78dda03254ea83d75c8073bc7823c60a738f171dd492e76910269fd41f1f5574da

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [1.19.0](https://github.com/sequra/sequra-style/compare/v1.18.0...v1.19.0) (2026-07-29)
+
+
+### Features
+
+* [COR-1992] Flag mailer .later stubs in NoSidekiqPerformStubs ([#81](https://github.com/sequra/sequra-style/issues/81)) ([b9ea46e](https://github.com/sequra/sequra-style/commit/b9ea46e97649b40aae30bfa4f6cbbc51fe0c72f0))
+
+## [1.18.0](https://github.com/sequra/sequra-style/compare/v1.17.0...v1.18.0) (2026-07-28)
+
+
+### Features
+
+* **rubocop:** add PrometheusMetricLabels cop ([#79](https://github.com/sequra/sequra-style/issues/79)) ([a8f3ec1](https://github.com/sequra/sequra-style/commit/a8f3ec16cdf9779ad391c7032eca2b109892569d))
+
 ## [1.17.0](https://github.com/sequra/sequra-style/compare/v1.16.0...v1.17.0) (2026-07-20)
 
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    sequra-style (1.17.0)
+    sequra-style (1.19.0)
       rubocop (~> 1.75)
       rubocop-performance (~> 1.25)
       rubocop-rails (~> 2.31)

data/default.yml

@@ -857,3 +857,14 @@ Sequra/NoSidekiqPerformStubs:
     - "**/*_spec.rb"
     - "**/spec/support/**/*.rb"
     - "**/spec/shared_examples/**/*.rb"
+
+# Catch malformed labels on prometheus_exporter metric calls. `increment`,
+# `decrement` and `observe` take labels as a positional hash, so a `labels:`
+# keyword silently produces a series labelled `labels="{...}"` that no
+# by-label query can match. Also catches the value/labels argument order,
+# which is reversed between `observe` and `increment`. Autocorrectable.
+# `warning` severity: these are silently broken metrics, not style, so they
+# fail the build rather than waiting for adoption.
+Sequra/PrometheusMetricLabels:
+  Enabled: true
+  Severity: warning

data/lib/rubocop/cop/sequra/no_sidekiq_perform_stubs.rb

@@ -2,7 +2,8 @@ module RuboCop
   module Cop
     module Sequra
       # Detects RSpec stubs and spy assertions on Sidekiq enqueue methods
-      # (`perform_async`, `perform_at`, `perform_in`).
+      # (`perform_async`, `perform_at`, `perform_in`) and on the mailer
+      # enqueue wrapper (`SomeMailer.later`).
       #
       # Stubbing these methods bypasses `Sidekiq.strict_args!` validation,
       # which lets symbol-keyed hashes (and other non-JSON-native types)
@@ -12,12 +13,19 @@ module RuboCop
       # rescue-swallowers can mask the failure. This pattern caused a
       # silent push-notification drop in COR-1923.
       #
+      # `SomeMailer.later` (seQura's `ApplicationMailer.later`) is the
+      # standard mailer enqueue path and funnels through
+      # `ApplicationMailerJob.perform_async`, so stubbing it bypasses
+      # `strict_args!` exactly like stubbing `perform_async` directly.
+      # `.later` is only flagged when the stubbed subject is a `*Mailer`
+      # constant, so unrelated `.later` methods are left alone.
+      #
       # Use `have_enqueued_sidekiq_job` (or `change(SomeJob.jobs, :size)`)
       # instead. Both go through Sidekiq's client middleware chain, so
       # `strict_args!` validates the arguments as it would in production.
       #
       # `.and_call_original` is exempt: the stub spies on the call but
-      # then runs the real `perform_*`, which still exercises the
+      # then runs the real method, which still exercises the
       # serialization contract.
       #
       # @example
@@ -33,6 +41,9 @@ module RuboCop
       #   # bad - spy verification on a stubbed enqueue
       #   expect(SomeJob).to have_received(:perform_async).with(id)
       #
+      #   # bad - mailer enqueue wrapper bypasses strict_args! too
+      #   allow(WelcomeMailer).to receive(:later)
+      #
       #   # good - exercises strict_args! through Sidekiq's middleware
       #   expect(SomeJob).to have_enqueued_sidekiq_job(id, name: "value")
       #
@@ -43,17 +54,23 @@ module RuboCop
       #   expect(SomeJob).to receive(:perform_async).and_call_original
       #
       class NoSidekiqPerformStubs < Base
-        MSG = "Avoid stubbing Sidekiq enqueue methods (`perform_async`/`perform_at`/`perform_in`). " \
-              "Stubs bypass `Sidekiq.strict_args!` validation and can hide symbol-keyed hash bugs " \
-              "(see COR-1923). Use `have_enqueued_sidekiq_job` or `change(Job.jobs, :size)` instead. " \
-              "Use `.and_call_original` only as an escape hatch.".freeze
+        MSG = "Avoid stubbing job/mailer enqueue methods (`perform_async`/`perform_at`/`perform_in`, " \
+              "or `Mailer.later`). Stubs bypass `Sidekiq.strict_args!` validation and can hide " \
+              "symbol-keyed hash bugs (see COR-1923). Use `have_enqueued_sidekiq_job` or " \
+              "`change(Job.jobs, :size)` instead. Use `.and_call_original` only as an escape hatch.".freeze
+
+        SUBJECT_WRAPPERS = [:allow, :expect, :allow_any_instance_of, :expect_any_instance_of].freeze
 
         def_node_matcher :perform_method_stub?, <<~PATTERN
           (send nil? {:receive :have_received} (sym {:perform_async :perform_at :perform_in}))
         PATTERN
 
+        def_node_matcher :later_method_stub?, <<~PATTERN
+          (send nil? {:receive :have_received} (sym :later))
+        PATTERN
+
         def on_send(node)
-          return unless perform_method_stub?(node)
+          return unless perform_method_stub?(node) || mailer_later_stub?(node)
           return if chained_with_call_original?(node)
 
           add_offense(node)
@@ -61,6 +78,26 @@ module RuboCop
 
         private
 
+        def mailer_later_stub?(node)
+          return false unless later_method_stub?(node)
+
+          subject = stubbed_subject(node)
+          subject&.const_type? && subject.const_name.to_s.end_with?("Mailer")
+        end
+
+        def stubbed_subject(node)
+          current = node
+          current = current.parent while current.parent&.send_type? && current.parent.receiver == current
+
+          matcher = current.parent
+          return unless matcher&.send_type?
+
+          wrapper = matcher.receiver
+          return unless wrapper&.send_type? && SUBJECT_WRAPPERS.include?(wrapper.method_name)
+
+          wrapper.first_argument
+        end
+
         def chained_with_call_original?(node)
           current = node
           loop do

data/lib/rubocop/cop/sequra/prometheus_metric_labels.rb

@@ -0,0 +1,156 @@
+module RuboCop
+  module Cop
+    module Sequra
+      # Detects malformed label arguments on `prometheus_exporter` metric calls.
+      #
+      # `PrometheusExporter::Client::RemoteMetric` takes labels as a positional
+      # hash, and the position differs per method:
+      #
+      #   increment(keys = nil, value = 1)
+      #   decrement(keys = nil, value = 1)
+      #   observe(value = 1, keys = nil)
+      #
+      # None of them accept keyword arguments, so `increment(labels: {...})`
+      # does not raise. Ruby folds the keyword into the positional `keys` hash
+      # and the exporter emits a series carrying a label literally named
+      # `labels`, whose value is the stringified inner hash. The result is
+      # valid Prometheus exposition text, so the scrape succeeds and the
+      # target stays healthy — `sum by (outcome)` simply never matches.
+      #
+      # Nothing downstream can catch it: the exporter keys its series by the
+      # raw hash, `labels_text` interpolates label names without validating
+      # them, and `opts: { labels: [...] }` at registration is discarded
+      # outright for counters and gauges. There is no label schema anywhere,
+      # so a wrong label name is indistinguishable from a new one, and the
+      # mistake only surfaces when a query silently returns nothing.
+      #
+      # @example
+      #   # bad - folded into a label named "labels"
+      #   counter.increment(labels: { outcome: :bound })
+      #
+      #   # good
+      #   counter.increment({ outcome: :bound })
+      #
+      #   # bad - observe takes the value first
+      #   histogram.observe({ outcome: :ok }, duration)
+      #
+      #   # good
+      #   histogram.observe(duration, { outcome: :ok })
+      #
+      #   # bad - increment takes the labels first
+      #   counter.increment(1, { outcome: :bound })
+      #
+      #   # good
+      #   counter.increment({ outcome: :bound }, 1)
+      #
+      #   # bad - freezes the mistake into a passing spec
+      #   expect(counter).to receive(:increment).with(labels: { outcome: :bound })
+      #
+      #   # good
+      #   expect(counter).to receive(:increment).with({ outcome: :bound })
+      #
+      class PrometheusMetricLabels < Base
+        extend AutoCorrector
+
+        MSG_LABELS_KEYWORD = "Pass Prometheus labels positionally, not as a `labels:` keyword. " \
+                             "`increment`/`observe`/`decrement` take no keyword arguments, so this " \
+                             "becomes a single series labelled `labels=\"{...}\"` and by-label " \
+                             "queries never match. Use `increment({ outcome: :bound })`.".freeze
+
+        MSG_VALUE_FIRST = "`observe` takes the value first and the labels second: " \
+                          "`observe(value, { outcome: :ok })`. A labels hash in the first position " \
+                          "is recorded as the observed value.".freeze
+
+        MSG_LABELS_FIRST = "`%<method>s` takes the labels first and the value second: " \
+                           "`%<method>s({ outcome: :ok }, 1)`. This is the reverse of `observe`.".freeze
+
+        MSG_STUBBED_LABELS = "Stubbing `increment` with a `labels:` keyword asserts a label shape " \
+                             "prometheus_exporter never produces, so the spec stays green while " \
+                             "the metric is broken. Match the positional hash instead: " \
+                             "`.with({ outcome: :bound })`.".freeze
+
+        LABELS_FIRST_METHODS = [:increment, :decrement].freeze
+        VALUE_FIRST_METHODS = [:observe].freeze
+        METRIC_METHODS = (LABELS_FIRST_METHODS + VALUE_FIRST_METHODS).freeze
+
+        # `expect(counter).to receive(:increment).with(...)` and the
+        # `have_received` spy equivalent.
+        def_node_matcher :stubbed_metric_expectation?, <<~PATTERN
+          (send
+            (send nil? {:receive :have_received} (sym {:increment :decrement :observe}))
+            :with ...)
+        PATTERN
+
+        def on_send(node)
+          check_stubbed_labels_keyword(node)
+
+          return unless node.receiver && METRIC_METHODS.include?(node.method_name)
+
+          # A `labels:` key is the more specific diagnosis, so when it is
+          # present it wins and the positional checks stay quiet.
+          return if check_labels_keyword(node)
+
+          check_argument_order(node)
+        end
+
+        private
+
+        def check_labels_keyword(node)
+          pair = labels_pair(trailing_hash(node))
+          return false unless pair
+
+          register_labels_keyword_offense(node, pair, MSG_LABELS_KEYWORD)
+          true
+        end
+
+        def check_stubbed_labels_keyword(node)
+          return unless stubbed_metric_expectation?(node)
+
+          pair = labels_pair(trailing_hash(node))
+          return unless pair
+
+          register_labels_keyword_offense(node, pair, MSG_STUBBED_LABELS)
+        end
+
+        def check_argument_order(node)
+          arguments = node.arguments
+          return if arguments.empty?
+
+          if VALUE_FIRST_METHODS.include?(node.method_name)
+            add_offense(arguments.first, message: MSG_VALUE_FIRST) if arguments.first.hash_type?
+          elsif value_before_labels?(arguments)
+            add_offense(node, message: format(MSG_LABELS_FIRST, method: node.method_name))
+          end
+        end
+
+        # Only the unambiguous flip: a bare number where the labels belong,
+        # followed by the labels hash. Anything less literal than that could
+        # be a non-metric `increment` (`Rails.cache`, atomics) and is left
+        # alone.
+        def value_before_labels?(arguments)
+          arguments.size == 2 && arguments.first.numeric_type? && arguments.last.hash_type?
+        end
+
+        def trailing_hash(node)
+          last_argument = node.arguments.last
+          last_argument if last_argument&.hash_type?
+        end
+
+        def labels_pair(hash)
+          return unless hash
+
+          hash.pairs.find { |pair| pair.key.sym_type? && pair.key.value == :labels }
+        end
+
+        def register_labels_keyword_offense(node, pair, message)
+          add_offense(pair, message:) do |corrector|
+            # Unwrapping is only safe when `labels:` is the whole hash;
+            # with siblings present there is no single value to hoist.
+            hash = trailing_hash(node)
+            corrector.replace(hash, pair.value.source) if hash.pairs.one?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sequra/style/version.rb

@@ -1,5 +1,5 @@
 module Sequra
   module Style
-    VERSION = "1.17.0"
+    VERSION = "1.19.0"
   end
 end

data/lib/sequra_style.rb

@@ -1,3 +1,4 @@
 require "rubocop"
 require_relative "rubocop/cop/sequra/async_job_pattern"
 require_relative "rubocop/cop/sequra/no_sidekiq_perform_stubs"
+require_relative "rubocop/cop/sequra/prometheus_metric_labels"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sequra-style
 version: !ruby/object:Gem::Version
-  version: 1.17.0
+  version: 1.19.0
 platform: ruby
 authors:
 - Sequra engineering
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-20 00:00:00.000000000 Z
+date: 2026-07-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rubocop
@@ -142,6 +142,7 @@ files:
 - docs/decisions/template.md
 - lib/rubocop/cop/sequra/async_job_pattern.rb
 - lib/rubocop/cop/sequra/no_sidekiq_perform_stubs.rb
+- lib/rubocop/cop/sequra/prometheus_metric_labels.rb
 - lib/sequra/style.rb
 - lib/sequra/style/version.rb
 - lib/sequra_style.rb