constable-rails 0.1.0 → 1.0.0

data/lib/constable/config.rb

@@ -19,6 +19,7 @@ module Constable
       "coverage_threshold" => 90,
       "coverage_html" => false,
       "fail_on_warnings" => false,
+      "output" => "concise",
       "parallel_workers" => "auto",
       "tiers" => {
         "unit" => "test/cases/models/**/*",
@@ -33,8 +34,27 @@ module Constable
 
     def self.load(root: Constable.root, overrides: {})
       path = File.join(root.to_s, CONFIG_PATH)
-      raw  = File.exist?(path) ? (YAML.safe_load_file(path, permitted_classes: [], aliases: true) || {}) : {}
-      new(raw, root: root, overrides: overrides)
+      new(read_file(path), root: root, overrides: overrides)
+    end
+
+    # A typo in config.yml used to surface as a raw Psych::SyntaxError, or -- for a file
+    # that parsed but wasn't a mapping -- as "no implicit conversion of Array into Hash"
+    # from somewhere deep in the merge. Neither says which file to open.
+    def self.read_file(path)
+      return {} unless File.exist?(path)
+
+      loaded = YAML.safe_load_file(path, permitted_classes: [], aliases: true)
+      return {} if loaded.nil?
+
+      unless loaded.is_a?(Hash)
+        raise Constable::Error,
+              "#{CONFIG_PATH} must be a mapping of settings, but it parsed as " \
+              "#{loaded.class.name.downcase}. Check the indentation."
+      end
+
+      loaded
+    rescue Psych::SyntaxError => e
+      raise Constable::Error, "#{CONFIG_PATH} is not valid YAML: #{e.problem} at line #{e.line}."
     end
 
     def initialize(raw = {}, root: Constable.root, overrides: {})
@@ -45,14 +65,42 @@ module Constable
 
     def cold_cases         = Array(@raw["cold_cases"])
     def warrants?          = truthy(@raw["warrants"])
-    def warrant_retries    = @raw["warrant_retries"].to_i
+    # Negative retries are a typo for "off", not an instruction to count backwards.
+    def warrant_retries    = [@raw["warrant_retries"].to_i, 0].max
     def auto_relink?       = truthy(@raw["auto_relink"])
-    def parole_period      = @raw["parole_period"].to_i
+
+    # Clamped here rather than at each call site: Jail already refused a period of zero
+    # ("release on sight" is not parole), but the reporter read the raw value and would
+    # cheerfully print "Day 1 of 0 -- 0 clean runs to go" while the docket waited for 10.
+    def parole_period
+      period = @raw["parole_period"].to_i
+      period.positive? ? period : DEFAULTS["parole_period"]
+    end
+
     def coverage?          = truthy(@raw["coverage"])
-    def coverage_threshold = @raw["coverage_threshold"].to_i
+    # Clamped: a threshold above 100 is a build that can never go green, and a negative
+    # one is a gate that can never fail. Both are typos rather than intentions.
+    def coverage_threshold = @raw["coverage_threshold"].to_i.clamp(0, 100)
     def coverage_html?     = truthy(@raw["coverage_html"])
     def fail_on_warnings?  = truthy(@raw["fail_on_warnings"])
     def tiers              = @raw["tiers"] || {}
+
+    # How much the live stream says while the suite runs.
+    #
+    #   concise   one glyph per test, grouped into a run per case. The default: a
+    #             1,000-test suite stays inside one screen.
+    #   expanded  a line per test -- glyph, name, duration. Slower to read in bulk,
+    #             but you can see which test is hanging without waiting for the summary.
+    #
+    # The summary itself is identical either way. This only affects the live stream.
+    OUTPUT_MODES = %i[concise expanded].freeze
+
+    def output_mode
+      mode = @raw["output"].to_s.strip.downcase.to_sym
+      OUTPUT_MODES.include?(mode) ? mode : :concise
+    end
+
+    def expanded_output? = output_mode == :expanded
     def storage            = @raw["storage"] || {}
 
     def storage_adapter = (storage["adapter"] || "sqlite").to_s

data/lib/constable/identity.rb

@@ -33,6 +33,25 @@ module Constable
       digest("cold:#{relative}:#{description}")
     end
 
+    # Two investigations with byte-identical bodies hash to the same key, which would
+    # make them one test as far as the blotter is concerned: jail one and the other goes
+    # with it, and their flake histories merge into a single misleading record.
+    #
+    # Bodies repeat more often than the "content hash" idea suggests --
+    # `attest(build(:thing, name: nil)).not_to be_valid` is the same handful of tokens in
+    # every model case, and the model generator writes an identical first investigation
+    # into every file it touches. So the collision is routine, not theoretical.
+    #
+    # When it happens, the colliding tests are re-keyed on the body *plus* their class
+    # and description. The rename-survival promise is weaker for exactly those tests --
+    # rewording one of them starts its history over -- which is the right trade: a
+    # history that belongs to two tests at once is worse than one that resets.
+    def disambiguate(base, case_name:, description:, ordinal: nil)
+      key = "#{base}:#{case_name}:#{description}"
+      key = "#{key}:#{ordinal}" unless ordinal.nil?
+      digest(key)
+    end
+
     def digest(string)
       Digest::SHA256.hexdigest(string)[0, LENGTH]
     end

data/lib/constable/importer/modernizer.rb

@@ -508,6 +508,8 @@ module Constable
                                 "stub object.")
         end
 
