constable-rails 0.1.0 → 1.0.0

data/lib/constable/reporter.rb

@@ -46,6 +46,11 @@ module Constable
 
     DEFAULT_SLOWEST = 5
 
+    # Column the expanded stream right-aligns durations into. Descriptions are never
+    # truncated to fit it -- a clipped test name is not something you can grep for --
+    # so a long one simply pushes its own stamp out past the column.
+    EXPANDED_STAMP_COLUMN = 56
+
     # Result::GLYPHS covers statuses. These four are summary vocabulary, not statuses:
     # supervision and coverage are properties of a test, not outcomes of one.
     GLYPHS = Result::GLYPHS.merge(
@@ -95,13 +100,14 @@ module Constable
       0x1F900..0x1F9FF, 0x20000..0x3FFFD
     ].freeze
 
-    attr_reader :io, :config, :seed, :total
+    attr_reader :io, :config, :seed, :total, :mode
 
-    def initialize(io: $stdout, config: nil, color: nil, slowest: DEFAULT_SLOWEST)
+    def initialize(io: $stdout, config: nil, color: nil, slowest: DEFAULT_SLOWEST, mode: nil)
       @io      = io
       @config  = config || Constable.config
       @color   = resolve_color(color)
       @slowest = slowest.to_i
+      @mode    = resolve_mode(mode)
       @io.set_encoding(Encoding::UTF_8) if @io.respond_to?(:set_encoding)
 
       reset_stream!
@@ -141,6 +147,14 @@ module Constable
     def flush!
       return self unless streaming?
 
+      # The expanded stream never buffers -- every line was written as it happened, so
+      # there is nothing left to emit, only a blank line before the summary.
+      if expanded?
+        reset_stream!
+        writeln
+        return self
+      end
+
       close_stream_line
       pending_case_names.each { |name| open_stream_line(name) && close_stream_line }
       writeln
@@ -169,6 +183,9 @@ module Constable
 
       section_parole_violations(results)
       section_failures(results)
+      section_warrants(results)
+      section_jailed(results)
+      section_parole(results)
       section_warnings(warnings)
       section_slowest(results)
       rename_suggestions(suggestions)
@@ -193,6 +210,7 @@ module Constable
     def failed?  = !success?
     def color?   = @color
     def finished? = @finished
+    def expanded? = @mode == :expanded
 
     private
 
@@ -211,6 +229,8 @@ module Constable
     end
 
     def stream(result)
+      return stream_expanded(result) if expanded?
+
       name = result.case_name.to_s
       name = "(anonymous)" if name.empty?
       glyph = paint(result.glyph, COLORS[result.status])
@@ -263,6 +283,77 @@ module Constable
     # Glyphs may carry escape codes; count only the visible ones.
     def count_glyphs(string) = strip_ansi(string).length
 
