hecks 3.5.0 → 3.6.0

data/lib/hecks/cli/project_glossary.rb

@@ -23,21 +23,31 @@ module Hecks
         domain_path  = argv[0] or abort usage
         chapter_name = argv[1] or abort usage
 
-        domain  = File.expand_path(domain_path, Dir.pwd)
+        written = write_glossary(File.expand_path(domain_path, Dir.pwd), chapter_name)
+
+        puts "wrote #{written.size} file(s):"
+        written.each { |path| puts "  #{path}" }
+      end
+
+      # @api private
+      # @return [Array<String>] the files written under the domain's `glossary/` folder
+      def write_glossary(domain, chapter_name)
         runtime = Hecks.boot(domain)
         chapter = runtime.registry.bluebook(chapter_name)
 
-        markings = runtime.registry.pending_privacy_markings.select do |marking|
-          marking[:domain].to_s.start_with?("#{chapter_name}::")
-        end
-
-        written = Projector.write(
-          Projector.call(:glossary, bluebook: chapter, options: { markings: markings }),
+        Projector.write(
+          Projector.call(:glossary, bluebook: chapter, options: { markings: markings_for(runtime, chapter_name) }),
           File.join(domain, "glossary"), as: :files
         )
+      end
 
-        puts "wrote #{written.size} file(s):"
-        written.each { |path| puts "  #{path}" }
+      # The privacy markings the deployment declared for fields of one chapter.
+      #
+      # @api private
+      def markings_for(runtime, chapter_name)
+        runtime.registry.pending_privacy_markings.select do |marking|
+          marking[:domain].to_s.start_with?("#{chapter_name}::")
+        end
       end
     end
   end

data/lib/hecks/cli/refresh_rspec_runtime_baseline.rb

@@ -25,6 +25,10 @@ module Hecks
       # into a committed file. Seconds can arrive in exponent form (`9.69e-05`).
       RUNTIME_LINE = %r{\A(?<file>spec/\S+_spec\.rb):(?<seconds>\d+(?:\.\d+)?(?:e-?\d+)?)\z}
 
+      # What a `--from-run` refresh works with: the checkout, the CI run, where its artifacts
+      # download to, and where progress goes.
+      Download = Struct.new(:root, :run_id, :dir, :out)
+
       module_function
 
       # Refreshes the baselines from a CI run or a local run.
@@ -110,24 +114,36 @@ module Hecks
         dir = File.join(root, "tmp/ci-runtime-#{run_id}")
         FileUtils.rm_rf(dir)
 
-        written = families(root).count do |prefix, family|
-          system("gh", "run", "download", run_id, "-R", REPO, "-p", "#{prefix}-*", "-D", dir,
-                 out: File::NULL, err: File::NULL)
-          logs = Dir[File.join(dir, "#{prefix}-*", "*.log")]
-          legs = logs.map { |path| File.basename(File.dirname(path)) }.uniq.size
-          if legs == family[:legs]
-            write_baseline(root, family[:baseline], baseline_lines(logs), out)
-            true
-          else
-            warn "skipping #{family[:baseline]}: run #{run_id} has #{legs} of #{family[:legs]} #{prefix}-* artifacts"
-            false
-          end
-        end
+        download = Download.new(root, run_id, dir, out)
+        written = families(root).count { |prefix, family| refresh_family(download, prefix, family) }
         return unless written.zero?
 
         abort "hecks refresh_runtime_baseline: run #{run_id} had no complete artifact family — nothing written"
       end
 
+      # Downloads one artifact family and writes its baseline when every leg uploaded a log.
+      #
+      # @api private
+      # @return [Boolean] whether the family was complete and written
+      def refresh_family(download, prefix, family)
+        logs = download_logs(download, prefix)
+        legs = logs.map { |path| File.basename(File.dirname(path)) }.uniq.size
+        complete = legs == family[:legs]
+        if complete
+          write_baseline(download.root, family[:baseline], baseline_lines(logs), download.out)
+        else
+          warn "skipping #{family[:baseline]}: run #{download.run_id} has #{legs} of #{family[:legs]} #{prefix}-* artifacts"
+        end
+        complete
+      end
+
+      # @api private
+      def download_logs(download, prefix)
+        system("gh", "run", "download", download.run_id, "-R", REPO, "-p", "#{prefix}-*", "-D", download.dir,
+               out: File::NULL, err: File::NULL)
+        Dir[File.join(download.dir, "#{prefix}-*", "*.log")]
+      end
+
       # @param root [String] the checkout
       # @param workers [String] how many `parallel_rspec` workers to time with
       # @param out [IO] where what was written goes

data/lib/hecks/cli/release.rb

@@ -15,6 +15,16 @@ module Hecks
       DEFAULT_FLAGS = { dry_run: false, gem_only: false, npm_only: false, npm_local: false,
                         no_wait: false, yes: false }.freeze
 
+      # Each flag's switch and its help line, in the order the usage lists them.
+      FLAG_HELP = {
+        dry_run:   ["--dry-run", "run every check and build; tag, push and publish nothing"],
+        gem_only:  ["--gem-only", "publish the gem only"],
+        npm_only:  ["--npm-only", "skip the gem: wait for CI's publish, or with --npm-local publish from here"],
+        npm_local: ["--npm-local", "publish @hecks/client from this machine (first publish, or CI is down)"],
+        no_wait:   ["--no-wait", "do not wait for CI's publish to reach npm"],
+        yes:       ["--yes", "answer the confirmations yes"]
+      }.freeze
+
       module_function
 
       # Parses the flags and runs the release.
@@ -25,21 +35,27 @@ module Hecks
       def call(argv, root:)
         argv = argv.dup
         flags = DEFAULT_FLAGS.dup
-        parser = parser_for(flags)
-        begin
-          parser.parse!(argv)
-          raise OptionParser::InvalidArgument, argv.join(" ") unless argv.empty?
+        options, status = parse_flags(parser_for(flags), argv, flags)
+        return status unless options
 
-          return 0 if flags.delete(:help)
+        Hecks::Release::Runner.new(root: root, options: options).call
+      end
 
-          options = Hecks::Release::Runner::Options.new(**flags)
-        rescue OptionParser::ParseError, ArgumentError => e
-          warn "hecks publish: #{e.message}"
-          warn parser
-          return 2
-        end
+      # Reads the flags into the run's options.
+      #
+      # @api private
+      # @return [Array(Hecks::Release::Runner::Options, nil), Array(nil, Integer)] the options
+      #   to run with, or no options and the exit status to stop with (0 for help, 2 for a bad flag)
+      def parse_flags(parser, argv, flags)
+        parser.parse!(argv)
+        raise OptionParser::InvalidArgument, argv.join(" ") unless argv.empty?
+        return [nil, 0] if flags.delete(:help)
 
-        Hecks::Release::Runner.new(root: root, options: options).call
+        [Hecks::Release::Runner::Options.new(**flags), nil]
+      rescue OptionParser::ParseError, ArgumentError => e
+        warn "hecks publish: #{e.message}"
+        warn parser
+        [nil, 2]
       end
 
       # @param flags [Hash{Symbol => Boolean}] filled in as the parser reads each flag
@@ -49,16 +65,7 @@ module Hecks
           opts.banner = "Usage: hecks publish [--dry-run] [--gem-only | --npm-only] [--npm-local | --no-wait] [--yes]"
           opts.separator("Tags the merged release commit, publishes the gem, and gets @hecks/client published.")
           opts.separator("By default CI publishes the client from the tag and this waits for it.")
-          opts.on("--dry-run", "run every check and build; tag, push and publish nothing") { flags[:dry_run] = true }
-          opts.on("--gem-only", "publish the gem only") { flags[:gem_only] = true }
-          opts.on("--npm-only", "skip the gem: wait for CI's publish, or with --npm-local publish from here") do
-            flags[:npm_only] = true
-          end
-          opts.on("--npm-local", "publish @hecks/client from this machine (first publish, or CI is down)") do
-            flags[:npm_local] = true
-          end
-          opts.on("--no-wait", "do not wait for CI's publish to reach npm") { flags[:no_wait] = true }
-          opts.on("--yes", "answer the confirmations yes") { flags[:yes] = true }
+          FLAG_HELP.each { |key, (switch, help)| opts.on(switch, help) { flags[key] = true } }
           opts.on("--help", "print this usage") do
             puts opts
             flags[:help] = true

data/lib/hecks/cli/release_gem.rb

@@ -25,21 +25,27 @@ module Hecks
       def call(root:, commands: nil, out: $stdout, err: $stderr, version: Hecks::VERSION)
         Dir.chdir(root) do
           commands ||= Hecks::Release::Runner::Commands.new
-          registry = Hecks::Adapters::Codebase::GemRegistry.new(root: root, commands: commands)
           refusal = refusal_for(root, commands, version)
           if refusal
             err.puts refusal
             return 1
           end
 
-          out.puts "Building and pushing hecks-#{version}.gem to rubygems.org " \
-                   "(1Password will prompt for Touch ID)..."
-          registry.push!(version)
-          out.puts "Released hecks #{version}."
-          0
+          push(root, commands, version, out)
         end
       end
 
+      # @api private
+      # @return [Integer] 0 once pushed
+      def push(root, commands, version, out)
+        registry = Hecks::Adapters::Codebase::GemRegistry.new(root: root, commands: commands)
+        out.puts "Building and pushing hecks-#{version}.gem to rubygems.org " \
+                 "(1Password will prompt for Touch ID)..."
+        registry.push!(version)
+        out.puts "Released hecks #{version}."
+        0
+      end
+
       # @param root [String] the repository root
       # @param commands [#run!, #capture] runs the child commands
       # @param version [String] the version being released

data/lib/hecks/cli/rspec_io_parallel_files.rb

@@ -18,6 +18,10 @@ module Hecks
     #
     #   hecks list_io_parallel_specs '<exclude-pattern regex>' -- --tag io --tag ~fuzzing
     module RspecIoParallelFiles
+      # The parsed command line: the mode flag and its list path, the exclude pattern, the RSpec
+      # tag arguments, the checkout, and the two streams the command writes to.
+      Request = Struct.new(:mode, :list_path, :exclude_arg, :tag_args, :root, :out, :err)
+
       module_function
 
       # Lists the matching files, writes them, or checks a committed list.
@@ -31,23 +35,50 @@ module Hecks
       # @raise [SystemExit] on a bad command line, an empty candidate set, a failed dry run, or a
       #   stale committed list
       def call(argv, root: Dir.pwd, out: $stdout, err: $stderr)
+        request = parse_request(argv, root, out, err)
+        candidates = candidate_files(request)
+        files, example_count = matching_files(candidates, request.tag_args, root, err)
+        err.puts "hecks list_io_parallel_specs: #{files.size} of #{candidates.size} candidate files carry a " \
+                 "matching example (#{example_count} examples total) under `#{request.tag_args.join(" ")}`"
+        deliver(request, files)
+        0
+      end
+
+      # @param argv [Array<String>] the command line, as `call` takes it
+      # @param root [String] the checkout
+      # @param out [IO] where the list goes when neither flag is given
+      # @param err [IO] where the tally and any staleness go
+      # @return [Request] the command line, parsed
+      # @raise [SystemExit] on a bad command line
+      def parse_request(argv, root, out, err)
         argv = argv.dup
         mode, list_path = argv.shift(2) if %w[--check --write].include?(argv.first)
         abort "hecks list_io_parallel_specs: #{mode} needs a file path" if mode && list_path.nil?
 
         exclude_arg, tag_args = parse(argv)
-        candidates = Dir.glob("spec/**/*_spec.rb", base: root).grep_v(Regexp.new(exclude_arg)).sort
+        Request.new(mode, list_path, exclude_arg, tag_args, root, out, err)
+      end
+
+      # @param request [Request] the parsed command line
+      # @return [Array<String>] the spec files left after the exclude pattern, sorted
+      # @raise [SystemExit] when there are none
+      def candidate_files(request)
+        candidates = Dir.glob("spec/**/*_spec.rb", base: request.root).grep_v(Regexp.new(request.exclude_arg)).sort
         refuse_empty_candidates(candidates)
-        files, example_count = matching_files(candidates, tag_args, root, err)
-        err.puts "hecks list_io_parallel_specs: #{files.size} of #{candidates.size} candidate files carry a " \
-                 "matching example (#{example_count} examples total) under `#{tag_args.join(' ')}`"
+        candidates
+      end
 
-        case mode
-        when "--write" then File.write(File.expand_path(list_path, root), "#{files.join("\n")}\n")
-        when "--check" then check(files, File.expand_path(list_path, root), list_path, exclude_arg, tag_args, err)
-        else out.puts files
+      # Writes the list, checks it against the committed one, or prints it.
+      #
+      # @param request [Request] the parsed command line
+      # @param files [Array<String>] the files that carry a matching example
+      # @return [void]
+      def deliver(request, files)
+        case request.mode
+        when "--write" then File.write(File.expand_path(request.list_path, request.root), "#{files.join("\n")}\n")
+        when "--check" then check(files, request)
+        else request.out.puts files
         end
-        0
       end
 
       # @param argv [Array<String>] the exclude pattern, `--`, and the tag arguments
@@ -85,45 +116,71 @@ module Hecks
       #   examples matched
       # @raise [SystemExit] when the dry run fails, prints no JSON, or matches nothing
       def matching_files(candidates, tag_args, root, err)
+        examples = dry_run_examples(candidates, tag_args, root, err)
+        files = examples.map { |e| e.fetch("file_path").delete_prefix("./") }.uniq.sort
+        return [files, examples.size] unless files.empty?
+
+        abort "hecks list_io_parallel_specs: #{candidates.size} candidate files, but the dry run matched ZERO " \
+              "examples under `#{tag_args.join(" ")}` — that's almost certainly a broken tag filter, not a " \
+              "real empty set. Refusing to silently hand parallel_rspec nothing to run."
+      end
+
+      # @param candidates [Array<String>] the spec files to ask about
+      # @param tag_args [Array<String>] the RSpec tag arguments
+      # @param root [String] the directory the dry run runs in
+      # @param err [IO] where a failed run's stderr goes
+      # @return [Array<Hash>] the dry run's examples
+      # @raise [SystemExit] when the dry run fails or prints no JSON
+      def dry_run_examples(candidates, tag_args, root, err)
         command = ["bundle", "exec", "rspec", "--dry-run", *tag_args, "--format", "json", *candidates]
         stdout, stderr, status = Open3.capture3(*command, chdir: root)
-        unless status.success?
-          err.puts stderr
-          abort "hecks list_io_parallel_specs: `#{command.join(' ')}` exited #{status.exitstatus} — " \
-                "see stderr above. Refusing to guess a file list from a failed dry run."
-        end
+        refuse_failed_dry_run(command, status, stderr, err) unless status.success?
 
         start = stdout.index('{"version"')
         abort "hecks list_io_parallel_specs: couldn't find RSpec's JSON output in the dry-run's stdout:\n#{stdout}" unless start
 
-        examples = JSON.parse(stdout[start..])["examples"] || []
-        files = examples.map { |e| e.fetch("file_path").sub(%r{\A\./}, "") }.uniq.sort
-        return [files, examples.size] unless files.empty?
+        JSON.parse(stdout[start..])["examples"] || []
+      end
 
-        abort "hecks list_io_parallel_specs: #{candidates.size} candidate files, but the dry run matched ZERO " \
-              "examples under `#{tag_args.join(' ')}` — that's almost certainly a broken tag filter, not a " \
-              "real empty set. Refusing to silently hand parallel_rspec nothing to run."
+      # @param command [Array<String>] the dry-run command line
+      # @param status [Process::Status] the failed run's status
+      # @param stderr [String] what the run wrote to stderr
+      # @param err [IO] where the stderr goes
+      # @return [void]
+      # @raise [SystemExit] always
+      def refuse_failed_dry_run(command, status, stderr, err)
+        err.puts stderr
+        abort "hecks list_io_parallel_specs: `#{command.join(" ")}` exited #{status.exitstatus} — " \
+              "see stderr above. Refusing to guess a file list from a failed dry run."
       end
 
       # @param files [Array<String>] the files that carry a matching example
-      # @param path [String] the committed list's absolute path
-      # @param shown [String] the path as the person typed it
-      # @param exclude_arg [String] the exclude pattern, for the refresh command
-      # @param tag_args [Array<String>] the tag arguments, for the refresh command
-      # @param err [IO] where the difference goes
+      # @param request [Request] the parsed command line: its list path is the committed list
       # @return [void]
       # @raise [SystemExit] when the committed list differs
-      def check(files, path, shown, exclude_arg, tag_args, err)
+      def check(files, request)
+        path = File.expand_path(request.list_path, request.root)
         committed = File.exist?(path) ? File.readlines(path, chomp: true).reject(&:empty?) : []
         missing = files - committed
         stale = committed - files
         return if missing.empty? && stale.empty?
 
-        err.puts "#{shown} is out of date."
-        err.puts named("carries a matching example but is not listed (would never run in the shards)", missing) if missing.any?
-        err.puts named("listed but carries no matching example any more", stale) if stale.any?
+        report_stale(request, missing, stale)
+      end
+
+      # @param request [Request] the parsed command line
+      # @param missing [Array<String>] files that carry a matching example but are not listed
+      # @param stale [Array<String>] files listed that carry none
+      # @return [void]
+      # @raise [SystemExit] always, with the refresh command
+      def report_stale(request, missing, stale)
+        shown = request.list_path
+        request.err.puts "#{shown} is out of date."
+        unlisted = "carries a matching example but is not listed (would never run in the shards)"
+        request.err.puts named(unlisted, missing) if missing.any?
+        request.err.puts named("listed but carries no matching example any more", stale) if stale.any?
         abort "Refresh it and commit the result:\n  " \
-              "hecks list_io_parallel_specs --write #{shown} '#{exclude_arg}' -- #{tag_args.join(' ')}"
+              "hecks list_io_parallel_specs --write #{shown} '#{request.exclude_arg}' -- #{request.tag_args.join(" ")}"
       end
 
       # @param heading [String] what the paths have in common

data/lib/hecks/cli/rspec_shard_files.rb

@@ -25,6 +25,20 @@ module Hecks
       # @return [Integer] the exit status, 0 once printed
       # @raise [SystemExit] on missing or out-of-range arguments, or when there are no spec files
       def call(argv, root: Dir.pwd, out: $stdout, err: $stderr)
+        group, num_groups, runtime_log = parse_group(argv)
+        files = spec_files(root)
+
+        groups = Dir.chdir(root) { groups_of(files, num_groups, runtime_log && File.expand_path(runtime_log, root)) }
+        selected = groups[group - 1] || []
+        err.puts "hecks shard_specs: group #{group}/#{num_groups} has #{selected.size} of #{files.size} files"
+        out.puts selected
+        0
+      end
+
+      # @param argv [Array<String>] the group, the number of groups, and optionally a runtime log
+      # @return [Array(Integer, Integer, String)] the group, the number of groups, the log path
+      # @raise [SystemExit] on missing or out-of-range arguments
+      def parse_group(argv)
         group_arg, num_groups_arg, runtime_log = argv
         abort USAGE unless group_arg && num_groups_arg
 
@@ -32,17 +46,18 @@ module Hecks
         num_groups = Integer(num_groups_arg)
         abort "group must be between 1 and #{num_groups}, got #{group}" unless (1..num_groups).cover?(group)
 
+        [group, num_groups, runtime_log]
+      end
+
+      # @param root [String] the checkout whose `spec/` is split
+      # @return [Array<String>] the spec files, relative to the checkout
+      # @raise [SystemExit] when there are none
+      def spec_files(root)
         files = Dir.glob("spec/**/*_spec.rb", base: root)
-        if files.empty?
-          abort "hecks shard_specs: found ZERO spec files under spec/ — " \
-                "refusing to hand parallel_rspec nothing to run"
-        end
+        return files unless files.empty?
 
-        groups = Dir.chdir(root) { groups_of(files, num_groups, runtime_log && File.expand_path(runtime_log, root)) }
-        selected = groups[group - 1] || []
-        err.puts "hecks shard_specs: group #{group}/#{num_groups} has #{selected.size} of #{files.size} files"
-        out.puts selected
-        0
+        abort "hecks shard_specs: found ZERO spec files under spec/ — " \
+              "refusing to hand parallel_rspec nothing to run"
       end
 
       # Splits the files by recorded runtime, falling back to file size on a cold cache.

data/lib/hecks/cli/run.rb

@@ -3,6 +3,7 @@ require_relative "../../hecks"
 # ADR 0033 — a domain wired to PostgresEra needs this plugin loaded
 # explicitly; the era/lineage subsystem does not load with core.
 require_relative "../ports/persistence/plugins/era"
+require_relative "run_expectations"
 
 module Hecks
   module CLI
@@ -30,14 +31,26 @@ module Hecks
       def call(argv, program:)
         usage = "usage: #{program} [domain] <verb [name=value …] | script.json | - | '{\"steps\":[…]}'>"
         argv = argv.dup
-        here = Adapters::Folder.new.domain_root
-        domain = argv.first && File.directory?(argv.first) ? argv.shift : here
-        abort "no bluebook here — #{Dir.pwd} is not inside a domain. #{usage}" unless domain
+        domain = resolve_domain(argv, usage)
 
         # The command-line form answers unless the first argument is script-shaped,
         # in which case the step-list form takes over.
         cli_form(domain, argv, program) unless argv.first && script_shaped?(argv.first)
 
+        run_script(domain, argv, usage)
+      end
+
+      # @api private
+      def resolve_domain(argv, usage)
+        here = Adapters::Folder.new.domain_root
+        domain = argv.first && File.directory?(argv.first) ? argv.shift : here
+        abort "no bluebook here — #{Dir.pwd} is not inside a domain. #{usage}" unless domain
+
+        domain
+      end
+
+      # @api private
+      def run_script(domain, argv, usage)
         script = argv.first or abort usage
         document = parse(read_source(script))
         steps = document["steps"] or abort %(the script has no "steps" — #{usage})
@@ -99,12 +112,14 @@ module Hecks
           return
         end
 
-        verb = step["verb"]
-        begin
-          runtime.dispatch_flat(verb, args)
-        rescue StandardError => e
-          refusals << { verb: verb, error: e.message.to_s }
-        end
+        dispatch_verb(runtime, step["verb"], args, refusals)
+      end
+
+      # @api private
+      def dispatch_verb(runtime, verb, args, refusals)
+        runtime.dispatch_flat(verb, args)
+      rescue StandardError => e
+        refusals << { verb: verb, error: e.message.to_s }
       end
 
       # @api private
@@ -132,42 +147,8 @@ module Hecks
         end
       end
 
-      def unmet_expectations(expectations, report)
-        missing_events = Array(expectations["event_names"]) - report[:events].map { |event| event[:name] }
-        unmet = []
-        unmet << "matrix expected events missing: #{missing_events.join(', ')}" unless missing_events.empty?
-        unmet.concat(unmet_refusals(Array(expectations["refusals"]), report[:refusals]))
-        unmet.concat(unmet_instances(expectations["instances"] || {}, report[:instances]))
-      end
-
       # @api private
-      def unmet_refusals(expected_refusals, refusals)
-        expected_refusals.filter_map do |expected|
-          verb = expected.fetch("verb")
-          matched = refusals.any? do |refusal|
-            refusal[:verb] == verb && refusal[:error].include?(expected.fetch("includes"))
-          end
-          next if matched
-
-          # A refusal that changed its words is a different story from one that never
-          # happened, so the actual errors are printed beside the wanted one.
-          said = refusals.select { |refusal| refusal[:verb] == verb }.map { |refusal| refusal[:error] }.uniq
-          "matrix expected refusal missing: #{expected}\n  " \
-            "#{verb} actually refused with: #{said.empty? ? '(nothing — every attempt was accepted)' : said.inspect}"
-        end
-      end
-
-      # @api private
-      def unmet_instances(expected_instances, instances)
-        expected_instances.flat_map do |key, fields|
-          actual = instances[key] || {}
-          fields.filter_map do |field, value|
-            next if actual[field.to_sym] == value
-
-            "matrix expected #{key}.#{field}=#{value.inspect}, got #{actual[field.to_sym].inspect}"
-          end
-        end
-      end
+      def unmet_expectations(expectations, report) = RunExpectations.unmet(expectations, report)
     end
   end
 end

data/lib/hecks/cli/run_expectations.rb

@@ -0,0 +1,63 @@
+module Hecks
+  module CLI
+    # Judges a `hecks run` report against the script's `expectations`: the events that must
+    # appear, the refusals that must happen, and the instance fields that must hold.
+    module RunExpectations
+      module_function
+
+      # Every expectation the report does not meet, each as a sentence.
+      #
+      # @param expectations [Hash] the script's `"event_names"`, `"refusals"` and `"instances"`
+      # @param report [Hash] the run's `:events`, `:refusals` and `:instances`
+      # @return [Array<String>] one line per unmet expectation; empty when all are met
+      def unmet(expectations, report)
+        unmet_events(expectations, report) +
+          unmet_refusals(Array(expectations["refusals"]), report[:refusals]) +
+          unmet_instances(expectations["instances"] || {}, report[:instances])
+      end
+
+      # @api private
+      def unmet_events(expectations, report)
+        missing = Array(expectations["event_names"]) - report[:events].map { |event| event[:name] }
+        missing.empty? ? [] : ["matrix expected events missing: #{missing.join(", ")}"]
+      end
+
+      # @api private
+      def unmet_refusals(expected_refusals, refusals)
+        expected_refusals.filter_map { |expected| missing_refusal(expected, refusals) }
+      end
+
+      # A refusal that changed its words is a different story from one that never happened, so
+      # the actual errors are printed beside the wanted one.
+      #
+      # @api private
+      def missing_refusal(expected, refusals)
+        verb = expected.fetch("verb")
+        matched = refusals.any? do |refusal|
+          refusal[:verb] == verb && refusal[:error].include?(expected.fetch("includes"))
+        end
+        return if matched
+
+        said = refusals.select { |refusal| refusal[:verb] == verb }.map { |refusal| refusal[:error] }.uniq
+        "matrix expected refusal missing: #{expected}\n  #{verb} actually refused with: #{refusal_words(said)}"
+      end
+
+      # @api private
+      def refusal_words(said)
+        said.empty? ? "(nothing — every attempt was accepted)" : said.inspect
+      end
+
+      # @api private
+      def unmet_instances(expected_instances, instances)
+        expected_instances.flat_map do |key, fields|
+          actual = instances[key] || {}
+          fields.filter_map do |field, value|
+            next if actual[field.to_sym] == value
+
+            "matrix expected #{key}.#{field}=#{value.inspect}, got #{actual[field.to_sym].inspect}"
+          end
+        end
+      end
+    end
+  end
+end