sequra-style 1.17.0 → 1.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e247920824c3d061c6385b8c29a20843d4b1ee27fbca2d6fa3a498f7b4ff6833
-  data.tar.gz: 66fbba9730edfbc25eb5224438bfff22bba38d72399169fcab016633f23fe049
+  metadata.gz: c3cb23d52c4f8f874a5aad9ee232ab2b3de754fa4c993fe9a24575072f134d99
+  data.tar.gz: 0014151bbc9f819fdedf44f7604f2a47fa7e3e320873e501138f5c75886750fb
 SHA512:
-  metadata.gz: 20d6f4326a2b796cae26c3cb7457e80613f9ddd85704cf028d8a8307602293c77d67c22942974e7b3242d7bcfe5f7113dbb9760c6c5704785910e6b54f84fb9f
-  data.tar.gz: e36aa35cf7d5158c17d83f974fe9ac36f5d0e447521eebdeed4f6f4d8d49aec244af1e97b80ea63e9e8001c4b98c354ac7b095791d66240dfe85fdd6faa157b2
+  metadata.gz: d9ef0de4f838e0be3c4f2413ab7496aa8fa96baf5eb10026cc01a822112d1e51bd0428032b7505de0ef6f3922f77d840c0c9eda081098dfea559d01d3b6641cb
+  data.tar.gz: cf6170ea43e2aa6f3a03da557bb43927ec72f3ac48bbdefa55f7059426803b96f8439b603f3246df45347505ceb7311e0e0091dc3ea120d9b0c64b06469c8aca

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [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.18.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/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.18.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.18.0
 platform: ruby
 authors:
 - Sequra engineering
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-20 00:00:00.000000000 Z
+date: 2026-07-28 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