hecks 2.8.0 → 3.0.0

data/lib/hecks/hecks/adapters/codebase/sqlite_fixture.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "tree"
+require_relative "../shell"
+require_relative "../console_capture"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # The `SqliteFixture` adapter: regenerates the persistence legacy fixtures
+      # (`spec/fixtures/persistence_legacy/`) by writing through the real adapters.
+      #
+      # The fixtures are a baseline that later adapters are compared with, so the run is never
+      # started by accident: unconfirmed it reports what it would rewrite and whether the `sqlite3`
+      # program it dumps a database with is installed, and writes nothing. Confirmed, it runs
+      # `PersistenceLegacyFixture::Regenerate` in this process, which needs a reachable Postgres as
+      # well.
+      class SqliteFixture
+        # Where the fixtures stand, relative to the checkout.
+        DIRECTORY = "spec/fixtures/persistence_legacy"
+
+        # The stores each fixture set is written for.
+        STORES = %w[heki sqlite d1 postgres postgres_era].freeze
+
+        # @param tree [Tree] the checkout whose fixtures are rewritten
+        # @param shell [#capture, nil] starts the `sqlite3` probe; a `Shell` when nil
+        # @param regenerator [#call, nil] rewrites the fixtures, as `call(dir:)` answering what was
+        #   written; `PersistenceLegacyFixture::Regenerate` when nil
+        def initialize(tree, shell: nil, regenerator: nil)
+          @tree = tree
+          @shell = shell || Shell.new
+          @regenerator = regenerator
+        end
+
+        # Regenerates the fixtures, or reports what a regeneration would rewrite.
+        #
+        # @param confirm [Boolean] whether to rewrite
+        # @return [String] what was written, or (unconfirmed) what would be
+        # @raise [ConsoleCapture::Failure] when a fixture cannot be written
+        def regenerate(confirm:)
+          return rewrite if confirm
+
+          "dry run, would rewrite #{DIRECTORY}/ for #{STORES.join(', ')} through the real adapters " \
+            "(#{installed}; add --confirm)"
+        end
+
+        # @return [Boolean] whether the `sqlite3` program answers
+        def sqlite_installed?
+          @shell.capture("sqlite3", "--version").ok?
+        end
+
+        private
+
+        def rewrite
+          regenerator.call(dir: @tree.path(DIRECTORY))
+        rescue LoadError, StandardError => e
+          raise ConsoleCapture::Failure, "#{e.class}: #{e.message}"
+        end
+
+        def regenerator
+          @regenerator ||= begin
+            require "hecks/persistence_legacy_fixture"
+            PersistenceLegacyFixture::Regenerate
+          end
+        end
+
+        def installed = sqlite_installed? ? "sqlite3 is installed" : "sqlite3 is not installed"
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/codebase/style.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "tree"
+require_relative "ruby_child"
+require "hecks/canonical_json"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # What Codebase's `StyleRun` asks of the working tree: keeping comments to the style guides
+      # (Ruby's `docs/COMMENT_STYLE_GUIDE.md`, Rust's `docs/COMMENT_STYLE_GUIDE_RUST.md`), and
+      # writing a JSON document with its keys in order.
+      #
+      # The linters are `Hecks::Tools::CommentStyle` and `Hecks::Tools::RustCommentStyle`, which own
+      # their options, so each ask runs one in this process from the checkout's root. A check
+      # that finds violations refuses with the list. A fix rewrites files, so unconfirmed it lists
+      # what it would rewrite (the fixable categories only) and writes nothing.
+      module Style
+        # Every operation this family carries out.
+        OPERATIONS = %w[check_comments fix_comments write_comment_baseline check_comments_unchanged
+                        check_rust_comments fix_rust_comments canonicalise].freeze
+
+        # The categories a fix rewrites, in both linters.
+        FIXABLE = "all_caps,long_bold,long_line"
+
+        # Where the long-block baseline is written from, and what a `--code-unchanged` compares.
+        BASELINE_PATHS = ["lib/hecks"].freeze
+
+        # The paths a code-unchanged check looks at when none are named.
+        UNCHANGED_PATHS = ["lib"].freeze
+
+        # The linter each operation runs.
+        SCRIPTS = { "check_rust_comments"  => "standardize_comments_rust",
+                    "fix_rust_comments"    => "standardize_comments_rust",
+                    "report_rust_comments" => "standardize_comments_rust" }.freeze
+
+        module_function
+
+        # Carries out one operation.
+        #
+        # @param operation [String] one of `OPERATIONS`
+        # @param held [Hash] the `StyleRun` record's fields
+        # @param tree [Tree] the working tree, already known to be a hecks checkout
+        # @param shell [#capture, nil] unused: the linters run in this process
+        # @return [String] what the linter printed, or the file in order
+        # @raise [ConsoleCapture::Failure] when a check finds a violation, or the linter or file is
+        #   refused
+        def call(operation, held, tree, shell: nil)
+          args = held.transform_values { |value| value.is_a?(Hash) ? value[:value] : value }
+          return canonical(args, tree) if operation == "canonicalise"
+
+          child = RubyChild.new(tree)
+          case operation
+          when "check_comments", "check_rust_comments" then check(operation, args, child)
+          when "fix_comments", "fix_rust_comments" then fix(operation, args, child)
+          when "write_comment_baseline" then baseline(args, child)
+          else unchanged(args, child)
+          end
+        end
+
+        # A pure read: the linter's summary, its violations, or its JSON.
+        #
+        # @param operation [String] `report_comments` or `report_rust_comments`
+        # @param args [Hash] the query's plain arguments: `paths`, `only`, `json`, `top`
+        # @param tree [Tree] the checkout
+        # @param shell [#capture, nil] unused: the linters run in this process
+        # @return [String] the linter's report
+        # @raise [ConsoleCapture::Failure] when the linter refuses its arguments
+        def report(operation, args, tree, shell: nil)
+          flags = ["--report", *only_flags(args)]
+          flags << "--json" if args[:json]
+          flags.push("--top", args[:top].to_s) if args[:top]
+          paths = after_separator(paths_of(args))
+          RubyChild.new(tree).answer(script_of(operation), *flags, *paths)
+        end
+
+        # @param args [Hash] the record's plain fields
+        # @param tree [Tree] the checkout
+        # @return [String] the JSON document at `file`, every object's keys in order
+        # @raise [ConsoleCapture::Failure] when the file cannot be read or is not JSON
+        def canonical(args, tree)
+          path = File.expand_path(args[:file].to_s)
+          CanonicalJson.pretty(File.read(path))
+        rescue Errno::ENOENT
+          raise ConsoleCapture::Failure, "no such file #{path} (relative to #{Dir.pwd}, tree #{tree.root})"
+        rescue JSON::ParserError => e
+          raise ConsoleCapture::Failure, "#{path} is not JSON: #{e.message.lines.first.strip}"
+        end
+
+        # @param operation [String] `check_comments` or `check_rust_comments`
+        # @param args [Hash] the record's plain fields
+        # @param child [RubyChild] the linter's runner
+        # @return [String] the linter's clean verdict
+        # @raise [ConsoleCapture::Failure] with every violation, when there is one
+        def check(operation, args, child)
+          paths = after_separator(paths_of(args))
+          answer = child.answer(script_of(operation), "--check", *only_flags(args), *paths)
+          answer.empty? ? "no comment violations" : answer
+        end
+
+        # @param operation [String] `fix_comments` or `fix_rust_comments`
+        # @param args [Hash] the record's plain fields
+        # @param child [RubyChild] the linter's runner
+        # @return [String] the files rewritten, or (unconfirmed) the violations a fix would rewrite
+        # @raise [ConsoleCapture::Failure] when the linter refuses its arguments
+        def fix(operation, args, child)
+          script = script_of(operation)
+          paths = after_separator(paths_of(args))
+          return child.answer(script, "--fix", *only_flags(args), *paths) if args[:confirm] == true
+
+          found = child.capture(script, "--check", "--only", FIXABLE, *paths).out.strip
+          return "dry run: nothing a fix would rewrite" if found.empty?
+
+          "dry run, #{found.lines.size} violations a fix would rewrite (add --confirm to rewrite):\n#{found}"
+        end
+
+        # @param args [Hash] the record's plain fields
+        # @param child [RubyChild] the linter's runner
+        # @return [String] what the baseline recorded, or (unconfirmed) the blocks it would record
+        def baseline(args, child)
+          paths = after_separator(args[:paths] ? paths_of(args) : BASELINE_PATHS)
+          return child.answer("standardize_comments", "--write-baseline", *paths) if args[:confirm] == true
+
+          found = child.capture("standardize_comments", "--check", "--only", "long_block", *paths).out.strip
+          return "dry run: no block would be newly tolerated" if found.empty?
+
+          "dry run, #{found.lines.size} blocks would be recorded as tolerated (add --confirm):\n#{found}"
+        end
+
+        # @param args [Hash] the record's plain fields: `ref`, and `paths` (`lib` when absent)
+        # @param child [RubyChild] the linter's runner
+        # @return [String] "code unchanged"
+        # @raise [ConsoleCapture::Failure] naming each file whose code differs from the ref, or when
+        #   the ref is blank or begins with `-`
+        def unchanged(args, child)
+          ref = args[:ref].to_s.strip
+          raise ConsoleCapture::Failure, "a ref to compare with is required" if ref.empty?
+          raise ConsoleCapture::Failure, "a ref may not begin with '-': #{ref}" if ref.start_with?("-")
+
+          paths = args[:paths] ? paths_of(args) : UNCHANGED_PATHS
+          child.answer("standardize_comments", "--code-unchanged", ref, *after_separator(paths))
+        end
+
+        # @param operation [String] an operation
+        # @return [String] the linter it runs
+        def script_of(operation) = SCRIPTS.fetch(operation, "standardize_comments")
+
+        # @param args [Hash] the record's plain fields
+        # @return [Array<String>] `--only <list>` when categories are named
+        def only_flags(args) = args[:only] ? ["--only", args[:only].to_s] : []
+
+        # @param args [Hash] the record's plain fields
+        # @return [Array<String>] the paths, from a comma-separated list
+        def paths_of(args) = args[:paths].to_s.split(",").map(&:strip).reject(&:empty?)
+
+        # Paths as the linter takes them: after `--`, so no path is read as a flag.
+        #
+        # @param paths [Array<String>] the paths a query names, or its default paths
+        # @return [Array<String>] `--` and the paths
+        # @raise [ConsoleCapture::Failure] when a path begins with `-`
+        def after_separator(paths)
+          flagged = paths.select { |path| path.start_with?("-") }
+          raise ConsoleCapture::Failure, "paths may not begin with '-': #{flagged.join(', ')}" if flagged.any?
+
+          ["--", *paths]
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/codebase/test_runner.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "stringio"
+require_relative "tree"
+require_relative "../console_capture"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # The `TestRunner` adapter: runs one spec example through the test runner in this process.
+      #
+      # It hands the runner one file and one example description, so a caller never quotes the
+      # description for a shell. What the runner prints is captured and comes back as the answer;
+      # a run that fails refuses with the same text.
+      class TestRunner
+        class << self
+          # @return [#call, nil] takes `(args, err, out)` and answers the exit status; the test
+          #   runner when nil. A spec replaces it so no example has to run to test what is asked.
+          attr_accessor :runner
+        end
+
+        # @param tree [Tree] the checkout whose spec is run
+        def initialize(tree)
+          @tree = tree
+        end
+
+        # Runs one example of one spec file, from the checkout's root.
+        #
+        # @param file [String] the spec file, relative to the checkout or absolute
+        # @param example [String] part of the example's description
+        # @return [String] what the runner printed when every matching example passed
+        # @raise [ConsoleCapture::Failure] when the file is not there, or an example failed
+        def run(file:, example:)
+          path = File.expand_path(file, @tree.root)
+          raise ConsoleCapture::Failure, "no such spec file #{file}" unless File.file?(path)
+
+          out = StringIO.new
+          status = Dir.chdir(@tree.root) { runner.call(["--example", example, path], out, out) }
+          raise ConsoleCapture::Failure, out.string.strip unless status.zero?
+
+          out.string.strip
+        end
+
+        private
+
+        def runner
+          return self.class.runner if self.class.runner
+
+          require "rspec/core"
+          RSpec::Core::Runner.method(:run)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/codebase/test_suite.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require_relative "tree"
+require_relative "test_runner"
+require_relative "sqlite_fixture"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # What Codebase's `TestSuiteRun` asks of the working tree: the tooling around this
+      # repository's specs.
+      #
+      # The tooling owns its options, so each ask runs one of the `Hecks::CLI` commands in this
+      # process from the checkout's root, except a single example (the `TestRunner` adapter runs it)
+      # and the persistence fixtures (the `SqliteFixture` adapter). A listing is a pure read.
+      # Refreshing the committed timings, regenerating the fixtures and writing the committed spec
+      # list change tracked files, so unconfirmed they report what they would do and write nothing.
+      module TestSuite
+        # Every operation this family carries out.
+        OPERATIONS = %w[refresh_runtime_baseline run_spec_example stress_concurrency
+                        regenerate_legacy_fixtures seed_semantics_corpus write_io_parallel_spec_list].freeze
+
+        # The tag filter the postgres job lists its specs by when none is named.
+        DEFAULT_TAGS = "--tag io --tag ~fuzzing"
+
+        # The committed files a baseline refresh writes.
+        BASELINES = %w[.github/rspec_runtime_baseline.log .github/postgres_io_runtime_baseline.log].freeze
+
+        module_function
+
+        # Loads the command a `Hecks::CLI` file defines, the first time an ask needs it: several
+        # read the checkout's specs or need a development gem, which an installed gem lacks.
+        #
+        # @param file [String] the command's file under `lib/hecks/cli/`, without the extension
+        # @return [Module] the command, named as the file is, in camel case
+        def command(file)
+          require "hecks/cli/#{file}"
+          Hecks::CLI.const_get(file.split("_").map(&:capitalize).join)
+        end
+
+        # Carries out one operation.
+        #
+        # @param operation [String] one of `OPERATIONS`
+        # @param held [Hash] the `TestSuiteRun` record's fields
+        # @param tree [Tree] the working tree, already known to be a hecks checkout
+        # @param shell [#capture, nil] starts the fixtures' child process
+        # @return [String] what was found, run or written
+        # @raise [ConsoleCapture::Failure] when a run fails or a script is refused
+        def call(operation, held, tree, shell: nil)
+          args = plain(held)
+          case operation
+          when "refresh_runtime_baseline" then refresh(args, tree)
+          when "run_spec_example" then TestRunner.new(tree).run(file: args[:file], example: args[:example])
+          when "stress_concurrency"
+            answer { command("stress_concurrency_specs").call(stress_flags(args), root: tree.root) }
+          when "regenerate_legacy_fixtures"
+            SqliteFixture.new(tree, shell: shell).regenerate(confirm: args[:confirm] == true)
+          when "seed_semantics_corpus"
+            answer { command("seed_semantics_corpus").call(root: tree.root, env: seed_env(args)) }
+          else write_list(args, tree)
+          end
+        end
+
+        # A pure read: a listing, or the recorded pattern cases.
+        #
+        # @param operation [String] `shard_specs`, `list_io_parallel_specs`, `record_pattern_cases`
+        # @param args [Hash] the query's plain arguments
+        # @param tree [Tree] the checkout
+        # @param shell [#capture, nil] unused: every listing is read in this process
+        # @return [String] what the command printed to stdout
+        # @raise [ConsoleCapture::Failure] when the command refuses its arguments
+        def report(operation, args, tree, shell: nil)
+          case operation
+          when "shard_specs"
+            read { |out| command("rspec_shard_files").call(shard_args(args), root: tree.root, out: out) }
+          when "list_io_parallel_specs"
+            read { |out| command("rspec_io_parallel_files").call(list_args(args), root: tree.root, out: out) }
+          else read { |out| command("pattern_cases").call(out: out) }
+          end
+        end
+
+        # Runs a command in this process and answers what it printed to stdout only, for a command
+        # whose stdout is its data and whose stderr is progress.
+        #
+        # @yield [out] the command, given the stream its data goes to; it answers an exit status
+        # @yieldparam out [StringIO] where the data goes
+        # @return [String] the data, without the trailing newline
+        # @raise [ConsoleCapture::Failure] with what it printed when the status is not 0
+        def read
+          out = StringIO.new
+          outcome = ConsoleCapture.capture { exit(yield(out)) }
+          raise ConsoleCapture::Failure, outcome.output.strip unless outcome.ok?
+
+          out.string.chomp
+        end
+
+        # Runs a command in this process and answers everything it printed.
+        #
+        # @yield the command; it answers an exit status
+        # @return [String] what it printed to stdout and stderr
+        # @raise [ConsoleCapture::Failure] with what it printed when the status is not 0
+        def answer
+          ConsoleCapture.answer { exit(yield) }
+        end
+
+        # @param held [Hash] the record's fields, each perhaps a value object's `{ value: x }`
+        # @return [Hash] the same fields as plain values
+        def plain(held) = held.transform_values { |value| value.is_a?(Hash) ? value[:value] : value }
+
+        # @param args [Hash] `group`, `groups` and `runtime_log`
+        # @return [Array<String>] the script's arguments
+        def shard_args(args) = [args[:group].to_s, args[:groups].to_s, *args[:runtime_log]]
+
+        # @param args [Hash] `exclude`, `tags` and `check`
+        # @return [Array<String>] the script's arguments: `--check FILE`, the pattern, then the tags
+        def list_args(args)
+          check = args[:check] ? ["--check", args[:check]] : []
+          [*check, args[:exclude].to_s, "--", *tag_words(args)]
+        end
+
+        # @param args [Hash] `tags`, perhaps absent
+        # @return [Array<String>] the tag filter, one word each
+        def tag_words(args) = (args[:tags] || DEFAULT_TAGS).split
+
+        # @param args [Hash] `workers` and `from_run`
+        # @param tree [Tree] the checkout whose baselines are rewritten
+        # @return [String] what was written, or (unconfirmed) what would be
+        # @raise [ConsoleCapture::Failure] when the refresh ends badly
+        def refresh(args, tree)
+          source = args[:from_run] ? ["--from-run", args[:from_run]] : [*args[:workers]&.to_s]
+          return answer { command("refresh_rspec_runtime_baseline").call(source, root: tree.root) } if args[:confirm] == true
+
+          "dry run, would #{args[:from_run] ? "read CI run #{args[:from_run]}'s timings" : 'time a local run'} " \
+            "and rewrite #{BASELINES.join(', ')} (add --confirm)"
+        end
+
+        # @param args [Hash] `runs`, `parallel` and `seed_start`
+        # @return [Array<String>] the script's flags for those that are named
+        def stress_flags(args)
+          { "--runs" => :runs, "--parallel" => :parallel, "--seed-start" => :seed_start }
+            .filter_map { |flag, name| [flag, args[name].to_s] if args[name] }.flatten
+        end
+
+        # @param args [Hash] `fixture`, perhaps absent
+        # @return [Hash{String => String}] the variable that names the one fixture to re-seed
+        def seed_env(args) = args[:fixture] ? { "SEED" => args[:fixture] } : {}
+
+        # @param args [Hash] `exclude`, `tags`, `write` and `confirm`
+        # @param tree [Tree] the checkout whose spec list is written
+        # @return [String] what was written, or (unconfirmed) how many files would be
+        # @raise [ConsoleCapture::Failure] when the listing is refused
+        def write_list(args, tree)
+          if args[:confirm] == true
+            words = ["--write", args[:write], args[:exclude], "--", *tag_words(args)]
+            answer { command("rspec_io_parallel_files").call(words, root: tree.root) }
+            return "wrote #{args[:write]}"
+          end
+
+          files = report("list_io_parallel_specs", args, tree).lines.size
+          "dry run, would write #{files} spec files to #{args[:write]} (add --confirm)"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/codebase/tree.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "../console_capture"
+require "hecks/runtime/errors"
+
+module Hecks
+  module Adapters
+    # Adapters of the Codebase part of the Hecks domain: the tools for working on this repository.
+    module Codebase
+      # The working tree a Codebase request acts on, and the one rule they all share: it is a hecks
+      # checkout, a tree with `hecks.gemspec` beside `lib/`.
+      #
+      # The package carries `lib/` and the Rust workspace but never the gemspec, so an installed gem
+      # cannot be mistaken for a checkout and answers "needs a hecks checkout" instead of globbing
+      # an absent `rust/` or rewriting its own `lib/`. A request that changes files goes through
+      # {#apply}: it compares each file with what it should hold, reports the drift, and writes
+      # only when confirmed.
+      class Tree
+        # The file whose presence beside `lib/` marks a hecks checkout.
+        MARKER = "hecks.gemspec"
+
+        # What a request outside a checkout is refused with.
+        NEEDS = "needs a hecks checkout"
+
+        # The repository this file lives in.
+        DEFAULT_ROOT = File.expand_path("../../../../..", __dir__)
+
+        class << self
+          # @return [String, nil] the tree to act on; this repository when nil. A spec points it
+          #   at a directory that is not a checkout, so no install is needed to test the refusal.
+          attr_accessor :root
+        end
+
+        # Raised when a request needs a hecks checkout and the tree is not one. It is the runtime's
+        # own refusal for an unmet rule, so a query answered here reads as a refusal in the
+        # launcher.
+        class NeedsCheckout < Runtime::GivenNotMet; end
+
+        # @return [String] the tree's root directory
+        attr_reader :root
+
+        # @param root [String, nil] the tree's root; {.root}, or this repository, when nil
+        def initialize(root: nil)
+          @root = File.expand_path(root || self.class.root || DEFAULT_ROOT)
+        end
+
+        # @return [Boolean] whether the tree is a hecks checkout
+        def checkout?
+          File.exist?(File.join(@root, MARKER)) && Dir.exist?(File.join(@root, "lib"))
+        end
+
+        # @return [void]
+        # @raise [NeedsCheckout] "needs a hecks checkout" when the tree is not one
+        def require_checkout!
+          return if checkout?
+
+          raise NeedsCheckout, "#{NEEDS}: #{MARKER} does not stand beside lib/ in #{@root}"
+        end
+
+        # @param parts [Array<String>] path segments below the root
+        # @return [String] the absolute path
+        def path(*parts) = File.join(@root, *parts)
+
+        # @param absolute [String] a path inside the tree
+        # @return [String] the path relative to the root
+        def relative(absolute) = absolute.delete_prefix("#{@root}/")
+
+        # Compares each file with what it should hold, and writes the differences only when
+        # confirmed.
+        #
+        # @param files [Hash{String => String}] absolute path to the text it should hold
+        # @param stale [Array<String>] absolute paths that should not exist
+        # @param confirm [Boolean] whether to write; the comparison is all that happens when false
+        # @return [String] what differs, and whether it was written
+        def apply(files, stale: [], confirm: false)
+          changes = drift(files, stale)
+          return "nothing to change: #{files.size} files already hold what the language projects" if changes.empty?
+
+          write(files, stale) if confirm
+          summarize(changes, confirm)
+        end
+
+        private
+
+        def drift(files, stale)
+          changed = files.filter_map do |path, text|
+            next [:new, path] unless File.exist?(path)
+
+            [:changed, path] unless File.read(path) == text
+          end
+          changed + stale.select { |path| File.exist?(path) }.map { |path| [:removed, path] }
+        end
+
+        def write(files, stale)
+          files.each do |path, text|
+            FileUtils.mkdir_p(File.dirname(path))
+            File.write(path, text)
+          end
+          stale.each { |path| FileUtils.rm_f(path) }
+        end
+
+        def summarize(changes, confirm)
+          lines = changes.map { |kind, path| "  #{kind} #{relative(path)}" }
+          head = confirm ? "wrote #{changes.size} files:" : "dry run, #{changes.size} files differ (add --confirm to write):"
+          [head, *lines].join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/console_capture.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "monitor"
+require "stringio"
+
+module Hecks
+  module Adapters
+    # Runs a command-line entry point that prints and exits, and hands back what it said and how
+    # it ended, so an adapter can reuse `Hecks::CLI::*` unchanged.
+    #
+    # It is the shared base for every Custodian adapter that wraps an existing CLI: the entry
+    # point keeps its own printing, `exit` and `abort`, and the adapter turns the outcome into a
+    # port answer (the text) or a refusal (`Failed`). `$stdout`, `$stderr`, `ENV` and the working
+    # directory are process-wide, so every capture, and every `RustBuild` call, holds the one
+    # `LOCK` for its length: two captures never interleave, and one may nest inside another on
+    # the same thread.
+    module ConsoleCapture
+      # What an entry point said and how it ended.
+      #
+      # @!attribute [r] output
+      #   @return [String] everything printed to stdout and stderr, in order
+      # @!attribute [r] status
+      #   @return [Integer] the exit status; 0 when the entry point returned normally
+      Outcome = Struct.new(:output, :status) do
+        # @return [Boolean] whether the entry point ended with status 0
+        def ok? = status.zero?
+      end
+
+      # Raised when a captured entry point ends with a non-zero status; the message is its output.
+      class Failure < StandardError; end
+
+      # The process-wide lock a capture holds; reentrant, so a capture may run another.
+      LOCK = Monitor.new
+
+      module_function
+
+      # Runs the block holding the process-wide capture lock.
+      #
+      # @yield the work that swaps a process-wide stream, variable or directory
+      # @return [Object] the block's value
+      def synchronize(&) = LOCK.synchronize(&)
+
+      # Runs the block with stdout and stderr captured.
+      #
+      # @yield the entry point to run
+      # @return [Outcome] the text printed and the exit status
+      def capture
+        synchronize do
+          saved  = [$stdout, $stderr]
+          buffer = StringIO.new
+          begin
+            $stdout = $stderr = buffer
+            status = begin
+              yield
+              0
+            rescue SystemExit => e
+              e.status
+            end
+            Outcome.new(buffer.string, status)
+          ensure
+            $stdout, $stderr = saved
+          end
+        end
+      end
+
+      # Runs the block captured and answers its text, or refuses with it.
+      #
+      # @yield the entry point to run
+      # @return [String] the output when the entry point ended with status 0
+      # @raise [Failure] when it ended otherwise; the message is what it printed
+      def answer(&)
+        outcome = capture(&)
+        raise Failure, outcome.output.strip unless outcome.ok?
+
+        outcome.output
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/deploy_toolchain.adapter

@@ -0,0 +1,7 @@
+# Required by name, not relative to this file: a fuzz or model check boots a copy of this directory,
+# and the implementation must load once, from `lib/`, not from the copy.
+require "hecks/hecks/adapters/deploy_toolchain"
+
+Hecks.adapter "DeployToolchain" do
+  port "DeployToolchain"
+end