specguard-rspec 0.2.1

data/lib/specguard/rspec/schema.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "json"
+require "json_schemer"
+
+module SpecGuard
+  module RSpec
+    # The vendored OpenTestIntent schema could not be loaded.
+    #
+    # Deliberately *not* a {UsageError} even though both map to exit 2: this is
+    # the linter being broken, not the caller misusing it, and the message
+    # wording follows the reference tool rather than the CLI's own. Keeping the
+    # two distinct is what lets the CLI print
+    # `error: could not load schema <path>: ...` — byte-parity with
+    # `bin/validate-intent:858-862` — for one and `specguard-lint: error: ...`
+    # for the other.
+    class SchemaError < Error; end
+
+    # The OpenTestIntent v1 schema, loaded and applied.
+    #
+    # == Why loading failure is exit 2 and not exit 1
+    #
+    # The exit contract (SPGD-12 §1) spends `1` on "an annotation is
+    # malformed". If a packaging accident leaves the vendored schema out of the
+    # gem, the obvious Ruby implementation lets the exception escape and Ruby
+    # exits 1 — so CI reports a malformed annotation and a developer goes
+    # hunting for a bad annotation that does not exist. The reference tool
+    # already ruled on this:
+    #
+    #     except (OSError, json.JSONDecodeError) as exc:
+    #         print("error: could not load schema %s: %s" % (SCHEMA_PATH, exc), file=sys.stderr)
+    #         return 2
+    #     # open-test-intent, bin/validate-intent:858-862
+    #
+    # Hence {SchemaError}: every way loading can fail is caught here and
+    # retyped, so the CLI can map the whole class of them to 2 without
+    # inspecting exception classes from three different libraries.
+    #
+    # The CLI loads this **before** it scans anything, so a broken schema can
+    # never produce a run that reports "0 malformed" having validated nothing.
+    class Schema
+      # @param path [String] the vendored schema
+      # @return [Schema]
+      # @raise [SchemaError] if it cannot be read, parsed, or compiled
+      def self.load(path = SCHEMA_PATH)
+        document = ::JSON.parse(File.read(path, encoding: "UTF-8"))
+        new(document: document, path: path)
+      rescue StandardError => e
+        # Intentionally broad. Reading can raise SystemCallError/IOError,
+        # parsing JSON::ParserError, and compiling or meta-validating whatever
+        # json_schemer decides an unusable schema document deserves. All of
+        # them mean the same thing to the caller, and all of them must be 2
+        # rather than an uncaught exception's 1.
+        raise SchemaError, "could not load schema #{path}: #{e.message}"
+      end
+
+      attr_reader :document, :path
+
+      def initialize(document:, path: SCHEMA_PATH, renderer: ViolationRenderer.new)
+        @document = document
+        @path = path
+        @renderer = renderer
+        @schemer = JSONSchemer.schema(document)
+        reject_unusable_schema!
+      end
+
+      # @param intent [Object] one parsed annotation
+      # @return [Array<String>] reason lines in the reference tool's grammar
+      #   and order; empty means the annotation is valid
+      #
+      # The **validator** decides the verdict; the renderer only decides the
+      # wording. Deriving "is this annotation valid?" from "could we phrase a
+      # sentence about it?" would make an unphrasable violation and a clean
+      # annotation the same state — and under {Linter} that state is a green
+      # run, which is this project's signature vacuous green (KB SPGD-78)
+      # arriving through the one door the whole rendering strategy exists to
+      # close. The gemspec pins `~> 2.5`, which admits 2.6 and beyond; the
+      # renderer is built from structured fields precisely so a bump degrades
+      # to *wrong-looking text* rather than to silence, and this is what keeps
+      # that promise true for error shapes it has never seen.
+      def violations(intent)
+        errors = @schemer.validate(intent).to_a
+        return [] if errors.empty?
+
+        rendered = @renderer.render(errors, intent)
+        rendered.empty? ? errors.map { |error| unrenderable_reason(error) } : rendered
+      end
+
+      private
+
+      # Last resort: json_schemer's own sentence, and failing even that, the
+      # error's structure. Both are worse output than the reference grammar.
+      # Both are enormously better than reporting the annotation as clean.
+      def unrenderable_reason(error)
+        error["error"] || "does not match the schema at #{error['schema_pointer']}"
+      end
+
+      # Checks the vendored document against draft-07's own meta-schema before
+      # anything is validated against it.
+      #
+      # This is not belt-and-braces, it closes a real hole. json_schemer is
+      # permissive about nonsense in a *schema*: given `{"type": 42}` it
+      # compiles happily and then treats the keyword as absent — so a schema
+      # file corrupted in a way that still parses as JSON produces a linter
+      # that **accepts every annotation** and reports a clean run. That is this
+      # project's signature vacuous-green defect (KB SPGD-78) arriving through
+      # the back door, and it is worse than a crash because it looks like
+      # success.
+      #
+      # Some malformations are lazier still — `{"required": "nope"}` compiles,
+      # passes nothing, and raises NoMethodError from inside the first
+      # `#validate`. Meta-validating here converts that whole family into a
+      # SchemaError at load time, which the CLI reports as
+      # `error: could not load schema ...` and exits 2 on.
+      def reject_unusable_schema!
+        return if @schemer.valid_schema?
+
+        raise Error, "not a valid draft-07 schema (#{@schemer.validate_schema.first&.fetch('error')})"
+      end
+    end
+  end
+end