+    # --- expanded stream -----------------------------------------------------------
+    #
+    # One line per test instead of one glyph. The trade is deliberate: concise keeps a
+    # thousand-test suite on one screen, expanded tells you which test is hanging while
+    # it hangs, without waiting for the summary.
+    #
+    # Workers interleave, so a case can come back after another has spoken. It gets a
+    # second header rather than having its later tests silently appended under the
+    # wrong one -- the same honesty rule the concise stream follows.
+    def stream_expanded(result)
+      name = result.case_name.to_s
+      name = "(anonymous)" if name.empty?
+
+      if @stream_case != name
+        writeln if @stream_case
+        writeln(INDENT + paint(name, :bold))
+        @stream_case = name
+        @stream_open = true
+      end
+
+      writeln(expanded_line(result))
+    end
+
+    def expanded_line(result)
+      glyph = paint(result.glyph, COLORS[result.status])
+      line  = "#{ENTRY_INDENT}#{glyph} #{expanded_description(result)}"
+
+      stamp = expanded_duration(result)
+      return line if stamp.nil?
+
+      # Pad to a column so the durations line up, but never truncate a description --
+      # a clipped test name is not something you can grep for.
+      visible = strip_ansi(line).length
+      gap = [EXPANDED_STAMP_COLUMN - visible, 1].max
+      "#{line}#{" " * gap}#{paint(stamp, :dim)}"
+    end
+
+    def expanded_description(result)
+      description = result.description.to_s
+      description = "(no description)" if description.empty?
+      # A jailed test never ran its body, so say why rather than implying it passed.
+      return "#{description} #{paint("— #{result.jail_reason}", :dim)}" if jail_reason_worth_showing?(result)
+
+      description
+    end
+
+    def jail_reason_worth_showing?(result)
+      result.status == :jailed && !result.jail_reason.to_s.strip.empty?
+    end
+
+    # Only real, measured time. A jailed test never ran, and "0ms" would be a claim
+    # about a body that was skipped.
+    def expanded_duration(result)
+      return nil if result.status == :jailed
+      return nil unless result.duration.to_f.positive?
+
+      format_test_duration(result.duration)
+    end
+
+    # The summary's durations are run-scale, where "12.4s" is the useful unit. One test
+    # is usually sub-second, and "0.0s" against every line says nothing at all -- so the
+    # expanded stream counts milliseconds until a test is slow enough for seconds to mean
+    # something.
+    def format_test_duration(seconds)
+      seconds = seconds.to_f
+      return format_duration(seconds) if seconds >= 1
+
+      milliseconds = (seconds * 1000).round
+      milliseconds.zero? ? "<1ms" : "#{milliseconds}ms"
+    end
+
     # --- header and headline -------------------------------------------------------
 
     def header_line(results, duration)
@@ -359,8 +450,12 @@ module Constable
       each_entry(violations) do |result|
         writeln(INDENT + paint("#{GLYPHS[:parole_violation]} #{result.case_name}", COLORS[:parole_violation]))
         writeln(ENTRY_INDENT + paint(%("#{result.description}"), :dim))
+        writeln(ENTRY_INDENT + paint(result.location, :dim))
         writeln(ENTRY_INDENT + parole_violation_sentence(result))
       end
+      hint("Somebody trusted this test again and it let them down, so it is back on the " \
+           "docket. Fix it before the next constable jail parole — a second violation " \
+           "is the signal that the test, not the flake, is the problem.")
     end
 
     def parole_violation_sentence(result)
@@ -369,6 +464,95 @@ module Constable
       sentence
     end
 
