hecks 6.0.0 → 7.0.0

data/lib/hecks/bluebook/translation_plan.rb

@@ -7,11 +7,12 @@ module Hecks
     #   derive "to" "expression" (a tree)   rename "from" "to"   move "from" "to" (dotted paths)
     #   convert "from" "to" "values" ([old, new] pairs)   drop "path"   retype "from" "to"
     #   backfill "path" "default"   rekey_to "to"
+    #   split "into" "keyed_by" "fields" (a list of field names)
     module TranslationPlan
       VERSION = 1
 
       # The op names, in the order they apply; one per rule list of a `TranslationAggregate`.
-      OPS = %w[derive rename move convert drop retype backfill rekey_to].freeze
+      OPS = %w[derive rename move convert drop retype backfill rekey_to split].freeze
 
       module_function
 
@@ -31,7 +32,7 @@ module Hecks
 
       def ops(aggregate)
         [*derives(aggregate), *renames(aggregate), *moves(aggregate), *converts(aggregate), *drops(aggregate),
-         *retypes(aggregate), *backfills(aggregate), *rekeys(aggregate)]
+         *retypes(aggregate), *backfills(aggregate), *rekeys(aggregate), *splits(aggregate)]
       end
 
       def derives(aggregate)
@@ -65,6 +66,12 @@ module Hecks
       def rekeys(aggregate)
         aggregate.rekeys.map { |rekey| { "op" => "rekey_to", "to" => rekey.to } }
       end
+
+      def splits(aggregate)
+        aggregate.splits.map do |split|
+          { "op" => "split", "into" => split.into, "keyed_by" => split.keyed_by.to_s, "fields" => split.fields.map(&:to_s) }
+        end
+      end
     end
   end
 end

data/lib/hecks/ci_pipeline/adapters/ci_cache.adapter

@@ -0,0 +1,7 @@
+# Binds the `Cache` port to `CiCache`, which answers `Corpus`'s `Lookup` query from GitHub's cache.
+# Required by name, not relative, so a copy of this directory shares the one implementation loaded.
+require "hecks/ci_pipeline/adapters/ci_cache"
+
+Hecks.adapter "CiCache" do
+  port "Cache"
+end

data/lib/hecks/ci_pipeline/adapters/ci_cache.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "hecks/runtime/errors"
+
+module Hecks
+  module Adapters
+    # The `Cache` port's adapter for GitHub Actions: answers `Corpus`'s `Lookup` query by asking
+    # `gh` whether the repository's cache holds an entry under the key.
+    class CiCache
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] unused
+      # @param root [String, nil] the checkout `gh` runs in; this repository when nil
+      def initialize(aggregate: nil, settings: {}, root: nil)
+        @root = root || File.expand_path("../../../..", __dir__)
+      end
+
+      # @param key [Hash, String] the cache key, as the generated-rust action names it
+      # @return [Hash] `text:` a JSON document: whether the key is held, and its size when it is
+      # @raise [Runtime::GivenNotMet] when `gh` cannot list the cache
+      def lookup(key:)
+        name = key.is_a?(Hash) ? key.values.first : key
+        entries = JSON.parse(list(name.to_s))
+        { text: JSON.generate(hit: !entries.empty?, bytes: entries.first&.fetch("sizeInBytes")) }
+      end
+
+      private
+
+      def list(name)
+        out, err, status = Open3.capture3("gh", "cache", "list", "--key", name, "--json", "key,sizeInBytes",
+                                          chdir: @root)
+        raise Runtime::GivenNotMet, "gh could not list the cache: #{err.lines.first&.strip}" unless status.success?
+
+        out
+      end
+    end
+  end
+end

data/lib/hecks/ci_pipeline/adapters/ci_runner.adapter

@@ -0,0 +1,7 @@
+# Binds the `Runner` port to `CiRunner`, which answers `Build`'s queries from the run GitHub reports.
+# Required by name, not relative, so a copy of this directory shares the one implementation loaded.
+require "hecks/ci_pipeline/adapters/ci_runner"
+
+Hecks.adapter "CiRunner" do
+  port "Runner"
+end