data/lib/specguard/rspec/schemas/open-test-intent.v1.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://specguard.dev/schemas/open-test-intent.v1.json",
+  "title": "OpenTestIntent v1",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "entity":        { "type": "string", "minLength": 2 },
+    "action":        { "type": "string", "minLength": 2 },
+    "behavior":      { "type": "string", "minLength": 15 },
+    "layer":         { "type": "string", "enum": ["unit", "integration", "request", "system"] },
+    "preconditions": { "type": "array", "items": { "type": "string" } }
+  },
+  "required": ["entity", "action", "behavior", "layer"]
+}

data/lib/specguard/rspec/transport.rb

@@ -0,0 +1,310 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+require "zlib"
+
+require_relative "configuration"
+require_relative "version"
+
+module SpecGuard
+  module RSpec
+    # The one HTTP call this gem makes: `POST <endpoint>/api/v1/ingest`,
+    # carrying a whole run.
+    #
+    # == Why this returns a result instead of raising
+    #
+    # {SpecGuard::RSpecFormatter}'s never-block-CI guard is a `rescue` around
+    # each hook, and a `rescue` is structurally blind to the failure that
+    # matters most here: `Net::HTTP` hands back `Net::HTTPUnauthorized` as an
+    # ordinary return value. A wrong API key therefore raises nothing, warns
+    # nothing and logs nothing — the run's telemetry disappears in complete
+    # silence, which is precisely the outcome the client-gem spec's "if the API
+    # key is wrong … it logs a warning to stderr" forbids.
+    #
+    # So the two failure families are made the same *shape* rather than left to
+    # two different mechanisms: {#deliver} answers a {Result} for a non-2xx
+    # response and a {Result} for a raised exception, and the caller has one
+    # thing to check. Nothing escapes this class except `Interrupt`,
+    # `SignalException` and `SystemExit` — Ctrl-C must stay Ctrl-C.
+    #
+    # == One request per process, gzipped once it is big enough
+    #
+    # A run goes in a single POST, and the body is compressed above a size
+    # threshold. Both halves are decisions rather than defaults, and the
+    # roadmap asked for them to be made deliberately rather than discovered in
+    # production, so they are written down here.
+    #
+    # === Batching: no, and this is settled
+    #
+    #   * `Ingest::Payload` derives `total_specs_count` from the specs of *that*
+    #     request. Splitting a run across N POSTs with no way to say they are
+    #     one run would produce N `TestRun` rows with a split denominator,
+    #     corrupting the headline annotated-ratio metric.
+    #   * That is qualified rather than absolute, and the qualification is
+    #     `ci_run_id` + `shard_id`. The platform folds every POST carrying the
+    #     same run id onto one `TestRun`, keyed by shard so a slice that arrives
+    #     twice replaces itself, which is what makes a *sharded* run — N
+    #     processes, N POSTs, one run — land as one row. So the rule this class
+    #     keeps is narrower than it was: **one process sends one request.**
+    #   * Batching a single process's own run into several POSTs stays wrong,
+    #     and not only for the denominator: every part would carry the same
+    #     `shard_id`, so the parts would overwrite one another and the row would
+    #     keep only the last. Fixing that means a new part-of-a-shard concept on
+    #     the platform, which is a schema change bought to solve a problem that
+    #     compression already solved.
+    #
+    # === Streaming: no, for the same reason, and the reason is measured
+    #
+    # The pressure that made batching and streaming look necessary was size,
+    # and size is now a number rather than a worry. Measured by running a real
+    # 200-file / 20,000-example suite through this gem's own formatter, half of
+    # the examples annotated:
+    #
+    #   identity   7,354,782 bytes   7.01 MiB    needs 5.9 Mbit/s to write in 10s
+    #   gzip         346,206 bytes   0.33 MiB    needs 0.3 Mbit/s
+    #   ratio           21.2x        95.3% saved       60 ms to compress
+    #
+    # Uncompressed, that body has to be *written* inside
+    # `Configuration::DEFAULT_TIMEOUT_SECONDS` (10). At 5 Mbit/s of uplink it
+    # takes 11.8s and fails as a `write_timeout`; the run then lands in
+    # `log/test_results.jsonl` and the platform never sees it. Compressed, the
+    # same run takes 0.55s on that link and 2.8s on a 1 Mbit/s one. The 60 ms
+    # spent compressing is noise against a suite that took minutes.
+    #
+    # Two honesties about that ratio. It is *below* the 35x this change was
+    # proposed on, because SPGD-159 has since added `id` and `spec_file_path`
+    # to every row — re-measure rather than quote, is the lesson. And it is
+    # probably *above* what a real suite gets: synthetic example names repeat
+    # more than human ones do, so treat 21x as the optimistic end. Nothing here
+    # depends on the exact figure. Even a pessimistic 5x moves the 20k case
+    # from "cannot ship on a slow link" to "ships with room to spare", and
+    # 0.33 MiB is not a payload anyone needs to chunk.
+    #
+    # So: compression yes, batching and streaming no. Recorded rather than left
+    # implicit — an undocumented decision is one that gets re-opened in six
+    # months by someone who cannot tell it was ever made.
+    #
+    # === Why a threshold rather than always
+    #
+    # Below {GZIP_THRESHOLD_BYTES} the round trip buys nothing worth paying for
+    # in opacity: a small run stays identity-encoded, so it is still readable
+    # with `curl` and `tcpdump`, and the local-file and stub-server paths still
+    # show a human a JSON body. Compression is for the case that could not ship
+    # at all, not a uniform policy.
+    #
+    # Compression also sits *inside* the never-block-CI contract. A `Zlib`
+    # failure falls back to the identity body — which the platform still
+    # accepts — rather than raising: a run must not be lost to an optimisation.
+    #
+    # === The version floor this creates, which is a deploy order and not a merge order
+    #
+    # Sending `Content-Encoding: gzip` requires a platform that can inflate one,
+    # and that arrived with `GzipRequestBody` (SPGD-175). "Merge the platform PR
+    # first" is the half of this that is easy to say and is *not* sufficient:
+    # merge order only settles the source trees. What this gem actually talks to
+    # is a **deployment**.
+    #
+    # So a gem at this version pointed at an installation deployed before
+    # `GzipRequestBody` will 400 every run over {GZIP_THRESHOLD_BYTES} — the
+    # inflater is not there, the body reaches the JSON parser still gzipped, and
+    # `Api::V1::IngestsController` refuses it. {#deliver} answers
+    # `Result(outcome: :rejected, code: 400)`; there is no retry-as-identity, so
+    # the formatter falls back to `log/test_results.jsonl` and the run is lost
+    # to the platform. That is precisely the failure this change exists to
+    # close, reintroduced for precisely the large suites it targets — and it is
+    # silent apart from one stderr line, because CI still goes green.
+    #
+    # Written down rather than fixed, deliberately. A 400-triggered retry with
+    # the identity body would paper over it, but it doubles the request count on
+    # every genuinely-malformed payload and makes a client-side bug look like a
+    # flake; that is a contract decision, not a detail to slip in here. The
+    # honest statement of the constraint is a version floor: **this gem requires
+    # a platform deployment that includes `GzipRequestBody`.**
+    class Transport
+      # `config/routes.rb` mounts `post "ingest"` under the `/api/v1` scope.
+      # 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"
+      CONTENT_TYPE = "application/json"
+      USER_AGENT = "specguard-rspec/#{SpecGuard::RSpec::VERSION}"
+      CONTENT_ENCODING = "gzip"
+
+      # Bodies at least this large are gzipped; smaller ones go identity. See
+      # the class comment for why this is a threshold and not a switch.
+      #
+      # 256 KiB is roughly where the round trip starts paying — a few thousand
+      # examples. It is a judgement call, not a measured optimum, and the only
+      # thing that depends on the exact number is how large a run has to be
+      # before `curl` stops showing you a readable body.
+      GZIP_THRESHOLD_BYTES = 256 * 1024
+
+      # What the ingest endpoint said, in the one form the caller has to handle.
+      #
+      # `outcome` is one of:
+      #
+      #   :success   a 2xx. `code` carries it (202 in the happy path).
+      #   :rejected  a non-2xx. `code` carries it; nothing was raised.
+      #   :failed    an exception was raised. `error` carries it.
+      Result = Struct.new(:outcome, :code, :error, 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
+        # report and not a credentials problem. Printing a bare number would
+        # leave a CI operator to guess which of the two they are looking at.
+        ADVICE = {
+          400 => "the endpoint rejected the payload",
+          401 => "the API key was not accepted",
+          403 => "this API key may not write to that repository",
+          404 => "no ingest endpoint at that URL — check SPECGUARD_ENDPOINT",
+          413 => "the payload was too large for the endpoint",
+          429 => "rate limited by the endpoint"
+        }.freeze
+
+        def success? = outcome == :success
+
+        # A single clause naming what went wrong, for the one stderr line a run
+        # is allowed. `nil` on success, because there is nothing to say.
+        #
+        # @return [String, nil]
+        def reason
+          case outcome
+          when :success then nil
+          when :rejected then [+"HTTP #{code}", ADVICE[code]].compact.join(" — ")
+          else "#{error.class}: #{error.message}"
+          end
+        end
+      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.
+      # @param api_key [String, nil] sent verbatim as a Bearer token.
+      # @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)
+        @endpoint = endpoint
+        @api_key = api_key
+        @timeout = sanitize_timeout(timeout)
+      end
+
+      attr_reader :timeout
+
+      # Where this transport would POST.
+      #
+      # @return [URI::HTTP]
+      # @raise [ArgumentError] when the endpoint is missing or is not an
+      #   http(s) URL. Raised rather than returned because {#deliver} converts
+      #   it into a {Result} like every other failure, and a caller asking for
+      #   the URI directly wants to know.
+      def uri
+        @uri ||= build_uri
+      end
+
+      # @param payload [Hash] the run, as {SpecGuard::RSpecFormatter#payload}
+      #   assembles it. Sent as-is: its key names are already the platform's
+      #   ingest contract, and reshaping it here would put the wire format two
+      #   files away from the code that decides it.
+      # @return [Result] never nil, never raised through.
+      def deliver(payload)
+        response = post(JSON.generate(payload))
+        code = response.code.to_i
+
+        return Result.new(outcome: :success, code: code) if response.is_a?(Net::HTTPSuccess)
+
+        Result.new(outcome: :rejected, code: code)
+      rescue ScriptError, StandardError => e
+        # Connection refused, DNS failure, TLS failure, open/read timeout, a
+        # malformed endpoint — one family, one shape. `ScriptError` is in the
+        # list for the same reason the formatter's guard names it: an autoload
+        # blowing up under `net/http` is not a `StandardError`, and a bare
+        # rescue would let it escape and take the suite's exit code with it.
+        Result.new(outcome: :failed, error: e)
+      end
+
+      private
+
+      def post(body)
+        target = uri
+
+        http = Net::HTTP.new(target.host, target.port)
+        http.use_ssl = target.scheme == "https"
+        # All three, not just the two the spec names. Compression takes a
+        # 20k-example run from 7.01 MiB to 0.33 MiB, which is what puts the
+        # write comfortably inside the budget rather than past it — but a peer
+        # that accepts the connection and then stops reading still hangs in the
+        # *write* whatever the body's size, so the timeout is the thing that
+        # bounds it. Same unbounded wait, reached by a different door.
+        http.open_timeout = @timeout
+        http.read_timeout = @timeout
+        http.write_timeout = @timeout
+
+        http.start { |connection| connection.request(build_request(target, body)) }
+      end
+
+      def build_request(target, body)
+        request = Net::HTTP::Post.new(target.request_uri)
+        # `Api::BaseController#bearer_token` matches /\ABearer\s+(?<token>.+)\z/i.
+        request["Authorization"] = "Bearer #{@api_key}"
+        # Describes the body *inside* any encoding, which is what
+        # `Content-Type` means — the platform's `GzipRequestBody` inflates and
+        # then hands an ordinary JSON request downstream.
+        request["Content-Type"] = CONTENT_TYPE
+        request["Accept"] = CONTENT_TYPE
+        request["User-Agent"] = USER_AGENT
+
+        compressed = compress(body)
+        request["Content-Encoding"] = CONTENT_ENCODING if compressed
+        # `Net::HTTP::Post#body=` sets `Content-Length` from what it is given,
+        # so the length always describes the bytes actually on the wire.
+        request.body = compressed || body
+        request
+      end
+
+      # The compressed body, or `nil` to mean "send it as it is" — for a run
+      # under the threshold and, deliberately, for a compression that failed.
+      #
+      # Returning `nil` on failure rather than letting it out is the whole
+      # point: an identity body is something the platform accepts, so a broken
+      # `Zlib` costs a large run some bandwidth and nothing else. Letting the
+      # error reach {#deliver} would turn it into `Result(outcome: :failed)`
+      # and lose the run to a *saving*.
+      #
+      # `ScriptError, StandardError` matches {#deliver}'s own guard rather than
+      # naming `Zlib::Error`: the failure worth catching here is as likely to be
+      # the `zlib` extension missing from a stripped-down Ruby, which is a
+      # `LoadError` and so a `ScriptError`, as it is a compression fault.
+      def compress(body)
+        return nil if body.bytesize < GZIP_THRESHOLD_BYTES
+
+        Zlib.gzip(body)
+      rescue ScriptError, StandardError
+        nil
+      end
+
+      def build_uri
+        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)
+        # `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
+        # try to connect to.
+        raise ArgumentError, "endpoint must be an http:// or https:// URL, got #{base.inspect}" unless
+          parsed.is_a?(URI::HTTP) && !parsed.host.to_s.empty?
+
+        parsed
+      end
+
+      def sanitize_timeout(value)
+        parsed = Float(value, exception: false)
+        return Configuration::DEFAULT_TIMEOUT_SECONDS unless parsed&.finite? && parsed.positive?
+
+        parsed
+      end
+    end
+  end
+end