ruact 0.0.7 → 0.0.8

data/lib/ruact/testing/component_query.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require_relative "flight_wire_parser"
+
+module Ruact
+  module Testing
+    # Resolves "was component <name> rendered, and with what props?" out of a
+    # decoded Flight tree. Pure — no RSpec, no I/O. The public
+    # `have_ruact_component` matcher is a thin RSpec wrapper over this.
+    #
+    # A component is TWO wire rows (Story 7.5 / FR108 semantics):
+    #
+    #   * an `:import` row — `["<module path>", "<export name>", [chunks…]]` —
+    #     sourced from the client manifest (`reference_for`); its `:id` is the
+    #     integer the model rows reference; AND
+    #   * one or more `:model` rows carrying a React element
+    #     `["$", "$L<hex id>", key, {props}]` whose type references that import.
+    #
+    # `have_ruact_component("PostList")` matches the import row's DECLARED name
+    # (D3): its export name OR its module basename (`/PostList.jsx` → `PostList`)
+    # — honest to what the wire actually contains, not the ERB tag or a mapping
+    # the wire does not carry. Props are read from the model element's 4th slot
+    # in their SERIALIZED wire form (D4: string keys, serialized values).
+    class ComponentQuery
+      # A React element on the wire is a 4-tuple whose head is the sentinel "$".
+      ELEMENT_HEAD = "$"
+      # A client-component element's type is "$L" followed by the import's hex id.
+      CLIENT_REF = /\A\$L(?<hex>\h+)\z/
+
+      # @param wire [String] the raw Flight wire byte string.
+      def initialize(wire)
+        @rows = FlightWireParser.parse(wire)
+        @imports = index_imports(@rows)
+        @instances = collect_instances(@rows)
+      end
+
+      # @return [Boolean] whether any instance of `name` was rendered.
+      def rendered?(name)
+        !props_for(name).empty?
+      end
+
+      # @return [Array<Hash>] the serialized props hash of every rendered
+      #   instance of `name`, in wire order. Empty when `name` was not rendered.
+      def props_for(name)
+        ids = import_ids_for(name)
+        return [] if ids.empty?
+
+        @instances.select { |inst| ids.include?(inst[:ref_id]) }.map { |inst| inst[:props] }
+      end
+
+      # @return [Array<String>] every distinct component name present in the
+      #   wire (by declared export name), for a legible failure message.
+      def rendered_names
+        rendered_ids = @instances.map { |inst| inst[:ref_id] }.uniq
+        @imports.slice(*rendered_ids).map { |_, meta| meta[:export_name] }.uniq
+      end
+
+      private
+
+      def index_imports(rows)
+        rows.each_with_object({}) do |row, acc|
+          next unless row[:class] == :import
+
+          payload = row[:payload]
+          next unless payload.is_a?(Array)
+
+          module_path = payload[0]
+          export_name = payload[1]
+          acc[row[:id]] = {
+            module_path: module_path,
+            export_name: export_name,
+            basename: module_path.is_a?(String) ? File.basename(module_path, ".*") : nil
+          }
+        end
+      end
+
+      def import_ids_for(name)
+        @imports.select do |_id, meta|
+          meta[:export_name] == name || meta[:basename] == name
+        end.keys
+      end
+
+      # Walk every model row's payload, collecting each client-component element
+      # `["$", "$L<hex>", key, props]` as `{ ref_id:, props: }`.
+      def collect_instances(rows)
+        instances = []
+        rows.each do |row|
+          next unless row[:class] == :model
+
+          walk(row[:payload], instances)
+        end
+        instances
+      end
+
+      def walk(node, instances)
+        if element?(node)
+          ref = node[1].match(CLIENT_REF)
+          instances << { ref_id: ref[:hex].to_i(16), props: node[3] } if ref
+          # An element's props/children may themselves contain nested elements.
+          walk(node[3], instances)
+        elsif node.is_a?(Array)
+          node.each { |child| walk(child, instances) }
+        elsif node.is_a?(Hash)
+          node.each_value { |child| walk(child, instances) }
+        end
+      end
+
+      def element?(node)
+        node.is_a?(Array) && node.length >= 4 && node[0] == ELEMENT_HEAD && node[1].is_a?(String)
+      end
+    end
+  end
+end