data/lib/hecks/ci_pipeline/adapters/ci_runner.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "json"
+require "hecks/ci_speed/adapters/ci_reader"
+
+module Hecks
+  module Adapters
+    # The `Runner` port's adapter for GitHub Actions: answers `Build`'s `Reading` and `CriticalPath`
+    # queries from the run `gh` reports. A build id is a GitHub run id.
+    #
+    # GitHub does not report a job's `needs`, so the path here is the jobs ordered by wall time with
+    # the slowest first: the longest pole, which bounds the real chain from below. The needs edges
+    # the bluebook declares as policies are what a projection would add.
+    class CiRunner
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] unused
+      # @param root [String, nil] the checkout `gh` runs in; this repository when nil
+      def initialize(aggregate: nil, settings: {}, root: nil)
+        @reader = CiReader.new(root: root)
+      end
+
+      # @param build [Hash, String, Integer] the run to read
+      # @return [Hash] `text:` the run's commit, wall seconds, conclusion, cache state and jobs
+      def reading(build:)
+        @reader.reading(run_id: build)
+      end
+
+      # Answers `Head`'s `Check`: remote CI's verdict on one commit of a repository's main.
+      #
+      # @param commit [Hash, String] the commit
+      # @param branch [Hash, String] the branch the commit is on; only `main` is judged
+      # @param repo [Hash, String] `owner/name` of the repository
+      # @return [Hash] `commit`, `branch`, `repo`, `color` and `failing_jobs`, as the event
+      #   takes them
+      # @raise [Runtime::GivenNotMet] when remote CI has no settled verdict for the commit
+      def check(commit:, branch:, repo:)
+        verdict = JSON.parse(@reader.head(commit: commit, repo: repo).fetch(:text))
+        { commit: { value: verdict.fetch("commit") }, branch: { value: named(branch) },
+          repo: { value: named(repo) }, color: { value: verdict.fetch("color") },
+          failing_jobs: { value: verdict.fetch("failing_jobs") } }
+      end
+
+      # @return [String] the value a named or bare argument carries
+      def named(value) = value.is_a?(Hash) ? value.values.first.to_s : value.to_s
+
+      # @param build [Hash, String, Integer] the run to read
+      # @return [Hash] `text:` the run's jobs, the slowest first, and the slowest's seconds
+      def critical_path(build:)
+        document = JSON.parse(reading(build: build).fetch(:text))
+        path = document.fetch("jobs").sort_by { |job| -job.fetch("seconds") }
+        { text: JSON.generate(path: path, longest_seconds: path.first&.fetch("seconds")) }
+      end
+    end
+  end
+end

data/lib/hecks/ci_pipeline/ci_pipeline.behaviors

