hecks 4.0.0 → 6.0.0

data/lib/hecks/chapters.rb

@@ -1,147 +0,0 @@
-require_relative "naming"
-require_relative "framework"
-require_relative "runtime/registry"
-require_relative "bluebook/meta_validator"
-
-module Hecks
-  # The chapters the gem carries that a hecksagon can attach by name (ADR 0080): the language
-  # declared in itself, Expression, Tenancy, Deploy, Site, Tickets, Composer and QualityControl.
-  # Framework members stay in `Framework`; `table` and `attach!` find a name across both.
-  #
-  # A chapter is named by the `Hecks.bluebook "Name"` header of its files, and may span several.
-  # Beside its bluebook a chapter may carry what every hecksagon attaching it needs, whatever
-  # its store: `<snake_name>.ports.hecksagon` (the ports it declares, as a `Hecks.hecksagon`
-  # block that merges into the attaching one) and `adapters/*.adapter` (the adapters binding them).
-  module Chapters
-    # Where attachable chapters live, relative to `lib/hecks/`.
-    GLOBS = %w[language/**/*.bluebook grammar/expression.bluebook tenancy/bluebook/*.bluebook
-               deploy/bluebook/*.bluebook site/bluebook/*.bluebook tickets/bluebook/*.bluebook
-               composer/bluebook/*.bluebook quality_control/*.bluebook].freeze
-
-    # Every attachable chapter, by name, with the files that declare it.
-    #
-    # @return [Hash{String => Array<String>}] chapter name to its files' absolute paths, sorted
-    def self.index
-      @index ||= GLOBS.flat_map { |glob| Dir.glob(File.join(__dir__, glob)) }.sort
-                      .group_by { |path| chapter_name(path) }
-                      .reject { |name, _| name.nil? }
-                      .freeze
-    end
-
-    # Every chapter the gem carries, whichever module loads it: the one lookup table `attaches`
-    # finds a name in.
-    #
-    # @return [Hash{String => Array<String>}] chapter name to its files' absolute paths, the
-    #   framework members (`Framework.members`) and the attachable chapters (`index`) together
-    def self.table
-      Framework.members.transform_values { |path| [path] }.merge(index)
-    end
-
-    # Loads one gem chapter by name, found in `table`: a framework member through
-    # `Framework.load!`, any other chapter through `load!`.
-    #
-    # @param name [String, Symbol] the chapter's name, such as `"Governance"` or `"Deploy"`
-    # @return [Boolean, nil] true when this call loaded it, nil when it was already held
-    # @raise [Runtime::WiringError] if the gem carries no chapter of that name; the message
-    #   lists the known names and says how to attach a vendored package
-    def self.attach!(name)
-      key = name.to_s
-      return Framework.load!(key) if Framework.members.key?(key)
-      return load!(key) if index.key?(key)
-
-      raise Runtime::WiringError,
-            "attaches #{name.inspect}: the gem carries no chapter of that name — known: " \
-            "#{table.keys.sort.join(", ")}. To attach a vendored package, write " \
-            "`attaches #{name.to_s.inspect}, from: :vendor`"
-    end
-
-    # Loads a chapter's files into the current registry, unless it already holds the chapter.
-    #
-    # The files load together inside `MetaValidator.defer`, so a chapter spread over several files
-    # is judged once, whole. The chapter's ports file and adapters load after it, since a port
-    # names the chapter's aggregates.
-    #
-    # @param name [String] the chapter's name, such as `"Deploy"`
-    # @return [Boolean, nil] true when this call loaded the chapter, nil when it was already held
-    # @raise [Runtime::WiringError] if no attachable chapter has that name
-    def self.load!(name)
-      paths = chapter_paths(name)
-      registry = open_registry(name)
-      return refuse_own_chapter(registry, name.to_s) if registry.bluebook(name.to_s)
-
-      load_atomically(registry, name.to_s, paths)
-      true
-    end
-
-    # @return [Array<String>] the files of the named chapter
-    # @raise [Runtime::WiringError] if no attachable chapter has that name
-    def self.chapter_paths(name)
-      index.fetch(name.to_s) do
-        raise Runtime::WiringError,
-              "no attachable chapter named #{name.inspect} — known: #{index.keys.join(", ")}"
-      end
-    end
-
-    # @return [Runtime::Registry] the registry the current boot is loading into
-    # @raise [Runtime::WiringError] when no boot is open
-    def self.open_registry(name)
-      Hecks.current_registry or
-        raise Runtime::WiringError, "attaches #{name.to_s.inspect} outside a boot: no registry is open"
-    end
-
-    # Loads a chapter whole or not at all: a raise anywhere leaves the registry as it was, so a
-    # retry loads the chapter again instead of finding a half-built one already held.
-    def self.load_atomically(registry, name, paths)
-      before = { queued: Bluebook::MetaValidator.deferred_chapters.dup, ports: registry.ports.keys,
-                 adapters: registry.adapters.keys }
-      Bluebook::MetaValidator.defer { paths.each { |path| Kernel.load(path) } }
-      Bluebook::MetaValidator.judge_deferred!(registry)
-      load_wiring(name, paths)
-    rescue Exception # rubocop:disable Lint/RescueException -- rolls back, then re-raises
-      roll_back(registry, name, before)
-      raise
-    end
-
-    # Puts the registry back as `load_atomically` found it.
-    def self.roll_back(registry, name, before)
-      registry.forget_chapter(name)
-      Bluebook::MetaValidator.deferred_chapters.replace(before[:queued])
-      registry.ports.delete_if { |key, _| !before[:ports].include?(key) }
-      registry.adapters.delete_if { |key, _| !before[:adapters].include?(key) }
-    end
-    private_class_method :chapter_paths, :open_registry, :load_atomically, :roll_back
-
-    # Returns nil for a chapter this gem already loaded; raises for a chapter of the same name
-    # that a user's own file declared, which `attaches` would otherwise silently take for the
-    # gem's.
-    def self.refuse_own_chapter(registry, name)
-      foreign = Array(registry.bluebook_sources[name]).compact
-                                                      .reject { |path| File.expand_path(path).start_with?("#{__dir__}/") }
-      return if foreign.empty?
-
-      raise Runtime::WiringError,
-            "attaches #{name.inspect}, but a chapter named #{name.inspect} is already declared in " \
-            "#{foreign.join(", ")} — rename it, since the gem's own #{name} chapter cannot merge into it"
-    end
-    private_class_method :refuse_own_chapter
-
-    # Loads what a chapter ships beside its bluebook: its ports file, then its adapters.
-    #
-    # @param name [String] the chapter's name
-    # @param paths [Array<String>] the chapter's bluebook files
-    # @return [void]
-    def self.load_wiring(name, paths)
-      directory = File.dirname(paths.first)
-      ports     = File.join(directory, "#{Naming.snake(name)}.ports.hecksagon")
-      Kernel.load(ports) if File.file?(ports)
-      Dir.glob(File.join(directory, "adapters", "*.adapter")).each { |adapter| Kernel.load(adapter) }
-    end
-    private_class_method :load_wiring
-
-    # The name a file's `Hecks.bluebook "Name"` header declares, or nil for a file without one.
-    def self.chapter_name(path)
-      File.foreach(path) { |line| return Regexp.last_match(1) if line =~ /\A\s*Hecks\.bluebook\s+"([^"]+)"/ }
-      nil
-    end
-  end
-end

data/lib/hecks/gate/stages.yml

@@ -1,234 +0,0 @@
-# The checks a stage runs before its change is let through. `hecks gate <stage>` reads this file and
-# the git pre-push hook calls it, so the list of checks lives here and nowhere else.
-#
-# A check is one command run from the repository root, all of a stage's checks at once:
-#   id       the name it is reported and selected by (`only=a,b`)
-#   title    the heading its output is printed under
-#   run      the program and its arguments; `{workers}` is half the machine's cores, at least one
-#   blocked  what a red check means and what to do about it
-#
-# `env` is set only where the caller has not set it: a push check has no use for the Hecks
-# domain's database, so it runs on Memory, as a pull-request run does in CI.
-#
-# A check a second stage repeats is written once, under an anchor (`&name`), and aliased
-# (`*name`) where the other stage takes it, so the two stages cannot drift apart.
-#
-# The `ci` stage is the checks the CI workflow `ci-checks.yml` holds. Each of its steps runs one
-# job's checks with `hecks gate_run.gate stage=ci only=<ids> --wait`, so the commands live here and
-# the workflow keeps only which job runs which ids and what each step is called;
-# spec/gate_ci_stage_spec.rb pins that every check is run by exactly one step. Select checks
-# with `only=`: several of them write generated files and compare, so the stage is not meant to
-# run whole in one checkout.
-pre_push:
-  # HECKS_PROCESS_SPECS keeps the examples tagged `process` (they start child processes, so a plain
-  # `rspec` leaves them out) in the suite this stage runs.
-  env:
-    HECKS_ENVIRONMENT: memory
-    HECKS_PROCESS_SPECS: "1"
-  checks:
-    - id: rspec
-      title: rspec (parallel)
-      run:
-        - sh
-        - -ec
-        - |
-          # Workers are grouped by this machine's own last timings, kept under the git directory
-          # (shared by every worktree, never committed). CI's committed baseline leaves out the io
-          # specs this run includes, so it only seeds the first run; each run then rewrites the log.
-          log="$(git rev-parse --git-common-dir)/hecks_rspec_runtime.log"
-          [ -f "$log" ] || cp .github/rspec_runtime_baseline.log "$log"
-          bundle exec parallel_rspec spec -n {workers} --group-by runtime --runtime-log "$log" --allowed-missing 100 \
-            -o "--format ParallelTests::RSpec::RuntimeLogger --out $log"
-      blocked: the suite is red.
-    - &check_fuzzing
-      id: fuzzing
-      title: spec/fuzzing, which the parallel run above excludes
-      run: [bundle, exec, rspec, spec/fuzzing, --tag, fuzzing]
-      blocked: spec/fuzzing is red.
-    - id: query_agreement
-      title: adapter agreement, one declared query and every engine giving the same answer
-      run: [bundle, exec, rspec, spec/adapters/query_agreement_spec.rb, --tag, io]
-      blocked: the engines disagree about a declared query; one of them is wrong, and a self-consistent adapter spec cannot tell which.
-    - &check_engine_agreement
-      id: engine_agreement
-      title: engine agreement, every declared comparator on both engines
-      run: [bundle, exec, exe/hecks, conformance_run.check_engine_agreement, --wait]
-      blocked: a comparator is missing a shared case or a cross-engine spec.
-    - &check_model_check
-      id: model_check
-      title: model check, unreachable states, dead transitions and orphaned handlers
-      run: [bundle, exec, exe/hecks, model_check, --wait]
-      blocked: the model checker found something.
-    - &check_doc_coverage
-      id: doc_coverage
-      title: docs coverage, words with no running example
-      run: [bundle, exec, exe/hecks, conformance_run.measure_doc_coverage, --wait]
-      blocked: the language ships something undocumented; write the missing sections and examples.
-    - &check_rubocop
-      id: rubocop
-      title: rubocop, the static style and correctness gate
-      run: [bundle, exec, rubocop, -c, .rubocop.yml]
-      blocked: rubocop found an offense.
-    - &check_codegen_drift
-      id: codegen_drift
-      title: codegen drift, rust/src/generated/ must match a fresh regeneration
-      run: [bundle, exec, exe/hecks, regeneration_run.regenerate_corpus, --check, --wait]
-      blocked: regenerating hits a diff. Only pizzas, mod.rs and Cargo.toml are committed, so run `hecks regenerate_corpus --confirm` (it also materializes the rest on a fresh checkout) and commit what it changed.
-    - &check_comment_style
-      id: comment_style
-      title: comment style, every comment under lib/hecks against docs/COMMENT_STYLE_GUIDE.md
-      run: [bundle, exec, exe/hecks, style_run.check_comments, paths=lib/hecks, --wait]
-      blocked: a comment breaks the style guide, such as a line past 100 characters; `hecks fix_comments` rewrites the mechanical ones, and the rest are shortened by hand. CI runs this same check.
-    - &check_comment_blocks
-      id: comment_blocks
-      title: comment blocks, no run of comment lines past ADR 0075's cap
-      run: [bundle, exec, exe/hecks, style_run.check_comments, "paths=lib,spec,examples", only=long_block, --wait]
-      blocked: a comment block ran past the cap; shorten it.
-    - &check_rust_fmt
-      id: rust_fmt
-      title: rustfmt, every Rust crate laid out as `cargo fmt` would
-      run:
-        - sh
-        - -ec
-        - |
-          # The main crate's generated modules are not committed, so cargo fmt would stop at a
-          # missing file on a fresh checkout; its hand-written entry points are named instead.
-          rustfmt --check --edition 2021 rust/src/main.rs rust/src/kernel/mod.rs rust/tests/*.rs
-          for crate in parser codegen lsp host web build; do
-            cargo fmt --check --manifest-path "rust/$crate/Cargo.toml"
-          done
-      blocked: a Rust file is not laid out as rustfmt has it; run `cargo fmt` in its crate (rust/src/exemplar is exempt, it is text templates). Generated Rust is laid out by its generators, so fix the generator, not the output.
-
-# The checks a push of only unguarded lanes (`main`) runs in place of pre_push. The slow suite is
-# skipped there; the style checks are not, since an offense that lands on `main` is a red CI run,
-# and neither is spec/fuzzing, which no commit hook runs any more.
-unguarded_push:
-  env:
-    HECKS_ENVIRONMENT: memory
-  checks:
-    - *check_rubocop
-    - *check_comment_style
-    - *check_comment_blocks
-    - *check_fuzzing
-
-# The Rust io specs `ci-rust-io.yml` runs in its `rspec_rust_io` job, for a push that wants their
-# answer first: `hecks gate_run.gate stage=rust_io --wait`. No hook or workflow runs it. It sets CI
-# as the job does, so a skipped example fails here as it fails there. rust/src/generated is not
-# committed, so the check materializes it first, as the job's generated-rust action does. The specs
-# mutate rust/, and a stage's checks run at once, so the job's two legs run one after the other in
-# a single check. spec/gate_rust_io_stage_spec.rb pins the spec lists to the workflow's matrix.
-rust_io:
-  env:
-    CI: "true"
-    HECKS_ENVIRONMENT: memory
-  checks:
-    - id: rust_io
-      title: rust io specs, conformance, coercion, has_many, semantics corpus and feature exclusivity
-      run:
-        - sh
-        - -ec
-        - |
-          # Building the banking crate makes banking the default feature and rewrites the module
-          # list, both tracked. They are put back on the way out, and the check will not start over
-          # a person's uncommitted edits to them.
-          rewritten="rust/Cargo.toml rust/src/generated/mod.rs"
-          if [ -n "$(git status --porcelain -- $rewritten)" ]; then
-            echo "uncommitted changes in $rewritten; commit or discard them first" >&2
-            exit 1
-          fi
-          trap 'git checkout -q -- $rewritten' EXIT
-          env -u CARGO_TARGET_DIR bundle exec exe/hecks regeneration_run.regenerate_corpus --confirm --wait
-          bundle exec exe/hecks build.project_rust domain=examples/banking --wait
-          bundle exec rspec --tag io --profile 8 spec/rust_conformance_spec.rb spec/rust_conformance_fuzz_spec.rb spec/rust_numeric_coercion_spec.rb spec/rust_generated/has_many_spec.rb spec/semantics_corpus_spec.rb
-          bundle exec rspec --tag io --profile 8 spec/rust_generated/domain_feature_exclusivity_spec.rb
-      blocked: a Rust io spec failed, or skipped; the crate it built is under rust/target.
-
-# The checks `.github/workflows/ci-checks.yml` runs. It sets no `env`: the job's journal choice
-# (the `hecks-environment` action) reaches every check, as it reached each command before.
-ci:
-  checks:
-    - *check_model_check
-    - *check_engine_agreement
-    - *check_doc_coverage
-    - *check_rubocop
-    - *check_comment_style
-    - *check_comment_blocks
-    - *check_codegen_drift
-    - *check_rust_fmt
-    - id: rust_clippy
-      title: clippy, every Rust crate with its warnings as errors
-      run:
-        - sh
-        - -ec
-        - |
-          for crate in . parser codegen lsp host web build; do
-            cargo clippy --all-targets --manifest-path "rust/$crate/Cargo.toml" -- -D warnings
-          done
-      blocked: clippy found a warning in a Rust crate, under the strict `[lints.clippy]` table of its Cargo.toml. The main crate needs rust/src/generated, so run `hecks regenerate_corpus --confirm` first on a fresh checkout. Fix the code, or allow a lint at the one site with a line saying why; a warning in generated Rust is fixed in its generator.
-    - id: lint_deploy_recipes
-      title: generated deploy recipes, a command with no checked exit status or no echo
-      run: [bundle, exec, exe/hecks, deploy, makefile_check.lint, --wait]
-      blocked: a generated deploy Makefile has an unchecked command, or real AWS or database work with no echo telling the person running it what is about to happen.
-    - id: fuzz
-      title: fuzz, every example domain on the Memory adapter
-      run: [bundle, exec, exe/hecks, fuzz_run.fuzz, --wait]
-      blocked: a property, an interpreter crash or a determinism check failed on a replayed sequence; the seed is in the output.
-    - id: fuzz_sqlite
-      title: fuzz on a real on-disk SQLite database
-      run: [bundle, exec, exe/hecks, fuzz_run.fuzz, adapter=sqlite, seeds=6, --wait]
-      blocked: the SQLite adapter broke a property the Memory adapter held; seeds are 1..N, so the run repeats.
-    - id: fuzz_postgres
-      title: fuzz on real Postgres, up to four workers (each in its own scratch schema)
-      run: [bundle, exec, exe/hecks, fuzz_run.fuzz, adapter=postgres, seeds=3, steps=20, --wait]
-      blocked: the Postgres adapter broke a property the Memory adapter held; it needs PGHOST, PGUSER and PGPASSWORD.
-    - id: vocabulary_drift
-      title: vocabulary, the reserved-name tables regenerated must match the committed ones
-      run:
-        - sh
-        - -ec
-        - |
-          bundle exec exe/hecks language_run.project_vocabulary --confirm --wait
-          bundle exec exe/hecks language_run.project_reserved_names --confirm --wait
-          git diff --exit-code -- lib/hecks/vocabulary.rb rust/codegen/src/reserved_names.rs rust/build/src/reserved_names.rs
-      blocked: a generated vocabulary file is stale; the check rewrote it, so commit the result.
-    - id: ci_gates
-      title: ci gates, the CiGate rows must match the marked regions of the workflows
-      run: [bundle, exec, exe/hecks, regeneration_run.project_ci_gates, --wait]
-      blocked: a CiGate row changed with no projection, or a region was edited by hand; run `hecks regeneration_run.project_ci_gates --confirm`.
-    - id: tools_doc
-      title: tools doc, docs/tools.md must match the RetiredScript rows
-      run: [bundle, exec, exe/hecks, regeneration_run.project_tools_doc, --wait]
-      blocked: a command's arguments changed with no regenerated doc; run `hecks regeneration_run.project_tools_doc --confirm`.
-    - id: rust_coverage
-      title: rust coverage, every generated module
-      run: [bundle, exec, exe/hecks, query, corpus_run.corpus_rust_coverage, --wait]
-      blocked: a construct a domain declares has no generated Rust, or an entry on RUST_COVERAGE_PENDING is now fixed and must be deleted.
-    - id: rust_coverage_codegen
-      title: rust coverage against hecks-codegen's own manifest, pizzas governance identity banking meta
-      run:
-        - sh
-        - -ec
-        - |
-          for module in pizzas governance identity banking meta; do
-            bundle exec exe/hecks query build.rust_coverage module_name=$module codegen=rust --wait
-          done
-      blocked: hecks-codegen generated nothing for a construct a domain declares.
-    - id: kernel_coverage
-      title: rust kernel coverage, every capability variant has a kernel file
-      run: [bundle, exec, exe/hecks, kernel_run.measure_kernel_coverage, --wait]
-      blocked: a capability's enum variant has no rust/src/kernel file behind it.
-    - id: rust_vocabulary_drift
-      title: rust vocabulary, the kernel vocab tables regenerated must match the committed ones
-      run:
-        - sh
-        - -ec
-        - |
-          bundle exec exe/hecks language_run.project_rust_vocabulary --confirm --wait
-          git diff --exit-code -- rust/src/kernel/vocab/
-          untracked="$(git status --porcelain --untracked-files=all -- rust/src/kernel/vocab/)"
-          if [ -n "$untracked" ]; then
-            echo "rust/src/kernel/vocab has uncommitted generated files:" >&2
-            echo "$untracked" >&2
-            exit 1
-          fi
-      blocked: the generated kernel vocab tables are stale or untracked; the check rewrote them, so commit the result.

data/lib/hecks/hecks/governance.world

@@ -1,7 +0,0 @@
-# The Governance chapter's connection when the Hecks domain attaches it: boot reads a world
-# named for the chapter, not for the consuming domain. It is the same database hecks.world
-# names, so one journal holds both; environments/memory.world swaps it to Memory too.
-Hecks.world "Governance" do
-  default_adapter "PostgresEra"
-  default_database ENV.fetch("HECKS_DATABASE", "postgres://hecks@localhost/hecks")
-end

data/lib/hecks/ports/persistence/plugins/era/expected_era.rb

@@ -1,137 +0,0 @@
-require "json"
-require "net/http"
-require "uri"
-
-module Hecks
-  module Runtime
-    module EraCheck
-      # Compares a running host's reported era (`GET /version`) against an
-      # allow-list file of eras that should be running, for use after a roll.
-      module ExpectedEra
-        # The host could not be reached, or did not answer with a `200`.
-        class Unreachable < StandardError; end
-
-        # The host answered, but not with a `/version` document carrying an era.
-        class BadResponse < StandardError; end
-
-        # What a comparison concluded.
-        #
-        # @!attribute [r] status
-        #   @return [Symbol] `:match`, `:unlisted` (no era listed) or `:mismatch`
-        # @!attribute [r] era
-        #   @return [String] the era the host reported
-        # @!attribute [r] allowed
-        #   @return [Array<String>] the eras the list accepts
-        Verdict = Struct.new(:status, :era, :allowed) do
-          # Tells whether the roll is acceptable.
-          #
-          # @return [Boolean] true unless the reported era is off the list
-          def ok? = status != :mismatch
-        end
-
-        module_function
-
-        # Reads the eras out of an allow-list file's text.
-        #
-        # @param text [String] the file's contents
-        # @return [Array<String>] the era ids in file order, without comments or blanks
-        def parse(text)
-          text.each_line.filter_map do |line|
-            entry = line.strip.sub(/\s+#.*\z/, "")
-            entry unless entry.empty? || entry.start_with?("#")
-          end
-        end
-
-        # Builds the `/version` URL from what an operator gave.
-        #
-        # @param url [String] a host's base URL, or its `/version` URL itself
-        # @return [String] the URL to request
-        def version_url(url)
-          base = url.to_s.chomp("/")
-          base.end_with?("/version") ? base : "#{base}/version"
-        end
-
-        # Asks a host which era it reports.
-        #
-        # @param url [String] the host's base URL, or its `/version` URL
-        # @param timeout [Numeric] seconds allowed for connecting and for reading
-        # @return [String] the `era` the host's `/version` document carries
-        # @raise [Unreachable] if the request fails or the status is not `200`
-        # @raise [BadResponse] if the body is not JSON or its `era` is not a non-empty string
-        def fetch_era(url, timeout:)
-          fetch_version(url, timeout: timeout).fetch("era")
-        end
-
-        # Asks a host for its `/version` document.
-        #
-        # @param url [String] the host's base URL, or its `/version` URL
-        # @param timeout [Numeric] seconds allowed for connecting and for reading
-        # @return [Hash{String => String}] `"era"` (never empty) and `"version"` (empty when the
-        #   host reports none)
-        # @raise [Unreachable] if the request fails or the status is not `200`
-        # @raise [BadResponse] if the body is not JSON or its `era` is not a non-empty string
-        def fetch_version(url, timeout:)
-          target = version_url(url)
-          response = get(target, timeout)
-          raise Unreachable, "#{target} answered #{response.code}" unless response.code == "200"
-
-          document = JSON.parse(response.body)
-          { "era" => era_in(document, target), "version" => document["version"].to_s }
-        rescue JSON::ParserError, TypeError
-          raise BadResponse, "#{version_url(url)} did not answer a JSON version document"
-        end
-
-        # Reads the era out of a parsed `/version` document.
-        #
-        # @param document [Hash] the parsed document
-        # @param target [String] the URL it came from, named in the refusal
-        # @return [String] the non-empty era
-        # @raise [BadResponse] if the era is not a non-empty string
-        def era_in(document, target)
-          era = document["era"]
-          raise BadResponse, "#{target} carries no era" unless era.is_a?(String) && !era.empty?
-
-          era
-        end
-
-        # Compares a reported era with an allow-list.
-        #
-        # @param era [String] the era the host reported
-        # @param allowed [Array<String>] the eras the list accepts; empty accepts any
-        # @return [Verdict] `:unlisted` when the list is empty, else `:match` or `:mismatch`
-        def verdict(era, allowed)
-          status = if allowed.empty? then :unlisted
-                   elsif allowed.include?(era) then :match
-                   else :mismatch
-                   end
-          Verdict.new(status, era, allowed)
-        end
-
-        # Fetches the host's era and compares it with an allow-list file.
-        #
-        # @param url [String] the host's base URL, or its `/version` URL
-        # @param file [String] path of the allow-list file
-        # @param timeout [Numeric] seconds allowed for connecting and for reading
-        # @return [Verdict] the comparison
-        # @raise [Errno::ENOENT] if the allow-list file does not exist
-        # @raise [Unreachable] see `fetch_era`
-        # @raise [BadResponse] see `fetch_era`
-        def check(url, file, timeout:)
-          allowed = parse(File.read(file))
-          verdict(fetch_era(url, timeout: timeout), allowed)
-        end
-
-        def get(url, timeout)
-          uri = URI.parse(url)
-          Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
-                                              open_timeout: timeout, read_timeout: timeout) do |http|
-            http.request(Net::HTTP::Get.new(uri.request_uri, "Accept" => "application/json"))
-          end
-        rescue SystemCallError, SocketError, Timeout::Error, IOError, URI::InvalidURIError => e
-          raise Unreachable, "#{url} could not be reached: #{e.message}"
-        end
-        private_class_method :get
-      end
-    end
-  end
-end

data/lib/hecks/ports/persistence/postgres_dump/connection.rb

@@ -1,59 +0,0 @@
-require "uri"
-
-module Hecks
-  module Ports
-    module Persistence
-      class PostgresDump
-        # A Postgres connection URL, split so a password reaches child-process tools
-        # through their environment, never on a command line the process list exposes.
-        class Connection
-          def initialize(url)
-            @uri = URI.parse(url)
-            raise Error, "not a postgres URL" unless %w[postgres postgresql].include?(@uri.scheme)
-          end
-
-          # Names the database the URL points at, empty when the URL names none.
-          def database
-            @uri.path.to_s.delete_prefix("/")
-          end
-
-          # Points the same server and credentials at another database; this one is unchanged.
-          def with_database(name)
-            copy = @uri.dup
-            copy.path = "/#{name}"
-            self.class.new(copy.to_s)
-          end
-
-          # Lists the connection settings the URL carries, in `PG.connect` keyword form; the
-          # user and password come back percent-decoded.
-          def settings
-            {
-              host: (@uri.host unless @uri.host.to_s.empty?), port: @uri.port,
-              user: decode(@uri.user), password: decode(@uri.password),
-              dbname: (database unless database.empty?), sslmode: query_params["sslmode"]
-            }.compact
-          end
-
-          # Builds the libpq environment variables for a child process.
-          def env
-            settings.to_h { |key, value| ["PG#{key.to_s.sub("dbname", "database").upcase}", value.to_s] }
-          end
-
-          # Opens a connection with the `pg` gem; the caller closes it.
-          def connect
-            require "pg"
-            PG.connect(**settings)
-          end
-
-          private
-
-          def query_params = URI.decode_www_form(@uri.query.to_s).to_h
-
-          def decode(value)
-            value && URI.decode_www_form_component(value)
-          end
-        end
-      end
-    end
-  end
-end