+        flag_unknown_matcher(node, args.first) if %i[to not_to to_not].include?(name)
+
         if MOCK_ENTRY_POINTS.include?(name) && receiver.nil?
           note_untouched(:rspec_mocks, node,
                          "`#{first_line(node)}` uses rspec-mocks. Constable has no equivalent; convert it by hand.")
@@ -532,6 +534,14 @@ module Constable
           end
         when :should, :should_not
           flag(:should_syntax, node, "`#{name}` is RSpec's monkey-patched expectation syntax. Use `attest(...).to`.")
+        when :helper
+          if receiver.nil? && args.empty?
+            flag(:rspec_helper_object, node,
+                 "`helper` is RSpec's helper-spec proxy and has no Constable equivalent. " \
+                 "A helper is a plain module: `include YourHelper` in the case and call " \
+                 "the method directly -- which is exactly what `rails generate helper` " \
+                 "writes.")
+          end
         when :described_class
           if receiver.nil?
             flag(:described_class, node,
@@ -558,6 +568,36 @@ module Constable
         record_converted(:helper_require, node, value, replaced)
       end
 
+      # Constable's matcher set is deliberately smaller than RSpec's, and the rewrite
+      # carries any matcher name straight across. Without this check the first anyone
+      # hears about it is a NoMethodError at runtime, naming the matcher -- or worse, an
+      # internal deferred class -- rather than the line that needs a decision.
+      def flag_unknown_matcher(node, matcher_node)
+        name = root_matcher_name(matcher_node)
+        return if name.nil?
+        return if Constable::Matchers.matcher_name?(name)
+
+        flag(:unknown_matcher, node,
+             "`#{name}` is not one of Constable's matchers. Define it in " \
+             "test/support/matchers.rb with `Constable::Matchers.define(:#{name})`, or " \
+             "rewrite the assertion.")
+      end
+
+      # `contain_exactly(1, 2)` -> :contain_exactly. `be_within(0.5).of(10)` -> :be_within.
+      # `change { x }.by(1)` -> :change. Anything that is not ultimately a bare method
+      # call -- a local variable holding a matcher, a constant -- returns nil and is left
+      # alone, because we cannot know what it is.
+      def root_matcher_name(node)
+        return nil unless node.is_a?(::Parser::AST::Node)
+
+        current = node
+        current = current.children.first while current.type == :send && current.children.first
+
+        return nil unless current.type == :send && current.children.first.nil?
+
+        current.children[1]
+      end
+
       def mock_expectation?(node)
         return false unless node.is_a?(::Parser::AST::Node)
 

data/lib/constable/investigation.rb

@@ -38,6 +38,16 @@ module Constable
       @identity ||= Identity.for_block(@block)
     end
 
+    # Re-keys this investigation because another one has the same body. Called by the
+    # registry once the whole suite is loaded, which is the first moment a collision can
+    # be seen. See Identity.disambiguate.
+    def disambiguate!(ordinal: nil)
+      @identity = Identity.disambiguate(identity, case_name: case_name,
+                                                  description: full_description,
+                                                  ordinal: ordinal)
+      self
+    end
+
     def location
       "#{relative_file}:#{@line}"
     end

data/lib/constable/jail.rb

@@ -267,13 +267,20 @@ module Constable
     # Call it *before* writing the result to flake history (the flip check reads the
     # previous status) and *after* Warrants has had its say (a warranted result is not a
     # failure, so it never reaches the docket).
-    def adjudicate(result, jail_mode: false)
+    # `systemic:` says this run failed for a reason that has nothing to do with any
+    # individual test -- see Runner#systemic_failure. The failures still stand and the
+    # build still goes red, but they are not *evidence*: nothing moves through the state
+    # machine, because "the database was locked for the whole run" is not a fact about a
+    # test and must not put one on the docket.
+    def adjudicate(result, jail_mode: false, systemic: false)
       return result if result.nil?
 
       docket = entry(result.identity)
 
+      return mark_jailed(result) if docket&.jailed?
+      return result if systemic
+
       return record_result(result) if docket&.paroled?
-      return mark_jailed(result)   if docket&.jailed?
       return result unless result.failed?
 
       if jail_mode
@@ -331,17 +338,37 @@ module Constable
     # test that is not on the docket yet.
     #
     # Returns an identity String, or nil when nothing matches.
-    def resolve(target)
+    # Every docket row a target could mean.
+    #
+    # The interesting case is a bare path. "test/cases/users_case.rb" with three tests
+    # on the docket is a question, not an instruction: picking one silently acts on a
+    # test the user never named -- and not even the first one, since the order is
+    # whatever storage returns. Callers ask for the candidates and refuse to guess.
+    def candidates(target)
       text = target.to_s.strip
-      return nil if text.empty?
-      return text if identity_like?(text) && entry(text)
+      return [] if text.empty?
+
+      if identity_like?(text) && (row = entry(text))
+        return [row]
+      end
 
       file, line = self.class.split_target(text)
-      return nil if file.empty?
+      return [] if file.empty?
 
       matches = entries.select { |e| self.class.same_path?(e.file, file) }
       matches = matches.select { |e| e.line == line } if line
-      return matches.first.identity if matches.any?
+      matches
+    end
+
+    # An identity String, or nil when nothing matches -- or when more than one does.
+    # Ambiguity is the caller's to report, with the candidates in hand.
+    def resolve(target)
+      matches = candidates(target)
+      return matches.first.identity if matches.size == 1
+      return nil unless matches.empty?
+
+      file, line = self.class.split_target(target.to_s.strip)
+      return nil if file.empty?
 
       self.class.registry_identity(file, line)
     end

data/lib/constable/matchers.rb

@@ -33,7 +33,7 @@ module Constable
       not_found: 404, method_not_allowed: 405, not_acceptable: 406,
       request_timeout: 408, conflict: 409, gone: 410, precondition_failed: 412,
       payload_too_large: 413, unsupported_media_type: 415, im_a_teapot: 418,
-      unprocessable_entity: 422, locked: 423, too_many_requests: 429,
+      unprocessable_entity: 422, unprocessable_content: 422, locked: 423, too_many_requests: 429,
       internal_server_error: 500, not_implemented: 501, bad_gateway: 502,
       service_unavailable: 503, gateway_timeout: 504
     }.freeze
