holdfast 0.1.0

data/lib/holdfast/draft.rb

@@ -0,0 +1,303 @@
+module Holdfast
+  # A first inputs file for one method, drafted from what the code says: the
+  # method's parameters (a record by a factory of its name, a date by its
+  # default), the conditions it branches on, and the literals and constants
+  # those conditions compare with. A date argument is drawn around each date
+  # column of a record argument that the method reads, because "before the
+  # due date" and "after it" are where date code differs.
+  #
+  # A draft with no placeholder left is complete: the run pins it at once,
+  # marked as drafted, and the agent accepts it by copying it to evidence.
+  # A draft with a placeholder is only written, and the row names it.
+  class Draft
+    OFFSETS = [-10, -1, 0, 1, 10].freeze
+    ANCHOR = "Date.new(2026, 3, 20)".freeze
+    COMPARE = %i[< <= > >= == !=].freeze
+
+    Result = Data.define(:path, :data, :holes, :basis) do
+      def complete? = holes.empty?
+    end
+
+    def self.path(root, target) = File.join(Holdfast.dir(root), "drafts", "#{Holdfast.slug(target)}.inputs.json")
+
+    def self.for(change, rev, target)
+      new(change, rev, target).result
+    end
+
+    def initialize(change, rev, target)
+      @change, @rev, @target = change, rev, target
+    end
+
+    def result
+      const_name, kind, name = @target.name.match(/\A(.+?)([#.])(\w+[?!=]?)\z/).captures
+      node = method_node(@target.source, name) || scope_node(@target.source)
+      holes = []
+      basis = []
+      return Result.new(path: nil, data: nil, holes: ["no def found for #{name}"], basis:) unless node
+      # A controller built with `.new` has no request, so every action fails
+      # inside Rails the same way on both sides, and that pin compares nothing.
+      if @target.file.start_with?("app/controllers/")
+        return Result.new(path: nil, data: nil, holes: ["#{@target.name} runs through a request; write a request spec, or a suspicion whose `do` sends that request, and run holdfast check"], basis:)
+      end
+
+      params = node.parameters
+      params = params.parameters if params.is_a?(Prism::BlockParametersNode)
+      records = {}
+      args = Array(params&.requireds).map do |p|
+        param_value(p.name.to_s, nil, records, holes)
+      end
+      kwargs = {}
+      Array(params&.keywords).each do |p|
+        default = p.respond_to?(:value) && p.value ? p.value.slice : nil
+        if date_default?(default) || date_name?(p.name.to_s)
+          kwargs[p.name.to_s] = :date
+        elsif default.nil?
+          kwargs[p.name.to_s] = param_value(p.name.to_s, nil, records, holes)
+        end
+      end
+
+      receiver = receiver_for(const_name, kind, holes)
+      # A record receiver is drafted like a record argument: its own column
+      # reads (`returned_at`, `due_on`) choose its factory's attributes.
+      if receiver.is_a?(Hash) && (model = receiver["ruby"].to_s[/\AFactoryBot\.create\(:(\w+)\)\z/, 1])
+        records["self"] = model
+        receiver = { "factory" => model, "param" => "self" }
+      end
+      reads = attribute_reads(node, records.keys)
+      draws = {}
+      overrides = Hash.new { |h, k| h[k] = {} }
+      records.each do |param, factory|
+        columns = columns_of(factory)
+        reads.fetch(param, []).uniq.each do |attr, bounds|
+          col = columns[attr] || columns["#{attr.delete_suffix("?")}_at"] && "#{attr.delete_suffix("?")}_at"
+          if columns[attr] == "integer" && bounds.any?
+            draw = "#{param}_#{attr}"
+            draws[draw] = { "one_of" => ([0] + bounds.flat_map { [_1 - 1, _1, _1 + 1] }).select { _1 >= 0 }.uniq.sort }
+            overrides[param][attr] = "%{#{draw}}"
+            basis << "#{param}.#{attr} around #{bounds.join(", ")}"
+          elsif columns[attr] == "datetime" && !attr.match?(/\A(created|updated)_at\z/)
+            draw = "#{param}_#{attr}"
+            draws[draw] = { "booleans" => true }
+            overrides[param][attr] = "(%{#{draw}} ? Time.utc(2026, 3, 1, 12) : nil)"
+            basis << "#{param}.#{attr} set and unset"
+          elsif attr.end_with?("?") && col.is_a?(String) && columns[col] == "datetime"
+            draw = "#{param}_#{col}"
+            draws[draw] = { "booleans" => true }
+            overrides[param][col] = "(%{#{draw}} ? Time.utc(2026, 3, 1, 12) : nil)"
+            basis << "#{param}.#{attr} both ways"
+          end
+        end
+        dates = columns.select { _2 == "date" }.keys
+        read = dates & reads.fetch(param, []).map(&:first)
+        next unless kwargs.value?(:date) && (anchor = read.first || dates.first)
+
+        overrides[param][anchor] = ANCHOR
+        @anchored ||= [param, anchor]
+      end
+      world = world_for(node, records, draws, overrides, basis)
+      offsets = OFFSETS | literals(node).flat_map { [_1, _1 + 1] }.select { _1.abs <= 40 }
+      kwargs.each_key do |key|
+        next unless kwargs[key] == :date
+
+        draws["#{key}_days"] = { "one_of" => offsets.sort }
+        kwargs[key] = { "ruby" => "#{ANCHOR} + %{#{key}_days}" }
+        basis << (@anchored ? "#{key}: around #{@anchored.join(".")}" : "#{key}: around #{ANCHOR}")
+      end
+      factory_args = ->(param) do
+        o = overrides[param]
+        o.empty? ? "" : ", #{o.map { "#{_1}: #{_2}" }.join(", ")}"
+      end
+      create = ->(param) { "FactoryBot.create(:#{records[param]}#{factory_args.(param)})" }
+      # A drafted world makes each record once, in `before`, so the record
+      # the world links to is the one the method receives.
+      fill = lambda do |v|
+        next v unless v.is_a?(Hash) && v["factory"]
+
+        { "ruby" => world ? "@#{v["param"]}#{v["suffix"]}" : "#{create.(v["param"])}#{v["suffix"]}" }
+      end
+      entry = { "receiver" => fill.(receiver), "args" => args.map(&fill), "kwargs" => kwargs.transform_values(&fill) }.compact
+      if world
+        made = records.keys.map { "@#{_1} = #{create.(_1)}" }
+        entry = { "before" => { "ruby" => (made + [world]).join("; ") } }.merge(entry)
+      end
+      entry.delete("kwargs") if entry["kwargs"].empty?
+      data = if draws.empty?
+               { "inputs" => [entry.merge("note" => "drafted by holdfast")] }
+             else
+               product = draws.values.map { (_1["one_of"] || [true, false]).size }.inject(1, :*)
+               { "generate" => [entry.merge("draws" => draws, "cases" => [product, 120].min, "note" => "drafted by holdfast")] }
+             end
+      Result.new(path: self.class.path(@change.root, @target.name), data:, holes:, basis:)
+    end
+
+    def write(result)
+      FileUtils.mkdir_p(File.dirname(result.path))
+      File.write(result.path, "#{JSON.pretty_generate(result.data)}\n")
+    end
+
+private
+
+# The changed value a caller reads through a scope (Hold.open reads
+# OPEN_STATUSES as `status`): one record of the scope's model, linked to
+# each record argument it belongs to, with that column drawn over every
+# value either side's list holds, one value neither holds, and no record
+# at all. A method that tests the constant on an argument's attribute
+# (`OPEN_STATUSES.include?(hold.status)`) gets that attribute drawn.
+def world_for(node, records, draws, overrides, basis)
+  r = @target.reads or return nil
+  values = Array(r["values"]) + Array(r["outside"])
+  return nil if values.empty?
+
+  const = r["constant"].to_s.split("::").last
+  walk(node) do |n|
+    next unless n.is_a?(Prism::CallNode) && n.name == :include? && const_name(n.receiver) == const && n.arguments
+
+    pa = param_attr(n.arguments.arguments.first, records.keys) or next
+    draw = "#{pa[0]}_#{pa[1]}"
+    draws[draw] = { "one_of" => values }
+    overrides[pa[0]][pa[1]] = "%{#{draw}}"
+    basis << "#{pa[0]}.#{pa[1]} over #{r["constant"]} on both sides"
+  end
+  return nil unless r["model"] && r["column"]
+
+  factory = Holdfast.snake(r["model"].split("::").last)
+  return nil unless factories.include?(factory)
+
+  owners = file_text(model_file(r["model"])).scan(/^\s*belongs_to\s+:(\w+)/).flatten
+  links = records.select { |param, f| param != "self" && owners.include?(f) }.map { |param, f| "#{f}: @#{param}" }
+  draw = "#{factory}_#{r["column"]}"
+  draws[draw] = { "one_of" => values + ["none"] }
+  basis << "a #{r["model"]} whose #{r["column"]} is drawn over #{r["constant"]} (read through #{r["via"] || @target.name})"
+  "FactoryBot.create(:#{factory}#{links.map { ", #{_1}" }.join}, #{r["column"]}: %{#{draw}}) unless %{#{draw}} == \"none\""
+end
+
+def const_name(n) = n.is_a?(Prism::ConstantReadNode) || n.is_a?(Prism::ConstantPathNode) ? n.name.to_s : nil
+
+def model_file(model) = "app/models/#{model.split("::").map { Holdfast.snake(_1) }.join("/")}.rb"
+
+def scope_node(source)
+  call = Prism.parse(source.to_s).value.statements&.body&.first
+  return nil unless call.is_a?(Prism::CallNode) && call.name == :scope && call.arguments
+
+  call.arguments.arguments[1].then { _1.is_a?(Prism::LambdaNode) ? _1 : call.block }
+end
+
+    def method_node(source, name)
+      found = nil
+      walk(Prism.parse(source.to_s).value) { found ||= _1 if _1.is_a?(Prism::DefNode) && _1.name.to_s == name }
+      found
+    end
+
+    def walk(node, &block)
+      return unless node
+
+      yield node
+      node.compact_child_nodes.each { walk(_1, &block) }
+    end
+
+    def date_default?(src) = src.to_s.match?(/\A(Date\.(current|today)|Time\.(current|zone\.today))/)
+    def date_name?(name) = name.match?(/\A(on|date|day)\z|_on\z/)
+
+    def param_value(name, _default, records, holes)
+      stem = name.delete_suffix("_id")
+      # `request` names the one factory that ends with it (interlibrary_request).
+      factory = factories.include?(stem) ? stem : factories.grep(/_#{Regexp.escape(stem)}\z/).then { _1.size == 1 ? _1.first : nil }
+      if factory
+        records[stem] = factory
+        { "factory" => factory, "param" => stem, "suffix" => name.end_with?("_id") ? ".id" : nil }.compact
+      else
+        holes << name
+        { "fill" => "#{name}: a value the method takes" }
+      end
+    end
+
+    def receiver_for(const_name, kind, holes)
+      return nil if kind == "."
+
+      model = Holdfast.snake(const_name.split("::").last)
+      return { "ruby" => "FactoryBot.create(:#{model})" } if factories.include?(model) && model_class?(const_name)
+
+      if file_text(@target.file).match?(/^\s*module\s+#{Regexp.escape(const_name.split("::").last)}\b/) && !file_text(@target.file).match?(/^\s*class\s+#{Regexp.escape(const_name.split("::").last)}\b/)
+        return { "ruby" => "Object.new.extend(#{const_name})" }
+      end
+
+      init = method_node(file_text(@target.file), "initialize")
+      required = init && (Array(init.parameters&.requireds) + Array(init.parameters&.keywords).select { _1.is_a?(Prism::RequiredKeywordParameterNode) })
+      if required.nil? || required.empty?
+        { "ruby" => "#{const_name}.new" }
+      else
+        holes << "receiver"
+        { "fill" => "#{const_name}.new(#{required.map(&:name).join(", ")}): the receiver" }
+      end
+    end
+
+    def model_class?(const_name) = file_text(@target.file).match?(/class\s+#{const_name.split("::").last}\s*<\s*(ApplicationRecord|ActiveRecord::Base)/)
+
+    # param => [[attr, [bounds]]] for each `param.attr` the method calls,
+    # with the integer literals and constants a comparison sets it against.
+    def attribute_reads(node, params)
+      reads = Hash.new { |h, k| h[k] = [] }
+      walk(node) do |n|
+        next unless n.is_a?(Prism::CallNode)
+
+        if COMPARE.include?(n.name) && n.receiver && n.arguments&.arguments&.size == 1
+          [[n.receiver, n.arguments.arguments.first], [n.arguments.arguments.first, n.receiver]].each do |side, other|
+            next unless (pa = param_attr(side, params))
+
+            bound = integer_of(other)
+            reads[pa[0]] << [pa[1], bound ? [bound] : []]
+          end
+        elsif (pa = param_attr(n, params))
+          reads[pa[0]] << [pa[1], []]
+        end
+      end
+      reads.transform_values { |list| list.group_by(&:first).map { |attr, rows| [attr, rows.flat_map(&:last).uniq] } }
+    end
+
+    def param_attr(n, params)
+      return ["self", n.name.to_s] if params.include?("self") && n.is_a?(Prism::CallNode) && (n.receiver.nil? || n.receiver.is_a?(Prism::SelfNode)) && n.arguments.nil?
+      return nil unless n.is_a?(Prism::CallNode) && n.receiver.is_a?(Prism::LocalVariableReadNode) && params.include?(n.receiver.name.to_s)
+
+      [n.receiver.name.to_s, n.name.to_s]
+    end
+
+    def integer_of(n)
+      case n
+      when Prism::IntegerNode then n.value
+      when Prism::ConstantReadNode then constants[n.name.to_s]
+      end
+    end
+
+    def literals(node)
+      found = []
+      walk(node) do |n|
+        next unless n.is_a?(Prism::CallNode) && COMPARE.include?(n.name) && n.arguments&.arguments&.size == 1
+
+        [n.receiver, n.arguments.arguments.first].each { (v = integer_of(_1)) && found << v }
+      end
+      found.uniq
+    end
+
+    def constants = @constants ||= file_text(@target.file).scan(/^\s*([A-Z][A-Z0-9_]*)\s*=\s*(-?\d+)\s*$/).to_h { [_1, _2.to_i] }
+
+    def factories
+      @factories ||= git_files(%r{\A(spec|test)/(factories|support)/.*\.rb\z|\A(spec|test)/factories\.rb\z})
+                     .flat_map { file_text(_1).scan(/^\s*factory\s+:(\w+)/).flatten }.uniq
+    end
+
+    def columns_of(factory)
+      table = factory.sub(/y\z/, "ie").sub(/(s|sh|ch|x)\z/, '\1e') + "s"
+      block = file_text("db/schema.rb")[/create_table "#{table}".*?^  end/m].to_s
+      block.scan(/t\.(\w+)\s+"(\w+)"/).to_h { [_2, _1] }
+    end
+
+    def git_files(pattern) = Change.git(@change.root, "ls-tree", "-r", "--name-only", @rev).lines.map(&:strip).grep(pattern)
+
+    def file_text(path)
+      return "" unless path
+
+      @files ||= {}
+      @files[path] ||= (Open3.capture2("git", "show", "#{@rev}:#{path}", chdir: @change.root).then { |out, st| st.success? ? out : "" })
+    end
+  end
+end

data/lib/holdfast/drawn.rb

@@ -0,0 +1,186 @@
+module Holdfast
+  # What an input has to draw before a row may say clean: each value the
+  # change added or removed that the target can see (a member of a changed
+  # list or table constant it reads, a literal a changed line compares
+  # with), and each branch the change added to it. Tests that reach a line
+  # and agree say nothing about a value none of them drew: a scope that
+  # stopped selecting `in_transit` agrees on every hold that is not in
+  # transit.
+  module Drawn
+    # arm is set for a branch whose body shares the line with its condition
+    # (`return x if y`): every run of that line counts it, so only branch
+    # coverage, matched on the body's span, can tell whether the body ran.
+    Need = Data.define(:value, :file, :line, :why, :arm) do
+      def initialize(value:, file:, line:, why:, arm: nil) = super
+      def label = value ? value.inspect : "the branch at #{File.basename(file)}:#{line}"
+    end
+    COMPARE = %i[== != === include? in? eql?].freeze
+
+    # Qualified constant name => { "added" => [...], "removed" => [...] } for
+    # every list or table constant the change edits, adds or deletes.
+    def self.constants(change)
+      @constants ||= {}
+      @constants[[change.base, change.head]] ||= begin
+        files = Change.git(change.root, "diff", "--name-only", change.base, change.head, "--", "app", "lib").lines.map(&:strip).select { _1.end_with?(".rb") }
+        files.each_with_object({}) do |file, out|
+          old = members(show(change, change.base, file))
+          new = members(show(change, change.head, file))
+          (old.keys | new.keys).each do |name|
+            a, r = Array(new[name]) - Array(old[name]), Array(old[name]) - Array(new[name])
+            out[name] = { "added" => a, "removed" => r, "file" => file } if a.any? || r.any?
+          end
+        end
+      end
+    end
+
+    def self.show(change, rev, file)
+      out, status = Open3.capture2("git", "show", "#{rev}:#{file}", chdir: change.root, err: File::NULL)
+      status.success? ? out : ""
+    end
+
+    # NAME = %w[...] / [...] / { "k" => ... } (with or without .freeze), by
+    # its qualified name.
+    def self.members(source)
+      found = {}
+      walk = lambda do |node, nesting|
+        case node
+        when Prism::ClassNode, Prism::ModuleNode
+          inner = nesting + [node.constant_path.slice]
+          node.compact_child_nodes.each { walk.(_1, inner) }
+          return
+        when Prism::ConstantWriteNode
+          value = node.value
+          value = value.receiver if value.is_a?(Prism::CallNode) && value.name == :freeze && value.receiver
+          list = case value
+                 when Prism::ArrayNode then value.elements.filter_map { literal(_1) }
+                 when Prism::HashNode then value.elements.filter_map { literal(_1.key) if _1.is_a?(Prism::AssocNode) }
+                 end
+          found[(nesting + [node.name.to_s]).join("::")] = list if list&.any?
+        end
+        node.compact_child_nodes.each { walk.(_1, nesting) }
+      end
+      walk.(Prism.parse(source).value, [])
+      found
+    end
+
+    def self.literal(node) = node.is_a?(Prism::StringNode) || node.is_a?(Prism::SymbolNode) ? node.unescaped : nil
+
+    # The needs of one target: the changed constants it reads (by a changed
+    # line, or as the value a caller was walked from), the literals its
+    # changed lines compare with that the other side lacks, and the
+    # branches the change added inside it.
+    def self.needs(change, t, changed)
+      table = constants(change)
+      out = []
+      if (via = t.reads&.fetch("constant", nil)) && (entry = lookup(table, via))
+        out += members_needs(via, entry)
+      end
+      span = t.span || {}
+      head_lines = Array(changed.dig(t.file, "head")).select { |l| span["new_start"] && (span["new_start"]..span["new_end"]).cover?(l) }
+      base_lines = Array(changed.dig(t.file, "base")).select { |l| span["old_start"] && (span["old_start"]..span["old_end"]).cover?(l) }
+      head_src = show(change, change.head, t.file)
+      base_src = show(change, change.base, t.file)
+      head_ast = Prism.parse(head_src).value
+      base_ast = Prism.parse(base_src).value
+      [[head_ast, head_lines], [base_ast, base_lines]].each do |ast, lines|
+        nodes(ast) { |n| lines.include?(n.location.start_line) && (n.is_a?(Prism::ConstantReadNode) || n.is_a?(Prism::ConstantPathNode)) }
+          .each { |n| (entry = lookup(table, n.slice)) && (out += members_needs(n.slice, entry)) }
+      end
+      head_vals = compared(head_ast, head_lines)
+      base_vals = compared(base_ast, base_lines)
+      head_all = compared(head_ast, span["new_start"] ? (span["new_start"]..span["new_end"]).to_a : [])
+      base_all = compared(base_ast, span["old_start"] ? (span["old_start"]..span["old_end"]).to_a : [])
+      (head_vals - base_all).each { out << Need.new(value: _1, file: t.file, line: nil, why: "a changed line of #{t.name} compares with it") }
+      (base_vals - head_all).each { out << Need.new(value: _1, file: t.file, line: nil, why: "#{t.name} no longer compares with it") }
+      branches(head_ast, head_lines).each { |line, arm, text| out << Need.new(value: nil, file: t.file, line:, arm:, why: "the change adds `#{text}`") }
+      out.uniq { [_1.value, _1.line] }
+    end
+
+    def self.lookup(table, name)
+      return table[name] if table.key?(name)
+
+      hit = table.keys.select { _1 == name || _1.end_with?("::#{name.split("::").last}") && name.split("::").last == _1.split("::").last }
+      hit.size == 1 ? table[hit.first] : nil
+    end
+
+    def self.members_needs(name, entry)
+      entry["added"].map { Need.new(value: _1, file: entry["file"], line: nil, why: "#{name} adds it") } +
+        entry["removed"].map { Need.new(value: _1, file: entry["file"], line: nil, why: "#{name} drops it") }
+    end
+
+    # String and symbol literals in a comparison, a `when`, or an `in` on
+    # the given lines.
+    def self.compared(ast, lines)
+      return [] if lines.empty?
+
+      vals = []
+      nodes(ast) { lines.include?(_1.location.start_line) }.each do |n|
+        case n
+        when Prism::CallNode
+          next unless COMPARE.include?(n.name)
+
+          ([n.receiver] + Array(n.arguments&.arguments)).each do |x|
+            vals << literal(x) if literal(x)
+            vals += x.elements.filter_map { literal(_1) } if x.is_a?(Prism::ArrayNode)
+          end
+        when Prism::WhenNode then vals += n.conditions.filter_map { literal(_1) }
+        when Prism::InNode then vals << literal(n.pattern) if literal(n.pattern)
+        end
+      end
+      vals.compact.uniq
+    end
+
+    # Each if, unless, elsif, when or in that starts on a changed line,
+    # with the first line of its body: reaching it is drawing the branch. A
+    # body on the condition's own line also carries its span.
+    def self.branches(ast, lines)
+      nodes(ast) { |n| (n.is_a?(Prism::IfNode) || n.is_a?(Prism::UnlessNode) || n.is_a?(Prism::WhenNode) || n.is_a?(Prism::InNode)) && lines.include?(n.location.start_line) }.filter_map do |n|
+        body = n.statements&.body&.first or next
+        line = body.location.start_line
+        # An arm's start alone is ambiguous: the else arm of `x if y` starts where
+        # the whole expression does, so the arm is named by its start and end.
+        arm = (l = body.location; "#{l.start_line}:#{l.start_column}-#{l.end_line}:#{l.end_column}") if line == n.location.start_line && !n.is_a?(Prism::WhenNode)
+        [line, arm, n.slice.lines.first.strip[0, 60]]
+      end
+    end
+
+    def self.nodes(ast, &keep)
+      found = []
+      stack = [ast]
+      while (n = stack.pop)
+        found << n if keep.(n)
+        stack.concat(n.compact_child_nodes)
+      end
+      found
+    end
+
+    # A value counts as drawn when one reached test wrote it on both sides:
+    # the same input on base and head. Written on one side only, it came
+    # from the code under test, not from an input. A branch counts when a
+    # reached test ran its first body line on head, or, for a body on the
+    # condition's line, took that arm.
+    def self.missing(needs, outcomes, reach)
+      needs.reject do |need|
+        outcomes.any? do |o|
+          if need.value then sides_writing(reach, o, need.value).size == 2
+          elsif need.arm then Stages::Diff.ran(reach, o, "2").fetch(Stages::Diff::ARMS + need.file, []).include?(need.arm)
+          else Stages::Diff.ran(reach, o, "2").fetch(need.file, []).include?(need.line)
+          end
+        end
+      end
+    end
+
+    def self.sides_writing(reach, outcome, value) = %w[1 2].select { Array(reach.dig(outcome.source.path, _1, Stages::Diff::DREW)).include?(value) }
+
+    # "in_transit: written on base only by spec/services/member_merge_spec.rb"
+    def self.one_sided(needs, outcomes, reach)
+      needs.filter_map do |need|
+        next unless need.value
+
+        o = outcomes.find { sides_writing(reach, _1, need.value).size == 1 } or next
+        side = sides_writing(reach, o, need.value).first == "1" ? "base" : "head"
+        "#{need.label} was written on #{side} only, by the code that #{Stages::Diff.shown_path(o.source)} runs, and the tests still agree"
+      end
+    end
+  end
+end

data/lib/holdfast/harness.rb

@@ -0,0 +1,90 @@
+module Holdfast
+  # One run: read the record and the change, then run the stages the change
+  # calls for. The harness decides what runs from the change alone; the
+  # caller only adds evidence (tests, pin inputs) between runs.
+  #   change  select -> fill (inputs or drafts) -> diff -> fold, one row per target
+  #           (+ hunt over the changed areas with --sequences)
+  #   before  select the named targets -> fill and vary -> one row per target
+  #   hunt    nothing changed and nothing named: sequences over the whole app
+  module Harness
+    Result = Data.define(:change, :verdicts, :notes, :seconds)
+
+    def self.run(root, base:, named:, relearn: false, only: [], sequences: false, budget: nil, observe: false, intent: nil)
+      timings = {}
+      record = timed(timings, "record") { Record.load_or_learn(root, relearn:) }
+      change = Change.read(root, base_ref: base || record.base_branch, named:)
+      unless record.ok?
+        return Result.new(change:, notes: [], seconds: timings, verdicts: [
+          Verdict.of(target: "(all)", stage: "record", kind: "unchecked",
+                     reason: "project setup failed (#{record.failure}); see .holdfast/record.json steps",
+                     next_step: "fix the environment the failed step names, then holdfast run --learn")
+        ])
+      end
+
+      verdicts = []
+      notes = []
+      if change.mode == "hunt"
+        verdicts += timed(timings, "hunt") { Stages::Hunt.run(change, record, budget:) }
+      else
+        Tools.jitcatch!
+        selected = timed(timings, "select") { Stages::Select.run(change, record) }
+        targets = only.empty? ? selected.targets : selected.targets.select { only.include?(_1.name) }
+        notes += selected.notes + ["targets: #{targets.count(&:method?)} method(s), #{targets.count { _1.kind == "reader" }} reader(s)"]
+        verdicts += selected.verdicts
+        pins, gaps = timed(timings, "fill") { Stages::Fill.run(change, record, targets) }
+        if change.changed?
+          lines = Stages::Fold.changed_lines(change)
+          values = targets.flat_map { Drawn.needs(change, _1, lines) }.filter_map(&:value).uniq
+          diff = timed(timings, "diff") { Stages::Diff.run(change, record, targets, pins, values:) }
+          notes << "diff: #{diff.failure}" if diff.failure
+          verdicts += Stages::Fold.run(change, targets, diff, pins, gaps)
+          verdicts += timed(timings, "observe") { Stages::Observe.run(change, record, intent:, files: changed_files(change)) } if observe
+          verdicts += timed(timings, "sequences") { Stages::Hunt.run(change, record, budget:, files: changed_files(change)) } if sequences
+        else
+          verdicts += pins.flat_map { before_rows(change, _1) } + gaps.map { gap_row(_1) }
+        end
+      end
+      reach = verdicts.find { _1.target == "(hunt)" }
+      notes.unshift("#{reach.reason.include?("; 0 of ") ? "hunt" : "HUNT REACHED LITTLE"}: #{reach.reason}") if reach
+      notes << "sequences: not run; add --sequences before a pull request" if change.changed? && !sequences
+      Result.new(change:, verdicts: verdicts.sort_by { [_1.target == "(hunt)" ? -1 : KINDS.index(_1.kind), _1.stage == "caller" ? 0 : 1, _1.target] }, notes:, seconds: timings)
+    end
+
+    def self.changed_files(change) = Change.git(change.root, "diff", "--name-only", change.base, change.head, "--", "app").lines.map(&:strip)
+
+    def self.timed(timings, name)
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      yield
+    ensure
+      timings[name] = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started).round(1)
+    end
+
+    def self.before_rows(change, pins)
+      declared = pins.inputs.declared_errors
+      # An error the method raises itself (`raise Refused, ...`) is its
+      # behavior, and the pin holds it; only another error is a suspect.
+      own = ->(klass) { pins.target.source.to_s.match?(/raise\s+(#{Regexp.escape(klass)}|#{Regexp.escape(klass.split("::").last)})\b/) }
+      raised = pins.observed.select { _1["raises"] && !declared.include?(_1["raises"]) && !own.(_1["raises"]) }
+      details = Stages::Fold.pin_details(pins)
+      pins.observed.filter_map { _1["raises"] if _1["raises"] && own.(_1["raises"]) }.tally.each { |k, n| details << "#{n} input(s) raise #{k}, which the method raises itself; pinned" }
+      rows = raised.group_by { _1["raises"] }.map do |klass, same|
+        Verdict.of(target: pins.target.name, stage: "fill", kind: "bug_suspect",
+                   reason: "#{same.size} input(s) raised #{klass}: #{same.first["message"]}",
+                   evidence: details, next_step: "fix the code, or mark the input \"raises\": \"#{klass}\" in #{Stages::Fold.rel(pins.inputs.file)} if that error is the behavior")
+      end
+      ran = pins.observed.count { !_1["input_error"] }
+      kind = ran.zero? ? "unchecked" : "clean"
+      rows << Verdict.of(target: pins.target.name, stage: "fill", kind:,
+                         reason: ran.zero? ? "no input ran" : "pinned #{ran} input(s) at #{change.short(change.head)} by what each returns, raises and writes",
+                         evidence: details + pins.target.tests.first(3).map { "selected test: #{_1}" },
+                         scope: pins.dir.delete_prefix("#{change.root}/"),
+                         next_step: ran.zero? ? "fix the inputs the evidence names, then holdfast run" : "make the change, then holdfast run; these pins are compared on both sides")
+      rows
+    end
+
+    def self.gap_row(gap)
+      step = gap.draft ? "fill #{gap.draft.holes.join(", ")} in #{Stages::Fold.rel(gap.draft.path)}, copy it to .holdfast/evidence/, then holdfast run" : "write .holdfast/evidence/#{Holdfast.slug(gap.target.name)}.inputs.json, then holdfast run"
+      Verdict.of(target: gap.target.name, stage: "fill", kind: "unchecked", reason: "no pin: #{gap.reason}", next_step: step)
+    end
+  end
+end