specguard-ruby 0.3.31 → 0.3.33

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 14818808e8ef3b696b1b3834ea590734fa398f5fabbef1c5646d03699e844d99
-  data.tar.gz: ccce2e2cf09f6b3401284c0f7f3f343185c86fa2d48bc43ca7bbd9e48575910e
+  metadata.gz: f0f1cdce1e2e763d549b0ccb1bd5d9a22b1c5a9da9f63645704af3ecd8149de1
+  data.tar.gz: aa80ba0c1f264a50d307c83fd1a8c9a543d6b5eef75037f53ac5ffef68c5d812
 SHA512:
-  metadata.gz: a7612a5d841ecf6d7b1f675bfe362a5141948c1e227a89d7d90e449c9f3b802b650894e7cd3862bb37a897dcbc77ae6e0d627caa1b3cbde3275b54ebd41beb54
-  data.tar.gz: d78f0bea385d4a9ca63d1581648350c76662f7540b0c105dda6a0ebb15c7b3be1be98e7d2ca8f29b5536fac597a4ed155cb5b96f8ff8575e79bfde7292ff0034
+  metadata.gz: 4673b30c851eb2324326704ab72539c4a909b068f1addc354cb461de216816a05ee2f195b01c70a9c78cadd3810760d6d59c89947e6c56a31971ca6915e658e4
+  data.tar.gz: fd2ae5c3fafa5ed48b05c71f5109fea22b8b1796b7d0869cf1fb6bcfe2b8adaad440aa79c2cea493c2984bf7fb2a032fe17a7666d19387f4803852692f2f925d

data/README.md

@@ -1146,8 +1146,8 @@ body is encoded on the wire, never what is in it.
 
 | Field | What it holds | Where it comes from |
 | --- | --- | --- |
-| `commit_sha` | the commit the suite ran against | `SPECGUARD_COMMIT_SHA` if you set it, else `GITHUB_SHA`, `CI_COMMIT_SHA`, `CIRCLE_SHA1`, `BUILDKITE_COMMIT`, `GIT_COMMIT`, else `git rev-parse HEAD` |
-| `branch` | the branch name; `null` on a detached checkout | `SPECGUARD_BRANCH` if you set it, else `GITHUB_REF_NAME`, `CI_COMMIT_REF_NAME`, `CIRCLE_BRANCH`, `BUILDKITE_BRANCH`, `GIT_BRANCH`, else `git symbolic-ref --short -q HEAD` |
+| `commit_sha` | the commit the suite ran against | `SPECGUARD_COMMIT_SHA` if you set it, else — on a same-repository GitHub Actions `pull_request` / `pull_request_target` run — the pushed head sha from the event payload at `GITHUB_EVENT_PATH` (`GITHUB_SHA` there is an ephemeral merge commit), else `GITHUB_SHA`, `CI_COMMIT_SHA`, `CIRCLE_SHA1`, `BUILDKITE_COMMIT`, `GIT_COMMIT`, else `git rev-parse HEAD` |
+| `branch` | the branch name; `null` on a detached checkout | `SPECGUARD_BRANCH` if you set it, else — on a same-repository GitHub Actions `pull_request` / `pull_request_target` run — `GITHUB_HEAD_REF` (`GITHUB_REF_NAME` there is `<n>/merge`), else `GITHUB_REF_NAME`, `CI_COMMIT_REF_NAME`, `CIRCLE_BRANCH`, `BUILDKITE_BRANCH`, `GIT_BRANCH`, else `git symbolic-ref --short -q HEAD` |
 | `ci_run_id` | your provider's build id, so shards of one run fold together; `null` on a laptop | `SPECGUARD_RUN_ID` if you set it, else `GITHUB_RUN_ID`, `CI_PIPELINE_ID`, `CIRCLE_WORKFLOW_ID`, `BUILDKITE_BUILD_ID`, `BUILD_TAG` |
 | `shard_id` | which slice of that run this process is; `null` when unsharded | `SPECGUARD_SHARD_ID` if you set it, else `TEST_ENV_NUMBER`, `CI_NODE_INDEX`, `CIRCLE_NODE_INDEX`, `BUILDKITE_PARALLEL_JOB` |
 | `duration_seconds` | wall clock for the whole run | measured by the formatter |