@@ -0,0 +1,322 @@
+Hecks.behaviors "CiPipeline" do
+  vision "A workflow file is what its rows say, a job runs only after what it needs, and a build passes only when every required job settled."
+
+  # `ci_pipeline.hecksagon` binds every aggregate to Memory and attaches Governance, so a boot of
+  # these files passes the memory-only guard and the role check.
+  loads "ci_pipeline.bluebook", "ci_pipeline.hecksagon", "ci_pipeline.ports.hecksagon"
+
+  # Two different hex SHA-256 digests serve the verdict tests, and one more is a cache key.
+
+  test "Declare writes ci-rspec.yml down as a reusable workflow" do
+    tests "Declare", on: "Workflow"
+    input name: { value: "ci-rspec.yml" }, display_name: { value: "CI rspec (reusable)" },
+          concurrency_group: { value: "" }, cancel_in_progress: { value: false }, reusable: { value: true }
+    expect emits: ["WorkflowDeclared"]
+  end
+
+  test "Trigger names the workflow_call event that starts a reusable workflow" do
+    tests "Trigger", on: "Workflow"
+    setup "CiPipeline::Workflow.Declare", name: { value: "ci-rspec.yml" },
+          display_name: { value: "CI rspec (reusable)" }, concurrency_group: { value: "" },
+          cancel_in_progress: { value: false }, reusable: { value: true }
+    input workflow: "ci-rspec.yml", event: { value: "workflow_call" }
+    expect emits: ["WorkflowTriggerAdded"]
+  end
+
+  test "Secret names a repository secret the caller must pass in" do
+    tests "Secret", on: "Workflow"
+    setup "CiPipeline::Workflow.Declare", name: { value: "ci-rspec.yml" },
+          display_name: { value: "CI rspec (reusable)" }, concurrency_group: { value: "" },
+          cancel_in_progress: { value: false }, reusable: { value: true }
+    input workflow: "ci-rspec.yml", secret: { value: "HECKS_CI_ATTEST_KEY" }
+    expect emits: ["WorkflowSecretAdded"]
+  end
+
+  test "Project under check asks for the projection of the workflow" do
+    tests "Project", on: "Workflow"
+    setup "CiPipeline::Workflow.Declare", name: { value: "ci-rspec.yml" },
+          display_name: { value: "CI rspec (reusable)" }, concurrency_group: { value: "" },
+          cancel_in_progress: { value: false }, reusable: { value: true }
+    input workflow: "ci-rspec.yml", check: { value: true }
+    expect emits: ["WorkflowProjectionRequested"]
+  end
+
+  # A stale projection is reported under check: the committed file differs from the rows.
+  test "ReportStale reports a committed file that differs from its projection, under check" do
+    tests "ReportStale", on: "Workflow"
+    setup "CiPipeline::Workflow.Declare", name: { value: "ci-rspec.yml" },
+          display_name: { value: "CI rspec (reusable)" }, concurrency_group: { value: "" },
+          cancel_in_progress: { value: false }, reusable: { value: true }
+    setup "CiPipeline::Workflow.Project", workflow: "ci-rspec.yml", check: { value: true }
+    input workflow: "ci-rspec.yml",
+          projected: { value: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" },
+          on_disk: { value: "fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210" }
+    expect emits: ["WorkflowStale"]
+  end
+
+  test "ReportStale refuses a stale verdict that was not asked for under check" do
+    tests "ReportStale", on: "Workflow"
+    setup "CiPipeline::Workflow.Declare", name: { value: "ci-rspec.yml" },
+          display_name: { value: "CI rspec (reusable)" }, concurrency_group: { value: "" },
+          cancel_in_progress: { value: false }, reusable: { value: true }
+    setup "CiPipeline::Workflow.Project", workflow: "ci-rspec.yml", check: { value: false }
+    input workflow: "ci-rspec.yml",
+          projected: { value: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" },
+          on_disk: { value: "fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210" }
+    expect refused: "a stale projection is reported under check"
+  end
+
+  test "ReportCurrent confirms a committed file matches its projection, under check" do
+    tests "ReportCurrent", on: "Workflow"
+    setup "CiPipeline::Workflow.Declare", name: { value: "ci-rspec.yml" },
+          display_name: { value: "CI rspec (reusable)" }, concurrency_group: { value: "" },
+          cancel_in_progress: { value: false }, reusable: { value: true }
+    setup "CiPipeline::Workflow.Project", workflow: "ci-rspec.yml", check: { value: true }
+    input workflow: "ci-rspec.yml",
+          projected: { value: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" },
+          on_disk: { value: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" }
+    expect emits: ["WorkflowCurrent"]
+  end
+
+  test "JobSpec declares a job with its runner, time limit, and gate" do
+    tests "Declare", on: "JobSpec"
+    setup "CiPipeline::Workflow.Declare", name: { value: "ci-rspec.yml" },
+          display_name: { value: "CI rspec (reusable)" }, concurrency_group: { value: "" },
+          cancel_in_progress: { value: false }, reusable: { value: true }
+    input name: { value: "ci_attestation_rspec" }, workflow: "ci-rspec.yml",
+          runner: { value: "ubuntu-latest" }, timeout_minutes: { value: 10 },
+          permissions: { value: "contents: read" }, required: { value: false },
+          gate: { value: "attestation" }, condition: { value: "" }, shard_total: { value: 1 }
+    expect emits: ["JobSpecDeclared"]
+  end
+
+  test "AddStep refuses a step that both uses an action and runs a command" do
+    tests "AddStep", on: "JobSpec"
+    setup "CiPipeline::Workflow.Declare", name: { value: "ci-rspec.yml" },
+          display_name: { value: "CI rspec (reusable)" }, concurrency_group: { value: "" },
+          cancel_in_progress: { value: false }, reusable: { value: true }
+    setup "CiPipeline::JobSpec.Declare", name: { value: "rspec_shard" },
+          workflow: "ci-rspec.yml", runner: { value: "ubuntu-latest" },
+          timeout_minutes: { value: 20 }, permissions: { value: "contents: read" },
+          required: { value: true }, gate: { value: "" }, condition: { value: "" },
+          shard_total: { value: 4 }
+    input job_spec: "rspec_shard", step_name: { value: "checkout" },
+          uses: { value: "actions/checkout@v4" }, run: { value: "make" }, condition: { value: "" }
+    expect refused: "a step either uses an action or runs a command, not both"
+  end
+
+  test "AddStep records a step that uses a composite action in this repo" do
+    tests "AddStep", on: "JobSpec"
+    setup "CiPipeline::Workflow.Declare", name: { value: "ci-rspec.yml" },
+          display_name: { value: "CI rspec (reusable)" }, concurrency_group: { value: "" },
+          cancel_in_progress: { value: false }, reusable: { value: true }
+    setup "CiPipeline::JobSpec.Declare", name: { value: "rspec_shard" },
+          workflow: "ci-rspec.yml", runner: { value: "ubuntu-latest" },
+          timeout_minutes: { value: 20 }, permissions: { value: "contents: read" },
+          required: { value: true }, gate: { value: "" }, condition: { value: "" },
+          shard_total: { value: 4 }
+    input job_spec: "rspec_shard", step_name: { value: "setup-ruby" },
+          uses: { value: "./.github/actions/setup-ruby" }, run: { value: "" }, condition: { value: "" }
+    expect emits: ["StepAdded"]
+  end
+
+  test "AddEnv sets an environment variable for every step of a job" do
+    tests "AddEnv", on: "JobSpec"
+    setup "CiPipeline::Workflow.Declare", name: { value: "ci-rspec.yml" },
+          display_name: { value: "CI rspec (reusable)" }, concurrency_group: { value: "" },
+          cancel_in_progress: { value: false }, reusable: { value: true }
+    setup "CiPipeline::JobSpec.Declare", name: { value: "rspec_shard" },
+          workflow: "ci-rspec.yml", runner: { value: "ubuntu-latest" },
+          timeout_minutes: { value: 20 }, permissions: { value: "contents: read" },
+          required: { value: true }, gate: { value: "" }, condition: { value: "" },
+          shard_total: { value: 4 }
+    input job_spec: "rspec_shard", key: { value: "BUNDLE_WITHOUT" },
+          value: { value: "development" }
+    expect emits: ["EnvAdded"]
+  end
+
+  # ci-rspec.yml's attestation job, as far as its rows go: its checkout and attestation steps,
+  # and the input that names the check. Its run commands and conditions are not in the rows yet.
+  test "ci-rspec.yml's attestation job declares its checkout and attestation steps" do
+    tests "AddStepInput", on: "JobSpec"
+    setup "CiPipeline::Workflow.Declare", name: { value: "ci-rspec.yml" },
+          display_name: { value: "CI rspec (reusable)" }, concurrency_group: { value: "" },
+          cancel_in_progress: { value: false }, reusable: { value: true }
+    setup "CiPipeline::JobSpec.Declare", name: { value: "ci_attestation_rspec" },
+          workflow: "ci-rspec.yml", runner: { value: "ubuntu-latest" },
+          timeout_minutes: { value: 10 }, permissions: { value: "contents: read" },
+          required: { value: false }, gate: { value: "attestation" }, condition: { value: "" },
+          shard_total: { value: 1 }
+    setup "CiPipeline::JobSpec.AddStep", job_spec: "ci_attestation_rspec",
+          step_name: { value: "checkout" }, uses: { value: "actions/checkout@v4" },
+          run: { value: "" }, condition: { value: "" }
+    setup "CiPipeline::JobSpec.AddStep", job_spec: "ci_attestation_rspec",
+          step_name: { value: "attest" }, uses: { value: "./.github/actions/check-attestation" },
+          run: { value: "" }, condition: { value: "" }
+    input job_spec: "ci_attestation_rspec", step: { value: "attest" },
+          key: { value: "checks" }, value: { value: "rspec" }
+    expect emits: ["StepInputAdded"]
+  end
+
+  # ci-rspec.yml's rspec_shard: the legs follow the stated total, which is the matrix size.
+  test "A sharded job plans a leg for each index within its shard total" do
+    tests "PlanShard", on: "JobSpec"
+    setup "CiPipeline::Workflow.Declare", name: { value: "ci-rspec.yml" },
+          display_name: { value: "CI rspec (reusable)" }, concurrency_group: { value: "" },
+          cancel_in_progress: { value: false }, reusable: { value: true }
+    setup "CiPipeline::JobSpec.Declare", name: { value: "rspec_shard" },
+          workflow: "ci-rspec.yml", runner: { value: "ubuntu-latest" },
+          timeout_minutes: { value: 20 }, permissions: { value: "contents: read" },
+          required: { value: true }, gate: { value: "" }, condition: { value: "" },
+          shard_total: { value: 4 }
+    input job_spec: "rspec_shard", index: { value: 4 }
+    expect emits: ["ShardPlanned"]
+  end
+
+  test "A sharded job refuses a leg past its shard total" do
+    tests "PlanShard", on: "JobSpec"
+    setup "CiPipeline::Workflow.Declare", name: { value: "ci-rspec.yml" },
+          display_name: { value: "CI rspec (reusable)" }, concurrency_group: { value: "" },
+          cancel_in_progress: { value: false }, reusable: { value: true }
+    setup "CiPipeline::JobSpec.Declare", name: { value: "rspec_shard" },
+          workflow: "ci-rspec.yml", runner: { value: "ubuntu-latest" },
+          timeout_minutes: { value: 20 }, permissions: { value: "contents: read" },
+          required: { value: true }, gate: { value: "" }, condition: { value: "" },
+          shard_total: { value: 4 }
+    input job_spec: "rspec_shard", index: { value: 5 }
+    expect refused: "a shard index is within the shard total"
+  end
+
+  # A job with several needs queues only after all of them are met. One met need is not enough.
+  test "Queue refuses a job until every edge into it is met" do
+    tests "Queue", on: "Job"
+    setup "CiPipeline::CiRun.Open", build: { value: "b1" }, commit: { value: "93f8e68c6" },
+          required_total: { value: 1 }
+    setup "CiPipeline::Job.Declare", build: "b1", name: { value: "rspec_shard" },
+          required: { value: true }, gate: { value: "" }, needs_total: { value: 2 }
+    input job: "rspec_shard", touched: { value: false }
+    expect refused: "every need is settled first"
+  end
+
+  test "Queue admits a job once both of its needs are met" do
+    tests "Queue", on: "Job"
+    setup "CiPipeline::CiRun.Open", build: { value: "b1" }, commit: { value: "93f8e68c6" },
+          required_total: { value: 1 }
+    setup "CiPipeline::Job.Declare", build: "b1", name: { value: "rspec_shard" },
+          required: { value: true }, gate: { value: "" }, needs_total: { value: 2 }
+    setup "CiPipeline::Job.Satisfy", job: "rspec_shard"
+    setup "CiPipeline::Job.Satisfy", job: "rspec_shard"
+    input job: "rspec_shard", touched: { value: false }
+    expect emits: ["Queued"]
+  end
+
+  # A skipped gate counts as met, so its dependents run. The attestation skip and the corpus hit
+  # are the edges into rspec_shard.
+  test "A skipped gate leaves its dependents runnable" do
+    tests "Skip", on: "Job"
+    setup "CiPipeline::CiRun.Open", build: { value: "b1" }, commit: { value: "93f8e68c6" },
+          required_total: { value: 1 }
+    setup "CiPipeline::Job.Declare", build: "b1", name: { value: "ci_attestation_rspec" },
+          required: { value: false }, gate: { value: "attestation" }, needs_total: { value: 0 }
+    setup "CiPipeline::Job.Declare", build: "b1", name: { value: "rspec_shard" },
+          required: { value: true }, gate: { value: "" }, needs_total: { value: 2 }
+    setup "CiPipeline::Corpus.Open", build: { value: "b1" },
+          key: { value: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" }
+    setup "CiPipeline::Corpus.Hit", corpus: "b1"
+    input job: "ci_attestation_rspec", of_job: { value: "ci_attestation_rspec" }, was_required: { value: false }, of_build: { value: "b1" }, touched: { value: false }
+    expect emits: ["Skipped", "Satisfied"]
+  end
+
+  test "Queue admits rspec_shard once its skipped gate and its corpus hit both settled it" do
+    tests "Queue", on: "Job"
+    setup "CiPipeline::CiRun.Open", build: { value: "b1" }, commit: { value: "93f8e68c6" },
+          required_total: { value: 1 }
+    setup "CiPipeline::Job.Declare", build: "b1", name: { value: "ci_attestation_rspec" },
+          required: { value: false }, gate: { value: "attestation" }, needs_total: { value: 0 }
+    setup "CiPipeline::Job.Declare", build: "b1", name: { value: "rspec_shard" },
+          required: { value: true }, gate: { value: "" }, needs_total: { value: 2 }
+    setup "CiPipeline::Corpus.Open", build: { value: "b1" },
+          key: { value: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" }
+    setup "CiPipeline::Corpus.Hit", corpus: "b1"
+    setup "CiPipeline::Job.Skip", job: "ci_attestation_rspec", of_job: { value: "ci_attestation_rspec" },
+          was_required: { value: false }, of_build: { value: "b1" },
+          touched: { value: false }
+    input job: "rspec_shard", touched: { value: false }
+    expect emits: ["Queued"]
+  end
+
+  test "A gated job is not skipped when the change touches its gate" do
+    tests "Skip", on: "Job"
+    setup "CiPipeline::CiRun.Open", build: { value: "b1" }, commit: { value: "93f8e68c6" },
+          required_total: { value: 1 }
+    setup "CiPipeline::Job.Declare", build: "b1", name: { value: "ci_attestation_rspec" },
+          required: { value: false }, gate: { value: "attestation" }, needs_total: { value: 0 }
+    input job: "ci_attestation_rspec", of_job: { value: "ci_attestation_rspec" }, was_required: { value: false }, of_build: { value: "b1" }, touched: { value: true }
+    expect refused: "a gate skips its job only when the change does not touch it"
+  end
+
+  # A cache miss regenerates the corpus once, and the job that needs it waits for that.
+  test "A cache miss forces Materialize before a job that needs the corpus can start" do
+    tests "Miss", on: "Corpus"
+    setup "CiPipeline::CiRun.Open", build: { value: "b1" }, commit: { value: "93f8e68c6" },
+          required_total: { value: 1 }
+    setup "CiPipeline::Job.Declare", build: "b1", name: { value: "rspec_shard" },
+          required: { value: true }, gate: { value: "" }, needs_total: { value: 2 }
+    setup "CiPipeline::Corpus.Open", build: { value: "b1" },
+          key: { value: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" }
+    input corpus: "b1"
+    expect emits: ["Miss", "Materialized", "Satisfied"]
+  end
+
+  test "A cache hit does not regenerate the corpus" do
+    tests "Hit", on: "Corpus"
+    setup "CiPipeline::CiRun.Open", build: { value: "b1" }, commit: { value: "93f8e68c6" },
+          required_total: { value: 1 }
+    setup "CiPipeline::Job.Declare", build: "b1", name: { value: "rspec_shard" },
+          required: { value: true }, gate: { value: "" }, needs_total: { value: 2 }
+    setup "CiPipeline::Corpus.Open", build: { value: "b1" },
+          key: { value: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" }
+    input corpus: "b1"
+    expect emits: ["Hit", "Satisfied"]
+  end
+
+  test "Build passes once every required job has passed" do
+    tests "CountPass", on: "CiRun"
+    setup "CiPipeline::CiRun.Open", build: { value: "b1" }, commit: { value: "93f8e68c6" },
+          required_total: { value: 1 }
+    setup "CiPipeline::CiRun.Start", build: "b1"
+    input build: "b1"
+    expect emits: ["PassCounted", "BuildPassed"]
+  end
+
+  test "Build does not pass while a required job is still unsettled" do
+    tests "Pass", on: "CiRun"
+    setup "CiPipeline::CiRun.Open", build: { value: "b1" }, commit: { value: "93f8e68c6" },
+          required_total: { value: 2 }
+    setup "CiPipeline::CiRun.Start", build: "b1"
+    input build: "b1"
+    expect refused: "every required job passed or was skipped by its gate"
+  end
+
+  test "Build fails when one required job fails" do
+    tests "CountFailure", on: "CiRun"
+    setup "CiPipeline::CiRun.Open", build: { value: "b1" }, commit: { value: "93f8e68c6" },
+          required_total: { value: 2 }
+    setup "CiPipeline::CiRun.Start", build: "b1"
+    input build: "b1"
+    expect emits: ["FailureCounted", "BuildFailed"]
+  end
+
+  test "A required job's pass counts toward its build, which then passes" do
+    tests "Pass", on: "Job"
+    setup "CiPipeline::CiRun.Open", build: { value: "b1" }, commit: { value: "93f8e68c6" },
+          required_total: { value: 1 }
+    setup "CiPipeline::CiRun.Start", build: "b1"
+    setup "CiPipeline::Job.Declare", build: "b1", name: { value: "rspec_shard" },
+          required: { value: true }, gate: { value: "" }, needs_total: { value: 0 }
+    setup "CiPipeline::Job.Queue", job: "rspec_shard", touched: { value: false }
+    setup "CiPipeline::Job.Start", job: "rspec_shard"
+    input job: "rspec_shard", of_job: { value: "rspec_shard" }, was_required: { value: true }, of_build: { value: "b1" }, seconds: { value: 200 }
+    expect emits: ["Passed", "PassCounted", "BuildPassed"]
+  end
+end