+    # A section says what happened; a hint says what to do about it. One dim sentence,
+    # and only where there is a real next step -- a tip printed on every run stops being
+    # read on the second one.
+    def hint(text)
+      writeln
+      lines = wrap(text, width: RULE_WIDTH - INDENT.length - 2, indent: "  ")
+      writeln(INDENT + paint("→ #{lines.first}", :dim))
+      lines.drop(1).each { |line| writeln(INDENT + paint(line, :dim)) }
+    end
+
+    # Every test currently under a warrant: it failed, then passed when rerun in
+    # isolation, so it is flaky rather than broken. Loud, but not build-blocking.
+    def section_warrants(results)
+      warranted = results.select(&:warranted?)
+      return if warranted.empty?
+
+      section("WARRANTS")
+      each_entry(warranted) do |result|
+        writeln(INDENT + paint("#{GLYPHS[:warrant]} #{result.case_name}", COLORS[:warranted]))
+        writeln(ENTRY_INDENT + paint(%("#{result.description}"), :dim))
+        writeln(ENTRY_INDENT + paint(result.location, :dim))
+        writeln(ENTRY_INDENT + warrant_sentence(result))
+      end
+      hint("A warrant is \"not reproducible\", not \"not a problem\" — it stops blocking the " \
+           "build and stays visible until someone deals with it. " \
+           "Fixed the flake? constable warrants release PATH:LINE")
+    end
+
+    def warrant_sentence(result)
+      statuses = Array(result.retries).map(&:to_sym)
+      return "Failed once, then passed on retry." if statuses.empty?
+
+      passed = statuses.count(:passed)
+      "Failed, then passed #{passed} of #{statuses.size} #{pluralize(statuses.size, "retry")} " \
+        "run in isolation."
+    end
+
+    # The docket. These never ran their bodies, so they are neither passing nor failing --
+    # which is exactly why they get their own category rather than being folded into
+    # either one.
+    def section_jailed(results)
+      jailed = results.select { |result| result.status == :jailed }
+      return if jailed.empty?
+
+      section("JAILED")
+      each_entry(jailed) do |result|
+        writeln(INDENT + paint("#{GLYPHS[:jailed]} #{result.case_name}", COLORS[:jailed]))
+        writeln(ENTRY_INDENT + paint(%("#{result.description}"), :dim))
+        writeln(ENTRY_INDENT + paint(result.location, :dim))
+        writeln(ENTRY_INDENT + jailed_sentence(result))
+      end
+      hint("Jailed means skipped and tracked, not passing. Think one is fixed? " \
+           "constable jail parole PATH:LINE runs it for real again — " \
+           "#{@config.parole_period} clean runs and it releases itself.")
+    end
+
+    def jailed_sentence(result)
+      reason   = result.jail_reason.to_s.strip
+      sentence = reason.empty? ? "Body skipped; setup still ran." : "#{reason.capitalize}."
+      sentence += " Its #{ordinalize(result.times_jailed)} time in jail." if result.times_jailed.to_i > 1
+      sentence
+    end
+
+    # Out on parole and behaving. Worth naming every run, because the count only means
+    # something if you can see it moving.
+    def section_parole(results)
+      paroled = results.select { |result| result.parole_day && !result.parole_violation? }
+      return if paroled.empty?
+
+      section("ON PAROLE")
+      each_entry(paroled) do |result|
+        writeln(INDENT + paint("#{GLYPHS[:parole]} #{result.case_name}", COLORS[:parole]))
+        writeln(ENTRY_INDENT + paint(%("#{result.description}"), :dim))
+        writeln(ENTRY_INDENT + paint(result.location, :dim))
+        writeln(ENTRY_INDENT + parole_progress_sentence(result))
+      end
+      hint("A paroled test runs for real and is watched: one failure sends it straight " \
+           "back to jail. constable watchlist shows everything under supervision.")
+    end
+
+    def parole_progress_sentence(result)
+      day       = result.parole_day.to_i
+      period    = @config.parole_period
+      remaining = [period - day, 0].max
+      return "Day #{day} of #{period} — releases after this run." if remaining.zero?
+
+      "Day #{day} of #{period} — #{remaining} #{pluralize(remaining, "clean run")} to go."
+    end
+
     def section_failures(results)
       failures = results.select(&:failed?)
       return if failures.empty?
@@ -432,11 +616,21 @@ module Constable
           writeln(INDENT + paint("#{GLYPHS[:warning]} #{message}", COLORS[:warning]))
         else
           writeln(INDENT + paint("#{GLYPHS[:warning]} #{location}", COLORS[:warning]))
-          message.each_line { |line| writeln(ENTRY_INDENT + line.chomp) }
+          warning_message_lines(message).each { |line| writeln(ENTRY_INDENT + line) }
         end
       end
     end
 
+    # A warning carries the author's own words -- an unsafe block's reason, a cold case's
+    # count -- and those are easily ninety columns. Wrapped to the frame, but respecting
+    # any line breaks the message already chose.
+    def warning_message_lines(message)
+      message.to_s.lines.flat_map do |line|
+        text = line.chomp
+        text.empty? ? [""] : wrap(text, width: RULE_WIDTH - ENTRY_INDENT.length, indent: "")
+      end
+    end
+
     def section_slowest(results)
       # A jailed test never ran its body, so it has no honest duration. A parole
       # violation did run -- and failing slowly is still worth seeing.
@@ -551,7 +745,28 @@ module Constable
     end
 
     def pluralize(count, word)
