hecks 2.8.0 → 3.0.0

data/lib/hecks/quality_control/adapters/github_checks.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "open3"
+require "json"
+
+module Hecks
+  module Adapters
+    # The `CI` port adapter: answers `Clearance.CI.Run` from GitHub's check runs for a commit.
+    # Raises when no checks exist, any are still running, or any failed.
+    class GithubChecks
+      # All keywords are unused; the adapter takes no per-boot configuration.
+      def initialize(aggregate: nil, settings: {}, root: nil); end
+
+      # Check-run conclusions that count as green; `skipped` covers path-filtered workflows.
+      PASSING = %w[success neutral skipped].freeze
+
+      # A commit sha as GitHub accepts it in an API path.
+      SHA_PATTERN = /\A[0-9a-fA-F]{7,40}\z/
+
+      # Check runs asked for per page; GitHub's maximum.
+      PER_PAGE = 100
+
+      # Asks GitHub by commit sha, matching `Clearance`'s identity, so it works after the
+      # branch is gone. `{owner}/{repo}` is a `gh api` template resolved from the git remote.
+      #
+      # @param commit [Hash, String] a materialized value object (`{value: sha}`) or a bare sha
+      # @return [Hash] `{ summary: { value: ... } }` when every check is green
+      # @raise [RuntimeError] when the sha is malformed, `gh` is missing or fails, no checks
+      #   exist, any are incomplete, or any failed
+      def run(commit:, **)
+        sha = sha_of(commit)
+        raise "not a commit sha: #{sha.inspect}" unless sha.match?(SHA_PATTERN)
+
+        runs = check_runs(sha)
+
+        raise "gh reports no checks at all against #{sha}" if runs.empty?
+
+        # Refuse rather than answer on an incomplete run; asking again once it settles is safe.
+        incomplete = runs.reject { |run| run["status"] == "completed" }
+        raise "checks against #{sha} are still running — asked before they settled" if incomplete.any?
+
+        failing = runs.reject { |run| PASSING.include?(run["conclusion"]) }
+        return { summary: { value: "#{runs.length} checks, all green (#{sha[0, 7]})" } } if failing.empty?
+
+        raise "#{failing.length} of #{runs.length} checks failed against #{sha[0, 7]}: " \
+              "#{failing.map { |run| run['name'] }.join(', ')}"
+      end
+
+      private
+
+      # Accepts a materialized value hash with symbol or string keys, or a bare string.
+      def sha_of(commit)
+        return commit if commit.is_a?(String)
+
+        (commit.key?(:value) ? commit[:value] : commit["value"]).to_s
+      end
+
+      # Every page of check runs: a red run past the first page must still be seen.
+      def check_runs(sha)
+        runs = []
+        page = 1
+        loop do
+          batch = check_run_page(sha, page)["check_runs"] || []
+          runs.concat(batch)
+          break if batch.length < PER_PAGE
+
+          page += 1
+        end
+        runs
+      end
+
+      def check_run_page(sha, page)
+        path = "repos/{owner}/{repo}/commits/#{sha}/check-runs?per_page=#{PER_PAGE}&page=#{page}"
+        out, err, status = Open3.capture3("gh", "api", path)
+        raise "gh api check-runs failed for #{sha}: #{err.strip.empty? ? out.strip : err.strip}" unless status.success?
+
+        JSON.parse(out)
+      rescue Errno::ENOENT
+        raise "gh is not installed or not on PATH — cannot read check runs for #{sha}"
+      end
+    end
+  end
+end

