specguard-ruby 0.3.1

data/lib/specguard/rspec/ingest_reporter.rb

@@ -0,0 +1,280 @@
+# frozen_string_literal: true
+
+require "json"
+
+module SpecGuard
+  module RSpec
+    # `specguard-ingest --json`: the machine-readable renderer over the same
+    # per-line facts the human report is built from.
+    #
+    # == Why a second renderer, on the one command that most needed it
+    #
+    # An HTTP 400 is the only *permanent* verdict in this command's contract
+    # ({IngestCLI::CONTENT_REFUSAL_CODES}) — a refused line is refused every
+    # time it is offered — so the only way to land the run is to learn which
+    # specs the platform objected to and fix the payload. The platform sends one
+    # error per offending spec, each naming it by index, file and line
+    # (`Ingest::Payload#label`, and `Api::BaseController#render_bad_request`
+    # puts every one of them on the wire). {Transport::Result} keeps the whole
+    # array, and then {Transport::Result#reason} renders three of them,
+    # truncated to 300 characters, because it is built for the **one stderr
+    # line an in-run CI warning is allowed**.
+    #
+    # That cap is right where it was set and is not touched here. It is a cap on
+    # a *line*, and this document is not a line: `specguard-ingest` already
+    # prints a row per line, a summary and its folding observations, out of band
+    # and nowhere near a CI log. So the refusal's own grounds do not reach a
+    # second channel, and this is that channel — the command whose entire job is
+    # to fix and re-send a refused run can now show you all of why it was
+    # refused.
+    #
+    # This is SPGD-305 done again for the gem's other executable, and it is a
+    # RENDERER: it reads the {IngestCLI::LineResult}s the delivery already
+    # produced and the {IngestCLI::ListedLine}s the listing already extracted,
+    # and decides nothing. The exit code, the statuses, the selection and the
+    # cap are all upstream of here and identical on both paths.
+    #
+    # == Why it is NOT `json_reporter.rb`
+    #
+    # {JSONReporter} is the *lint* document over `Linter::Result`, and it mirrors
+    # `validate-intent --json --source` key for key on purpose: the gem consumes
+    # that document, so the two must not need two parsers. This one is about
+    # **deliveries**, not annotations. It therefore does not claim that
+    # document's `"schema" => "open-test-intent.v1.json"` or its
+    # `"mode" => "source"` — naming a schema this document has nothing to do
+    # with would assert a conformance it cannot have. `"tool"` says what wrote
+    # it instead.
+    #
+    # == There is no `ok` and no `exit_code` in the document
+    #
+    # Deliberately, and this is the one place the two renderers differ in kind
+    # rather than in form. {JSONReporter} carries an `ok` because a linter's
+    # verdict is a boolean. This command's is not: 0, 1 and 2 mean "accepted",
+    # "the platform refused content" and "this tool could not do its job", and
+    # collapsing that to a boolean would have to pick which of 1 and 2 counts as
+    # false — the exact confusion {IngestCLI}'s class comment is arranged
+    # against. Restating the integer here would be a second copy of a fact the
+    # process already exits with, free to drift from it. So the exit status
+    # stays the one carrier of the verdict, unchanged by this flag, and the
+    # document carries the facts it is computed from.
+    #
+    # == Which runs emit a document
+    #
+    # By cause, not by exit code. {JSONReporter}'s rule — a run that checked
+    # nothing must not emit `{"findings": []}`, because that is how a gate that
+    # checked nothing gets mistaken for one that found nothing — transfers, but
+    # it does not transfer as "no exit-2 run emits a document": this command
+    # reaches 2 with a *real* report on a file whose lines were delivered and
+    # one of them never arrived.
+    #
+    # So the line is drawn where the file was: a run that got as far as reading
+    # <file> emits a document, whatever its exit code and even when the file
+    # held nothing to deliver (`"lines": []` next to a `summary` of zeroes is a
+    # true statement about an empty file, and the warning naming *why* it was
+    # empty is on stderr either way). A run that never got that far — a bad
+    # flag, `--from-line` with `--lines`, no endpoint or API key, a file that
+    # cannot be read — emits prose on stderr and nothing at all on stdout,
+    # because there is nothing yet to be a document about.
+    #
+    # == The counts are handed in, not recomputed
+    #
+    # `summary`'s status counts are the ones {IngestCLI} computes once for
+    # whichever renderer runs, for {JSONReporter}'s reason: two renderers of one
+    # result list that can disagree about how much of a file was delivered are
+    # worse than prose alone, because the disagreement is unfalsifiable from
+    # outside the process. That holds on the listing path too, where the only
+    # count that can be positive is `unparseable` and the text summary states no
+    # counterpart to disagree with — it is handed in anyway, so the discipline
+    # is structural at both entry points rather than true of one by luck. The
+    # folding observations are the same shape of thing — one grouping, rendered
+    # here as data and there as a sentence.
+    module IngestReporter
+      # What wrote the document. Not a schema id: see the class comment.
+      TOOL = "specguard-ingest"
+
+      # Whether lines were sent or only shown. The distinction a consumer most
+      # needs, because it decides whether the status counts below are verdicts
+      # or zeroes — see {#summary}'s `attempted`.
+      MODE_DELIVER = "deliver"
+      MODE_LIST = "list"
+
+      # A listed line that is a run. Its delivery-side counterparts are
+      # {IngestCLI::STATUS_LABELS}' keys, rendered by name (`undelivered`, not
+      # the prose renderer's `not delivered`) so a consumer branches on the
+      # tool's vocabulary rather than on its wording.
+      STATUS_LISTED = "listed"
+      STATUS_UNPARSEABLE = "unparseable"
+
+      # @param source [IngestCLI::Source] the file, its blanks and its skips
+      # @param results [Array<IngestCLI::LineResult>] one per line delivered,
+      #   in the file's order
+      # @param counts [Hash{Symbol=>Integer}] status counts, computed once by
+      #   {IngestCLI} for both renderers
+      # @param foldings [Array<IngestCLI::Folding>] the folding observations,
+      #   grouped once for both renderers
+      # @return [String] one JSON document, without a trailing newline
+      def self.render_delivery(source:, results:, counts:, foldings:)
+        document(
+          mode: MODE_DELIVER,
+          source: source,
+          lines: results.map { |result| delivered(result) },
+          summary: summary(source, lines: results.length, counts: counts, attempted: attempted(counts)),
+          foldings: foldings.map { |folding| folded(folding) }
+        )
+      end
+
+      # @param source [IngestCLI::Source]
+      # @param lines [Array<IngestCLI::ListedLine>] the envelope facts the text
+      #   listing prints, extracted once for both renderers
+      # @param counts [Hash{Symbol=>Integer}] status counts, computed once by
+      #   {IngestCLI} for both renderers — `unparseable` is the only one a
+      #   listing can carry
+      # @return [String] one JSON document, without a trailing newline
+      def self.render_listing(source:, lines:, counts:)
+        # Every delivery status is 0 and `attempted` is 0, which is this
+        # document's way of saying what the text listing says in words:
+        # nothing was delivered. `unparseable` is the one that can be positive,
+        # because a line that is not a run is knowable without sending it — and
+        # it is stated for the reason the text row states it, so a preview
+        # cannot under-report what the delivery would do.
+        document(
+          mode: MODE_LIST,
+          source: source,
+          lines: lines.map { |line| listed(line) },
+          summary: summary(source, lines: lines.length, attempted: 0, counts: counts),
+          foldings: []
+        )
+      end
+
+      def self.document(mode:, source:, lines:, summary:, foldings:)
+        JSON.pretty_generate(
+          "tool" => TOOL,
+          "mode" => mode,
+          "file" => source.path,
+          "summary" => summary,
+          "lines" => lines,
+          "foldings" => foldings
+        )
+      end
+
+      # `lines` is the rows in this document; `attempted` is how many of them
+      # were offered to the endpoint. The pair is what keeps the four status
+      # counts readable: three zeroes under `"mode": "list"` mean "nothing was
+      # sent", and the same three under a delivery of 40 lines would mean
+      # something very different.
+      #
+      # `blank` and `skipped` are the two ways a line of <file> is not a row
+      # here. They are stated always, and for the reason {IngestCLI::Source}
+      # counts rather than drops them: a summary that quietly narrows what it is
+      # summarising is the failure this command is arranged against.
+      def self.summary(source, lines:, counts:, attempted:)
+        {
+          "lines" => lines,
+          "attempted" => attempted,
+          "accepted" => counts.fetch(:accepted, 0),
+          "refused" => counts.fetch(:refused, 0),
+          "undelivered" => counts.fetch(:undelivered, 0),
+          "unparseable" => counts.fetch(:unparseable, 0),
+          "blank" => source.blank,
+          "skipped" => source.skipped,
+          "selector" => selector(source)
+        }
+      end
+
+      # Every line that reached the endpoint, which is every line except the
+      # ones that were never a run.
+      def self.attempted(counts)
+        counts.fetch(:accepted, 0) + counts.fetch(:refused, 0) + counts.fetch(:undelivered, 0)
+      end
+
+      # Which flag held lines back, named on exactly the terms the text summary
+      # names it: only when it demonstrably held something back. `--from-line`
+      # defaults to 1 when it was not given at all, so reporting it
+      # unconditionally would claim a selector the user never typed.
+      #
+      # @return [String, nil]
+      def self.selector(source)
+        return nil unless source.skipped.positive?
+
+        source.selector == :line_set ? "--lines" : "--from-line"
+      end
+
+      # One delivered line.
+      #
+      # `code` is the HTTP status, and `null` where there is not one: a line
+      # that was never a run, and a delivery that never got an answer at all
+      # (connection refused, DNS, TLS, a timeout). Together with `status` it is
+      # what tells the two apart from a refusal, which is why `reasons` can
+      # collapse all three into one list.
+      #
+      # `test_run_id` and `ci_run_id` are Strings or `null`, on the terms
+      # {Transport::Result#test_run_id} and {IngestCLI}'s `#scalar` already set:
+      # a non-scalar is not an id, and inventing structure the envelope does not
+      # have is not this tool's business.
+      def self.delivered(result)
+        {
+          "number" => result.number,
+          "status" => result.status.to_s,
+          "code" => result.code,
+          "reasons" => reasons(result.reasons),
+          "test_run_id" => result.test_run_id,
+          "ci_run_id" => result.ci_run_id
+        }
+      end
+
+      # One listed line: the envelope facts the text row prints, as values
+      # rather than as prose. `null` is the row's `no branch` / `no specs` /
+      # `no duration_seconds` — a fact the line does not carry, which is a
+      # different thing from one it carries as empty.
+      def self.listed(line)
+        {
+          "number" => line.number,
+          "status" => line.problem ? STATUS_UNPARSEABLE : STATUS_LISTED,
+          "reasons" => reasons(line.problem),
+          "branch" => line.branch,
+          "commit_sha" => line.commit_sha,
+          "ci_run_id" => line.ci_run_id,
+          "examples" => line.examples,
+          "duration_seconds" => line.duration_seconds
+        }
+      end
+
+      def self.folded(folding)
+        {
+          "ci_run_id" => folding.ci_run_id,
+          "test_run_id" => folding.test_run_id,
+          "lines" => folding.numbers
+        }
+      end
+
+      # ALWAYS a list of strings — `[]` where the line landed and where a
+      # refusal's body said nothing this gem could read, never `null` and never
+      # a bare string. {JSONReporter}'s `errors` makes the identical guarantee
+      # for the identical reason: `report.go:23-26` is explicit that a consumer
+      # must never have to branch on the type of the field that says why
+      # something failed, and one list is what lets a refusal's per-spec errors,
+      # a socket error and "this line is not a run" be read by one code path.
+      #
+      # The whole array, uncapped — that is the point of the document. It is
+      # what the platform sent, in its own words and in its own order, filtered
+      # only of what is not a String, because the source is a free-form JSON
+      # body and a Hash in there is not a reason.
+      #
+      # `scrub` for the same reason {Transport::Result#one_line} does it: a body
+      # from a proxy is bytes, not necessarily valid UTF-8, and `JSON.generate`
+      # raises on an invalid sequence. Raising here would cost the run its whole
+      # document — stdout empty, exit 2, an internal error on stderr — over a
+      # decoration. Note what is NOT done: the whitespace is left alone.
+      # Collapsing it is `#one_line`'s job because a CI log has one line to
+      # spend, and a JSON string has no such budget.
+      #
+      # @param values [Array, String, nil]
+      # @return [Array<String>]
+      def self.reasons(values)
+        Array(values).filter_map { |value| value.scrub("") if value.is_a?(String) }
+      end
+
+      private_class_method :document, :summary, :attempted, :selector, :delivered, :listed, :folded, :reasons
+    end
+  end
+end

