specguard-ruby 0.3.30 → 0.3.32

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 916a7326516ee737b20d0a0790fd6b6a0f1abe56404083ad67fe61d7d7fb5c46
-  data.tar.gz: 0b39ff94f46fb053ea659cb5f69f878bf86a3b04ed1e0e630394769bed0d6589
+  metadata.gz: 4e2f8dd966880d2075d3989184c5f9df89d702445edcdf88583c0b8976021a46
+  data.tar.gz: 4e5d985eda3fb38fc4832412585f6f389a5d9429c915bc9797d02d349576a713
 SHA512:
-  metadata.gz: 0d721e5d2d50648b3dfc7cf22ebbd2af16a9edd422feffa80b6d32d1092860c145ef6598919a802e3341a3eaa9fea6341fa26cab71f8abef33e0ff9d74d127b6
-  data.tar.gz: 77a24a2798088706388f6ef2ba7c6d4bd648d4fd152b1dcf55eb9e391409a0ece0ec3046d6b0b14bfaa24db03e68dac7e89d4eef340d6c34ba6b9512acdfda7a
+  metadata.gz: dfc1753a08f2e9c713c61ed12ac18b557f5e32fbaa3577735383ac6adea9bf237ff6374baf6fe276e6735c0e2da38344574c2ab6b02de1a8f42fe41c3fc51aa9
+  data.tar.gz: eca2722d9dcfa6117c21ee589b2b2afdfa422c9983a49d66ee80974574e33f8163f10c2ccab65345badef6dec01d94ad25b436980d5d87beb81b224c3c2c6d1b

data/README.md

@@ -474,6 +474,15 @@ export SPECGUARD_API_KEY=…          # from your repository's settings
 export SPECGUARD_TIMEOUT=10         # optional; seconds, applied to connect and read
 ```
 
+**Using an `sga_` agent key? Also set `SPECGUARD_REPOSITORY_ID`.** An agent key
+covers a set of repositories, so the key cannot say which one a run belongs to;
+the request has to. With `SPECGUARD_REPOSITORY_ID=42` the run is POSTed to
+`<endpoint>/api/v1/repositories/42/ingest` instead of `<endpoint>/api/v1/ingest`
+(`config.repository_id` in Ruby). Under a repository `sgk_` key leave it unset —
+if you do set it, the server ignores it. The id may contain only letters, digits,
+`-` and `_`; anything else is refused before a request is made. A `404` with an
+id configured means no repository with that id is available to the key.
+
 ```ruby
 # ...or in Ruby, if you would rather not use the environment
 SpecGuard.configure do |config|
@@ -515,6 +524,7 @@ offered to the endpoint and not accepted — so the run can be replayed later wi
 ```
 SpecGuard: could not deliver test telemetry (HTTP 401 — the API key was not
 accepted). Falling back to log/test_results.jsonl; the test run is unaffected.
+Once the delivery is fixed, replay this run with: bundle exec specguard-ingest log/test_results.jsonl
 ```
 
 **That line carries the endpoint's own words when it has any.** A `400` refusal
@@ -527,7 +537,8 @@ SpecGuard: could not deliver test telemetry (HTTP 400 — the endpoint rejected
 the payload — spec 3 (spec/orders_spec.rb:9): line_number is required and must
 be a positive integer; spec 7 (spec/orders_spec.rb:31): outcome must be one of
 passed, failed, pending). Falling back to log/test_results.jsonl; the test run
-is unaffected.
+is unaffected. Once the delivery is fixed, replay this run with: bundle exec
+specguard-ingest log/test_results.jsonl
 ```
 
 It stays **one** line whatever comes back. A systemic problem can have the
@@ -628,8 +639,9 @@ specguard-ingest: lines 1, 2 carried ci_run_id 17442 and each came back with
 test_run_id 41f2c9b8 — the endpoint folded them onto one run
 ```
 