@@ -44,6 +44,22 @@ module Constable
       error: (500..599), server_error: (500..599)
     }.freeze
 
+    # Rack renames statuses -- 422 became :unprocessable_content in Rack 3.1, and Rails
+    # 8.1 deprecates the old spelling -- so the table above is a floor, not the whole
+    # truth. Anything Rack knows is accepted, which means a rename costs no release here.
+    def self.rack_status_codes
+      return @rack_status_codes if defined?(@rack_status_codes)
+
+      @rack_status_codes =
+        if defined?(::Rack::Utils::SYMBOL_TO_STATUS_CODE)
+          ::Rack::Utils::SYMBOL_TO_STATUS_CODE.transform_keys(&:to_sym)
+        else
+          {}
+        end
+    rescue StandardError
+      @rack_status_codes = {}
+    end
+
     MAX_INSPECT = 200
     MAX_BODY    = 800
 
@@ -222,7 +238,9 @@ module Constable
         case expected
         when Integer then expected
         when /\A\d+\z/ then expected.to_i
-        else HTTP_STATUS_CODES[expected.to_s.to_sym]
+        else
+          name = expected.to_s.to_sym
+          HTTP_STATUS_CODES[name] || Matchers.rack_status_codes[name]
         end
       end
 
@@ -345,6 +363,104 @@ module Constable
       end
     end
 
