rubocop-constable 0.1.0

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Constable
+      # Small AST helpers shared by every `Constable/*` cop: recognising the
+      # `unsafe { }` escape hatch, and rendering receiver chains as readable names.
+      #
+      # `unsafe` is the one legal way to bend a native rule for a single call. It is
+      # never silent -- the runtime emits a warning for every occurrence, with
+      # `file:line` and the adjacent comment -- so the cops treat anything lexically
+      # inside an `unsafe` block as already accounted for, and stay quiet.
+      module Helpers
+        extend ::RuboCop::AST::NodePattern::Macros
+
+        # `unsafe { ... }`, `unsafe do ... end`, `unsafe("reason") { ... }`
+        def_node_matcher :unsafe_block?, <<~PATTERN
+          ({block numblock} (send nil? :unsafe ...) ...)
+        PATTERN
+
+        # @return [Boolean] whether the node sits lexically inside an `unsafe` block.
+        def inside_unsafe_block?(node)
+          node.each_ancestor(:block, :numblock).any? { |ancestor| unsafe_block?(ancestor) }
+        end
+
+        # Renders a statically-resolvable receiver chain as a dotted string:
+        # `Time.now` -> "Time.now", `Time.zone.now` -> "Time.zone.now",
+        # `Net::HTTP.get` -> "Net::HTTP.get". Returns nil when any link in the
+        # chain takes arguments or isn't a constant/plain send.
+        def qualified_call_name(node)
+          return nil if node.nil?
+
+          case node.type
+          when :const
+            name = node.const_name
+            name && name.sub(/\A::/, "")
+          when :send
+            return nil unless node.arguments.empty?
+            return node.method_name.to_s if node.receiver.nil?
+
+            base = qualified_call_name(node.receiver)
+            base && "#{base}.#{node.method_name}"
+          end
+        end
+
+        # A constant node's dotless name: `(const (const nil :Net) :HTTP)` -> "Net::HTTP".
+        def constant_string(node)
+          name = node.const_name
+          name && name.sub(/\A::/, "")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Constable
+      # An assertion behind a branch is an assertion that might not run. The test
+      # goes green either way, so nobody notices when the interesting branch stops
+      # being taken -- the case quietly stops testing anything while still counting
+      # itself as coverage. Worse, the branch condition is usually the very thing
+      # that varies between machines: an environment flag, a record that may or may
+      # not exist, a feature toggle.
+      #
+      # Split the branches into separate investigations (or separate `docket`
+      # blocks) so each one asserts unconditionally, and each one's name says which
+      # world it describes.
+      #
+      # Only the outermost conditional wrapping an assertion is reported, so one
+      # nested `if` tree yields one offense, not five.
+      #
+      # @example
+      #   # bad
+      #   investigate "creates the user" do
+      #     if admin?
+      #       attest(response).to be_created
+      #     else
+      #       attest(response).to be_forbidden
+      #     end
+      #   end
+      #
+      #   # bad
+      #   attest(response).to be_created unless skip_check
+      #
+      #   # good
+      #   docket "as an admin" do
+      #     investigate("creates the user") { attest(response).to be_created }
+      #   end
+      #
+      #   docket "as a guest" do
+      #     investigate("is forbidden") { attest(response).to be_forbidden }
+      #   end
+      class NoConditionalAssertions < Base
+        include CaseScope
+        include Helpers
+
+        MSG = "This %<construct>s decides whether an assertion runs at all, so the " \
+              "case passes whichever way the branch falls. Split it into separate " \
+              "investigations (or `docket` blocks) that each assert unconditionally."
+
+        DEFAULT_ASSERTION_METHODS = %w[attest].freeze
+        DEFAULT_ASSERTION_PREFIXES = %w[assert refute].freeze
+
+        CONDITIONAL_TYPES = %i[if case case_match].freeze
+
+        def on_if(node)
+          return unless constable_case_file?
+
+          check_conditional(node, node.ternary? ? "ternary" : "conditional")
+        end
+
+        def on_case(node)
+          return unless constable_case_file?
+
+          check_conditional(node, "`case`")
+        end
+
+        def on_case_match(node)
+          return unless constable_case_file?
+
+          check_conditional(node, "`case/in`")
+        end
+
+        private
+
+        def check_conditional(node, construct)
+          return unless assertion_in_branches?(node)
+          return if outer_conditional?(node)
+          return if inside_unsafe_block?(node)
+
+          add_offense(offense_range(node), message: format(MSG, construct: construct))
+        end
+
+        # Report only the outermost conditional that guards an assertion.
+        def outer_conditional?(node)
+          node.each_ancestor(*CONDITIONAL_TYPES).any? { |ancestor| assertion_in_branches?(ancestor) }
+        end
+
+        # The condition itself may legitimately call a predicate; only the branch
+        # bodies decide whether an assertion runs.
+        def assertion_in_branches?(node)
+          branch_bodies(node).any? { |body| assertion?(body) || body.each_descendant(:send, :csend).any? { |d| assertion?(d) } }
+        end
+
+        def branch_bodies(node)
+          case node.type
+          when :if
+            [node.if_branch, node.else_branch].compact
+          when :case
+            (node.when_branches.map(&:body) + [node.else_branch]).compact
+          when :case_match
+            (node.in_pattern_branches.map(&:body) + [node.else_branch]).compact
+          else
+            []
+          end
+        end
+
+        def assertion?(node)
+          return false unless node.respond_to?(:send_type?) && (node.send_type? || node.csend_type?)
+
+          name = node.method_name.to_s
+          assertion_methods.include?(name) ||
+            assertion_prefixes.any? { |prefix| name == prefix || name.start_with?("#{prefix}_") }
+        end
+
+        def offense_range(node)
+          loc = node.loc
+          return loc.keyword if loc.respond_to?(:keyword) && loc.keyword
+          return loc.question if loc.respond_to?(:question) && loc.question
+
+          node.source_range
+        end
+
+        def assertion_methods
+          @assertion_methods ||= Array(cop_config.fetch("AssertionMethods", DEFAULT_ASSERTION_METHODS)).map(&:to_s)
+        end
+
+        def assertion_prefixes
+          @assertion_prefixes ||= Array(cop_config.fetch("AssertionPrefixes", DEFAULT_ASSERTION_PREFIXES)).map(&:to_s)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Constable
+      # A case that talks to the real network is not a test of your code, it is a
+      # test of somebody else's uptime. It fails on a plane, on a flaky DNS
+      # resolver, and on the day the third party rate-limits CI -- none of which
+      # are your bug.
+      #
+      # Constable ships `stub_network!`, which installs a guard that raises on any
+      # real outbound connection. Call it in a `briefing` and every investigation in
+      # the case is covered; this cop then goes quiet for the whole file. If the
+      # outbound call itself is the subject, `unsafe { }` says so on the record.
+      #
+      # @example
+      #   # bad
+      #   investigate "fetches the profile" do
+      #     attest(Net::HTTP.get(uri)).to include("ok")
+      #   end
+      #
+      #   # good
+      #   briefing { stub_network! }
+      #
+      #   investigate "fetches the profile" do
+      #     attest(Net::HTTP.get(uri)).to include("ok")
+      #   end
+      class NoNetworkWithoutStub < Base
+        include CaseScope
+        include Helpers
+
+        MSG = "`%<call>s` reaches the real network, and this case never calls " \
+              "`stub_network!`. A test that depends on somebody else's uptime is " \
+              "not testing your code -- add `briefing { stub_network! }`, or use " \
+              "`unsafe { }` if the live call is the subject."
+
+        DEFAULT_HTTP_CONSTANTS = %w[
+          Net::HTTP
+          Net::HTTPS
+          HTTParty
+          Faraday
+          RestClient
+          Excon
+          Typhoeus
+          HTTPClient
+          HTTPX
+          HTTP
+          Curl
+          Patron
+          Mechanize
+          OpenURI
+          Down
+        ].freeze
+
+        DEFAULT_STUB_HELPERS = %w[stub_network!].freeze
+
+        # `URI` is a perfectly innocent constant right up until you `.open` it.
+        URI_NETWORK_METHODS = %i[open read].freeze
+        URL_LITERAL = %r{\Ahttps?://}i.freeze
+
+        def on_new_investigation
+          @network_stubbed = nil
+          super
+        end
+
+        def on_send(node)
+          return unless constable_case_file?
+          return if network_stubbed?
+          return unless (call = network_call_name(node))
+          return if inside_unsafe_block?(node)
+
+          add_offense(node, message: format(MSG, call: call))
+        end
+        alias on_csend on_send
+
+        private
+
+        # The stub is a file-level fact: `stub_network!` in a `briefing` runs before
+        # every investigation, so one call anywhere covers the case.
+        def network_stubbed?
+          return @network_stubbed unless @network_stubbed.nil?
+
+          ast = processed_source&.ast
+          @network_stubbed =
+            !ast.nil? && ast.each_node(:send, :csend).any? do |send_node|
+              send_node.receiver.nil? && stub_helpers.include?(send_node.method_name.to_s)
+            end
+        end
+
+        # Matches only calls made *directly* on a known entry-point constant. That
+        # is deliberate: it flags the innermost link of a chain exactly once, so
+        # `Faraday.new.get(url)` reports on `Faraday.new` rather than twice, and
+        # `Net::HTTP.get(uri).to_s` never reports a nonsense `Net::HTTP.to_s`.
+        # Calls on an object handed around by a `witness` are out of reach of a
+        # static check and are left to `stub_network!` itself to catch at runtime.
+        def network_call_name(node)
+          receiver = node.receiver
+
+          if receiver.nil?
+            # open-uri patches Kernel#open; `open("https://...")` is a live request.
+            return "open" if node.method_name == :open && url_literal_argument?(node)
+
+            return nil
+          end
+
+          return nil unless receiver.const_type?
+
+          root = constant_string(receiver)
+          return nil if root.nil?
+
+          if root == "URI"
+            return nil unless URI_NETWORK_METHODS.include?(node.method_name)
+
+            return "URI.#{node.method_name}"
+          end
+
+          return nil unless http_constant?(root)
+
+          "#{root}.#{node.method_name}"
+        end
+
+        def http_constant?(root)
+          http_constants.any? { |name| root == name || root.start_with?("#{name}::") }
+        end
+
+        def url_literal_argument?(node)
+          first = node.first_argument
+          return false unless first.respond_to?(:str_type?) && (first.str_type? || first.dstr_type?)
+
+          URL_LITERAL.match?(first.source.delete_prefix('"').delete_prefix("'"))
+        end
+
+        def http_constants
+          @http_constants ||= Array(cop_config.fetch("HttpConstants", DEFAULT_HTTP_CONSTANTS)).map(&:to_s)
+        end
+
+        def stub_helpers
+          @stub_helpers ||= Array(cop_config.fetch("StubHelpers", DEFAULT_STUB_HELPERS)).map(&:to_s)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Constable
+      # Retrying is how a flaky test hides. `retry`, `eventually { }`, `wait_for`
+      # and hand-rolled polling loops all take a test that fails some of the time
+      # and turn it into a test that passes most of the time -- which is strictly
+      # worse, because now nobody is looking at it. The real defect stays in the
+      # code, and the suite gets slower on every run that has to use the retries.
+      #
+      # Constable has a first-class answer for genuine flakiness: **warrants**.
+      # Turn them on and the runner reruns a failing test in isolation, records
+      # what it finds in the blotter, and reports it in its own section -- visible,
+      # counted, and never quietly swallowed by a `rescue; retry; end`.
+      #
+      # `wait_for(timeout:, interval:)` does exist in the runtime DSL for genuinely
+      # asynchronous things, but it is legal only inside `unsafe { }`; outside it,
+      # the DSL raises. This cop enforces the same rule statically.
+      #
+      # Polling loops are recognised by their signature: a `loop`/`while`/`until`
+      # whose body sleeps. That is a deliberately narrow heuristic -- an ordinary
+      # `while` that does real work is left alone.
+      #
+      # @example
+      #   # bad
+      #   begin
+      #     attest(job).to be_finished
+      #   rescue Constable::AssertionFailed
+      #     retry
+      #   end
+      #
+      #   # bad
+      #   eventually { attest(page).to have_content("Done") }
+      #
+      #   # bad
+      #   until job.reload.finished?
+      #     sleep 0.1
+      #   end
+      #
+      #   # good
+      #   perform_enqueued_jobs
+      #   attest(job.reload).to be_finished
+      #
+      #   # good -- genuinely async, on the record
+      #   # the browser drives this repaint on its own schedule
+      #   unsafe { wait_for(timeout: 2, interval: 0.05) { page.has_content?("Done") } }
+      class NoRetryHelpers < Base
+        include CaseScope
+        include Helpers
+
+        MSG_RETRY = "`retry` turns a failing investigation into a passing one " \
+                    "without fixing anything. Remove the retry and let the failure " \
+                    "stand -- if the test is genuinely flaky, that is what warrants " \
+                    "(`constable test --warrants`) are for."
+
+        MSG_HELPER = "`%<name>s` is a retry helper, and retrying is how a flaky " \
+                     "test hides. Assert on the completed state instead, or wrap it " \
+                     "in `unsafe { }` with a comment if the work is genuinely async."
+
+        MSG_LOOP = "This %<construct>s polls with `sleep`, which is a retry loop " \
+                   "wearing a different hat: slow when it passes, flaky when it " \
+                   "does not. Assert on the completed state, or wrap it in " \
+                   "`unsafe { }` with a comment if the work is genuinely async."
+
+        DEFAULT_RETRY_HELPERS = %w[
+          wait_for
+          eventually
+          with_retries
+          try_again
+          retry_until
+          retry_on_failure
+          poll_until
+          keep_trying
+        ].freeze
+
+        LOOP_TYPES = %i[while until while_post until_post].freeze
+
+        def on_retry(node)
+          return unless constable_case_file?
+          return if inside_unsafe_block?(node)
+
+          add_offense(node, message: MSG_RETRY)
+        end
+
+        def on_send(node)
+          return unless constable_case_file?
+          return unless node.receiver.nil?
+
+          name = node.method_name.to_s
+          return unless retry_helpers.include?(name)
+          return if inside_unsafe_block?(node)
+
+          add_offense(node, message: format(MSG_HELPER, name: name))
+        end
+        alias on_csend on_send
+
+        def on_while(node)
+          return unless constable_case_file?
+          return unless sleeps_in_body?(node.body)
+          return if inside_unsafe_block?(node)
+
+          add_offense(offense_range(node), message: format(MSG_LOOP, construct: "`#{node.keyword}`"))
+        end
+        alias on_until on_while
+        alias on_while_post on_while
+        alias on_until_post on_while
+
+        def on_block(node)
+          return unless constable_case_file?
+          return unless kernel_loop?(node)
+          return unless sleeps_in_body?(node.body)
+          return if inside_unsafe_block?(node)
+
+          add_offense(node.send_node, message: format(MSG_LOOP, construct: "`loop`"))
+        end
+        alias on_numblock on_block
+
+        private
+
+        def kernel_loop?(node)
+          send_node = node.send_node
+          send_node.receiver.nil? && send_node.method_name == :loop && send_node.arguments.empty?
+        end
+
+        def sleeps_in_body?(body)
+          return false if body.nil?
+
+          sleep_call?(body) || body.each_descendant(:send, :csend).any? { |node| sleep_call?(node) }
+        end
+
+        def sleep_call?(node)
+          return false unless node.respond_to?(:method_name)
+          return false unless node.method_name == :sleep
+
+          receiver = node.receiver
+          receiver.nil? || (receiver.const_type? && constant_string(receiver) == "Kernel")
+        end
+
+        def offense_range(node)
+          loc = node.loc
+          return loc.keyword if loc.respond_to?(:keyword) && loc.keyword
+
+          node.source_range
+        end
+
+        def retry_helpers
+          @retry_helpers ||= Array(cop_config.fetch("RetryHelpers", DEFAULT_RETRY_HELPERS)).map(&:to_s)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Constable
+      # Isolation is non-negotiable in native code. A class variable or a global
+      # written from inside a case survives the investigation that wrote it, which
+      # means the suite's result now depends on its order -- and the failure lands
+      # on whichever test happened to run second, not on the one that caused it.
+      # This is the single hardest class of flake to debug, so Constable simply
+      # does not have a `before(:all)`.
+      #
+      # Reading `@@x` or `$x` is fine. This cop is about *writing*: assignment,
+      # `||=`, `<<`, and the other in-place mutators.
+      #
+      # Use `witness` for per-test memoized data (never per-process), `briefing`
+      # for per-test setup, and an ordinary instance variable for anything an
+      # investigation needs to remember about itself.
+      #
+      # @example
+      #   # bad
+      #   class ImportCase < UnitCase
+      #     @@rows = []
+      #
+      #     investigate "collects a row" do
+      #       @@rows << build_row
+      #       attest(@@rows.size).to eq(1)
+      #     end
+      #   end
+      #
+      #   # bad
+      #   investigate "remembers the token" do
+      #     $token = issue_token
+      #   end
+      #
+      #   # good
+      #   class ImportCase < UnitCase
+      #     witness(:rows) { [] }
+      #
+      #     investigate "collects a row" do
+      #       rows << build_row
+      #       attest(rows.size).to eq(1)
+      #     end
+      #   end
+      class NoSharedMutableState < Base
+        include CaseScope
+        include Helpers
+
+        MSG_ASSIGN = "Assigning %<kind>s `%<name>s` leaks state between " \
+                     "investigations and makes the suite order-dependent. Use " \
+                     "`witness` for per-test data or `briefing` for per-test setup."
+
+        MSG_MUTATE = "Mutating %<kind>s `%<name>s` with `%<method>s` leaks state " \
+                     "between investigations and makes the suite order-dependent. " \
+                     "Use `witness` for per-test data or `briefing` for per-test setup."
+
+        ASSIGNMENT_TYPES = %i[cvasgn gvasgn].freeze
+        OP_ASSIGNMENT_TYPES = %i[op_asgn or_asgn and_asgn].freeze
+
+        # In-place mutators. Anything ending in `!` or `=` counts too, which is why
+        # this list only needs the ones that break the convention.
+        MUTATING_METHODS = %i[
+          << push pop shift unshift concat insert append prepend
+          clear delete delete_at delete_if keep_if
+          replace fill store update
+        ].freeze
+
+        def on_cvasgn(node)
+          return unless constable_case_file?
+          return if operator_assignment_target?(node)
+          return if inside_unsafe_block?(node)
+
+          add_offense(node, message: format(MSG_ASSIGN, kind: "class variable", name: node.name))
+        end
+
+        def on_gvasgn(node)
+          return unless constable_case_file?
+          return if operator_assignment_target?(node)
+          return if inside_unsafe_block?(node)
+
+          add_offense(node, message: format(MSG_ASSIGN, kind: "global", name: node.name))
+        end
+
+        def on_op_asgn(node)
+          return unless constable_case_file?
+          return if inside_unsafe_block?(node)
+
+          target = node.children.first
+          return unless target.respond_to?(:type) && shared_state_type?(target.type)
+
+          add_offense(node, message: format(MSG_ASSIGN, kind: kind_for(target), name: variable_name(target)))
+        end
+        alias on_or_asgn on_op_asgn
+        alias on_and_asgn on_op_asgn
+
+        def on_send(node)
+          return unless constable_case_file?
+          return if inside_unsafe_block?(node)
+
+          receiver = node.receiver
+          return unless receiver.respond_to?(:type) && shared_state_read_type?(receiver.type)
+          return unless mutating_method?(node.method_name)
+
+          add_offense(
+            node,
+            message: format(
+              MSG_MUTATE,
+              kind: kind_for(receiver),
+              name: variable_name(receiver),
+              method: node.method_name
+            )
+          )
+        end
+        alias on_csend on_send
+
+        private
+
+        # `@@x ||= []` parses as `(or-asgn (cvasgn :@@x) ...)`; the inner `cvasgn`
+        # would otherwise be reported alongside its own operator assignment.
+        def operator_assignment_target?(node)
+          parent = node.parent
+          !parent.nil? && OP_ASSIGNMENT_TYPES.include?(parent.type)
+        end
+
+        def shared_state_type?(type)
+          ASSIGNMENT_TYPES.include?(type) || shared_state_read_type?(type)
+        end
+
+        def shared_state_read_type?(type)
+          %i[cvar gvar].include?(type)
+        end
+
+        def kind_for(node)
+          node.type.to_s.start_with?("cv") ? "class variable" : "global"
+        end
+
+        def variable_name(node)
+          node.children.first
+        end
+
+        def mutating_method?(method_name)
+          name = method_name.to_s
+          MUTATING_METHODS.include?(method_name) || name.end_with?("!", "=")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Constable
+      # A bare `sleep` is the single most common way a suite becomes both slow and
+      # flaky at once. It buys time the machine may not need and, on a loaded CI
+      # box, may not be enough of -- so it costs seconds on every green run and
+      # still fails on the red one.
+      #
+      # Wait on the condition itself instead. If the sleep *is* the subject under
+      # test -- you are exercising a real timeout path -- say so out loud with the
+      # `unsafe` escape hatch, which is reported in every run summary until someone
+      # deals with it.
+      #
+      # @example
+      #   # bad
+      #   investigate "expires the session" do
+      #     sleep(0.2)
+      #     attest(session).to be_expired
+      #   end
+      #
+      #   # good
+      #   investigate "expires the session" do
+      #     travel_to(2.hours.from_now)
+      #     attest(session).to be_expired
+      #   end
+      #
+      #   # good -- the timeout is the thing under test, and it says so
+      #   investigate "times out after thirty seconds" do
+      #     # testing an actual timeout path, not a code smell
+      #     unsafe { sleep(0.1) }
+      #     attest(subject).to have_timed_out
+      #   end
+      class NoSleep < Base
+        include CaseScope
+        include Helpers
+
+        MSG = "Do not `sleep` in a case. It makes this investigation slow on every " \
+              "green run and flaky on the red one -- wait on the condition, freeze " \
+              "time, or if the delay itself is under test, wrap it in `unsafe { }` " \
+              "with a comment saying why."
+
+        RESTRICT_ON_SEND = %i[sleep].freeze
+
+        def on_send(node)
+          return unless constable_case_file?
+          return unless bare_sleep?(node)
+          return if inside_unsafe_block?(node)
+
+          add_offense(node)
+        end
+        alias on_csend on_send
+
+        private
+
+        # `sleep(0.1)` and `Kernel.sleep(0.1)` both count. `foo.sleep` does not --
+        # that is somebody's own object, not the process going to bed.
+        def bare_sleep?(node)
+          receiver = node.receiver
+          return true if receiver.nil?
+
+          receiver.const_type? && constant_string(receiver) == "Kernel"
+        end
+      end
+    end
+  end
+end