-It reads the same `SPECGUARD_ENDPOINT`, `SPECGUARD_API_KEY` and
-`SPECGUARD_TIMEOUT` the formatter does, and sends each line through the same
+It reads the same `SPECGUARD_ENDPOINT`, `SPECGUARD_API_KEY`, `SPECGUARD_REPOSITORY_ID`
+(for `sga_` agent keys — a replay queue written under one is re-delivered to the same
+repository-scoped route) and `SPECGUARD_TIMEOUT` the formatter does, and sends each line through the same
 transport — so a run that was refused for a rotated key appears on the platform
 once the secret is fixed, with the shard folding described in
 [If you shard your suite](#if-you-shard-your-suite) applying exactly as it would
@@ -1212,9 +1224,11 @@ export SPECGUARD_ENDPOINT=https://specguard.internal.example.com
   nothing any other formatter wrote, is read or forwarded.
 - **No environment.** SpecGuard's own code reads a fixed list of variables and
   no others: the ones named in the envelope table above, which fill
-  `commit_sha`, `branch`, `ci_run_id` and `shard_id`; plus four that configure
+  `commit_sha`, `branch`, `ci_run_id` and `shard_id`; plus five that configure
   the gem itself rather than describing your suite — `SPECGUARD_ENDPOINT` (where
-  to send the run), `SPECGUARD_OUTPUT_PATH` (where to write the replay queue —
+  to send the run), `SPECGUARD_REPOSITORY_ID` (which repository an `sga_` agent
+  key's run belongs to — sent as a path segment of the request URL, nothing else),
+  `SPECGUARD_OUTPUT_PATH` (where to write the replay queue —
   runs the endpoint refused or could not be reached for), `SPECGUARD_LOCAL_OUTPUT_PATH`
   (where to write the local development record when there is no key),
   `SPECGUARD_TIMEOUT` (how long to wait), and

data/lib/specguard/client/configuration.rb

@@ -318,6 +318,7 @@ module SpecGuard
       LOCAL_OUTPUT_PATH_KEYS = %w[SPECGUARD_LOCAL_OUTPUT_PATH].freeze
       ENDPOINT_KEYS = %w[SPECGUARD_ENDPOINT].freeze
       API_KEY_KEYS = %w[SPECGUARD_API_KEY].freeze
+      REPOSITORY_ID_KEYS = %w[SPECGUARD_REPOSITORY_ID].freeze
       TIMEOUT_KEYS = %w[SPECGUARD_TIMEOUT].freeze
 
       # The commit the suite ran against. `nil` when nothing said.
@@ -344,7 +345,9 @@ module SpecGuard
       attr_accessor :local_output_path
       # The SpecGuard installation to POST to, scheme and host only:
       # `https://specguard.example.com`. The `/api/v1/ingest` path is the
-      # platform's contract, not a setting. `nil` when nothing said.
+      # platform's contract, not a setting — with one exception: when
+      # {#repository_id} is set the path is `/api/v1/repositories/<id>/ingest`
+      # instead. `nil` when nothing said.
       attr_accessor :endpoint
       # The repository's SpecGuard API key. Present means "deliver over HTTP".
       #
@@ -354,6 +357,16 @@ module SpecGuard
       # nobody can retroactively fix. Send whatever is configured and let a 401
       # be the answer.
       attr_accessor :api_key
+      # The repository the run belongs to, sent as a path segment
+      # (`/api/v1/repositories/<id>/ingest`). Needed by an `sga_` agent key,
+      # which covers a set of repositories and so cannot name the run's
+      # repository itself; under an `sgk_` key the platform ignores it. `nil`
+      # when unset or blank, which keeps the plain `/api/v1/ingest` path.
+      #
+      # Deliberately **not** format-checked against the key prefix or a numeric
+      # shape (same reasoning as {#api_key}): the platform's 400/403/404 is the
+      # answer. {Transport} only refuses ids that are unsafe as a path segment.
+      attr_accessor :repository_id
       # Seconds, applied to opening the connection and to reading the response.
       attr_accessor :timeout
 
@@ -374,6 +387,7 @@ module SpecGuard
         @local_output_path = first_present(env, LOCAL_OUTPUT_PATH_KEYS) || DEFAULT_LOCAL_OUTPUT_PATH
         @endpoint = first_present(env, ENDPOINT_KEYS)
         @api_key = first_present(env, API_KEY_KEYS)
+        @repository_id = first_present(env, REPOSITORY_ID_KEYS)
         @timeout = seconds(first_present(env, TIMEOUT_KEYS)) || DEFAULT_TIMEOUT_SECONDS
       end
 

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)
+        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

@@ -127,6 +127,21 @@ module SpecGuard
       # Part of the platform's contract, so it is not configurable — the
       # `endpoint` setting is the installation's address and nothing more.
       PATH = "/api/v1/ingest"
+
+      # The repository-scoped form of the same endpoint (`post "ingest"` nested
+      # under `resources :repositories`). It exists because an `sga_` agent key
+      # covers a SET of repositories, so the credential cannot name the run's
+      # repository and the request has to, as a path segment. `%s` is only ever
+      # filled with an id that passed {REPOSITORY_ID_PATTERN}. Under an `sgk_`
+      # key the server ignores the segment, so {PATH} stays the default.
+      REPOSITORY_PATH = "/api/v1/repositories/%s/ingest"
+
+      # What a repository id may look like before it becomes a path segment.
+      # Deliberately not "digits": the platform's ids are numeric today and the
+      # gem must not bake that in. Dots are excluded outright, which is what
+      # refuses `..` (percent-escaping would not neutralise a dot segment), and
+      # `/`, `?`, `#` can never survive as path structure.
+      REPOSITORY_ID_PATTERN = /\A[0-9A-Za-z_-]+\z/
       CONTENT_TYPE = "application/json"
       USER_AGENT = "specguard-ruby/#{SpecGuard::VERSION}"
       CONTENT_ENCODING = "gzip"
@@ -167,7 +182,12 @@ module SpecGuard
       # same reason turned around: a 202 whose body will not parse is still an
       # acceptance, and relabelling it would tell the operator something untrue
       # about a run the platform has already stored. See {#test_run_id}.
-      Result = Struct.new(:outcome, :code, :error, :reasons, :body, keyword_init: true) do
+      #
+      # `repository_scoped` is true when the request went to the repository-
+      # scoped route. It only changes the 404 sentence: under that route a 404
+      # means no repository with that id is available to this key, not a wrong
+      # URL. Nil/false (every pre-existing `Result.new`) keeps today's wording.
+      Result = Struct.new(:outcome, :code, :error, :reasons, :body, :repository_scoped, keyword_init: true) do
         # The status codes worth spelling out, because each implies a different
         # thing for the reader to *do*. A 401 means "rotate or fix the key"; a
         # 400 means "the payload this gem built was refused", which is a bug
@@ -193,6 +213,10 @@ module SpecGuard
         # tells the reader how widespread it is.
         MAX_RENDERED_REASONS = 3
 
+        # The 404 sentence when a repository id was sent. See `repository_scoped`.
+        REPOSITORY_NOT_FOUND_ADVICE =
+          "no repository with that id is available to this API key — check SPECGUARD_REPOSITORY_ID"
+
         # Ceiling on the spelled-out reasons, before the `and N more` tail,
         # which is appended afterwards so the count can never be the thing that
         # gets truncated away.
@@ -224,13 +248,19 @@ module SpecGuard
         def reason
           case outcome
           when :success then nil
-          when :rejected then [+"HTTP #{code}", ADVICE[code], rendered_reasons].compact.join(" — ")
+          when :rejected then [+"HTTP #{code}", advice, rendered_reasons].compact.join(" — ")
           else "#{error.class}: #{error.message}"
           end
         end
 
         private
 
+        def advice
+          return REPOSITORY_NOT_FOUND_ADVICE if code == 404 && repository_scoped
+
+          ADVICE[code]
+        end
+
         # The refusal, bounded and flattened to fit on the one line. `nil` when
         # there is nothing readable to add, which is what keeps the bare
         # `HTTP 400 — the endpoint rejected the payload` intact for every body
@@ -263,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.
@@ -270,9 +315,15 @@ module SpecGuard
       # @param timeout [Numeric, String, nil] seconds. Anything that is not a
       #   positive finite number falls back to the default rather than raising:
       #   a typo in `SPECGUARD_TIMEOUT` must not be able to fail a suite.
-      def initialize(endpoint:, api_key:, timeout: Configuration::DEFAULT_TIMEOUT_SECONDS)
+      # @param repository_id [String, Integer, nil] when present, POST to the
+      #   repository-scoped route an `sga_` agent key needs. nil/blank keeps the
+      #   `sgk_` path byte-identical. An id outside {REPOSITORY_ID_PATTERN} makes
+      #   {#uri} raise `ArgumentError`.
+      def initialize(endpoint:, api_key:, timeout: Configuration::DEFAULT_TIMEOUT_SECONDS, repository_id: nil)
         @endpoint = endpoint
         @api_key = api_key
+        @repository_id = repository_id.to_s.strip
+        @repository_id = nil if @repository_id.empty?
         @timeout = sanitize_timeout(timeout)
       end
 
@@ -301,7 +352,8 @@ module SpecGuard
         return Result.new(outcome: :success, code: code, body: success_body(response)) if
           response.is_a?(Net::HTTPSuccess)
 
-        Result.new(outcome: :rejected, code: code, reasons: refusal_reasons(response))
+        Result.new(outcome: :rejected, code: code, reasons: refusal_reasons(response),
+                   repository_scoped: !@repository_id.nil?)
       rescue ScriptError, StandardError => e
         # Connection refused, DNS failure, TLS failure, open/read timeout, a
         # malformed endpoint — one family, one shape. `ScriptError` is in the
@@ -427,7 +479,7 @@ module SpecGuard
         base = @endpoint.to_s.strip
         raise ArgumentError, "no endpoint is configured (set SPECGUARD_ENDPOINT)" if base.empty?
 
-        parsed = URI.parse(base.sub(%r{/+\z}, "") + PATH)
+        parsed = URI.parse(base.sub(%r{/+\z}, "") + ingest_path)
         # `URI::HTTPS < URI::HTTP`, so this admits both and rejects the
         # scheme-less `specguard.example.com` that `URI.parse` happily returns
         # as a `URI::Generic` with a nil host — which `Net::HTTP` would then
@@ -438,6 +490,17 @@ module SpecGuard
         parsed
       end
 
+      def ingest_path
+        return PATH if @repository_id.nil?
+
+        unless REPOSITORY_ID_PATTERN.match?(@repository_id)
+          raise ArgumentError,
+                "SPECGUARD_REPOSITORY_ID must contain only letters, digits, '-' and '_', got #{@repository_id.inspect}"
+        end
+
+        format(REPOSITORY_PATH, @repository_id)
+      end
+
       def sanitize_timeout(value)
         parsed = Float(value, exception: false)
         return Configuration::DEFAULT_TIMEOUT_SECONDS unless parsed&.finite? && parsed.positive?

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,11 +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
-        )
+        SpecGuard::Client::Transport.from_configuration(@configuration)
       end
 
       def row_for(result)
@@ -403,12 +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 "Falling back to the replay queue. The test run is unaffected." if error.nil?
-
-        "The replay queue #{path} could not be written either " \
-          "(#{error.class}: #{error.message}), so this run's telemetry was lost."
+        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,11 +1038,7 @@ module SpecGuard
     end
 
     def transport_for(configuration)
-      SpecGuard::Client::Transport.new(
-        endpoint: configuration.endpoint,
-        api_key: configuration.api_key,
-        timeout: configuration.timeout
-      )
+      SpecGuard::Client::Transport.from_configuration(configuration)
     end
 
     def blank?(value)
@@ -1200,12 +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 "Falling back to #{path}; the test run is unaffected." if error.nil?
-
-      "The replay queue #{path} could not be written either " \
-        "(#{error.class}: #{error.message}), so this run's telemetry was lost."
+      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.30"
+  VERSION = "0.3.32"
 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.30
+  version: 0.3.32
 platform: ruby
 authors:
 - specguard Agent
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-02 00:00:00.000000000 Z
+date: 2026-10-07 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