data/lib/specguard/rspec/json_reporter.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require "json"
+
+module SpecGuard
+  module RSpec
+    # `specguard-lint --json`: the machine-readable renderer over the same
+    # `Array<Linter::Result>` the text report is built from.
+    #
+    # == Why this is a renderer and not a feature
+    #
+    # {CLI#check} has exactly one branch on which validator produced the
+    # verdicts, and it closes immediately: both arms return the same
+    # {Linter::Result} list. Everything downstream of it — the FAIL blocks, the
+    # summary line, the exit code — is shared code rather than two renderers
+    # that have to be kept in step. This hangs off that same point, so it
+    # inherits that guarantee: the `--json` document and the text report are the
+    # *same checks* rendered twice, not a second implementation that can drift.
+    #
+    # What the text renderer destroys at the print site is the structure. A
+    # {Linter::Result} carries file, line, kind, problem and reasons; the FAIL
+    # block flattens all five into prose, leaving a consumer the exit code and a
+    # regex. `kind` is the field that suffers most — {Finding}'s own comment
+    # says it is carried "because a failed extraction and an unparseable payload
+    # both land in `problem`, which makes the two indistinguishable downstream
+    # once flattened to prose", and then the CLI flattens it to prose.
+    #
+    # == The shape, and why it is the port's shape
+    #
+    # This mirrors `validate-intent --json --source`
+    # (open-test-intent, `cmd/validate-intent/report.go`) key for key:
+    #
+    #   {"schema", "mode", "ok", "summary": {"files", "annotations", "failed"},
+    #    "findings": [{"file", "line", "ok", "kind", "errors", "intent"}, ...]}
+    #
+    # The gem is already a *consumer* of exactly this document —
+    # {ValidatorBackend::Runner} runs `--source --json` and reconstructs
+    # {Linter::Result}s from it — so emitting a different shape would mean a
+    # consumer of both tools needs two parsers for one protocol. It does not
+    # try to be byte-identical to the binary's document, only key-, type- and
+    # value-identical, which is what a parser sees.
+    #
+    # Three properties are load-bearing for a consumer and are asserted rather
+    # than described (`spec/specguard/rspec/cli_spec.rb`):
+    #
+    #   * `errors` is ALWAYS a list of strings — `reasons` when the schema
+    #     rejected the annotation, `[problem]` when discovery could not produce
+    #     one at all, `[]` when it passed. Never null, never a bare string:
+    #     `report.go:23-26` is explicit that a consumer must never branch on its
+    #     type, and this is the one place the gem's mutually-exclusive
+    #     `problem`/`reasons` pair is normalised into the port's single list.
+    #   * `line` is null exactly where the finding is not line-scoped, which is
+    #     {Linter::Result#line_scoped?} — the same rule `#location` uses to
+    #     print `file` rather than `file:0`. `:0` is not somewhere a reader can
+    #     go, and emitting it here would hand every CI annotation and quickfix
+    #     consumer a line that does not exist.
+    #   * `kind` is null on a passing finding and one of `extraction`, `parse`,
+    #     `read`, `schema` otherwise. The port has a fifth, `no-match`, which
+    #     cannot appear here: {ValidatorBackend} maps it onto
+    #     {Finding::KIND_READ} at the seam, because on this side of it a path
+    #     that matched nothing *is* a named path that could not be opened.
+    #
+    # == The counts are handed in, not recomputed
+    #
+    # `summary.files` and `summary.annotations` are passed by {CLI}, which
+    # computes them once for both renderers. Recounting them here would let the
+    # text summary line and this document disagree about the same run, which is
+    # the failure mode the shared-downstream design exists to prevent — and a
+    # disagreement between two renderers of one result list is unfalsifiable
+    # from the outside.
+    #
+    # `ok` is likewise handed in, derived from the exit code the text path would
+    # also have produced rather than recomputed from the findings, following
+    # `report.go:84-89` for the same reason.
+    #
+    # `summary.failed`, by contrast, is counted here — from the findings this
+    # document actually emitted, so `failed` always equals the number of entries
+    # with `"ok": false`. Note that it is NOT the text summary's "M malformed":
+    # that clause counts malformed *annotations* and reports unreadable files in
+    # a separate clause, while `failed` counts every failing finding, read
+    # failures included, exactly as the port's `Emit` does. Two different
+    # questions, each answered the same way in both implementations.
+    #
+    # == What is deliberately NOT in the document
+    #
+    # The backend provenance line (SPGD-247 — one stderr line per run naming the
+    # implementation that produced the verdicts) is not duplicated in here.
+    # Two reasons, and the decision is recorded rather than defaulted into:
+    # it would be the first key by which this document differs from the port's,
+    # reintroducing the second parser this shape exists to avoid; and provenance
+    # would then have two homes that can disagree about one fact, which is the
+    # shape SPGD-247 was written to close, not to widen. `2>` the stderr stream
+    # and read the line; it is still exactly one line, on every run, on both
+    # arms.
+    module JSONReporter
+      # The port's `jsonSchemaID` (`report.go:19`), and the basename of the
+      # gem's own vendored schema. Pinned to each other by a spec: the document
+      # names the protocol it validated against, so it must not be able to name
+      # one the gem does not carry.
+      SCHEMA_ID = "open-test-intent.v1.json"
+
+      # The port's `--source` mode: annotations found in spec *sources*, which
+      # is the only thing `specguard-lint` does. It is not the *selection* mode
+      # (`--changed` vs explicit files) — that is this tool's own vocabulary and
+      # the port has no field for it. Emitting `"changed"` here would tell a
+      # consumer that already reads `validate-intent --json` that it is looking
+      # at a mode that does not exist.
+      MODE = "source"
+
+      # @param results [Array<Linter::Result>] every verdict, in discovery order
+      # @param files [Integer] spec files selected — the count the text path
+      #   states in its leading `checked N spec file(s)` line
+      # @param annotations [Integer] annotation sites examined — the count the
+      #   text path states in its trailing summary line
+      # @param ok [Boolean] whether the run passed, derived from the exit code
+      # @return [String] one JSON document, without a trailing newline
+      def self.render(results, files:, annotations:, ok:)
+        findings = results.map { |result| finding(result) }
+
+        JSON.pretty_generate(
+          "schema" => SCHEMA_ID,
+          "mode" => MODE,
+          "ok" => ok,
+          "summary" => {
+            "files" => files,
+            "annotations" => annotations,
+            "failed" => findings.count { |entry| !entry["ok"] }
+          },
+          "findings" => findings
+        )
+      end
+
+      # @param result [Linter::Result]
+      # @return [Hash] one `findings` entry
+      def self.finding(result)
+        {
+          "file" => result.file,
+          "line" => result.line_scoped? ? result.line : nil,
+          "ok" => result.ok?,
+          "kind" => result.kind&.to_s,
+          "errors" => errors(result),
+          # {Linter::Result#representable_intent}, not `intent`: a payload
+          # holding a lone low surrogate parses in Ruby and then cannot be
+          # GENERATED, so emitting it raw would raise here and take the whole
+          # document with it — a `--json` run that dies rendering a finding it
+          # had already decided about. Null is the same answer this document
+          # gives for every other payload it does not have.
+          "intent" => result.representable_intent
+        }
+      end
+
+      # `problem` and `reasons` are mutually exclusive by construction and mean
+      # the same thing to a consumer — why this finding failed. `kind` is what
+      # tells them apart, so both collapse into the one list here and nothing is
+      # lost. The port's `RunSourceJSON` performs the identical collapse, and
+      # {ValidatorBackend} performs its inverse when reading the port's output.
+      #
+      # @param result [Linter::Result]
+      # @return [Array<String>]
+      def self.errors(result)
+        return [result.problem] if result.problem
+
+        result.reasons
+      end
+
+      private_class_method :finding, :errors
+    end
+  end
+end