data/lib/ruact/testing/flight_extractor.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+module Ruact
+  module Testing
+    # Raised by {FlightExtractor.extract} when the given response/String is not
+    # a Flight page render — most importantly when it is a plain-JSON
+    # function-call/query response. The message tells the spec author what they
+    # were handed and how to assert on it instead. Public: hosts may rescue it.
+    class NotAFlightResponseError < StandardError; end
+
+    # Pulls the Flight wire byte string out of whatever a host request spec
+    # hands the `have_ruact_component` matcher: an ActionDispatch/Rack response
+    # object (read via `.body`) or a raw String, in either of the two page
+    # shapes ruact emits —
+    #
+    #   1. a raw `text/x-component` body (RSC/navigation request), OR
+    #   2. a full HTML document embedding the payload in the `__FLIGHT_DATA`
+    #      bootstrap `<script>` (a plain browser GET).
+    #
+    # A `Ruact::Server` function-call/query answer is plain JSON, not Flight —
+    # feeding it here raises {NotAFlightResponseError} pointing at `JSON.parse`,
+    # rather than silently failing to parse. Pure: no I/O, no global state.
+    module FlightExtractor
+      # Matches the `<local>.push("<ruby-inspected literal>")` line the
+      # `__FLIGHT_DATA` bootstrap script emits (see
+      # `Ruact::ViewHelper#ruact_flight_data_script`). ANCHORED to the queue
+      # assignment (`self.__FLIGHT_DATA = self.__FLIGHT_DATA || [])`) so an
+      # unrelated earlier script on the page (analytics `dataLayer.push(…)`,
+      # etc.) can never be mistaken for the Flight payload. The captured group
+      # is the full double-quoted Ruby string literal (quotes included),
+      # honoring escaped quotes so a `\"` inside the payload does not end it.
+      FLIGHT_DATA_PUSH = /
+        self\.__FLIGHT_DATA\s*=\s*self\.__FLIGHT_DATA\s*\|\|\s*\[\]\)\s*;   # queue assignment
+        \s*[A-Za-z_$][\w$]*\.push\(                                        # <local>.push(
+        (?<literal>"(?:\\.|[^"\\])*")
+        \)\s*;
+      /mx
+
+      # A Flight wire body always starts with a row header: `<hex>:` (id + colon)
+      # or a hint row `:H`. JSON bodies start with `{`/`[`/`"`; HTML with `<`.
+      FLIGHT_ROW_START = /\A\s*(?:\h+:|:H)/
+
+      # Reverses `String#inspect` on the captured `__FLIGHT_DATA` literal.
+      # `JSON.parse` is unsafe here: Ruby's inspect escapes sequences JSON
+      # rejects (`\#` before `{`/`$`/`@`, `\e`, `\a`, …). These are the common
+      # single-char escapes; an unrecognized `\c` yields the literal `c`.
+      SIMPLE_ESCAPES = {
+        "n" => "\n", "t" => "\t", "r" => "\r", "s" => " ", "0" => "\0",
+        "a" => "\a", "b" => "\b", "e" => "\e", "f" => "\f", "v" => "\v",
+        '"' => '"', "\\" => "\\"
+      }.freeze
+
+      class << self
+        # @param response_or_string [#body, String] a response object or a raw
+        #   body String.
+        # @return [String] the extracted Flight wire byte string.
+        # @raise [NotAFlightResponseError] when the input is a JSON function-call
+        #   response, an empty body, or otherwise not a Flight page render.
+        def extract(response_or_string)
+          body, content_type = read(response_or_string)
+          return extract_by_content_type(body, content_type) if content_type
+
+          extract_by_sniffing(body)
+        end
+
+        private
+
+        # Reads `[body, content_type]` from a response object or String. A bare
+        # String has no content type; a response object may expose one via
+        # `content_type`/`media_type` (rack-test, ActionDispatch) — read
+        # defensively so any duck-typed `.body` object still works.
+        def read(response_or_string)
+          return [response_or_string, nil] if response_or_string.is_a?(String)
+
+          unless response_or_string.respond_to?(:body)
+            raise NotAFlightResponseError,
+                  "have_ruact_component expects a response object (responds to #body) or a String, " \
+                  "got #{response_or_string.class}."
+          end
+
+          [response_or_string.body.to_s, content_type_of(response_or_string)]
+        end
+
+        def content_type_of(response)
+          %i[media_type content_type].each do |m|
+            next unless response.respond_to?(m)
+
+            value = response.public_send(m)
+            return value.to_s.split(";").first&.strip unless value.nil? || value.to_s.empty?
+          end
+          nil
+        rescue StandardError
+          nil
+        end
+
+        def extract_by_content_type(body, content_type)
+          case content_type
+          when "text/x-component"
+            ensure_present!(body)
+            body
+          when "text/html", "application/xhtml+xml"
+            from_html(body)
+          when "application/json"
+            raise_json_error(body)
+          else
+            # Unknown content type — fall back to sniffing the bytes.
+            extract_by_sniffing(body)
+          end
+        end
+
+        def extract_by_sniffing(body)
+          ensure_present!(body)
+
+          return from_html(body) if body.include?("__FLIGHT_DATA")
+          return body if body.match?(FLIGHT_ROW_START)
+          # An HTML document that rendered no component reaches `from_html`,
+          # which raises the actionable "no `__FLIGHT_DATA` payload" error.
+          return from_html(body) if html_body?(body)
+
+          raise_json_error(body) if json_body?(body)
+
+          raise NotAFlightResponseError,
+                "have_ruact_component could not find a Flight payload in the response. " \
+                "The body is neither a raw `text/x-component` Flight body nor an HTML shell " \
+                "embedding `__FLIGHT_DATA`. First bytes: #{body[0, 80].inspect}"
+        end
+
+        def from_html(html)
+          match = html.match(FLIGHT_DATA_PUSH)
+          unless match
+            raise NotAFlightResponseError,
+                  "have_ruact_component received an HTML document with no `__FLIGHT_DATA` payload. " \
+                  "This response did not render a ruact component (no Flight data was inlined)."
+          end
+
+          decode_ruby_string_literal(match[:literal])
+        end
+
+        def json_body?(body)
+          stripped = body.lstrip
+          stripped.start_with?("{", "[", "\"")
+        end
+
+        def html_body?(body)
+          stripped = body.lstrip
+          stripped.start_with?("<") && /<(?:!doctype\b|html\b|body\b|div\b|head\b)/i.match?(stripped)
+        end
+
+        def raise_json_error(body)
+          raise NotAFlightResponseError,
+                "have_ruact_component received a plain-JSON response, not a Flight page. " \
+                "`Ruact::Server` function-call and query responses answer JSON — assert on them with " \
+                "`JSON.parse(response.body)` and a status check, not `have_ruact_component`. " \
+                "First bytes: #{body[0, 80].inspect}"
+        end
+
+        def ensure_present!(body)
+          return unless body.nil? || body.empty?
+
+          raise NotAFlightResponseError,
+                "have_ruact_component received an empty response body — nothing was rendered. " \
+                "(A 204/no-content function-call response has no Flight payload.)"
+        end
+
+        def decode_ruby_string_literal(literal)
+          inner = literal[1..-2] # strip surrounding quotes
+          out = +""
+          pos = 0
+          len = inner.length
+          while pos < len
+            ch = inner[pos]
+            if ch == "\\" && pos + 1 < len
+              decoded, consumed = decode_escape(inner, pos + 1)
+              out << decoded
+              pos += 1 + consumed
+            else
+              out << ch
+              pos += 1
+            end
+          end
+          out
+        end
+
+        # Decodes the escape sequence that begins at `inner[pos]` (the char right
+        # after the backslash). Returns `[decoded_string, input_chars_consumed]`
+        # where `input_chars_consumed` counts only the chars AFTER the
+        # backslash, so the caller can advance its cursor precisely.
+        def decode_escape(inner, pos)
+          ch = inner[pos]
+          case ch
+          when "u" then decode_unicode(inner, pos)
+          when "x" then decode_hex(inner, pos)
+          else
+            [SIMPLE_ESCAPES.fetch(ch, ch), 1]
+          end
+        end
+
+        # `\u{XXXX}` (braced, possibly multiple code points) or `\uXXXX`.
+        def decode_unicode(inner, pos)
+          if inner[pos + 1] == "{"
+            close = inner.index("}", pos + 2) || (return ["u", 1])
+            hex = inner[(pos + 2)...close]
+            decoded = hex.split.map { |cp| cp.to_i(16) }.pack("U*")
+            [decoded, (close - pos) + 1]
+          else
+            hex = inner[(pos + 1), 4].to_s
+            [[hex.to_i(16)].pack("U"), 1 + hex.length]
+          end
+        end
+
+        # `\xHH` (one or two hex digits).
+        def decode_hex(inner, pos)
+          hex = inner[(pos + 1)..].to_s[/\A\h{1,2}/].to_s
+          return ["x", 1] if hex.empty?
+
+          [[hex.to_i(16)].pack("C").force_encoding(inner.encoding), 1 + hex.length]
+        end
+      end
+    end
+  end
+end

