hecks 3.10.0 → 3.12.0

data/lib/hecks/hecks/adapters/rehearsal/environment.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    module Rehearsal
+      # Which environment overlay (`environments/<name>.hecksagon` and `.world`) a rehearsal loads
+      # the subject under, and where that was decided.
+      #
+      # A rehearsal is about the era the production binds will mint, so it loads `production` when
+      # the domain has `environments/production.hecksagon`, the same default the Rust host build
+      # takes (`ProjectRust::DomainLoader#load_environment`). Most domains bind their aggregates
+      # to a database only in that overlay, so the base files alone have no `persisted_by` bind.
+      # The choice is a reported fact (`environment_loaded`), never a silent one.
+      class Environment
+        # Where the name came from, in the order they are tried.
+        SOURCES = %w[world HECKS_PROJECT_ENVIRONMENT default none].freeze
+
+        NONE_WORDS = "no environment overlay (none named in rehearsed_by or HECKS_PROJECT_ENVIRONMENT, " \
+                     "and no environments/production.hecksagon)"
+
+        # @!attribute [r] name
+        #   @return [String] the overlay's name, or `""` when none was loaded
+        # @!attribute [r] source
+        #   @return [String] one of `SOURCES`
+        # @!attribute [r] directory
+        #   @return [String] the bluebook directory the overlay is looked for under
+        attr_reader :name, :source, :directory
+
+        # @param declared [String, nil] what the world's `rehearsed_by` names (`environment "..."`)
+        # @param directory [String] the domain's bluebook directory
+        # @return [Environment] the choice: the world's, else `HECKS_PROJECT_ENVIRONMENT`, else
+        #   `production` when its overlay exists, else none
+        def self.resolve(declared, directory)
+          env = ENV.fetch("HECKS_PROJECT_ENVIRONMENT", "")
+          return new(declared, "world", directory) if declared && !declared.empty?
+          return new(env, "HECKS_PROJECT_ENVIRONMENT", directory) unless env.empty?
+          return new("production", "default", directory) if File.exist?(File.join(directory, "environments",
+                                                                                  "production.hecksagon"))
+
+          new("", "none", directory)
+        end
+
+        # @param name [String] the overlay's name
+        # @param source [String] one of `SOURCES`
+        # @param directory [String] the bluebook directory
+        def initialize(name, source, directory)
+          @name = name
+          @source = source
+          @directory = directory
+        end
+
+        # @return [String, nil] the name to load, nil when no overlay is wanted
+        def overlay = name.empty? ? nil : name
+
+        # @return [Boolean] whether the hecksagon file of this overlay exists
+        def overlay_file? = File.exist?(file)
+
+        # @return [String] the hecksagon file the overlay is looked for in
+        def file = File.join(directory, "environments", "#{name}.hecksagon")
+
+        # @return [Hash] the report fact, as the `Environment` value object holds it
+        def facts = { name: name, source: source, file: name.empty? ? "" : file }
+
+        # @return [String] what the overlay choice was, in words
+        def to_s
+          return NONE_WORDS if name.empty?
+
+          "environment #{name.inspect} (#{source}), file #{file} #{overlay_file? ? "found" : "NOT FOUND"}"
+        end
+
+        # The overlays the directory holds, so a refusal can say what could be chosen.
+        #
+        # @return [Array<String>] the names of `environments/*.hecksagon`
+        def available
+          Dir.glob(File.join(directory, "environments", "*.hecksagon")).map { |path| File.basename(path, ".hecksagon") }.sort
+        end
+
+        # @return [String] the overlays the directory holds, comma separated, or `none`
+        def available_words = available.empty? ? "none" : available.join(", ")
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/rehearsal/inquiry.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require_relative "subject"
+require_relative "memory_store"
+require_relative "postgres_store"
+require_relative "rust_audit"
+require_relative "audit_report"
+
+module Hecks
+  module Adapters
+    module Rehearsal
+      # The two questions a rehearsal asks of a subject and its data copy: where the shape stands
+      # (`survey`) and what the mint's audit would refuse (`examine`). Each answer is the facts, as
+      # the `RehearsalRun` commands take them.
+      class Inquiry
+        # What every rehearsal says it did not check.
+        ENGINE_LIMIT = { what: "the Rust host's mint audit",
+                         why:  "no validate_harness was built, so the Ruby audit alone ran over the rows" }.freeze
+
+        ALWAYS = [
+          { what: "the mint itself",
+            why:  "no era was written: the edge, its approval and the audit were evaluated, nothing minted" },
+          { what: "an edge's coverage of every change in the shape", why: "the mint checks it; the rehearsal does not yet" },
+          { what: "commands, policies and requests", why: "no traffic was run: only the stored data and the shape were read" },
+          { what: "data written after the copy was made", why: "a copy is a moment; the mint sees the data of its own" }
+        ].freeze
+
+        # @param subject [Subject] the loaded domain
+        # @param store [MemoryStore, PostgresStore] its prepared data copy
+        def initialize(subject, store)
+          @subject = subject
+          @store = store
+        end
+
+        # @return [Hash] `booted`, `host_version`, `store`, `mode`, `before`, `after`, `minting`,
+        #   the schema and environment that were read, and what the copy holds
+        def survey
+          shape.merge(environment_loaded: @subject.environment.facts, copy_note: plain(copy_note)).merge(copy_facts)
+        end
+
+        # @return [Hash] the edge facts, every refused row and its total, what was read, the parity
+        #   of the two engines, and what was not checked
+        def examine
+          edge = minting == "next" ? @subject.edge_from(before) : nil
+          refusals, after = edge ? @store.audit(@subject, edge) : [[], {}]
+          rust = RustAudit.call(@subject, after)
+          report = AuditReport.new(minting: minting, edge: edge, states: after, ruby: refusals, rust: rust)
+          answer(edge, report, (refusals + rust.violations).uniq, limits(edge, rust, report))
+        end
+
+        private
+
+        def plain(value) = { value: value }
+
+        def shape
+          { booted: flag(true), host_version: plain(Rehearsal.host_version), store: plain(@subject.declaration.kind),
+            mode: plain(@subject.declaration.mode), before: plain(before), after: plain(@subject.label),
+            minting: plain(minting) }
+        end
+
+        def answer(edge, report, refused, unchecked)
+          rows, total = Rows.from(refused)
+          edge_facts(edge).merge(refused_rows: rows, refusal_total: plain(total), parity: report.parity,
+                                 unchecked: unchecked).merge(report.facts)
+        end
+
+        def flag(value) = plain(value)
+
+        def census = @census ||= @store.census(@subject)
+
+        def copy_note
+          domain = @subject.bluebook.name
+          copy_empty? ? census.refusal(domain) : census.summary(domain)
+        end
+
+        def copy_empty?
+          census.empty? && @subject.declaration.mode != "empty" && @subject.bluebook.aggregates.any?
+        end
+
+        # The copy is empty when a dump or a readonly copy was asked for and it holds no row of a
+        # domain that declares aggregates; a mode of `empty` is asked to hold nothing.
+        def copy_facts = census.facts.merge(copy_empty: flag(copy_empty?))
+
+        def edge_facts(edge)
+          { minting: plain(minting), edge_present: flag(!edge.nil?), edge_approved: flag(approved?(edge)) }
+        end
+
+        def eras = @eras ||= @store.eras(@subject)
+
+        def latest = @latest ||= eras.last && @subject.held.named(eras.last)
+
+        def before = latest ? latest[:label] : "none"
+
+        def minting
+          return "first" unless latest
+
+          before == @subject.label ? "none" : "next"
+        end
+
+        def approved?(edge)
+          return false unless edge
+
+          !Translation::ApprovalFile.needs_rehearsal?(edge) ||
+            !Translation::ApprovalFile.applicable(@subject.directory, edge).nil?
+        end
+
+        def limits(edge, rust, report)
+          engine = rust.ran ? [] : [ENGINE_LIMIT]
+          engine + report.limits + ALWAYS + @store.limits(edge) + [journal_limit] + attached_limits +
+            (@subject.held.capable? ? [] : [binding_note])
+        end
+
+        # The audit reads the journal's latest entry of each record, never the head tables.
+        def journal_limit
+          { what: "the head tables",
+            why:  "the audit reads each record's latest journal entry (hecks_journal_<domain>_era_N), not the head " \
+                  "tables, so an edit to a head table is not seen. The copy holds #{census.head_rows} head rows " \
+                  "and #{census.journal_rows} journal records#{divergence}" }
+        end
+
+        def divergence
+          census.head_rows == census.journal_rows ? "." : ": they differ, and only the journal's are audited."
+        end
+
+        # The chapters loaded beside the domain's own (a vendored package): the host holds eras
+        # for the domain's own aggregates only, so theirs can neither mint nor be refused.
+        def attached_limits
+          names = @subject.held.registry.bluebooks.values.map(&:name) - [@subject.bluebook.name]
+          return [] if names.empty?
+
+          [{ what: "the shape of the attached chapters (#{names.sort.join(", ")})",
+             why:  "their aggregates have no era row of their own, so a change to them is not a mint" }]
+        end
+
+        def binding_note
+          { what: "that a boot would mint", why: "the domain is bound to #{@subject.held.adapter_name}, which holds no eras " \
+                                                 "in this environment" }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/rehearsal/memory_store.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "rows"
+require_relative "census"
+
+module Hecks
+  module Adapters
+    module Rehearsal
+      # The data copy as a JSON document the world names (`rows`): the eras held and the records
+      # stored under the latest, in that era's shape. Nothing is created or dropped, so specs and
+      # fixtures rehearse without a database.
+      #
+      # The document is `{"eras": [{"ordinal": 1, "held_text": "<bluebook text>"}], "records":
+      # {"Aggregate": {"id": {"field": ...}}}}`.
+      class MemoryStore
+        # @param declaration [Declaration] a `memory` declaration
+        def initialize(declaration)
+          path = declaration.rows
+          @document = path ? JSON.parse(File.read(path)) : {}
+        end
+
+        # @return [void]
+        def prepare! = nil
+
+        # @return [void] there is nothing to drop
+        def drop! = nil
+
+        # @param _subject [Subject] unused: the document holds its own eras
+        # @return [Array<Hash>] the eras, `ordinal` and `held_text`
+        def eras(_subject)
+          Array(@document["eras"]).map { |era| { ordinal: era["ordinal"], held_text: era["held_text"] } }
+        end
+
+        # What the document holds: it keeps the latest state of each record only, so the head and
+        # the journal counts are the same number.
+        #
+        # @param subject [Subject] the loaded domain
+        # @return [Census] the counts
+        def census(subject)
+          counts = subject.bluebook.aggregates.map do |aggregate|
+            held = records(aggregate.name).size
+            Census::Count.new(aggregate: aggregate.name, head: held, journal: held)
+          end
+          Census.new(schema: "(memory document)", source: "memory", present: true, eras: eras(subject).size,
+                     journal_entries: counts.sum(&:journal), counts: counts)
+        end
+
+        # Runs the mint's audit over the stored records, translated through the edge in process.
+        #
+        # @param subject [Subject] the loaded domain
+        # @param edge [Bluebook::Translation] the edge leading to the shape
+        # @return [Array(Array<String>, Hash)] the audit's refusals, and the translated records
+        #   by aggregate name and id
+        def audit(subject, edge)
+          refusals = []
+          after = subject.bluebook.aggregates.to_h do |aggregate|
+            declared = edge.for_aggregate(aggregate.name)
+            before = records(declared&.was || aggregate.name)
+            translated = translate(aggregate, declared, before)
+            refusals.concat(Translation::Audit.check(aggregate: aggregate, declared: declared, before: before,
+                                                     after: translated).violations)
+            [aggregate.name, translated]
+          end
+          [refusals, after]
+        end
+
+        # @param edge [Bluebook::Translation] the edge
+        # @return [Array<Hash>] what memory cannot apply, as report limits
+        def limits(edge)
+          return [] unless edge && Translation::ApprovalFile.needs_rehearsal?(edge)
+
+          [{ what: "the edge's compute and rekey rules",
+             why:  "they are SQL, which only a postgres copy runs; memory leaves those fields as stored" }]
+        end
+
+        private
+
+        def records(name) = @document.dig("records", name.to_s) || {}
+
+        def translate(aggregate, declared, before)
+          lineage = Ports::Persistence::Lineage.from_declared(declared, aggregate.name)
+          return before unless lineage
+
+          before.to_h { |id, state| [id, lineage.translate(entry(id, state)).state] }
+        end
+
+        def entry(id, state)
+          Ports::Persistence::Entry.new(operation: "save", id: id, state: symbolise(state), mirrors: {})
+        end
+
+        def symbolise(state) = JSON.parse(JSON.generate(state), symbolize_names: true)
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/rehearsal/postgres_census.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require_relative "census"
+
+module Hecks
+  module Adapters
+    module Rehearsal
+      # Counts what a Postgres copy holds for the domain without creating anything: a plain
+      # connection, the schemas looked up before one is chosen, and counts over the relations that
+      # exist. A schema that is not in the copy is reported, never created.
+      class PostgresCensus
+        JOURNAL_LATEST = <<~SQL
+          SELECT aggregate, count(*) AS live FROM (
+            SELECT DISTINCT ON (aggregate, aggregate_id) aggregate, operation
+            FROM %<journal>s ORDER BY aggregate, aggregate_id, ordinal DESC
+          ) latest WHERE operation = 'save' GROUP BY aggregate
+        SQL
+
+        # @param url [String] the copy's database URL
+        # @param subject [Subject] the loaded domain
+        # @param candidates [Array<Array(String, String)>] schema and source, in the order tried
+        def initialize(url, subject, candidates)
+          @url = url
+          @subject = subject
+          @candidates = candidates
+        end
+
+        # @return [Census] the counts, in the first candidate schema that holds a lineage, else the
+        #   first that exists, else the first named
+        def read
+          db = PG.connect(@url)
+          present = schemas(db)
+          lineage = holders(db)
+          name, source = choose(present, lineage)
+          return absent(name, source, lineage) unless present.include?(name)
+
+          db.exec("SET search_path TO #{db.quote_ident(name)}")
+          counted(db, name, source, lineage - [name])
+        ensure
+          db&.close
+        end
+
+        private
+
+        def schemas(db) = db.exec("SELECT schema_name FROM information_schema.schemata").map { |row| row["schema_name"] }
+
+        def holders(db)
+          sql = "SELECT table_schema FROM information_schema.tables WHERE table_name = 'hecks_eras'"
+          db.exec(sql).map { |row| row["table_schema"] }.sort
+        end
+
+        def choose(present, lineage)
+          @candidates.find { |name, _| lineage.include?(name) } || @candidates.find { |name, _| present.include?(name) } ||
+            @candidates.first
+        end
+
+        def absent(name, source, lineage)
+          Census.new(schema: name, source: source, present: false, eras: 0, journal_entries: 0,
+                     counts: empty_counts, elsewhere: lineage)
+        end
+
+        def empty_counts = @subject.bluebook.aggregates.map { |a| Census::Count.new(aggregate: a.name, head: 0, journal: 0) }
+
+        def counted(db, name, source, elsewhere)
+          lineage = PostgresEra::Lineage.new(db, @subject.bluebook.name)
+          Census.new(schema: name, source: source, present: true, eras: eras(db), counts: counts(db, lineage),
+                     journal_entries: rows(db, lineage.journal), elsewhere: elsewhere)
+        end
+
+        def counts(db, lineage)
+          live = latest(db, lineage)
+          @subject.bluebook.aggregates.map do |aggregate|
+            Census::Count.new(aggregate: aggregate.name, head: rows(db, lineage.head_view(aggregate.storage_name)),
+                              journal: live.fetch(aggregate.storage_name, 0))
+          end
+        end
+
+        def eras(db)
+          return 0 unless relation?(db, "hecks_eras")
+
+          db.exec_params("SELECT count(*) FROM hecks_eras WHERE domain = $1", [@subject.bluebook.name])[0]["count"].to_i
+        end
+
+        def latest(db, lineage)
+          return {} unless relation?(db, lineage.journal)
+
+          db.exec(format(JOURNAL_LATEST, journal: db.quote_ident(lineage.journal))).to_h { |r| [r["aggregate"], r["live"].to_i] }
+        end
+
+        def rows(db, name)
+          relation?(db, name) ? db.exec("SELECT count(*) FROM #{db.quote_ident(name)}")[0]["count"].to_i : 0
+        rescue PG::Error
+          0
+        end
+
+        def relation?(db, name) = !db.exec_params("SELECT to_regclass($1) AS found", [db.quote_ident(name)])[0]["found"].nil?
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/rehearsal/postgres_reading.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "postgres_census"
+
+module Hecks
+  module Adapters
+    module Rehearsal
+      # What a `PostgresStore` reads from its database: the eras it holds and the mint's audit over
+      # the records under them. No table is provisioned and no era written; a copy somebody else
+      # made is read in a read-only session, and the database a run made is its own to touch.
+      #
+      # The schema is the world's `schema`, else `HECKS_SCHEMA`, else the one the domain's name
+      # gives (`Shop` is `shop`), else `public` when that holds the lineage. It is looked up
+      # before it is used, so a schema the copy does not have is reported and never created.
+      module PostgresReading
+        # @param subject [Subject] the loaded domain
+        # @return [Census] what the copy holds for the domain, counted once
+        def census(subject)
+          @census ||= PostgresCensus.new(url, subject, schema_candidates(subject)).read.tap do |found|
+            subject.held.read_schema(found.schema)
+          end
+        end
+
+        # @param subject [Subject] the loaded domain
+        # @return [Array<Hash>] the eras the database holds, none when it holds no lineage
+        def eras(subject)
+          return [] unless census(subject).present
+
+          reading(subject) { |lineage| subject.held.held_eras(lineage) }
+        end
+
+        # @param subject [Subject] the loaded domain
+        # @param _edge [Bluebook::Translation] the edge leading to the shape
+        # @return [Array(Array<String>, Hash)] what the audit's layers refuse over the stored
+        #   records, and the records as translated, by aggregate name and id
+        def audit(subject, _edge)
+          return [[], {}] unless census(subject).present
+
+          reading(subject) do |lineage|
+            finding = JournalStore::EdgeAudit.call(subject.held, lineage, subject.held.held_eras(lineage))
+            finding ? [finding.refusals, finding.after] : [[], {}]
+          end
+        end
+
+        # @param _edge [Bluebook::Translation] unused
+        # @return [Array<Hash>] none: a postgres copy runs the compiled rules itself
+        def limits(_edge) = []
+
+        private
+
+        def schema_candidates(subject)
+          return [[@declaration.schema, "world"]] if @declaration.schema
+          return [[ENV.fetch("HECKS_SCHEMA"), "HECKS_SCHEMA"]] if ENV.fetch("HECKS_SCHEMA", "") != ""
+
+          [[Naming.snake(subject.bluebook.name), "derived"], %w[public default]]
+        end
+
+        def reading(subject)
+          subject.held.read_from(url)
+          db = PostgresEra.connect_for(subject.bluebook.name, subject.held.settings)
+          db.exec("SET default_transaction_read_only = on") if @declaration.mode == "readonly_copy"
+          yield PostgresEra::Lineage.new(db, subject.bluebook.name)
+        ensure
+          db&.close
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/rehearsal/postgres_store.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "digest"
+require "open3"
+require "uri"
+require_relative "declaration"
+require_relative "postgres_reading"
+
+module Hecks
+  module Adapters
+    module Rehearsal
+      # The data copy as a throwaway database on the server the world's `connection_env` names.
+      #
+      # `empty` and `dump` create a database of this run's own (`hecks_rehearsal_<token>`) and
+      # restore the dump into it; `readonly_copy` reads a database somebody else made, as it is,
+      # in a read-only session, and never creates or drops one. A database is isolated, not a
+      # schema, because a dump carries its own schema names. The name derives from the run key, so
+      # every ask of one rehearsal reaches the same database and a dropped one is dropped once.
+      class PostgresStore
+        include PostgresReading
+
+        PREFIX = "hecks_rehearsal_"
+        NAME = /\A#{PREFIX}[0-9a-f]{16}\z/
+
+        # @param declaration [Declaration] a `postgres` declaration
+        # @param run [String] the rehearsal's key
+        # @param protected_databases [Array<String>] databases the domain's own world names
+        def initialize(declaration, run, protected_databases: [])
+          @declaration = declaration
+          @run = run
+          @protected = protected_databases
+        end
+
+        # @return [String] the database this rehearsal reads
+        def database_name
+          return URI.parse(server_url).path.delete_prefix("/") if @declaration.mode == "readonly_copy"
+
+          "#{PREFIX}#{Digest::SHA256.hexdigest(@run)[0, 16]}"
+        end
+
+        # Creates the database and restores the dump, or checks the copy is reachable. A failure
+        # leaves nothing behind.
+        #
+        # @return [void]
+        # @raise [Refused] if the server refuses, or the restore does
+        def prepare!
+          return reach_copy! if @declaration.mode == "readonly_copy"
+
+          discard!
+          admin { |db| db.exec("CREATE DATABASE #{db.quote_ident(database_name)}") }
+          restore! if @declaration.mode == "dump"
+        rescue Refused, PG::Error => e
+          discard!
+          raise e.is_a?(Refused) ? e : Refused.new(e.message.strip)
+        end
+
+        # Drops the throwaway database. A copy somebody else made is never dropped, and one the
+        # world asked to keep is refused here, so the run records why it stands.
+        #
+        # @return [void]
+        # @raise [Refused] if the world's `drop_after` is false and a database stands
+        def drop!
+          return if @declaration.mode == "readonly_copy" || !NAME.match?(database_name)
+          raise Refused, "kept #{database_name}: the world's drop_after is false" unless @declaration.drop_after
+
+          discard!
+        end
+
+        # @return [String] a URL for the database this rehearsal reads
+        def url
+          uri = URI.parse(server_url)
+          uri.path = "/#{database_name}"
+          uri.to_s
+        end
+
+        private
+
+        def discard!
+          return unless NAME.match?(database_name)
+
+          admin { |db| db.exec("DROP DATABASE IF EXISTS #{db.quote_ident(database_name)} WITH (FORCE)") }
+        rescue Refused, PG::Error
+          nil
+        end
+
+        def server_url
+          value = @declaration.connection
+          return value if value.match?(%r{\Apostgres(ql)?://})
+
+          raise Refused, "#{@declaration.connection_env} must hold a postgres:// URL"
+        end
+
+        def admin
+          require "pg"
+          db = PG.connect(server_url)
+          yield db
+        ensure
+          db&.close
+        end
+
+        def reach_copy!
+          raise Refused, "readonly_copy names a database the domain's own world persists to" if @protected.include?(url)
+
+          admin { |db| db.exec("SELECT 1") }
+        end
+
+        # argv arrays and PG* variables: no shell, and no password on a command line.
+        def restore!
+          file = @declaration.dump
+          raise Refused, "no such dump #{file.inspect}" unless File.file?(file)
+
+          _out, err, status = Open3.capture3(restore_env, *restore_argv(file))
+          raise Refused, "restoring the dump failed: #{err.strip.lines.first}" unless status.success?
+        end
+
+        def restore_argv(file)
+          return ["psql", "--no-psqlrc", "-v", "ON_ERROR_STOP=1", "-d", database_name, "-f", file] if file.end_with?(".sql")
+
+          ["pg_restore", "--no-owner", "--no-privileges", "-d", database_name, file]
+        end
+
+        # What the URL names, and nothing it leaves out: `postgres:///postgres` parses with an empty
+        # host, which would override a `PGHOST` the environment sets and send the restore to the
+        # local socket while the rest of the rehearsal reached the server by TCP.
+        def restore_env
+          uri = URI.parse(server_url)
+          { "PGHOST" => uri.host, "PGPORT" => uri.port&.to_s, "PGUSER" => uri.user, "PGPASSWORD" => uri.password }
+            .reject { |_name, value| value.to_s.empty? }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/rehearsal/rows.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    module Rehearsal
+      # The mint audit's refusals as report rows: `Aggregate#id`, the rule that refused, and the
+      # audit's own wording, capped, with the total of them all.
+      module Rows
+        # How many rows a report holds; the total counts the rest.
+        CAP = 50
+
+        ROW = /\A([^#:]+)#([^:]+): (.*)\z/m
+
+        module_function
+
+        # @param violations [Array<String>] the audit's refusals, `Aggregate#id: wording`
+        # @return [Array(Array<Hash>, Integer)] the first `CAP` rows, and how many there were
+        def from(violations)
+          [violations.first(CAP).map { |text| row(text) }, violations.size]
+        end
+
+        # @param text [String] one refusal
+        # @return [Hash] `aggregate`, `id`, `rule`, `wording`
+        def row(text)
+          match = ROW.match(text)
+          aggregate, id, wording = match ? match.captures : ["(edge)", "-", text]
+          { aggregate: aggregate, id: id, rule: rule(wording), wording: wording }
+        end
+
+        # @param wording [String] a refusal's words
+        # @return [String] `lifecycle`, `reference` or `value`
+        def rule(wording)
+          return "lifecycle" if wording.include?("lifecycle never reaches")
+          return "reference" if wording.include?("reference transform") || wording.include?("id set changed")
+
+          "value"
+        end
+      end
+    end
+  end
+end