data/lib/hecks/quality_control/adapters/github_ci_webhook.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "hecks/adapters/driving/github_webhook"
+require_relative "clearance_recorder"
+
+module Hecks
+  module Adapters
+    module Driving
+      # Records GitHub's `check_suite` webhook as a `QualityControl::Clearance`.
+      # GitHub sends one `check_suite` per GitHub App for a commit, so one suite is not the
+      # commit's verdict. A passing suite clears the commit only when it belongs to `CI_APP_SLUG`
+      # (Actions, which runs the gate); a passing suite from any other app is acknowledged and
+      # ignored. A failing suite from any app holds the commit red, and the first verdict stands.
+      class GithubCiWebhook < GithubWebhook
+        SHA_PATTERN = /\A[0-9a-fA-F]{7,40}\z/
+
+        # The GitHub App whose passing suite counts as the commit being green.
+        CI_APP_SLUG = "github-actions"
+
+        def handle_event(event, action, payload)
+          return ignored("not a check_suite event (got #{event.inspect})") unless event == "check_suite"
+          # `requested`/`rerequested` mean the suite has not finished, so there is no verdict yet.
+          return ignored("check_suite not yet completed (action=#{action.inspect})") unless action == "completed"
+
+          suite = payload["check_suite"] || {}
+          sha   = suite["head_sha"].to_s
+
+          unless sha.match?(SHA_PATTERN)
+            return [422, { error: "MalformedCommit", message: "check_suite.head_sha #{sha.inspect} does not look like a sha" }]
+          end
+
+          settle(sha, suite)
+        end
+
+        private
+
+        def ignored(reason) = [200, { ok: true, ignored: reason }]
+
+        def settle(sha, suite)
+          conclusion = suite["conclusion"].to_s
+          passed     = Hecks::QA::ClearanceRecorder::PASSING.include?(conclusion)
+          app        = suite.dig("app", "slug").to_s
+          if passed && app != CI_APP_SLUG
+            return ignored("passing check_suite from app #{app.inspect}, not #{CI_APP_SLUG.inspect}")
+          end
+
+          summary = "check_suite #{suite['id']} conclusion=#{conclusion} for #{sha[0, 7]} — via webhook"
+
+          cleared = Hecks::QA::ClearanceRecorder.record(commit: sha, passed: passed, summary: summary)
+
+          [200, { ok: true, commit: sha, status: cleared.status, summary: summary }]
+        end
+      end
+    end
+  end
+end

data/lib/hecks/quality_control/adapters/github_issues.adapter

@@ -0,0 +1,7 @@
+# Binds the `IssueTracker` port to `GithubIssues` for any boot that loads the chapter.
+# Required by name, not relative, so a copy of this directory shares the one implementation loaded.
+require "hecks/quality_control/adapters/github_issues"
+
+Hecks.adapter "GithubIssues" do
+  port "IssueTracker"
+end

data/lib/hecks/quality_control/adapters/github_issues.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Hecks
+  module Adapters
+    # The `IssueTracker` port's adapter: files a `QualityControl::Ticket` as a GitHub issue.
+    # Raises when `gh` refuses, which the runtime records as the ticket's refusal.
+    class GithubIssues
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] unused
+      # @param root [String, nil] unused
+      def initialize(aggregate: nil, settings: {}, root: nil); end
+
+      # Files the ticket the runtime hands over (its whole held state) with `gh issue create`.
+      #
+      # @param held [Hash] the ticket's fields; `repository`, `title` and `body` are materialized
+      #   value objects (`{value: ...}`) or bare strings, and `pull_request` names a proposed fix
+      # @return [Hash{Symbol => Hash}] `number:` and `url:` of the issue, in the shape the
+      #   ticket's `Filed` command takes
+      # @raise [RuntimeError] when `gh` exits non-zero or prints no issue URL
+      def file(**held)
+        repository = plain(held[:repository])
+        proposed   = plain(held[:pull_request]).to_s
+        body       = plain(held[:body]).to_s
+        body      += "\n\nA fix is proposed in #{proposed}" unless proposed.empty?
+
+        out, err, status = Open3.capture3("gh", "issue", "create", "--repo", repository,
+                                          "--title", plain(held[:title]).to_s, "--body", body)
+        raise "gh issue create failed — #{err.strip.empty? ? out.strip : err.strip}" unless status.success?
+
+        url    = out.strip.lines.last.to_s.strip
+        number = url[%r{/issues/(\d+)\z}, 1]
+        raise "gh issue create printed no issue URL: #{out.strip.inspect}" unless number
+
+        { number: { value: number.to_i }, url: { value: url } }
+      end
+
+      private
+
+      # A materialized value object (`{value: x}`, symbol or string keys) or the value itself.
+      def plain(field)
+        return field unless field.is_a?(Hash)
+
+        field.key?(:value) ? field[:value] : field["value"]
+      end
+    end
+  end
+end