-      count.to_i == 1 ? word : "#{word}s"
+      return word if count.to_i == 1
+      # "retry" -> "retries". Only the consonant-y rule earns a special case; every other
+      # word this reporter pluralizes takes a plain "s".
+      return "#{word[0..-2]}ies" if word.end_with?("y") && !"aeiou".include?(word[-2].to_s)
+
+      "#{word}s"
+    end
+
+    # Hints are prose, and prose that runs past the frame reads as a mistake. Wrapped to
+    # the same 60 columns the rules use, with continuation lines aligned under the arrow.
+    def wrap(text, width:, indent:)
+      words = text.split
+      lines = [+""]
+      words.each do |word|
+        candidate = lines.last.empty? ? word : "#{lines.last} #{word}"
+        if candidate.length <= width || lines.last.empty?
+          lines[-1] = candidate
+        else
+          lines << +word
+        end
+      end
+      lines.each_with_index.map { |line, i| i.zero? ? line : indent + line }
     end
 
     def format_duration(seconds)
@@ -571,6 +786,17 @@ module Constable
 
     # Colour is a nicety; correctness is not. NO_COLOR, a pipe, a dumb terminal or an
     # explicit --no-color all fall back to plain text with identical layout.
+    # An explicit argument (the --expanded / --concise flags) beats the config file, which
+    # beats the default. An unrecognized value falls back rather than raising: a typo in
+    # config.yml should not stop a suite from running.
+    def resolve_mode(mode)
+      configured = @config.respond_to?(:output_mode) ? @config.output_mode : :concise
+      return configured if mode.nil?
+
+      mode = mode.to_s.strip.downcase.to_sym
+      Config::OUTPUT_MODES.include?(mode) ? mode : configured
+    end
+
     def resolve_color(color)
       return !!color unless color.nil?
       return false if ENV["NO_COLOR"] && !ENV["NO_COLOR"].empty?

data/lib/constable/runner.rb

@@ -11,6 +11,14 @@ module Constable
   # chose, since reordering someone's untouched legacy file is exactly the kind of surprise
   # the cold-case story exists to avoid.
   class Runner
+    # Thresholds for "this run is broken, not these tests" -- see #systemic_failure.
+    SYSTEMIC_MINIMUM   = 5    # below this it is cheaper to believe the tests
+    SYSTEMIC_SHARE     = 0.25 # of the whole run
+    SYSTEMIC_AGREEMENT = 0.8  # of the failures, failing identically
+
+    # `failed` rather than `count` or `tally`, both of which override an Enumerable method.
+    Systemic = Struct.new(:exception_class, :failed, :total, keyword_init: true)
+
     # One unit of work. Native items are a single investigation; cold items are a whole
     # file, because their engine owns the granularity inside it.
     class Item
@@ -65,7 +73,11 @@ module Constable
       Constable::Coverage.start!(config: @config, force: true) if coverage?
 
       load_suite!
+      # Before anything is keyed on an identity -- selection, the docket, flake history --
+      # settle any two tests that happen to share a body.
+      Constable.registry.disambiguate_identities!
       items = build_items
+      refuse_empty_selection!(items)
       ordered = order(items)
 
       run_id = @storage.start_run(seed: @seed, mode: mode_label, full: @selection.full?)
@@ -91,6 +103,10 @@ module Constable
       @results = adjudicate(raw)
       duration = monotonic - started
 
+      # Cold-case engines hold a live session -- for RSpec that is a configuration
+      # carrying `after(:suite)` hooks that have not fired yet. Tear it down before our
+      # own after_suite so the engine's cleanup runs inside the suite, not after it.
+      ColdCase.reset_engines!
       Constable.configuration.run_after_suite!
       @coverage_report = build_coverage_report if coverage?
 
@@ -172,6 +188,17 @@ module Constable
       end
     end
 
+    # A run that was *asked* for something specific and found nothing is a usage error, not
+    # a pass. `constable test test/cases/typo_case.rb` used to print "0 passed, 0 failed"
+    # and exit 0, so a mistyped path in a CI script produced a green build that ran no
+    # tests at all. A full run with an empty suite is a different thing and stays quiet.
+    def refuse_empty_selection!(items)
+      return unless items.empty?
+      return unless @selection.explicit?
+
+      raise Constable::Error, @selection.empty_selection_message
+    end
+
     def build_items
       native = native_items
       cold = @selection.cold_targets_selected.map { |t| Item.new(path: t.path, kind: :cold) }
