constable-rails 0.1.0 → 1.1.0

data/lib/constable/cli.rb

@@ -17,7 +17,10 @@ module Constable
     # wrong", and CI needs to. Commands return a status; this turns it into one.
     def self.dispatch!(argv)
       start(argv)
-    rescue Thor::Error => e
+    # Thor::Error is a malformed command; Constable::Error is a wrong path, an unknown
+    # tier, an unreadable config. Both are the user's mistake rather than a crash, and
+    # both deserve one sentence and a usage status instead of a backtrace.
+    rescue Thor::Error, Constable::Error => e
       warn e.message
       exit(EXIT_USAGE)
     rescue Interrupt
@@ -42,6 +45,9 @@ module Constable
     option :workers,  type: :numeric, desc: "Parallel workers (default: config, or auto)"
     option :verbose,  type: :boolean, default: false, desc: "Stream log/test.log to stdout"
     option :tier,     type: :string,  desc: "Run one tier only: unit, integration or system"
+    option :output,   type: :string,  desc: "Live stream detail: concise (default) or expanded"
+    option :expanded, type: :boolean, default: false, desc: "Shorthand for --output=expanded"
+    option :concise,  type: :boolean, default: false, desc: "Shorthand for --output=concise"
     def test(*paths)
       config = load_config
       LogRouter.route!(verbose: options[:verbose])
@@ -299,7 +305,9 @@ module Constable
       no_commands do
         def act(locator)
           jail = Jail.new(config: Constable.config, storage: Constable.storage)
-          identity = jail.identity_for(locator)
+          refuse_ambiguous(locator, jail.candidates(locator), "on the docket")
+
+          identity = jail.resolve(locator)
           unless identity
             warn "Nothing on the docket at #{locator}"
             exit(EXIT_USAGE)
@@ -307,6 +315,18 @@ module Constable
           yield jail, identity
         end
 
+        # A bare path naming several tests is a question. Answer it with the list rather
+        # than acting on whichever row the database happened to return first.
+        def refuse_ambiguous(locator, candidates, noun)
+          return if candidates.size <= 1
+
+          warn "#{locator} matches #{candidates.size} tests #{noun}. Name one:"
+          candidates.sort_by { |entry| entry.line.to_i }.each do |entry|
+            warn "  #{entry.location}  #{entry.label}"
+          end
+          exit(EXIT_USAGE)
+        end
+
         def repeat_note(entry)
           count = entry.times_jailed
           count > 1 ? " (this is its #{Reporter.ordinalize(count)} time in jail)" : ""
@@ -344,12 +364,14 @@ module Constable
       desc "release PATH:LINE", "Clear a warrant by hand"
       def release(locator)
         warrants = Warrants.new(config: Constable.config, storage: Constable.storage)
-        identity = warrants.identity_for(locator)
+        JailCommand.new.send(:refuse_ambiguous, locator, warrants.candidates(locator), "under warrant")
+
+        identity = warrants.resolve(locator)
         unless identity
           warn "No warrant at #{locator}"
           exit(EXIT_USAGE)
         end
-        warrants.clear(identity)
+        warrants.release(identity)
         say "Warrant cleared."
       end
     end
@@ -377,6 +399,48 @@ module Constable
       end
     end
 