data/lib/hecks/quality_control/adapters/qa_tool.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "open3"
+require "shellwords"
+require "hecks/runtime/errors"
+require_relative "../cli/child"
+
+module Hecks
+  module Adapters
+    # The base of the adapters that answer the QA scripts' queries (`SweepTools`,
+    # `ClearanceTools`, `AngleTools`, `TargetTools`): each starts one command of
+    # `Hecks::QualityControlCli` as its own OS process and answers what it printed.
+    #
+    # A child, not this process: the commands boot the ledger, fork, spawn and open Postgres
+    # connections of their own, and a crash or an `exit` in one must end only that run. The answer
+    # is the command's output, unchanged, so the launcher shows the bytes the script prints.
+    class QaTool
+      # A command ended in an error. It is a refusal, since the launcher and the ledger's policies
+      # treat it as one, but not a `given`'s: no description of the command's guards quotes it, so
+      # the fuzzer's guard checks must not read it as one.
+      class ToolRefused < Runtime::GivenNotMet; end
+
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] unused
+      # @param root [String, nil] the checkout the commands run in; this repository when nil
+      def initialize(aggregate: nil, settings: {}, root: nil)
+        @root = root || File.expand_path("../../../..", __dir__)
+      end
+
+      private
+
+      # Runs one command and answers its output.
+      #
+      # @param command [String] a key of `QualityControlCli::Child::COMMANDS`
+      # @param args [Array<String>] the command's own arguments
+      # @param answers [Array<Integer>] the exit statuses that are an answer: a finding, or a
+      #   judgment, is one, an operational error is not
+      # @return [Hash] `text:` what the command printed, stdout and stderr in
+      #   order
+      # @raise [ToolRefused] with what the command printed, when it ended with another
+      #   status
+      def run_command(command, *, answers: [0])
+        output, status = Open3.capture2e(*QualityControlCli::Child.argv(@root, command, *), chdir: @root)
+        return { text: output } if answers.include?(status.exitstatus)
+
+        raise ToolRefused, "#{output.strip}\n(#{command} ended with status #{status.exitstatus.inspect})"
+      end
+
+      # @param value [Hash, String, nil] a value object's materialized `{ value: "..." }`, or plain
+      #   text
+      # @return [String, nil] the text, nil when absent
+      def plain(value) = value.is_a?(Hash) ? value[:value] : value
+
+      # @param value [Hash, String, nil] words in the command's own flag syntax
+      # @return [Array<String>] the words, split as a shell would
+      def words(value) = Shellwords.split(plain(value).to_s)
+    end
+  end
+end

data/lib/hecks/quality_control/adapters/sweep_tools.adapter

@@ -0,0 +1,7 @@
+# Binds the `SweepTools` port to `SweepTools`, which answers `Sweep`'s queries: a tick, a sweep, the Heki migration, the ledger's role and a racer.
+# Required by name, not relative, so a copy of this directory shares the one implementation loaded.
+require "hecks/quality_control/adapters/sweep_tools"
+
+Hecks.adapter "SweepTools" do
+  port "SweepTools"
+end