data/lib/specguard/client/configuration.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "json"
+
 module SpecGuard
   module Client
     # Where the checkout is sitting — which commit, and which branch — asked of
@@ -180,6 +182,12 @@ module SpecGuard
       # every GitLab, CircleCI, Buildkite and Jenkins run 400ing as a matter of
       # course — the *default* outcome on four of the five providers this gem is
       # likely to meet.
+      #
+      # On a GitHub Actions `pull_request` / `pull_request_target` run from the
+      # same repository, the pushed head commit in the event payload
+      # (`#pull_request_head`) is consulted *between* `SPECGUARD_COMMIT_SHA` and
+      # the rest of this list: `GITHUB_SHA` there is the ephemeral merge commit
+      # (the base tip on `_target`), a sha nobody pushed.
       COMMIT_SHA_KEYS = %w[
         SPECGUARD_COMMIT_SHA
         GITHUB_SHA
@@ -195,6 +203,11 @@ module SpecGuard
       # (`origin/main` on many setups), because `branch` is a free-form string
       # to the platform and inventing a normalization here would be this gem
       # guessing at somebody's ref layout.
+      #
+      # On a same-repository GitHub Actions `pull_request` /
+      # `pull_request_target` run, {PULL_REQUEST_BRANCH_KEYS} (`GITHUB_HEAD_REF`,
+      # the source branch) is consulted between `SPECGUARD_BRANCH` and the rest
+      # of this list, because `GITHUB_REF_NAME` there is `<n>/merge`.
       BRANCH_KEYS = %w[
         SPECGUARD_BRANCH
         GITHUB_REF_NAME
@@ -314,6 +327,22 @@ module SpecGuard
       # than absent. See trap 1 above.
       BLANK_MEANS_FIRST_SHARD_KEY = "TEST_ENV_NUMBER"
 
+      # GitHub Actions only: the event that triggered the run, the file holding
+      # its payload, and the source branch of a pull request. They are read
+      # only together, by `#pull_request_head`, and only when `GITHUB_EVENT_NAME`
+      # is one of {PULL_REQUEST_EVENTS}.
+      EVENT_NAME_KEYS = %w[GITHUB_EVENT_NAME].freeze
+      EVENT_PATH_KEYS = %w[GITHUB_EVENT_PATH].freeze
+      PULL_REQUEST_BRANCH_KEYS = %w[GITHUB_HEAD_REF].freeze
+
+      # The GitHub events whose `GITHUB_SHA` / `GITHUB_REF_NAME` describe a
+      # merge ref rather than anything a person pushed.
+      PULL_REQUEST_EVENTS = %w[pull_request pull_request_target].freeze
+
+      # Largest `GITHUB_EVENT_PATH` payload read; a bigger file is treated as
+      # unreadable (mirrors specguard-ts).
+      MAX_EVENT_PAYLOAD_BYTES = 1024 * 1024
+
       OUTPUT_PATH_KEYS = %w[SPECGUARD_OUTPUT_PATH].freeze
       LOCAL_OUTPUT_PATH_KEYS = %w[SPECGUARD_LOCAL_OUTPUT_PATH].freeze
       ENDPOINT_KEYS = %w[SPECGUARD_ENDPOINT].freeze
@@ -377,10 +406,22 @@ module SpecGuard
       #   reason, and so a test does not silently pick up the sha or the branch
       #   of whatever repository it runs in.
       def initialize(env: ENV, git: GitCheckout)
-        @commit_sha = first_present(env, COMMIT_SHA_KEYS) || blank_to_nil(git.commit_sha)
+        explicit_sha = first_present(env, COMMIT_SHA_KEYS.first(1))
+        explicit_branch = first_present(env, BRANCH_KEYS.first(1))
+        # One read of the event payload decides branch and sha together, so
+        # they cannot disagree; skipped when both were set explicitly.
+        pr_head = explicit_sha && explicit_branch ? nil : pull_request_head(env)
+
         # `||` short-circuits, which is the whole of "do not spawn a subprocess
         # when a provider already answered".
-        @branch = first_present(env, BRANCH_KEYS) || blank_to_nil(git.branch)
+        @commit_sha = explicit_sha ||
+                      pr_head&.fetch(:sha) ||
+                      first_present(env, COMMIT_SHA_KEYS) ||
+                      blank_to_nil(git.commit_sha)
+        @branch = explicit_branch ||
+                  (pr_head && first_present(env, PULL_REQUEST_BRANCH_KEYS)) ||
+                  first_present(env, BRANCH_KEYS) ||
+                  blank_to_nil(git.branch)
         @run_id = first_present(env, RUN_ID_KEYS)
         @shard_id = resolve_shard_id(env)
         @output_path = first_present(env, OUTPUT_PATH_KEYS) || DEFAULT_OUTPUT_PATH
@@ -393,6 +434,65 @@ module SpecGuard
 
       private
 
+      # The pushed head of a GitHub Actions pull-request run, or nil when it
+      # cannot be established as a SAME-REPOSITORY pull request.
+      #
+      # On `pull_request` / `pull_request_target`, `GITHUB_SHA` is the
+      # ephemeral merge commit (the base tip on `_target`) and
+      # `GITHUB_REF_NAME` is `<n>/merge` — neither is anything a person pushed.
+      # `git rev-parse HEAD` does not rescue it: `actions/checkout` puts the
+      # merge commit at HEAD. The real head sha lives only in the event payload
+      # at `GITHUB_EVENT_PATH`.
+      #
+      # A fork PR yields nil: `GITHUB_HEAD_REF` is then the FORK's branch name
+      # (`main` on a `contrib:main` PR would be filed under the base
+      # repository's own `main`), so the merge-ref behaviour is kept. A
+      # missing, unreadable, oversized or garbled payload also yields nil.
+      # Never raises and shells out to nothing.
+      #
+      # @return [Hash{Symbol=>String,nil}, nil] `{sha:}` — sha is nil when the
+      #   payload's head sha is not 40 hex characters (the branch is still the
+      #   source branch then) — or nil when this is not a same-repo PR.
+      def pull_request_head(env)
+        return nil unless PULL_REQUEST_EVENTS.include?(first_present(env, EVENT_NAME_KEYS))
+
+        path = first_present(env, EVENT_PATH_KEYS)
+        return nil if path.nil?
+
+        pull_request = read_event_payload(path)&.fetch("pull_request", nil)
+        return nil unless pull_request.is_a?(Hash)
+
+        head = pull_request["head"]
+        base = pull_request["base"]
+        head_repo = repo_full_name(head)
+        return nil if head_repo.nil? || head_repo != repo_full_name(base)
+
+        sha = head["sha"]
+        { sha: sha.is_a?(String) && sha.match?(/\A[0-9a-f]{40}\z/i) ? sha : nil }
+      rescue ScriptError, StandardError
+        nil
+      end
+
+      def repo_full_name(side)
+        return nil unless side.is_a?(Hash) && side["repo"].is_a?(Hash)
+
+        name = side["repo"]["full_name"]
+        name.is_a?(String) && !name.empty? ? name : nil
+      end
+
+      # @return [Hash, nil] the parsed payload, or nil if it is absent, not a
+      #   regular file, larger than {MAX_EVENT_PAYLOAD_BYTES}, or not a JSON
+      #   object.
+      def read_event_payload(path)
+        return nil unless File.file?(path)
+
+        raw = File.open(path, "rb") { |file| file.read(MAX_EVENT_PAYLOAD_BYTES + 1) }
+        return nil if raw.nil? || raw.bytesize > MAX_EVENT_PAYLOAD_BYTES
+
+        parsed = JSON.parse(raw)
+        parsed.is_a?(Hash) ? parsed : nil
+      end
+
       # {SHARD_ID_KEYS} in order, first non-blank wins — except that a
       # {BLANK_MEANS_FIRST_SHARD_KEY} which is *set* counts as a hit even when
       # it is empty, and resolves to `"1"`.

data/lib/specguard/client/delivery_warning.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module SpecGuard
+  module Client
+    # The two clauses that finish a delivery-failure warning line, shared by
+    # the RSpec formatter and the Minitest reporter.
+    #
+    # Both clients print the same sentence after their own prefix and status
+    # clause: where the run ended up, and (when it was saved) the command that
+    # gets it back. They used to carry two inline copies kept equal
+    # "word-for-word" by hand, and the pair had already been co-edited in
+    # separate commits (SPGD-1139, SPGD-1413). One definition here means a
+    # wording change cannot reach one client and miss the other.
+    #
+    # What stays in each client: the prefix, the warning budget (`@warned`),
+    # and the `append` that decides whether `error` is nil. Those differ by
+    # design; only the clause text is shared.
+    module DeliveryWarning
+      module_function
+
+      # Report, not promise. Composed after the write so it can tell the
+      # operator which of the two things actually happened. `error` is the
+      # client's `append` answer: `nil` means the queue took the run (the
+      # success arm, {#replay_clause}); anything else means both sinks are
+      # gone and the run really is lost (SPGD-1413).
+      def sink_clause(path, error)
+        return replay_clause(path) if error.nil?
+
+        "The replay queue #{path} could not be written either " \
+          "(#{error.class}: #{error.message}), so this run's telemetry was lost."
+      end
+
+      # The success arm (SPGD-1139): where the run sits AND the command that
+      # gets it back, fix-the-delivery first and replay after — the order the
+      # ingest CLI's own doctrine describes. The lost-run arm deliberately
+      # names no command: with no queue written there is nothing to replay.
+      def replay_clause(path)
+        "Falling back to #{path}; the test run is unaffected. " \
+          "Once the delivery is fixed, replay this run with: bundle exec specguard-ingest #{path}"
+      end
+    end
+  end
+end

data/lib/specguard/client/ingest_cli.rb

@@ -739,8 +739,7 @@ module SpecGuard
         raise UsageError, "no endpoint is configured (set SPECGUARD_ENDPOINT)" if blank?(configuration.endpoint)
         raise UsageError, "no API key is configured (set SPECGUARD_API_KEY)" if blank?(configuration.api_key)
 
-        transport = Transport.new(endpoint: configuration.endpoint, api_key: configuration.api_key,
-                                  timeout: configuration.timeout, repository_id: configuration.repository_id)
+        transport = Transport.from_configuration(configuration)
         # Asked once, here, so a malformed `SPECGUARD_ENDPOINT` is one exit 2
         # rather than N identical `:failed` lines. `Transport#deliver` would
         # otherwise swallow the same `ArgumentError` once per line and report a

data/lib/specguard/client/transport.rb

@@ -293,6 +293,21 @@ module SpecGuard
         end
       end
 
+      # Builds a transport from a {Configuration}, projecting the four settings
+      # every ingest writer forwards (endpoint, api_key, timeout, repository_id)
+      # so a new keyword is threaded in one place rather than in each writer.
+      #
+      # @param configuration [Configuration, #endpoint, #api_key, #timeout, #repository_id]
+      # @return [Transport]
+      def self.from_configuration(configuration)
+        new(
+          endpoint: configuration.endpoint,
+          api_key: configuration.api_key,
+          timeout: configuration.timeout,
+          repository_id: configuration.repository_id
+        )
+      end
+
       # @param endpoint [String, nil] the installation's base URL. Any trailing
       #   slashes are dropped; a path prefix is preserved, so an installation
       #   behind `https://tools.example.com/specguard` works.

data/lib/specguard/minitest/reporter.rb

@@ -9,6 +9,7 @@ require "fileutils"
 # loads them on a minitest-only consumer's machine.
 require_relative "../client"
 require_relative "../client/configuration"
+require_relative "../client/delivery_warning"
 
 # The annotation lookup is the third framework-free half: what counts as a
 # test's annotation is a property of the source line, not of the framework
@@ -244,12 +245,7 @@ module SpecGuard
 
       def transport_for
         require_relative "../client/transport"
-        SpecGuard::Client::Transport.new(
-          endpoint: @configuration.endpoint,
-          api_key: @configuration.api_key,
-          timeout: @configuration.timeout,
-          repository_id: @configuration.repository_id
-        )
+        SpecGuard::Client::Transport.from_configuration(@configuration)
       end
 
       def row_for(result)
@@ -404,21 +400,10 @@ module SpecGuard
       end
 
       # Report, not promise — see `#fall_back` for why that is the whole of
-      # this slice, and why the order above it did not move.
+      # this slice, and why the order above it did not move. The wording is
+      # shared with the RSpec formatter in {Client::DeliveryWarning}.
       def sink_clause(path, error)
-        return replay_clause(path) if error.nil?
-
-        "The replay queue #{path} could not be written either " \
-          "(#{error.class}: #{error.message}), so this run's telemetry was lost."
-      end
-
-      # The success arm (SPGD-1139): names the configured path (the one
-      # `#append` just wrote) and the replay command, word-for-word the
-      # formatter's clause. The lost-run arm names no command — nothing to
-      # replay.
-      def replay_clause(path)
-        "Falling back to #{path}; the test run is unaffected. " \
-          "Once the delivery is fixed, replay this run with: bundle exec specguard-ingest #{path}"
+        SpecGuard::Client::DeliveryWarning.sink_clause(path, error)
       end
 
       # Once per process, like the formatter's `warn_once`: fifty failing

data/lib/specguard/rspec/formatter.rb

@@ -48,6 +48,7 @@ require "fileutils"
 require_relative "../rspec"
 require_relative "../client/configuration"
 require_relative "../client/transport"
+require_relative "../client/delivery_warning"
 # Brings the linter's discovery chain with it (Scanner, Finding, Schema). That
 # direction is safe — `specguard/rspec` does not require `rspec/core`, so the
 # linter stays loadable without RSpec; it is only the reverse that would break
@@ -1037,12 +1038,7 @@ module SpecGuard
     end
 
     def transport_for(configuration)
-      SpecGuard::Client::Transport.new(
-        endpoint: configuration.endpoint,
-        api_key: configuration.api_key,
-        timeout: configuration.timeout,
-        repository_id: configuration.repository_id
-      )
+      SpecGuard::Client::Transport.from_configuration(configuration)
     end
 
     def blank?(value)
@@ -1201,22 +1197,10 @@ module SpecGuard
 
     # Report, not promise. Composed after the write so it can tell the operator
     # which of the two things actually happened — see {#fall_back} for why that
-    # is the whole of this slice, and why the order above it did not move.
+    # is the whole of this slice, and why the order above it did not move. The
+    # wording is shared with the Minitest reporter in {Client::DeliveryWarning}.
     def sink_clause(path, error)
-      return replay_clause(path) if error.nil?
-
-      "The replay queue #{path} could not be written either " \
-        "(#{error.class}: #{error.message}), so this run's telemetry was lost."
-    end
-
-    # The success arm (SPGD-1139): where the run sits AND the command that gets
-    # it back, fix-the-delivery first and replay after — the order the ingest
-    # CLI's own doctrine describes. The lost-run arm above deliberately names no
-    # command: with no queue written there is nothing to replay. Kept
-    # word-for-word identical to the Minitest reporter's clause.
-    def replay_clause(path)
-      "Falling back to #{path}; the test run is unaffected. " \
-        "Once the delivery is fixed, replay this run with: bundle exec specguard-ingest #{path}"
+      SpecGuard::Client::DeliveryWarning.sink_clause(path, error)
     end
 
     def emit_warning(line)

data/lib/specguard/version.rb

@@ -7,5 +7,5 @@
 # framework-scoped version constant a lie, so the number moved here and the
 # rspec module now points at it for back-compat.
 module SpecGuard
-  VERSION = "0.3.31"
+  VERSION = "0.3.33"
 end

data/script/bump-version.sh

@@ -58,9 +58,9 @@ if git rev-parse -q --verify "refs/tags/v$NEW_VERSION" >/dev/null || \
     exit 1
 fi
 if command -v curl >/dev/null 2>&1; then
-    if curl -fsS --max-time 10 "https://rubygems.org/api/v1/versions/specguard-rspec.json" 2>/dev/null \
+    if curl -fsS --max-time 10 "https://rubygems.org/api/v1/versions/specguard-ruby.json" 2>/dev/null \
        | grep -q "\"number\":\"$NEW_VERSION\""; then
-        echo "Error: specguard-rspec $NEW_VERSION is already published on RubyGems"
+        echo "Error: specguard-ruby $NEW_VERSION is already published on RubyGems"
         exit 1
     fi
 fi

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: specguard-ruby
 version: !ruby/object:Gem::Version
-  version: 0.3.31
+  version: 0.3.33
 platform: ruby
 authors:
 - specguard Agent
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-04 00:00:00.000000000 Z
+date: 2026-11-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -52,6 +52,7 @@ files:
 - lib/specguard/client/annotation_scanner.rb
 - lib/specguard/client/cli.rb
 - lib/specguard/client/configuration.rb
+- lib/specguard/client/delivery_warning.rb
 - lib/specguard/client/file_selector.rb
 - lib/specguard/client/finding.rb
 - lib/specguard/client/ingest_cli.rb