+    desc "prune", "Forget docket rows and warrants for tests that no longer exist"
+    long_desc <<~DESC
+      A test's key is a content hash of its body, so editing a jailed test gives it a new
+      identity and leaves the old row behind -- pointing at a file:line that may now hold
+      something else. That is identity working as designed; this is the broom.
+
+      Loads the whole suite first, because which tests still exist is only knowable once
+      every case file has been read. Cold cases are never pruned while their file exists:
+      their tests cannot be enumerated without running their own engine, so silence about
+      them means nothing.
+    DESC
+    option :dry_run, type: :boolean, default: false, desc: "List what would go, change nothing"
+    def prune
+      config = load_config
+      known  = Runner.identities(config: config)
+      cold   = ->(path) { config.cold_case?(path) }
+
+      jail     = Jail.new(config: config, storage: Constable.storage)
+      warrants = Warrants.new(config: config, storage: Constable.storage)
+
+      stale_rows     = jail.stale_entries(known, cold_case: cold)
+      stale_warrants = warrants.stale_entries(known, cold_case: cold)
+
+      if stale_rows.empty? && stale_warrants.empty?
+        say "Nothing to prune -- every row on the docket still names a test that exists."
+        return 0
+      end
+
+      report_prunable("docket", stale_rows)
+      report_prunable("warrants", stale_warrants)
+
+      if options[:dry_run]
+        say "Dry run: nothing was changed."
+        return 0
+      end
+
+      stale_rows.each { |entry| jail.forget(entry.identity) }
+      stale_warrants.each { |entry| warrants.release(entry.identity) }
+      say "Pruned #{stale_rows.size + stale_warrants.size} row(s). Flake history is left alone."
+      0
+    end
+
     desc "jail SUBCOMMAND", "The jail docket"
     subcommand "jail", JailCommand
 
@@ -387,6 +451,16 @@ module Constable
     subcommand "history", HistoryCommand
 
     no_commands do
+      def report_prunable(heading, entries)
+        return if entries.empty?
+
+        say "#{heading} (#{entries.size}):"
+        entries.sort_by { |entry| [entry.file.to_s, entry.line.to_i] }.each do |entry|
+          say "  #{entry.location}  #{entry.label}"
+        end
+        say ""
+      end
+
       def load_config
         Constable.config
       end
@@ -400,7 +474,18 @@ module Constable
       end
 
       def reporter(config)
-        Reporter.new(io: $stdout, config: config, color: color?)
+        Reporter.new(io: $stdout, config: config, color: color?, mode: output_mode)
+      end
+
+      # nil means "the config file decides". The explicit --output wins over the two
+      # shorthands, and --concise wins over --expanded if somebody passes both -- the
+      # quieter of two contradictory instructions is the safer one to obey.
+      def output_mode
+        return options[:output] if options[:output]
+        return :concise if options[:concise]
+        return :expanded if options[:expanded]
+
+        nil
       end
 
       def say_table(heading, entries)

data/lib/constable/cold_case/rspec.rb

@@ -120,7 +120,12 @@ module Constable
             with_engine do
               collector  = Collector.new
               load_error = capture_load(path)