data/lib/hecks/quality_control/adapters/sweep_tools.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "qa_tool"
+
+module Hecks
+  module Adapters
+    # The `SweepTools` port's adapter: answers `Sweep`'s queries by running the QA commands that
+    # work a whole pass: a tick, a sweep, the Heki migration, the ledger's role and a concurrency
+    # racer. A run that finds something ends with status 2, which is an answer; anything else the
+    # command calls an error is refused with its report.
+    class SweepTools < QaTool
+      # @return [Hash] `text:` one tick's report
+      def tick
+        run_command("qa_tick", answers: [0, 2])
+      end
+
+      # @param target [Hash, String, nil] the target to sweep; the rotation's pick when absent
+      # @param arguments [Hash, String, nil] the sweep's own flags, such as `--all --seeds 5`
+      # @return [Hash] `text:` the sweep's report
+      def run(target: nil, arguments: nil)
+        run_command("qa_sweep", *plain(target), *words(arguments), answers: [0, 2])
+      end
+
+      # @param domain [Hash, String] the domain directory whose bindings are the destination
+      # @param data [Hash, String] the Heki data directory read from
+      # @param arguments [Hash, String, nil] aggregate names, and `--force` to apply
+      # @return [Hash] `text:` what was, or would be, migrated
+      def migrate_ledger_from_heki(domain:, data:, arguments: nil)
+        run_command("qa_postgres_migrate", plain(domain), plain(data), *words(arguments))
+      end
+
+      # @param database [Hash, String] the database the role is made to own
+      # @param role [Hash, String, nil] the role's name; `hecks_qa` when absent
+      # @return [Hash] `text:` what was done, and what already held
+      def create_ledger_role(database:, role: nil)
+        run_command("qa_postgres_role", plain(database), *(role ? ["--role", plain(role)] : []))
+      end
+
+      # @param domain [Hash, String] the domain directory
+      # @param database [Hash, String] the scratch database
+      # @param schema [Hash, String] the schema this racer dispatches into
+      # @param verb [Hash, String] the command to dispatch
+      # @param step_arguments [Hash, String] the command's arguments, as JSON
+      # @return [Hash] `text:` `succeeded`, `refused` or `crashed:<class>: <message>`
+      def race(domain:, database:, schema:, verb:, step_arguments:)
+        run_command("qa_concurrency_racer", plain(domain), plain(database), plain(schema), plain(verb),
+                    plain(step_arguments))
+      end
+    end
+  end
+end

data/lib/hecks/quality_control/adapters/target_tools.adapter

@@ -0,0 +1,7 @@
+# Binds the `TargetTools` port to `TargetTools`, which answers `Target`'s queries: the seed, generated domains, the miner, the novelty gate and the scan.
+# Required by name, not relative, so a copy of this directory shares the one implementation loaded.
+require "hecks/quality_control/adapters/target_tools"
+
+Hecks.adapter "TargetTools" do
+  port "TargetTools"
+end

data/lib/hecks/quality_control/adapters/target_tools.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "qa_tool"
+
+module Hecks
+  module Adapters
+    # The `TargetTools` port's adapter: answers `Target`'s queries by running the QA commands that
+    # enrol, generate and judge chapters: the seed, the generated-domain check, the combination
+    # miner, the novelty gate and the external-domain scan. A finding or a judgment is an answer;
+    # anything else the command calls an error is refused with its report.
+    class TargetTools < QaTool
+      # @return [Hash] `text:` each corpus domain's outcome: identified, or already on file
+      def seed
+        run_command("qa_seed_targets")
+      end
+
+      # @param arguments [Hash, String, nil] the command's own flags, such as `--domains 3 --rust`
+      # @return [Hash] `text:` the report of the generated domains' check
+      def check_generated_domains(arguments: nil)
+        run_command("qa_generated_domains", *words(arguments), answers: [0, 2])
+      end
+
+      # @param arguments [Hash, String, nil] the command's own flags, such as `--brief`
+      # @return [Hash] `text:` the miner's report
+      def mine_combinations(arguments: nil)
+        run_command("qa_mine_combinations", *words(arguments), answers: [0, 1])
+      end
+
+      # @param domain [Hash, String] the candidate stress domain's path
+      # @param arguments [Hash, String, nil] `--against` and the paths to compare with
+      # @return [Hash] `text:` the new form pairs it earns its place with, or that it earns none
+      def judge_novelty(domain:, arguments: nil)
+        run_command("qa_domain_novelty", plain(domain), *words(arguments), answers: [0, 1])
+      end
+
+      # @param arguments [Hash, String, nil] the command's own flags, such as `--max-depth 4`
+      # @return [Hash] `text:` the sibling domains that depend on hecks and are not enrolled
+      def discover_external_domains(arguments: nil)
+        run_command("qa_discover_external_domains", *words(arguments))
+      end
+    end
+  end
+end

