ruact 0.0.2 → 0.0.4

data/spec/support/flight_wire_parser.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "strscan"
+require "json"
+
+module Ruact
+  # Test-support utilities. Code under `Ruact::Spec` is consumed only by the
+  # gem's own RSpec suite; it is not part of the public API and may change
+  # shape across stories without a deprecation cycle.
+  module Spec
+    # Raised when {FlightWireParser.parse} encounters input it cannot decode.
+    # The message names the byte offset of the unparseable row so the spec
+    # author can locate the problem in a printed wire string.
+    class FlightWireParseError < StandardError; end
+
+    # Parses a Flight wire byte string into an ordered array of row records.
+    #
+    # Used by the structural Flight RSpec matchers
+    # (`match_flight_structure` / `include_flight_row`) to assert on parsed
+    # semantics rather than literal bytes. Pure function — no I/O, no global
+    # state, no `Thread.current`.
+    #
+    # @example
+    #   wire = "1:I[\"/L.jsx\",\"L\",[\"/L.jsx\"]]\n0:[\"$\",\"$L1\",null,{}]\n"
+    #   Ruact::Spec::FlightWireParser.parse(wire)
+    #   # => [
+    #   #      { id: 1, class: :import, payload: ["/L.jsx", "L", ["/L.jsx"]], raw: "1:I...\n" },
+    #   #      { id: 0, class: :model,  payload: ["$", "$L1", nil, {}],       raw: "0:[\"$\"...\n" }
+    #   #    ]
+    class FlightWireParser
+      # Parse a complete Flight wire byte string.
+      #
+      # @param wire [String] the raw bytes emitted by `Ruact::Flight::Renderer`.
+      # @return [Array<Hash>] one hash per row, in wire order. See class docs
+      #   for the hash shape (`:id`, `:class`, `:payload`, `:raw`).
+      # @raise [Ruact::Spec::FlightWireParseError] when a row is malformed.
+      def self.parse(wire)
+        rows = []
+        scanner = StringScanner.new(wire)
+
+        until scanner.eos?
+          start_offset = scanner.pos
+          rows << parse_row(scanner, start_offset)
+        end
+
+        rows
+      end
+
+      def self.parse_row(scanner, start_offset)
+        # Hint rows have no ID: ":H<code><json>\n"
+        if scanner.peek(2) == ":H"
+          scanner.pos += 2
+          code = scanner.getch
+          raise_parse_error(start_offset, "missing hint code char") if code.nil?
+
+          json = read_to_newline(scanner, start_offset)
+          return {
+            id: nil,
+            class: :hint,
+            payload: [code, parse_json(json, start_offset)],
+            raw: scanner.string.byteslice(start_offset, scanner.pos - start_offset)
+          }
+        end
+
+        hex = scanner.scan(/\h+/) || raise_parse_error(start_offset, "expected hex id")
+        scanner.skip(":") || raise_parse_error(start_offset, "expected ':' after id")
+        id = hex.to_i(16)
+
+        case scanner.peek(1)
+        when "I" then parse_tagged(:import, scanner, id, start_offset)
+        when "T" then parse_text_row(scanner, id, start_offset)
+        when "E" then parse_tagged(:error, scanner, id, start_offset)
+        else          parse_model_row(scanner, id, start_offset)
+        end
+      end
+
+      def self.parse_tagged(klass, scanner, id, start_offset)
+        scanner.getch # consume the tag byte (I or E)
+        json = read_to_newline(scanner, start_offset)
+        {
+          id: id,
+          class: klass,
+          payload: parse_json(json, start_offset),
+          raw: scanner.string.byteslice(start_offset, scanner.pos - start_offset)
+        }
+      end
+
+      def self.parse_model_row(scanner, id, start_offset)
+        json = read_to_newline(scanner, start_offset)
+        {
+          id: id,
+          class: :model,
+          payload: parse_json(json, start_offset),
+          raw: scanner.string.byteslice(start_offset, scanner.pos - start_offset)
+        }
+      end
+
+      def self.parse_text_row(scanner, id, start_offset)
+        scanner.getch # consume "T"
+        len_hex = scanner.scan(/\h+/) || raise_parse_error(start_offset, "expected hex length after T")
+        scanner.skip(",") || raise_parse_error(start_offset, "expected ',' after T<len>")
+        len = len_hex.to_i(16)
+
+        text = scanner.peek(len)
+        raise_parse_error(start_offset, "T row truncated") if text.nil? || text.bytesize < len
+
+        scanner.pos += len
+        {
+          id: id,
+          class: :text,
+          payload: text,
+          raw: scanner.string.byteslice(start_offset, scanner.pos - start_offset)
+        }
+      end
+
+      def self.read_to_newline(scanner, start_offset)
+        line = scanner.scan_until(/\n/) || raise_parse_error(start_offset, "missing trailing newline")
+        line.chomp
+      end
+
+      def self.parse_json(str, offset)
+        JSON.parse(str)
+      rescue JSON::ParserError => e
+        raise_parse_error(offset, "invalid JSON: #{e.message}")
+      end
+
+      def self.raise_parse_error(offset, reason)
+        raise FlightWireParseError, "FlightWireParser: cannot parse row at offset #{offset}: #{reason}"
+      end
+
+      private_class_method :parse_row, :parse_tagged, :parse_model_row, :parse_text_row,
+                           :read_to_newline, :parse_json, :raise_parse_error
+    end
+  end
+end