+    # `be_within(0.5).of(10)` -- a matcher spelled across two calls, so it has to survive
+    # the first one and collect its subject on the second.
+    #
+    # Registering it matters for a second reason: without an entry, `be_within` fell
+    # through to the be_*/have_* predicate fallback, which happily built a
+    # PredicateDeferred and then blew up on `.of` with a NoMethodError naming an internal
+    # class rather than the matcher the author actually wrote.
+    class WithinDeferred < Deferred
+      def of(expected)
+        @expected = expected
+        @expected_set = true
+        self
+      end
+
+      def matches?(actual)
+        unless @expected_set
+          return [false, "be_within(#{@args.first.inspect}) is incomplete -- it needs .of: " \
+                         "attest(value).to be_within(0.5).of(10)", nil]
+        end
+
+        delta = @args.first
+        difference = (actual - @expected).abs
+        return true if difference <= delta
+
+        [false, "expected #{Matchers.describe(actual)} to be within #{delta.inspect} of " \
+                "#{Matchers.describe(@expected)}, but it differed by #{difference}", nil]
+      rescue NoMethodError, TypeError, ArgumentError
+        [false, "expected #{Matchers.describe(actual)} to be within #{delta.inspect} of " \
+                "#{Matchers.describe(@expected)}, but a #{actual.class} cannot be subtracted", nil]
+      end
+
+      def description
+        return "be within #{@args.first.inspect} of #{Matchers.describe(@expected)}" if @expected_set
+
+        "be within #{@args.first.inspect} of (nothing -- .of was never called)"
+      end
+    end
+
+    # `be`, in its three RSpec spellings:
+    #
+    #   attest(x).to be(other)   identity -- the same object, not merely equal
+    #   attest(x).to be >= 0     an operator comparison
+    #   attest(x).to be          truthiness
+    #
+    # `==` is deliberately not among the operators. Defining it on a matcher object
+    # breaks equality everywhere the object is compared, and `eq` already says it.
+    class BeDeferred < Deferred
+      COMPARISONS = %i[< <= > >=].freeze
+
+      COMPARISONS.each do |operator|
+        define_method(operator) do |operand|
+          @operator = operator
+          @operand  = operand
+          self
+        end
+      end
+
+      def matches?(actual)
+        return compare(actual) if @operator
+        # `.empty?`, not `.any?`: `[nil].any?` is false, which would send `be(nil)` down
+        # the truthiness branch and assert the opposite of what was written.
+        return identity(actual) unless @args.empty?
+        return true if actual
+
+        [false, "expected a truthy value, but got #{actual.inspect}", nil]
+      end
+
+      def description
+        return "be #{@operator} #{Matchers.describe(@operand)}" if @operator
+        return "be #{Matchers.describe(@args.first)}" unless @args.empty?
+
+        "be truthy"
+      end
+
+      private
+
+      def compare(actual)
+        return true if actual.public_send(@operator, @operand)
+
+        [false, "expected #{Matchers.describe(actual)} to be #{@operator} " \
+                "#{Matchers.describe(@operand)}", nil]
+      rescue NoMethodError, ArgumentError, TypeError
+        [false, "expected #{Matchers.describe(actual)} to be #{@operator} " \
+                "#{Matchers.describe(@operand)}, but a #{actual.class} cannot be compared", nil]
+      end
+
+      # `be` is identity, not equality -- that distinction is the only reason to reach for
+      # it over `eq`, so the failure message says which one failed.
+      def identity(actual)
+        expected = @args.first
+        return true if actual.equal?(expected)
+
+        hint = actual == expected ? " (they are equal, but not the same object)" : ""
+        [false, "expected #{Matchers.describe(actual)} to be the same object as " \
+                "#{Matchers.describe(expected)}#{hint}", nil]
+      end
+    end
+
     # The be_*/have_* fallback: with no matcher registered under the name, the name itself
     # is the assertion -- `be_created` asks the actual whether it is `created?`.
     class PredicateDeferred < Deferred
@@ -795,6 +911,94 @@ module Constable
       raise Constable::Error, "change is only usable through attest { ... }.to change { ... }"
     end
 