@@ -188,14 +215,29 @@ module Constable
 
     # PATH:LINE means "the investigation at that line" -- but developers point at any line
     # inside the block, so pick the investigation whose declaration is nearest above it.
+    #
+    # Bounded by the end of the file. Unbounded, `:999` on a twenty-line file quietly ran
+    # the last investigation in it: not the test the user asked for, not an error, and
+    # green either way. A line past the end is a typo, and no answer beats a wrong one.
     def narrow_to_line(investigations, line)
       exact = investigations.select { |inv| inv.line == line }
       return exact if exact.any?
+      return [] unless line_within_file?(investigations.first, line)
 
       nearest = investigations.select { |inv| inv.line <= line }.max_by(&:line)
       nearest ? [nearest] : []
     end
 
+    def line_within_file?(investigation, line)
+      path = investigation&.file
+      return false if path.nil?
+
+      path = File.join(@config.root, path) unless File.exist?(path)
+      return false unless File.exist?(path)
+
+      line <= File.foreach(path).count
+    end
+
     def order(items)
       native, cold = items.partition(&:native?)
       [*native.shuffle(random: Random.new(@seed)), *cold]
@@ -205,13 +247,32 @@ module Constable
       return [] if items.empty?
 
       count = worker_count(items)
-      if count > 1 && forkable?
+      if count > 1 && forkable? && parallel_safe?
         run_parallel(items, count)
       else
         run_serial(items)
       end
     end
 
+    # Forking is only safe once each worker has a database of its own. Without that,
+    # every worker opens the same one: on SQLite the run dissolves into "database is
+    # locked", and on a client/server database the tests quietly see each other's rows,
+    # which is worse. An app with no ActiveRecord has nothing to shard and is always safe.
+    #
+    # When we cannot shard, we run serially and say why. Slow is a trade-off; wrong is not.
+    def parallel_safe?
+      return true unless WorkerDatabases.active_record?
+      return true if WorkerDatabases.shardable?
+
+      Constable.warn!(
+        "parallel workers need one database per worker, and this app's ActiveRecord " \
+        "cannot provide them (active_record/test_databases did not load). Running " \
+        "serially instead -- pass --workers N once that is available.",
+        kind: :parallel
+      )
+      false
+    end
+
     def worker_count(items)
       requested = @workers || @config.parallel_workers
       requested.to_i.clamp(1, items.size)
@@ -240,7 +301,11 @@ module Constable
       # driver rightly complains about it.
       @storage.close
 
-      buckets.each do |bucket|
+      # Same reasoning for the app's own connections: a child that inherits a live
+      # handle can corrupt it. Rails does exactly this before its own fork.
+      WorkerDatabases.before_fork!
+
+      buckets.each_with_index do |bucket, worker_index|
         reader, writer = IO.pipe
         # Marshal payloads are binary. Left in text mode, the first byte that isn't valid
         # UTF-8 takes the worker down with an encoding error.
@@ -248,10 +313,21 @@ module Constable
         writer.binmode
         pid = fork do
           reader.close
+
+          # Before a single test runs: build this worker's own database and point the
+          # process at it. Raises rather than falling back to the shared one, because a
+          # silent fallback is the bug we are here to prevent.
+          WorkerDatabases.after_fork!(worker_index)
+
           bucket.each do |item|
             run_item(item).each { |result| write_message(writer, :result, result.to_h) }
           end
 
+          # A worker owns its own cold-case session, and it dies here. Fire the engine's
+          # after(:suite) hooks in the process that ran the before(:suite) half, before
+          # coverage is read -- the parent has no hooks to run on its behalf.
+          ColdCase.reset_engines!
+
           # Ruby's Coverage counts lines in the process that executed them, so a worker's
           # hits would die with it. They ride home on the same pipe as the results.
           write_message(writer, :coverage, Constable::Coverage.peek_raw) if coverage?