-              run_world(collector) unless load_error
+              unless load_error
+                # After the file has loaded -- that load is what registers them -- and
+                # before its examples run. See #run_pending_before_suite_hooks.
+                run_pending_before_suite_hooks(::RSpec.configuration)
+                run_world(collector)
+              end
 
               ColdCase.warn_for_file(path, base_class_name, collector.examples.size, config: config)
               results = build_results(path, collector.examples, config: config, seed: seed,
@@ -134,14 +139,101 @@ module Constable
         # configuration -- which also means any RSpec.configure hooks a rails_helper
         # installed are gone, so this is a teardown call, not a between-files call.
         def reset_engine!
+          # Inside the global-state swap, not outside it. Building a SuiteHookContext
+          # makes rspec-core lazily construct a world and a configuration, so running
+          # these hooks bare would leave both behind in a host process that had none --
+          # exactly the leak #with_engine exists to prevent.
+          with_engine { run_after_suite_hooks! } if after_suite_hooks_pending?
+
           @session_world = nil
           @session_configuration = nil
           @session_prepared = false
+          @ran_before_suite_hooks = nil
           nil
         end
 
         private
 
+        # --- Suite hooks ------------------------------------------------------------
+        #
+        # RSpec's own Runner wraps its group loop in `configuration.with_suite_hooks`.
+        # We drive the groups directly (see #run_world), so without this a cold case
+        # never fires `before(:suite)` -- and that is exactly where webmock/rspec calls
+        # `WebMock.enable!`, where VCR and DatabaseCleaner install themselves, and where
+        # SimpleCov starts. Skipping them fails *open*: a spec that stubs HTTP opens a
+        # real socket instead of erroring, which is the worst direction for a testing
+        # tool to be wrong in.
+        #
+        # `with_suite_hooks` itself is the wrong shape here. It is a bracket around one
+        # block, but "suite" means the whole run rather than one file: wrapping each file
+        # would fire `after(:suite)` after file one and hand file two the wreckage. Nor
+        # can the hooks all be run up front, because a legacy file's own
+        # `require "rails_helper"` is what registers them -- before the first load there
+        # is nothing to run.
+        #
+        # So each hook runs exactly once, the first time we see it: after a file has
+        # loaded, before its examples. `after(:suite)` runs once, from #reset_engine!.
+        def run_pending_before_suite_hooks(configuration)
+          pending = suite_hooks(configuration, :@before_suite_hooks) - ran_before_suite_hooks
+          return if pending.empty?
+
+          ran_before_suite_hooks.concat(pending)
+          invoke_suite_hooks(configuration, "a `before(:suite)` hook", pending,
+                             scope: :before_suite_hook)
+        end
+
+        # Only worth running if we ever ran the matching before(:suite) half -- otherwise
+        # this is a teardown for setup that never happened.
+        def run_after_suite_hooks!
+          configuration = @session_configuration
+          return if configuration.nil? || ran_before_suite_hooks.empty?
+
+          hooks = suite_hooks(configuration, :@after_suite_hooks)
+          return if hooks.empty?
+
+          invoke_suite_hooks(configuration, "an `after(:suite)` hook", hooks,
+                             scope: :after_suite_hook)
+        end
+
+        def ran_before_suite_hooks
+          @ran_before_suite_hooks ||= []
+        end
+
+        # Nothing was set up, so there is nothing to tear down -- and no reason to build
+        # an RSpec world to discover that.
+        def after_suite_hooks_pending?
+          !@session_configuration.nil? &&
+            ran_before_suite_hooks.any? &&
+            suite_hooks(@session_configuration, :@after_suite_hooks).any?
+        end
+
+        # RSpec keeps these in plain ivars with no public reader. Read them defensively:
+        # a missing ivar means a version that stores them elsewhere, and running no suite
+        # hooks is the behavior we already had.
+        def suite_hooks(configuration, ivar)
+          return [] unless configuration.respond_to?(:instance_variable_defined?)
+          return [] unless configuration.instance_variable_defined?(ivar)
+
+          Array(configuration.instance_variable_get(ivar))
+        end
+
+        # `run_suite_hooks` is private on Configuration, and it is the part that builds a
+        # SuiteHookContext and keeps one failing before-hook from running the rest. Use it
+        # when it is there, and fall back to driving the hooks ourselves when it is not.
+        def invoke_suite_hooks(configuration, description, hooks, scope:)
+          previous = ::RSpec.current_scope if ::RSpec.respond_to?(:current_scope)
+          ::RSpec.current_scope = scope if ::RSpec.respond_to?(:current_scope=)
+
+          if configuration.respond_to?(:run_suite_hooks, true)
+            configuration.send(:run_suite_hooks, description, hooks)
+          else
+            context = ::RSpec::Core::SuiteHookContext.new(description, configuration.reporter)
+            hooks.each { |hook| hook.run(context) }
+          end
+        ensure
+          ::RSpec.current_scope = previous if previous && ::RSpec.respond_to?(:current_scope=)
+        end
+
         # Running RSpec in-process is a global-state problem: RSpec.world holds every
         # registered example group and RSpec.configuration holds every hook. We swap in a
         # session world/configuration for the duration of a file and put whatever was

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: {})
@@ -43,23 +63,83 @@ module Constable
       @raw  = deep_merge(@raw, stringify(overrides || {}))
     end
 
+    # Merges values set in Ruby (Constable.configure) over the ones read from the file.
+    # Called once, after case_helper.rb has been loaded -- which is the first moment those
+    # values exist.
+    def apply_overrides!(overrides)
+      return self if overrides.nil? || overrides.empty?
+
+      @raw = deep_merge(@raw, stringify(overrides))
+      self
+    end
+
     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
