rubocop-constable 0.1.0

data/lib/rubocop/cop/constable/no_unfrozen_time.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Constable
+      # Reading the wall clock inside a case makes the test a function of when it
+      # runs. Most of the time that is invisible; then the suite goes red at
+      # midnight, on the last day of a month, or in the one CI region that isn't
+      # UTC. Freeze the clock and the whole class of failure disappears.
+      #
+      # The cop is satisfied by any of:
+      #
+      # * a lexically enclosing `freeze_time { }` / `travel_to(...) { }` block,
+      # * a bare `freeze_time` / `travel_to` earlier in the same `investigate`,
+      # * a `freeze_time` / `travel_to` in any `briefing` in the file (a briefing
+      #   runs before every investigation, so it covers all of them),
+      # * being the argument to a freeze helper (`freeze_time(Time.now)` is fine),
+      # * the `unsafe { }` escape hatch.
+      #
+      # @example
+      #   # bad
+      #   investigate "stamps the record" do
+      #     attest(record.created_at).to eq(Time.now)
+      #   end
+      #
+      #   # good
+      #   investigate "stamps the record" do
+      #     freeze_time
+      #     attest(record.created_at).to eq(Time.now)
+      #   end
+      #
+      #   # good
+      #   briefing { freeze_time }
+      #
+      #   investigate "stamps the record" do
+      #     attest(record.created_at).to eq(Time.current)
+      #   end
+      class NoUnfrozenTime < Base
+        include CaseScope
+        include Helpers
+
+        MSG = "`%<call>s` reads the wall clock, which makes this investigation a " \
+              "function of when it runs. Call `freeze_time` (or `travel_to`) first, " \
+              "or reach for `unsafe { }` if the real clock is genuinely the subject."
+
+        DEFAULT_FORBIDDEN_CALLS = %w[
+          Time.now Time.current Time.zone.now
+          Date.today Date.current
+          DateTime.now DateTime.current
+        ].freeze
+
+        DEFAULT_FREEZE_HELPERS = %w[freeze_time travel_to].freeze
+
+        # Blocks whose body is one investigation's worth of scope.
+        SCOPE_METHODS = %i[investigate briefing docket witness].freeze
+
+        def on_new_investigation
+          @freeze_calls = nil
+          super
+        end
+
+        def on_send(node)
+          return unless constable_case_file?
+
+          name = qualified_call_name(node)
+          return unless name && forbidden_calls.include?(name)
+          return if exempt?(node)
+
+          add_offense(node, message: format(MSG, call: name))
+        end
+        alias on_csend on_send
+
+        private
+
+        def exempt?(node)
+          inside_unsafe_block?(node) ||
+            freeze_helper_argument?(node) ||
+            inside_freeze_block?(node) ||
+            frozen_by_briefing? ||
+            frozen_earlier_in_scope?(node)
+        end
+
+        # `freeze_time(Time.now)` / `travel_to(Time.now + 1.day)` -- the clock read
+        # is what gets frozen, so it cannot itself be unfrozen.
+        def freeze_helper_argument?(node)
+          # A freeze helper takes no receiver, so anything below it in the tree is
+          # necessarily one of its arguments.
+          node.each_ancestor(:send, :csend).any? { |ancestor| freeze_helper?(ancestor) }
+        end
+
+        def inside_freeze_block?(node)
+          node.each_ancestor(:block, :numblock).any? do |ancestor|
+            freeze_helper?(ancestor.send_node)
+          end
+        end
+
+        def frozen_by_briefing?
+          freeze_calls.any? { |call| inside_briefing?(call) }
+        end
+
+        # A bare `freeze_time` earlier in the same investigation covers everything
+        # after it. When the call isn't inside a recognisable scope block at all
+        # (a plain helper method, say), fall back to "anywhere earlier in the file".
+        def frozen_earlier_in_scope?(node)
+          scope = enclosing_scope(node)
+
+          freeze_calls.any? do |call|
+            next false if call.loc.line > node.loc.line
+
+            scope.nil? || enclosing_scope(call).equal?(scope)
+          end
+        end
+
+        def enclosing_scope(node)
+          node.each_ancestor(:block, :numblock).find do |ancestor|
+            send_node = ancestor.send_node
+            send_node.receiver.nil? && SCOPE_METHODS.include?(send_node.method_name)
+          end
+        end
+
+        def inside_briefing?(node)
+          node.each_ancestor(:block, :numblock).any? do |ancestor|
+            send_node = ancestor.send_node
+            send_node.receiver.nil? && send_node.method_name == :briefing
+          end
+        end
+
+        def freeze_helper?(node)
+          return false unless node.respond_to?(:method_name)
+          return false unless node.receiver.nil?
+
+          freeze_helpers.include?(node.method_name.to_s)
+        end
+
+        def freeze_calls
+          @freeze_calls ||= begin
+            ast = processed_source&.ast
+            if ast.nil?
+              []
+            else
+              ast.each_node(:send, :csend).select { |send_node| freeze_helper?(send_node) }
+            end
+          end
+        end
+
+        def forbidden_calls
+          @forbidden_calls ||= Array(cop_config.fetch("ForbiddenCalls", DEFAULT_FORBIDDEN_CALLS)).map(&:to_s)
+        end
+
+        def freeze_helpers
+          @freeze_helpers ||= Array(cop_config.fetch("FreezeHelpers", DEFAULT_FREEZE_HELPERS)).map(&:to_s)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/constable/unsafe_block_visibility.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Constable
+      # Every escape hatch is visible. `unsafe { }` is allowed to exist -- it is the
+      # honest way to say "this one call really does need to bend a rule" -- but an
+      # `unsafe` with nothing next to it is just a rule being broken quietly, and
+      # the next person to read it has no way to tell whether it is still needed.
+      #
+      # So this cop does not object to `unsafe` at all. It objects only to an
+      # `unsafe` that does not say why. A trailing comment on the same line, or a
+      # comment on the line immediately above, satisfies it -- and that comment is
+      # what the runner quotes in the WARNINGS section of every run summary:
+      #
+      #   ⚠ spec/controllers/sessions_case.rb:44
+      #     unsafe { sleep(0.1) } -- "testing an actual timeout path, not a code smell"
+      #
+      # A literal reason passed to `unsafe("...")` counts as well, since the runtime
+      # DSL reports that string the same way. Set `AllowReasonArgument: false` to
+      # insist on a comment.
+      #
+      # @example
+      #   # bad
+      #   unsafe { sleep(0.1) }
+      #
+      #   # good
+      #   unsafe { sleep(0.1) } # testing an actual timeout path, not a code smell
+      #
+      #   # good
+      #   # testing an actual timeout path, not a code smell
+      #   unsafe do
+      #     sleep(0.1)
+      #   end
+      #
+      #   # good (with AllowReasonArgument: true, the default)
+      #   unsafe("testing an actual timeout path, not a code smell") { sleep(0.1) }
+      class UnsafeBlockVisibility < Base
+        include CaseScope
+        include Helpers
+
+        MSG = "This `unsafe` block has nothing saying why. Every escape hatch is " \
+              "reported in the run summary, so give it a reason: a trailing comment, " \
+              "a comment on the line above, or `unsafe(\"reason\") { }`."
+
+        def on_block(node)
+          return unless constable_case_file?
+          return unless unsafe_block?(node)
+          return if justified?(node)
+
+          add_offense(node.send_node)
+        end
+        alias on_numblock on_block
+
+        private
+
+        def justified?(node)
+          reason_argument?(node.send_node) || adjacent_comment?(node)
+        end
+
+        def reason_argument?(send_node)
+          return false unless allow_reason_argument?
+
+          argument = send_node.first_argument
+          return false if argument.nil?
+          return false unless argument.respond_to?(:type)
+
+          case argument.type
+          when :str then !argument.value.to_s.strip.empty?
+          when :dstr, :sym then true
+          else false
+          end
+        end
+
+        # "Adjacent" means the same line (a trailing comment) or the line directly
+        # above. A comment three lines up is documenting something else.
+        def adjacent_comment?(node)
+          line = node.send_node.loc.line
+
+          comment_text?(line) || comment_text?(line - 1)
+        end
+
+        def comment_text?(line)
+          return false if line < 1
+
+          comment = processed_source.comment_at_line(line)
+          return false if comment.nil?
+
+          !comment.text.to_s.sub(/\A#+/, "").strip.empty?
+        end
+
+        def allow_reason_argument?
+          cop_config.fetch("AllowReasonArgument", true)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/constable_cops.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Shared mixins first -- every cop includes them.
+require_relative "constable/case_scope"
+require_relative "constable/helpers"
+
+require_relative "constable/no_conditional_assertions"
+require_relative "constable/no_network_without_stub"
+require_relative "constable/no_retry_helpers"
+require_relative "constable/no_shared_mutable_state"
+require_relative "constable/no_sleep"
+require_relative "constable/no_unfrozen_time"
+require_relative "constable/unsafe_block_visibility"

data/lib/rubocop-constable.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# The entry point users name in `.rubocop.yml`:
+#
+#   require:
+#     - rubocop-constable
+#
+require "yaml"
+require "rubocop"
+
+require_relative "rubocop/constable"
+require_relative "rubocop/constable/version"
+require_relative "rubocop/constable/inject"
+
+RuboCop::Constable::Inject.defaults!
+
+require_relative "rubocop/cop/constable_cops"

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification
+name: rubocop-constable
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ray Hughes
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.50'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.50'
+description: |
+  The companion RuboCop extension for Constable, the opinionated Rails testing gem.
+
+  Constable's second principle is that nondeterminism is caught by the linter, not
+  discovered in CI. These seven cops are that linter: bare `sleep`, unfrozen
+  `Time.now`, unstubbed HTTP, class-level shared state, assertions hidden behind a
+  branch, retry and eventually helpers, and an `unsafe` block that never says why.
+
+  Every cop is scoped to native `Constable::Case` files. Cold cases -- untouched
+  RSpec or Minitest files running through `Constable::ColdCase::*` -- are exempt by
+  design, because the whole point of the adoption story is that taking the on-ramp
+  costs nothing.
+
+  Install it alongside `constable-rails` and add `require: rubocop-constable` to
+  `.rubocop.yml`.
+email:
+- r.hughes2136@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- config/default.yml
+- lib/rubocop-constable.rb
+- lib/rubocop/constable.rb
+- lib/rubocop/constable/inject.rb
+- lib/rubocop/constable/version.rb
+- lib/rubocop/cop/constable/case_scope.rb
+- lib/rubocop/cop/constable/helpers.rb
+- lib/rubocop/cop/constable/no_conditional_assertions.rb
+- lib/rubocop/cop/constable/no_network_without_stub.rb
+- lib/rubocop/cop/constable/no_retry_helpers.rb
+- lib/rubocop/cop/constable/no_shared_mutable_state.rb
+- lib/rubocop/cop/constable/no_sleep.rb
+- lib/rubocop/cop/constable/no_unfrozen_time.rb
+- lib/rubocop/cop/constable/unsafe_block_visibility.rb
+- lib/rubocop/cop/constable_cops.rb
+homepage: https://github.com/Ray-Hughes/constable
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Ray-Hughes/constable
+  source_code_uri: https://github.com/Ray-Hughes/constable/tree/main/rubocop-constable
+  changelog_uri: https://github.com/Ray-Hughes/constable/blob/main/rubocop-constable/CHANGELOG.md
+  bug_tracker_uri: https://github.com/Ray-Hughes/constable/issues
+  documentation_uri: https://github.com/Ray-Hughes/constable/blob/main/rubocop-constable/README.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: RuboCop cops that catch test nondeterminism before CI does.
+test_files: []