data/spec/support/flight_wire_parser_spec.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require_relative "flight_wire_parser"
+
+module Ruact
+  module Spec
+    RSpec.describe FlightWireParser do
+      describe ".parse" do
+        it "parses a single model row" do
+          rows = described_class.parse(%(0:{"className":"box"}\n))
+
+          expect(rows).to eq([
+                               {
+                                 id: 0,
+                                 class: :model,
+                                 payload: { "className" => "box" },
+                                 raw: %(0:{"className":"box"}\n)
+                               }
+                             ])
+        end
+
+        it "parses a single import row and decodes the hex id" do
+          rows = described_class.parse(%(a:I["/L.jsx","L",["/L.jsx"]]\n))
+
+          expect(rows.length).to eq(1)
+          expect(rows.first).to include(
+            id: 10,
+            class: :import,
+            payload: ["/L.jsx", "L", ["/L.jsx"]]
+          )
+        end
+
+        it "parses a single error row" do
+          rows = described_class.parse(%(2:E{"message":"boom"}\n))
+
+          expect(rows.first).to include(
+            id: 2,
+            class: :error,
+            payload: { "message" => "boom" }
+          )
+        end
+
+        it "parses a hint row with no id" do
+          rows = described_class.parse(%(:HL"/preload.js"\n))
+
+          expect(rows.first).to include(
+            id: nil,
+            class: :hint,
+            payload: ["L", "/preload.js"]
+          )
+        end
+
+        it "parses a T row of exactly LARGE_TEXT_THRESHOLD bytes followed by a model row that references it" do
+          large_text = "a" * 1024
+          wire = "1:T#{1024.to_s(16)},#{large_text}0:\"$T1\"\n"
+
+          rows = described_class.parse(wire)
+
+          expect(rows.length).to eq(2)
+          expect(rows[0]).to include(id: 1, class: :text, payload: large_text)
+          expect(rows[1]).to include(id: 0, class: :model, payload: "$T1")
+        end
+
+        it "parses a mixed-row sequence preserving wire order" do
+          wire = %(1:I["/L.jsx","L",["/L.jsx"]]\n0:["$","$L1",null,{}]\n)
+
+          rows = described_class.parse(wire)
+
+          expect(rows.map { |r| [r[:id], r[:class]] }).to eq([[1, :import], [0, :model]])
+        end
+
+        it "parses empty input as an empty array" do
+          expect(described_class.parse("")).to eq([])
+        end
+
+        it "raises FlightWireParseError naming the byte offset on malformed JSON" do
+          wire = %(0:{not-json}\n)
+
+          expect { described_class.parse(wire) }
+            .to raise_error(FlightWireParseError, /cannot parse row at offset \d+/)
+        end
+
+        it "raises FlightWireParseError when a T row is truncated" do
+          wire = "0:T#{10.to_s(16)},abc" # claims 16 bytes but provides 3
+
+          expect { described_class.parse(wire) }
+            .to raise_error(FlightWireParseError, /cannot parse row at offset 0: T row truncated/)
+        end
+      end
+    end
+  end
+end

data/spec/support/matchers/flight_fixture_matcher.rb

@@ -1,5 +1,278 @@
 # frozen_string_literal: true
 