-    def storage_url     = storage["url"]
+    # Storage is the one setting that cannot be written in Ruby -- the blotter is opened
+    # before test/case_helper.rb loads, so `constable jail` and `constable status` can read
+    # the docket without booting the app. That would leave .constable/config.yml mandatory
+    # for anyone not on the default SQLite, so the environment can say it instead:
+    #
+    #   CONSTABLE_STORAGE_URL=postgres://user:pass@host/constable_metadata
+    #   CONSTABLE_STORAGE_PATH=/var/lib/constable/blotter.sqlite3
+    #
+    # Which is also the right shape for CI, where the value is a secret and differs per
+    # machine. The environment wins over the file, as an environment usually should.
+    def storage_url = env_or("CONSTABLE_STORAGE_URL", storage["url"])
+
+    def storage_adapter
+      explicit = env_or("CONSTABLE_STORAGE_ADAPTER", storage["adapter"])
+      return explicit.to_s if explicit
+
+      # A URL with no adapter names its own: postgres://... can only mean postgres.
+      scheme = storage_url.to_s[%r{\A([a-z][a-z0-9+.-]*)://}, 1]
+      return "postgres" if %w[postgres postgresql].include?(scheme)
+      return "mysql" if %w[mysql mysql2].include?(scheme)
+
+      "sqlite"
+    end
 
     def storage_path
-      path = storage["path"] || DEFAULTS["storage"]["path"]
+      path = env_or("CONSTABLE_STORAGE_PATH", storage["path"]) ||
+             DEFAULTS["storage"]["path"]
       File.absolute_path?(path) ? path : File.join(@root, path)
     end
 
@@ -97,6 +177,13 @@ module Constable
 
     private
 
+    # An empty environment variable is not a value. `CONSTABLE_STORAGE_URL=` in a CI
+    # config means "unset", not "connect to the empty string".
+    def env_or(name, fallback)
+      value = ENV.fetch(name, nil)
+      value.nil? || value.strip.empty? ? fallback : value.strip
+    end
+
     def truthy(value)
       return false if value.nil? || value == false
       return false if value.to_s.strip.downcase == "false"

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

@@ -241,6 +241,11 @@ module Constable
     # `constable jail release PATH:LINE`. Off the docket entirely, no supervision.
     def release(identity) = @storage.release(identity.to_s) ? true : false
 
+    # Pruning is not release. Release says "this test is trusted again"; prune says "this
+    # row is about a test that no longer exists". The distinction matters because release
+    # is a judgement someone made and prune is bookkeeping.
+    def forget(identity) = @storage.release(identity.to_s) ? true : false
+
     # `jail run` never auto-releases and never auto-paroles. One green run proves nothing;
     # it only earns a mention. A human reads this list and decides.
     #
@@ -267,13 +272,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 +343,70 @@ 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
+
+    # Rows whose test no longer exists.
+    #
+    # A test's key is a content hash of its body, so editing a jailed test gives it a new
+    # identity and leaves the old row behind -- pointing at a file:line that may now hold
+    # something else entirely. That is content-hash identity working as designed, but over
+    # a few months the docket fills with tests nobody can find.
+    #
+    # `known` is every identity the loaded suite registered, so this is only meaningful
+    # after a full load. Two things are deliberately conservative about it:
+    #
+    #   * A known identity is never stale, even when the file recorded beside it is gone.
+    #     The path is a display label; the identity is the truth. A test that moved file
+    #     has an out-of-date label, not a missing test.
+    #   * A cold case is never pruned while its file exists. Cold-case tests cannot be
+    #     enumerated without running their own engine, so absence from `known` says
+    #     nothing about them.
+    def stale_entries(known, cold_case: nil)
+      known = Array(known)
+      entries.reject { |entry| known.include?(entry.identity) }
+             .select { |entry| gone?(entry, cold_case) }
+    end
+
+    def gone?(entry, cold_case)
+      relative = entry.file.to_s
+      return true if relative.empty?
+
+      path = File.absolute_path?(relative) ? relative : File.join(Constable.root, relative)
+      return true unless File.exist?(path)
+      return false if cold_case&.call(relative)
+
+      true
+    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