data/lib/specguard/rspec/linter.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require "json"
+
+module SpecGuard
+  module RSpec
+    # The shared verdict shape both renderers and the exit code derive from.
+    #
+    # == Where this sits after SPGD-867 (the cutover)
+    #
+    # This used to be a class that APPLIED the schema to Findings the Ruby
+    # scanner had produced. That Ruby hand-rolled validation arm is gone:
+    # `specguard-lint` validates through the `validate-intent` binary and only
+    # the binary ({ValidatorBackend}), and the formatter's half
+    # ({AnnotationLookup}) asks the same binary. What survives is the one
+    # thing both sides of the seam still share — {Result}, the single shape
+    # the reporter and the exit code are both derived from, so "what was
+    # printed" and "what we exited with" cannot drift apart.
+    #
+    # == What counts as a failure
+    #
+    # Three things reach the same verdict from different directions:
+    #
+    #   * the payload could not be captured off the line at all
+    #     (`Finding::KIND_EXTRACTION`) — a typo'd annotation;
+    #   * it was captured but is not JSON even after normalization
+    #     (`Finding::KIND_PARSE`);
+    #   * it parsed but violates the schema.
+    #
+    # All three are "an annotation is malformed", which the contract fixes at
+    # exit 1. A **missing** annotation is not among them — "lint, don't
+    # require" (SPGD-12 §1): a file with no `@intent:` at all is clean.
+    #
+    # `Finding::KIND_READ` — a spec file that could not be opened or is not
+    # valid UTF-8 — is also reported as a failure, and therefore also exits 1.
+    # That matches `validate-intent`, which classifies it separately (its own
+    # `read` kind) and still reports it as `FAIL` with exit 1.
+    module Linter
+      # One annotation's verdict. `problem` is set when discovery could not
+      # produce an intent at all; `reasons` when the schema rejected one.
+      # They are mutually exclusive by construction.
+      #
+      # `intent` is WHAT THE PAYLOAD PARSED TO, carried alongside the verdict
+      # rather than left for a second parser to re-derive. It is nil when there
+      # was no payload (any `problem`), and — like the port's `intent` key — it
+      # is populated even when `reasons` is not empty: a schema-rejected
+      # annotation did parse, and `ok?` already reports the verdict.
+      Result = Data.define(:file, :line, :kind, :problem, :reasons, :intent) do
+        def initialize(file:, line:, kind: nil, problem: nil, reasons: [], intent: nil)
+          super
+        end
+
+        def ok?
+          problem.nil? && reasons.empty?
+        end
+
+        def failed?
+          !ok?
+        end
+
+        # A read failure is not line-scoped: nothing in the file was ever seen,
+        # and slice 1's `line` is a 0 sentinel rather than a location. The
+        # binary drops the line for exactly these findings (`JSONFinding` in
+        # open-test-intent's cmd/validate-intent/report.go — "`line` is null
+        # where a finding is not line-scoped, `kind` is null on a passing
+        # finding"), and `:0` is not somewhere a reader can go: anything
+        # parsing `file:line` — CI annotations, editor quickfix, review
+        # comments — would point at a line that does not exist.
+        #
+        # This is what makes `kind` load-bearing rather than decorative.
+        #
+        # The rule is a predicate rather than an inline comparison because it
+        # has two renderers: `CLI#report_failure` prints `file` instead of
+        # `file:0`, and `JSONReporter` emits `"line": null` for the same
+        # findings. Spelling `kind == Finding::KIND_READ` in both would let one
+        # of them keep emitting the sentinel after the rule changed here.
+        def line_scoped?
+          kind != Finding::KIND_READ
+        end
+
+        def location
+          line_scoped? ? "#{file}:#{line}" : file
+        end
+
+        # The nesting budget a payload gets, well under `JSON.generate`'s
+        # default ceiling of 100.
+        #
+        # The margin is deliberate rather than tight. Both renderers WRAP the
+        # payload before generating it — {JSONReporter} in `findings[] ->
+        # finding -> intent` and {Formatter} in `specs[] -> spec -> intent`,
+        # three levels each — so a payload probed at the bare ceiling would be
+        # accepted here and still raise there. Budgeting 32 leaves either
+        # envelope room to grow without silently re-opening this hole.
+        #
+        # It costs nothing real: the schema admits four string values and
+        # nothing nested, so every payload a consumer could act on is depth 1.
+        # Anything deep enough to be refused here was already schema-invalid;
+        # this only decides whether its finding also carries the value.
+        MAX_INTENT_DEPTH = 32
+
+        # The intent, but only when it is a value this gem can actually hand on
+        # — nil otherwise.
+        #
+        # Parsing a payload is not the same as being able to REPRODUCE it, and
+        # Ruby draws that line in a place the validator does not. Three classes
+        # clear the binary's verdict AND then detonate at the point of USE:
+        #
+        # * a lone LOW surrogate (`"\udc00Or"`) — the report parser may accept
+        #   it and hand back a String whose `valid_encoding?` is false, and
+        #   `JSON.generate` refuses that same value with `source sequence is
+        #   illegal/malformed utf-8`;
+        # * a non-finite Float — {ValidatorBackend}'s parse options set
+        #   `allow_nan: true` on the way IN, while generate's default is
+        #   `allow_nan: false` on the way OUT;
+        # * a container nested past the generator's `max_nesting` — the same
+        #   asymmetry, since those parse options also set `max_nesting: false`.
+        #
+        # The last two are the parse options' own doing. Relaxing the parse side
+        # without relaxing the generate side does not remove the failure, it
+        # MOVES it — out of the parser, where it costs one annotation its
+        # payload, and into the generator, where it costs the whole batch its
+        # document and its exit code. Admitting a value we cannot then emit is
+        # strictly worse than never admitting it.
+        #
+        # So the question is ASKED rather than enumerated: hand the value to
+        # the generator and see whether it comes back. A predicate that lists the
+        # known-bad shapes is a list somebody has to keep complete, and the two
+        # cases above are exactly what that list missed while covering the
+        # first. `JSON.generate` is not an approximation of the oracle here, it
+        # IS the call both renderers go on to make.
+        #
+        # Answered here, once, because BOTH renderers need it and neither is the
+        # natural owner. Nothing is substituted — a repaired payload is one the
+        # author did not write, and shipping it is indistinguishable downstream
+        # from shipping the right one (KB SPGD-78). Unshippable means
+        # unannotated.
+        def representable_intent
+          intent unless unrepresentable?(intent)
+        end
+
+        private
+
+        # `NestingError` is rescued alongside `GeneratorError` rather than
+        # folded into it: despite being what the GENERATOR raises past
+        # max_nesting`, it descends from `JSON::ParserError`, so catching
+        # `GeneratorError` alone would let the over-deep case straight through.
+        def unrepresentable?(value)
+          JSON.generate(value, max_nesting: MAX_INTENT_DEPTH)
+          false
+        rescue JSON::GeneratorError, JSON::NestingError
+          true
+        end
+      end
+    end
+  end
+end