data/lib/ruact/testing/flight_structure_diff.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+module Ruact
+  module Testing
+    # Pure structural diff + predicate-matching engine over parsed Flight rows
+    # (see {FlightWireParser}). No RSpec dependency — the RSpec matcher DSL that
+    # consumes it (the public `have_ruact_component` and the internal
+    # `match_flight_structure`/`include_flight_row`) lives elsewhere. Promoted
+    # from `spec/support` in Story 15.4 so the public helper and the internal
+    # matchers share ONE implementation (wrap, not fork).
+    # rubocop:disable Metrics/ClassLength -- single cohesive helper for matcher diffing/formatting; splitting would scatter related logic across files.
+    class FlightStructureDiff
+      # Keys the parser produces on every row. Predicates and expected rows
+      # may only reference these keys; unknown keys raise upfront so typos
+      # like `payloed:` don't silently match every row via `nil == nil`.
+      KNOWN_ROW_KEYS = %i[id class payload raw].freeze
+
+      # Keys that must be present in every expected-row hash passed to
+      # `match_flight_structure`. Excludes `:raw` because expected rows are
+      # authored as semantic descriptions, not byte-level snapshots.
+      REQUIRED_EXPECTED_KEYS = %i[id class payload].freeze
+
+      # Compute the set of differences between actual parsed rows and the
+      # expected structure. Import rows are matched as a multiset (their
+      # relative order among each other is not significant per AC1);
+      # everything else compares positionally.
+      def self.compute(actual_rows, expected_rows)
+        validate_expected_rows!(expected_rows)
+        return diffs_for_length_mismatch(actual_rows, expected_rows) if actual_rows.length != expected_rows.length
+
+        diffs = []
+        pending_actual_imports = []
+        pending_expected_imports = []
+
+        actual_rows.zip(expected_rows).each_with_index do |(actual, expected), i|
+          if actual[:class] == :import && expected[:class] == :import
+            pending_actual_imports << [i, actual]
+            pending_expected_imports << [i, expected]
+            next
+          end
+
+          next if rows_equal?(actual, expected)
+
+          diffs << build_field_diff(i, actual, expected)
+        end
+
+        diffs.concat(diff_imports_unordered(pending_actual_imports, pending_expected_imports))
+        diffs.sort_by { |d| d[:idx] }
+      end
+
+      # Imports are an unordered multiset within their class (AC1). Sort both
+      # sides by `:id` (always unique per render) and any leftover diffs come
+      # from semantic mismatch in the same-position-after-sort pair.
+      def self.diff_imports_unordered(actual_pairs, expected_pairs)
+        return [] if actual_pairs.empty? && expected_pairs.empty?
+
+        sort_key = ->(pair) { [pair[1][:id].to_i, pair[1][:payload].to_s] }
+        sorted_actual = actual_pairs.sort_by(&sort_key)
+        sorted_expected = expected_pairs.sort_by(&sort_key)
+
+        sorted_actual.zip(sorted_expected).filter_map do |(act_idx, act_row), (_exp_idx, exp_row)|
+          next if rows_equal?(act_row, exp_row)
+
+          build_field_diff(act_idx, act_row, exp_row)
+        end
+      end
+
+      def self.diffs_for_length_mismatch(actual_rows, expected_rows)
+        diffs = []
+        [actual_rows.length, expected_rows.length].max.times do |i|
+          actual = actual_rows[i]
+          expected = expected_rows[i]
+          if actual.nil?
+            diffs << { kind: :missing, idx: i, expected_row: expected }
+          elsif expected.nil?
+            diffs << { kind: :extra, idx: i, actual_row: actual }
+          elsif !rows_equal?(actual, expected)
+            diffs << build_field_diff(i, actual, expected)
+          end
+        end
+        diffs
+      end
+
+      def self.rows_equal?(actual, expected)
+        REQUIRED_EXPECTED_KEYS.all? { |k| actual[k] == expected[k] }
+      end
+
+      def self.build_field_diff(idx, actual, expected)
+        field_diff = nil
+        REQUIRED_EXPECTED_KEYS.each do |key|
+          next if actual[key] == expected[key]
+
+          path, sub_expected, sub_actual = first_difference(expected[key], actual[key], ".#{key}")
+          field_diff = { path: path, expected: sub_expected, got: sub_actual }
+          break
+        end
+
+        {
+          kind: :differs,
+          idx: idx,
+          row_class: actual[:class],
+          path: field_diff[:path],
+          expected: field_diff[:expected],
+          got: field_diff[:got],
+          expected_row: expected,
+          got_row: actual
+        }
+      end
+
+      # Walks parallel structures (Hash/Array/scalar) and returns the path,
+      # expected leaf, and actual leaf at the first differing position.
+      def self.first_difference(expected, actual, path)
+        return [path, expected, actual] if expected.class != actual.class
+        return [path, expected, actual] unless expected.is_a?(Array) || expected.is_a?(Hash)
+
+        return diff_in_array(expected, actual, path) if expected.is_a?(Array)
+
+        diff_in_hash(expected, actual, path)
+      end
+
+      def self.diff_in_array(expected, actual, path)
+        [expected.length, actual.length].max.times do |i|
+          return ["#{path}[#{i}]", expected[i], actual[i]] if i >= expected.length || i >= actual.length
+          next if expected[i] == actual[i]
+
+          return first_difference(expected[i], actual[i], "#{path}[#{i}]")
+        end
+        [path, expected, actual]
+      end
+
+      def self.diff_in_hash(expected, actual, path)
+        (expected.keys | actual.keys).each do |key|
+          return ["#{path}[#{key.inspect}]", expected[key], actual[key]] if !expected.key?(key) || !actual.key?(key)
+          next if expected[key] == actual[key]
+
+          return first_difference(expected[key], actual[key], "#{path}[#{key.inspect}]")
+        end
+        [path, expected, actual]
+      end
+
+      # Validates each expected row carries the required `:id`, `:class`,
+      # `:payload` keys. Without this, an expected row of `{ id: 0, class:
+      # :model }` would silently pass against any actual row whose payload
+      # was nil — because the `==` check reads `expected[:payload]` as nil.
+      def self.validate_expected_rows!(expected_rows)
+        expected_rows.each_with_index do |row, i|
+          unless row.is_a?(Hash)
+            raise ArgumentError,
+                  "match_flight_structure: expected row #{i} must be a Hash, got #{row.class}: #{row.inspect}"
+          end
+
+          missing = REQUIRED_EXPECTED_KEYS.reject { |k| row.key?(k) }
+          next if missing.empty?
+
+          raise ArgumentError,
+                "match_flight_structure: expected row #{i} is missing required keys: #{missing.inspect}. " \
+                "Each expected row must include :id, :class, and :payload."
+        end
+      end
+
+      # Validates a predicate hash for `include_flight_row`. Unknown keys
+      # (typos like `payloed:` or `clas:`) raise immediately so they don't
+      # silently match any row via `row[:payloed]` returning nil.
+      def self.validate_predicate!(predicate)
+        unless predicate.is_a?(Hash)
+          raise ArgumentError,
+                "include_flight_row: predicate must be a Hash, got #{predicate.class}: #{predicate.inspect}"
+        end
+        raise ArgumentError, "include_flight_row: predicate cannot be empty" if predicate.empty?
+
+        unknown = predicate.keys - KNOWN_ROW_KEYS
+        return if unknown.empty?
+
+        raise ArgumentError,
+              "include_flight_row: predicate has unknown keys: #{unknown.inspect}. " \
+              "Allowed keys: #{KNOWN_ROW_KEYS.inspect}."
+      end
+
+      def self.format_single(diff)
+        case diff[:kind]
+        when :missing
+          row = diff[:expected_row]
+          "Expected row #{diff[:idx]} (#{row[:class]}) was not produced.\n  expected: #{row.inspect}"
+        when :extra
+          row = diff[:actual_row]
+          "Got unexpected row #{diff[:idx]} (#{row[:class]}): #{row.inspect}"
+        else
+          format_field_diff(diff)
+        end
+      end
+
+      def self.format_field_diff(diff)
+        <<~MSG.strip
+          Expected Flight output to match structure.
+
+          Row #{diff[:idx]} (#{diff[:row_class]}) differs at #{diff[:path]}:
+            expected: #{diff[:expected].inspect}
+            got:      #{diff[:got].inspect}
+
+          Row #{diff[:idx]} (#{diff[:row_class]}) full diff:
+            expected: #{diff[:expected_row][:payload].inspect}
+            got:      #{diff[:got_row][:payload].inspect}
+        MSG
+      end
+
+      # Builds the multi-row failure message: header naming the diff count,
+      # AC3-specified wording for missing / extra / differing rows, and a
+      # `Row N (<class>): ✓` summary line for every matching row so the
+      # reader can see what passed.
+      def self.format_multi(diffs, actual_rows, expected_rows)
+        header = "Expected Flight output to match structure. #{diffs.length} rows differ:"
+        total = [actual_rows.length, expected_rows.length].max
+        diff_by_idx = diffs.to_h { |d| [d[:idx], d] }
+
+        body = (0...total).map do |i|
+          diff = diff_by_idx[i]
+          if diff
+            format_entry(diff)
+          else
+            row_class = (actual_rows[i] || expected_rows[i])[:class]
+            "Row #{i} (#{row_class}): ✓"
+          end
+        end
+
+        ([header, ""] + body).join("\n")
+      end
+
+      def self.format_entry(diff)
+        case diff[:kind]
+        when :missing
+          row = diff[:expected_row]
+          "Expected row #{diff[:idx]} (#{row[:class]}) was not produced.\n  expected: #{row.inspect}"
+        when :extra
+          row = diff[:actual_row]
+          "Got unexpected row #{diff[:idx]} (#{row[:class]}): #{row.inspect}"
+        else
+          <<~ENTRY.strip
+            Row #{diff[:idx]} (#{diff[:row_class]}) differs at #{diff[:path]}:
+              expected: #{diff[:expected].inspect}
+              got:      #{diff[:got].inspect}
+          ENTRY
+        end
+      end
+
+      # Subset / case-equality match used by `include_flight_row`. Plain
+      # values use `==`; richer matchers (`hash_including`, `array_including`,
+      # `kind_of`, regexes) use `===` which delegates to their custom logic.
+      # Predicate keys are validated upfront by `validate_predicate!`, so
+      # this method can assume every key is one of the known row keys.
+      def self.row_matches?(row, predicate)
+        predicate.all? do |key, expected_value|
+          actual_value = row[key]
+          case expected_value
+          when Symbol, Numeric, NilClass, TrueClass, FalseClass
+            expected_value == actual_value
+          else
+            # rubocop:disable Style/CaseEquality -- intentional: lets RSpec mock argument matchers
+            # (hash_including, array_including, kind_of, etc.) drive predicate semantics via #===.
+            expected_value === actual_value
+            # rubocop:enable Style/CaseEquality
+          end
+        end
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end