@@ -513,6 +589,9 @@ module Constable
     # Turns raw pass/fail into the verdict the build acts on: warrants decide whether a
     # failure is even real, then jail decides whether it blocks.
     def adjudicate(raw)
+      @systemic = systemic_failure(raw)
+      announce_systemic_failure(@systemic) if @systemic
+
       raw.map do |result|
         decided = warrants.adjudicate(
           result,
@@ -520,10 +599,54 @@ module Constable
           subject: investigation_for(result.identity)
         ) { |subject, _attempt| rerun_in_isolation(subject) }
 
-        jail_run? ? decided : jail.adjudicate(decided, jail_mode: jail_mode?)
+        next decided if jail_run?
+
+        jail.adjudicate(decided, jail_mode: jail_mode?, systemic: systemic?(decided))
       end
     end
 
+    # A run is "systemically broken" when a large share of it failed the same way: the
+    # database was down, a worker could not start, a shared fixture never loaded. Thirty
+    # tests did not each independently go bad in the same second.
+    #
+    # This matters because flake history reads "passed last run, failed this run" as
+    # evidence about a *test*, and jails it. One bad afternoon on CI could therefore
+    # quarantine a third of a healthy suite, and the docket -- which is supposed to be a
+    # record of tests worth distrusting -- fills up with tests that were never at fault.
+    def systemic_failure(results)
+      failures = results.select(&:failed?)
+      return nil if failures.size < SYSTEMIC_MINIMUM
+      return nil if failures.size < results.size * SYSTEMIC_SHARE
+
+      grouped = failures.group_by { |result| result.failure&.exception_class.to_s }
+      grouped.delete("")
+      return nil if grouped.empty?
+
+      exception_class, sharing = grouped.max_by { |_klass, group| group.size }
+      return nil if sharing.size < failures.size * SYSTEMIC_AGREEMENT
+
+      Systemic.new(exception_class: exception_class, failed: sharing.size, total: results.size)
+    end
+
+    # Only the failures that look like the outage are exempt. A genuine failure that
+    # happened to land in the same run is still a genuine failure.
+    def systemic?(result)
+      return false unless @systemic
+      return false unless result.failed?
+
+      result.failure&.exception_class.to_s == @systemic.exception_class
+    end
+
+    def announce_systemic_failure(systemic)
+      Constable.warn!(
+        "#{systemic.failed} of #{systemic.total} tests failed with the same error " \
+        "(#{systemic.exception_class}). That reads as one broken run rather than " \
+        "#{systemic.failed} newly flaky tests, so flake history and the jail docket were " \
+        "left alone. Fix the cause and run again.",
+        kind: :systemic
+      )
+    end
+
     def investigation_for(identity)
       @investigation_index ||= Constable.registry.investigations.to_h { |inv| [inv.identity, inv] }
       @investigation_index[identity]
@@ -564,6 +687,11 @@ module Constable
 
     def persist(run_id, results, coverage_report)
       results.each do |result|
+        # The blotter is the evidence file. A result produced by an outage is not
+        # evidence about the test, so it is not filed -- otherwise the next run reads
+        # "failed, then passed" and draws a conclusion from a power cut.
+        next if systemic?(result)
+
         @storage.record_result(run_id, result)
         @storage.record_duration(result.identity, result.duration)
       end

data/lib/constable/selection.rb

@@ -33,10 +33,13 @@ module Constable
       @root        = root.to_s
       @full        = full
       @unsafe_only = unsafe_only
-      @tier        = tier&.to_sym
+      # Downcased: `--tier UNIT` used to match nothing at all and report a clean run.
+      @tier        = tier.to_s.strip.downcase.to_sym unless tier.to_s.strip.empty?
       @reason      = nil
     end
 
+    TIERS = %w[unit integration system].freeze
+
     def full?        = @full
     def unsafe_only? = @unsafe_only
 
@@ -60,6 +63,25 @@ module Constable
       end
     end
 