data/lib/hecks/quality_control/cli/child.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Hecks
+  module QualityControlCli
+    # How one QA command starts another as its own OS process, from `lib/` rather than through a
+    # launcher script: a sweep spawns racers and generated-domain checks, and a launcher query runs
+    # any of them. A fresh process is the point: its own boot, its own Postgres connections, and a
+    # crash that ends only itself.
+    module Child
+      # Each command's class, and how it is called: `:argv_root` is `call(ARGV, root:)`, `:argv` is
+      # `call(ARGV)` and `:root` is `call(root:)`. A command lives in
+      # `hecks/quality_control/cli/<command>`.
+      COMMANDS = {
+        "qa_tick"                      => ["QaTick", :argv_root],
+        "qa_sweep"                     => ["QaSweep", :argv_root],
+        "qa_pr_check"                  => ["QaPrCheck", :argv_root],
+        "qa_generated_domains"         => ["QaGeneratedDomains", :argv_root],
+        "qa_mine_combinations"         => ["QaMineCombinations", :argv_root],
+        "qa_domain_novelty"            => ["QaDomainNovelty", :argv_root],
+        "qa_discover_external_domains" => ["QaDiscoverExternalDomains", :argv_root],
+        "qa_concurrency_racer"         => ["QaConcurrencyRacer", :argv_root],
+        "qa_postgres_migrate"          => ["QaPostgresMigrate", :argv],
+        "qa_postgres_role"             => ["QaPostgresRole", :argv],
+        "qa_seed_angles"               => ["QaSeedAngles", :root],
+        "qa_seed_targets"              => ["QaSeedTargets", :root]
+      }.freeze
+
+      module_function
+
+      # @param root [String] the checkout whose `lib/` holds the command and where it runs
+      # @param command [String] a key of `COMMANDS`
+      # @param args [Array<String>] the command's own arguments
+      # @return [Array<String>] the argv that runs it under Bundler, ready for `Process.spawn`
+      #   or `Open3` with `chdir: root`
+      # @raise [KeyError] when the command is not one of `COMMANDS`
+      def argv(root, command, *args)
+        klass, style = COMMANDS.fetch(command)
+        call = { argv_root: "ARGV, root: #{root.inspect}", argv: "ARGV", root: "root: #{root.inspect}" }.fetch(style)
+        code = "require #{"hecks/quality_control/cli/#{command}".inspect}; " \
+               "exit(Hecks::QualityControlCli::#{klass}.call(#{call}))"
+        ["bundle", "exec", "ruby", "-I", File.join(root, "lib"), "-e", code, "--", *args]
+      end
+    end
+  end
+end

data/lib/hecks/quality_control/cli/qa_concurrency_racer.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../../../hecks"
+require_relative "../../ports/persistence/plugins/era"
+require_relative "../../fuzzing/concurrent_dispatch"
+
+module Hecks
+  module QualityControlCli
+    # The command behind `hecks quality_control race`: one racer of
+    # `Hecks::Fuzzing::ConcurrentDispatch`, run as its own OS process.
+    #
+    # It is spawned, not forked: the caller (`hecks quality_control ask run`) holds live
+    # `PostgresEra` connections, and fork duplicates their file descriptors and SSL state,
+    # corrupting them when a child exits.
+    #
+    #   hecks quality_control race <domain-path> <database> <schema> <verb> <args-json>
+    #
+    # It prints one line, `succeeded`, `refused` or `crashed:<class>: <message>`, and always exits
+    # 0.
+    class QaConcurrencyRacer
+      USAGE = "usage: hecks quality_control race <domain-path> <database> <schema> <verb> <args-json>"
+
+      # Dispatches the one step and prints how it went.
+      #
+      # @param argv [Array<String>] the domain path, database, schema, verb and args JSON
+      # @param root [String] unused; a racer needs no checkout of its own
+      # @param out [IO] where the outcome goes
+      # @return [Integer] 0 always
+      # @raise [SystemExit] with the usage line when an argument is missing
+      def self.call(argv, root: nil, out: $stdout)
+        domain_path, database, schema, verb, args_json = argv
+        abort USAGE unless domain_path && database && schema && verb && args_json
+
+        step = { "verb" => verb, "args" => JSON.parse(args_json) }
+        outcome = Hecks::Fuzzing::ConcurrentDispatch.boot_preserving_schema(domain_path, database: database,
+                                                                                         schema:   schema) do |copy|
+          Hecks::Fuzzing::ConcurrentDispatch.dispatch_one(Hecks.boot(copy), step)
+        end
+        out.puts outcome
+        0
+      end
+    end
+  end
+end