+    # Order-independent collection equality. `modernize` converts
+    # `expect(x).to contain_exactly(a, b)` verbatim, so not having it turned every
+    # converted spec that used it into a NoMethodError.
+    define_builtin(:contain_exactly) do |actual, *expected|
+      unless actual.respond_to?(:to_a)
+        next [false, "expected #{Matchers.describe(actual)} to be a collection, " \
+                     "but a #{actual.class} does not respond to #to_a", nil]
+      end
+
+      items = actual.to_a
+      missing = expected.dup
+      extra   = []
+      items.each do |item|
+        index = missing.index { |candidate| candidate == item }
+        index ? missing.delete_at(index) : extra << item
+      end
+      next true if missing.empty? && extra.empty?
+
+      parts = []
+      parts << "missing #{Matchers.describe(missing)}" unless missing.empty?
+      parts << "unexpected #{Matchers.describe(extra)}" unless extra.empty?
+      [false, "expected the collection to contain exactly #{expected.size} " \
+              "#{expected.size == 1 ? "item" : "items"}: #{parts.join(", ")}",
+       { "Actual" => Matchers.describe(items) }]
+    end
+    # Not an alias: RSpec's match_array takes one array where contain_exactly takes
+    # varargs, so aliasing them makes match_array([1, 2]) assert that the collection
+    # holds a single element which is itself the array [1, 2].
+    define_builtin(:match_array) do |actual, expected|
+      unless expected.respond_to?(:to_a)
+        next [false, "match_array takes an array: attest(list).to match_array([1, 2])", nil]
+      end
+
+      Matchers.matcher_for(:contain_exactly).block.call(actual, *expected.to_a)
+    end
+
+    define_builtin(:start_with) do |actual, prefix|
+      unless actual.respond_to?(:start_with?) || actual.respond_to?(:first)
+        next [false, "expected #{Matchers.describe(actual)} to start with " \
+                     "#{Matchers.describe(prefix)}, but a #{actual.class} cannot say", nil]
+      end
+      passed = if actual.respond_to?(:start_with?)
+                 actual.start_with?(prefix)
+               else
+                 actual.first(Array(prefix).size) == Array(prefix)
+               end
+      next true if passed
+
+      [false, "expected #{Matchers.describe(actual)} to start with #{Matchers.describe(prefix)}", nil]
+    end
+
+    define_builtin(:end_with) do |actual, suffix|
+      unless actual.respond_to?(:end_with?) || actual.respond_to?(:last)
+        next [false, "expected #{Matchers.describe(actual)} to end with " \
+                     "#{Matchers.describe(suffix)}, but a #{actual.class} cannot say", nil]
+      end
+      passed = if actual.respond_to?(:end_with?)
+                 actual.end_with?(suffix)
+               else
+                 actual.last(Array(suffix).size) == Array(suffix)
+               end
+      next true if passed
+
+      [false, "expected #{Matchers.describe(actual)} to end with #{Matchers.describe(suffix)}", nil]
+    end
+
+    define_builtin(:be_between) do |actual, low, high|
+      next true if actual.between?(low, high)
+
+      [false, "expected #{Matchers.describe(actual)} to be between " \
+              "#{Matchers.describe(low)} and #{Matchers.describe(high)}", nil]
+    end
+
+    define_builtin(:satisfy) do |actual, &block|
+      next [false, "satisfy needs a block: attest(x).to satisfy { |value| ... }", nil] unless block
+      next true if block.call(actual)
+
+      [false, "expected #{Matchers.describe(actual)} to satisfy the block", nil]
+    end
+
+    define_builtin(:be_within, deferred_class: WithinDeferred) do |_actual, *_args|
+      raise Constable::Error, "be_within needs .of: attest(value).to be_within(0.5).of(10)"
+    end
+
+    define_builtin(:be, deferred_class: BeDeferred) do |_actual, *_args|
+      raise Constable::Error, "be is handled by BeDeferred and should never invoke its block"
+    end
+
     define_builtin(:be_a) do |actual, klass|
       next true if actual.is_a?(klass)
 

data/lib/constable/registry.rb

@@ -42,6 +42,30 @@ module Constable
       @cases.find { |klass| klass.constable_display_name == name.to_s || klass.name == name.to_s }
     end
 
+    # Re-keys any investigations that share a body with another, so the blotter never
+    # treats two tests as one. Runs once, after the whole suite is loaded -- a collision
+    # is invisible until every case file has been seen.
+    #
+    # Returns the groups it re-keyed, so a caller can report them if it wants to.
+    def disambiguate_identities!
+      collisions = investigations.group_by(&:identity).select { |_key, group| group.size > 1 }
+      return [] if collisions.empty?
+
+      collisions.each_value { |group| group.each(&:disambiguate!) }
+
+      # Class and description are usually enough to tell two identical bodies apart. When
+      # they are not -- a copy-pasted `investigate` with the same name and the same body
+      # in the same case -- fall back to position, which is the only thing left that
+      # differs. History for those resets whenever the file is reordered, which is the
+      # honest cost of two tests that are indistinguishable by anything a human wrote.
+      still_colliding = investigations.group_by(&:identity).select { |_key, group| group.size > 1 }
+      still_colliding.each_value do |group|
+        group.each_with_index { |investigation, index| investigation.disambiguate!(ordinal: index) }
+      end
+
+      collisions.values
+    end
+
     def each(&) = @cases.each(&)
 
     def size    = @cases.size