+    # Did the user ask for something in particular? If so, finding nothing is an error
+    # rather than a clean run -- see Runner#refuse_empty_selection!.
+    def explicit? = @args.any? { |arg| !arg.to_s.strip.empty? } || !@tier.nil?
+
+    # Says which part of the request came up empty, because "0 tests" on its own does not
+    # tell you whether the path was wrong, the tier was, or both.
+    def empty_selection_message
+      if @tier && !TIERS.include?(@tier.to_s)
+        return "unknown tier #{@tier.inspect} -- expected one of #{TIERS.join(", ")}."
+      end
+
+      described = @args.reject { |arg| arg.to_s.strip.empty? }
+      subject   = described.empty? ? "this run" : described.join(", ")
+      suffix    = @tier ? " in the #{@tier} tier" : ""
+
+      "no tests matched #{subject}#{suffix}. Check the path, the line number, and " \
+        "whether the file is a case or a cold case."
+    end
+
     def native_targets = targets.select(&:native?)
     def cold_targets_selected = targets.select(&:cold?)
     def empty? = targets.empty?

data/lib/constable/storage/sqlite_adapter.rb

@@ -36,16 +36,36 @@ module Constable
 
       def connect!
         require_driver!
+        open_database!
+      end
+
+      # The blotter is the one file Constable owns outright, and it is disposable: it
+      # holds flake history, the docket and warrants, never a test. So when it cannot be
+      # opened, say that deleting it is a real option -- the raw
+      # `SQLite3::NotADatabaseException: file is not a database: PRAGMA journal_mode = WAL`
+      # tells a reader nothing about what to do next, and a blotter that got committed to
+      # git and then merged is exactly how it ends up unreadable.
+      def open_database!
         FileUtils.mkdir_p(File.dirname(path))
         @connection = SQLite3::Database.new(path)
         @connection.results_as_hash = true
         @connection.busy_timeout = BUSY_TIMEOUT_MS
-        # Readers never block the writer and the writer never blocks readers.
+        # Readers never block the writer and the writer never blocks readers. This is also
+        # the first statement to touch the file, so a corrupt blotter surfaces here.
         @connection.execute("PRAGMA journal_mode = WAL")
         # WAL + NORMAL is durable across process crashes, which is the only failure that
         # matters here; a machine losing power mid-run costs us one run's bookkeeping.
         @connection.execute("PRAGMA synchronous = NORMAL")
         @connection
+      rescue SystemCallError => e
+        raise Constable::Error,
+              "Constable cannot open its blotter at #{path} (#{e.class}: #{e.message}). " \
+              "Point `storage.path` in .constable/config.yml somewhere writable."
+      rescue StandardError => e
+        raise Constable::Error,
+              "Constable's blotter at #{path} is not a readable database " \
+              "(#{e.class}). It holds flake history, the jail docket and warrants -- " \
+              "never your tests -- so deleting it is safe and starts that record fresh."
       end
 
       def require_driver!

data/lib/constable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Constable
-  VERSION = "0.1.0"
+  VERSION = "1.0.0"
 end

data/lib/constable/warrants.rb

@@ -222,17 +222,35 @@ module Constable
 
     # The CLI speaks in file:line, the blotter is keyed by content hash. Warrant rows
     # carry both; loaded investigations are the fallback.
-    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 text.match?(/\A[0-9a-f]{8,64}\z/) && entry(text)
+      return [] if text.empty?
+
+      if text.match?(/\A[0-9a-f]{8,64}\z/) && (row = entry(text))
+        return [row]
+      end
 
       file, line = Jail.split_target(text)
-      return nil if file.empty?
+      return [] if file.empty?
 
       matches = entries.select { |e| Jail.same_path?(e.file, file) }
       matches = matches.select { |e| e.line == line } if line
-      return matches.first.identity if matches.any?
+      matches
+    end
+
+    def resolve(target)
+      matches = candidates(target)
+      return matches.first.identity if matches.size == 1
+      return nil unless matches.empty?
+
+      file, line = Jail.split_target(target.to_s.strip)
+      return nil if file.empty?
 
       Jail.registry_identity(file, line)
     end