+require_relative "../flight_wire_parser"
+
+module Ruact
+  module Spec
+    # Internal helpers shared by the structural Flight matchers. Lives under
+    # `Ruact::Spec` (test-only namespace) — no top-level constants leak into
+    # the gem's public API surface.
+    # 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
+
+# `match_flight_fixture(name)` — Phase 1 byte-exact snapshot matcher.
+#
+# Reads `spec/fixtures/flight/<name>.txt` and compares the actual wire bytes
+# to the file contents via `==`. Used when the wire format itself is the
+# contract (escape rules, ordering invariants, payload framing).
+#
+# @example
+#   expect(serializer.serialize_value("$danger")).to match_flight_fixture("string_dollar_escape")
 RSpec::Matchers.define :match_flight_fixture do |name|
   match do |actual|
     fixtures_dir = File.expand_path("../../fixtures/flight", __dir__)
@@ -23,3 +296,86 @@ RSpec::Matchers.define :match_flight_fixture do |name|
     "match Flight wire fixture '#{name}'"
   end
 end
+
+# `match_flight_structure(expected)` — Phase 2 structural matcher (Story 7.5).
+#
+# Parses the actual Flight wire output via `Ruact::Spec::FlightWireParser`,
+# then compares the resulting array of row records against `expected`. Hash
+# payloads are compared structurally (key insertion order is ignored), so
+# cosmetic JSON re-ordering does not break specs that assert on semantics.
+# Import rows are matched as a multiset; non-import rows are compared
+# positionally because Flight semantics depend on their order.
+#
+# Failure messages name the row index and the differing field — bytes are
+# only printed when no narrower diff is available.
+#
+# @example
+#   expect(wire).to match_flight_structure([
+#     { id: 1, class: :import, payload: ["/L.jsx", "L", ["/L.jsx"]] },
+#     { id: 0, class: :model,  payload: ["$", "$L1", nil, {}] }
+#   ])
+RSpec::Matchers.define :match_flight_structure do |expected|
+  match do |actual|
+    @parsed = Ruact::Spec::FlightWireParser.parse(actual)
+    @expected_rows = expected
+    @diffs = Ruact::Spec::FlightStructureDiff.compute(@parsed, expected)
+    @diffs.empty?
+  end
+
+  failure_message do |_actual|
+    if @diffs.length == 1
+      Ruact::Spec::FlightStructureDiff.format_single(@diffs.first)
+    else
+      Ruact::Spec::FlightStructureDiff.format_multi(@diffs, @parsed, @expected_rows)
+    end
+  end
+
+  failure_message_when_negated do |_actual|
+    "Expected output NOT to match the given Flight wire structure, but it did."
+  end
+
+  description do
+    "match Flight wire structure (#{expected.length} row(s))"
+  end
+end
+
+# `include_flight_row(predicate)` — Phase 2 ordering-independent presence matcher (Story 7.5).
+#
+# Parses the actual Flight wire output, then asserts at least one parsed row
+# satisfies the predicate hash. Subset semantics: only the keys present in
+# `predicate` are compared. Predicate keys must be one of `:id`, `:class`,
+# `:payload`, `:raw` — unknown keys raise upfront so typos don't silently
+# match every row. Values may be plain Ruby values (compared with `==`) or
+# RSpec argument matchers like `hash_including(...)` (compared with `===`).
+# Negation (`not_to`) is supported.
+#
+# @example
+#   expect(wire).to include_flight_row(class: :model, payload: hash_including("postId" => 42))
+RSpec::Matchers.define :include_flight_row do |predicate|
+  match do |actual|
+    Ruact::Spec::FlightStructureDiff.validate_predicate!(predicate)
+    @parsed = Ruact::Spec::FlightWireParser.parse(actual)
+    @predicate = predicate
+    @matched_idx = @parsed.find_index { |row| Ruact::Spec::FlightStructureDiff.row_matches?(row, predicate) }
+    !@matched_idx.nil?
+  end
+
+  failure_message do |_actual|
+    summary = @parsed.each_with_index.map do |row, i|
+      payload_snippet = row[:payload].inspect
+      payload_snippet = "#{payload_snippet[0, 80]}…" if payload_snippet.length > 80
+      "  [#{i}] id=#{row[:id].inspect}, class=#{row[:class]}, payload=#{payload_snippet}"
+    end.join("\n")
+    summary = "  (no rows parsed)" if @parsed.empty?
+
+    "Expected Flight output to include a row matching: #{predicate.inspect}.\nParsed rows:\n#{summary}"
+  end
+
+  failure_message_when_negated do |_actual|
+    "Expected Flight output NOT to include a row matching: #{predicate.inspect}, but row #{@matched_idx} matched."
+  end
+
+  description do
+    "include a Flight row matching #{predicate.inspect}"
+  end
+end