RubyGems - ruact - Versions diffs - 0.0.7 → 0.0.8 - Mend

ruact 0.0.7 → 0.0.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (38) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +24 -0
data/docs/internal/decisions/server-functions-api.md +55 -0
data/lib/generators/ruact/install/install_generator.rb +114 -1
data/lib/generators/ruact/install/templates/AGENTS.md.tt +159 -0
data/lib/ruact/controller.rb +9 -0
data/lib/ruact/doctor.rb +67 -9
data/lib/ruact/erb_preprocessor.rb +113 -0
data/lib/ruact/errors.rb +16 -0
data/lib/ruact/manifest_resolver.rb +2 -2
data/lib/ruact/serializable.rb +98 -6
data/lib/ruact/server.rb +163 -0
data/lib/ruact/server_functions/introspection.rb +81 -0
data/lib/ruact/server_functions.rb +26 -4
data/lib/ruact/testing/component_query.rb +113 -0
data/lib/ruact/testing/flight_extractor.rb +221 -0
data/lib/ruact/testing/flight_structure_diff.rb +267 -0
data/lib/ruact/testing/flight_wire_parser.rb +138 -0
data/lib/ruact/testing.rb +90 -0
data/lib/ruact/version.rb +1 -1
data/lib/tasks/ruact.rake +55 -2
data/spec/ruact/doctor_spec.rb +141 -0
data/spec/ruact/erb_preprocessor_spec.rb +145 -0
data/spec/ruact/install_generator_spec.rb +285 -0
data/spec/ruact/manifest_resolver_spec.rb +15 -0
data/spec/ruact/serializable_spec.rb +126 -0
data/spec/ruact/server_bucket_request_spec.rb +291 -0
data/spec/ruact/server_functions/introspection_spec.rb +135 -0
data/spec/ruact/tasks_json_introspection_spec.rb +141 -0
data/spec/ruact/testing/have_ruact_component_spec.rb +170 -0
data/spec/ruact/testing/no_production_load_spec.rb +41 -0
data/spec/support/flight_wire_parser.rb +12 -126
data/spec/support/matchers/flight_fixture_matcher.rb +7 -258
data/vendor/javascript/ruact-server-functions-runtime/index.d.ts +25 -0
data/vendor/javascript/ruact-server-functions-runtime/index.js +104 -7
data/vendor/javascript/ruact-server-functions-runtime/index.test.mjs +173 -0
data/vendor/javascript/vite-plugin-ruact/type-tests/auto-revalidate.test-d.ts +25 -0
metadata +14 -2

data/spec/ruact/testing/have_ruact_component_spec.rb ADDED Viewed

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+require "spec_helper"
+require "ruact/testing"
+# Story 15.4 (FR108) — end-to-end specs for the PUBLIC render-assertion matcher
+# `have_ruact_component`. Every example asserts against a REAL Flight wire body
+# produced by `Ruact::RenderPipeline` (the same serializer the controller runs),
+# not a hand-authored fixture — so import rows, `$L<id>` references, and the
+# serialized props hash are exactly what a host would receive.
+module Ruact
+  RSpec.describe "have_ruact_component matcher", :story_15_4 do
+    let(:manifest) do
+      ClientManifest.from_hash({
+                                 "LikeButton" => {
+                                   "id" => "/assets/LikeButton-abc.js",
+                                   "name" => "LikeButton",
+                                   "chunks" => ["/assets/LikeButton-abc.js"]
+                                 },
+                                 "PostCard" => {
+                                   "id" => "/components/PostCard.jsx",
+                                   "name" => "PostCard",
+                                   "chunks" => ["/components/PostCard.jsx"]
+                                 }
+                               })
+    end
+    let(:pipeline) { RenderPipeline.new(manifest) }
+    # Renders an ERB snippet to a REAL Flight wire string.
+    def render_wire(erb_source, **ivars)
+      ctx = Object.new
+      ivars.each { |k, v| ctx.instance_variable_set("@#{k}", v) }
+      pipeline.render({ erb: erb_source, binding: ctx.instance_eval { binding } }, mode: :string)
+    end
+    # Wraps a wire in the REAL HTML shell the gem emits (`__FLIGHT_DATA` push),
+    # via the shipped `Ruact::ViewHelper#ruact_flight_data_script`.
+    def html_shell(wire)
+      emitter = Object.new.extend(Ruact::ViewHelper)
+      script = emitter.send(:ruact_flight_data_script, wire)
+      "<!DOCTYPE html><html><body><div id=\"root\"></div>#{script}</body></html>"
+    end
+    # A minimal duck-typed response object exposing `.body` (+ optional
+    # `.content_type`), like an ActionDispatch/Rack response.
+    def response_double(body, content_type: nil)
+      Struct.new(:body, :content_type).new(body, content_type)
+    end
+    describe "presence (raw text/x-component body)" do
+      it "passes when the named component was rendered" do
+        wire = render_wire("<LikeButton postId={42} />")
+        expect(wire).to have_ruact_component("LikeButton")
+      end
+      it "resolves the name by module basename too (D3)" do
+        wire = render_wire("<PostCard title={\"Hi\"} />")
+        # Manifest module path is /components/PostCard.jsx → basename PostCard.
+        expect(wire).to have_ruact_component("PostCard")
+      end
+      it "fails with a legible message naming what was found when absent" do
+        wire = render_wire("<LikeButton />")
+        expect do
+          expect(wire).to have_ruact_component("Missing")
+        end.to raise_error(RSpec::Expectations::ExpectationNotMetError,
+                           /component named "Missing".*found.*LikeButton/m)
+      end
+      it "supports negation for an absent component" do
+        wire = render_wire("<LikeButton />")
+        expect(wire).not_to have_ruact_component("Missing")
+      end
+      it "negation fails legibly when the component IS present" do
+        wire = render_wire("<LikeButton />")
+        expect do
+          expect(wire).not_to have_ruact_component("LikeButton")
+        end.to raise_error(RSpec::Expectations::ExpectationNotMetError, /NOT to have rendered.*"LikeButton"/m)
+      end
+    end
+    describe ".with_props (serialized wire form, D4)" do
+      it "passes when props satisfy a hash_including matcher" do
+        wire = render_wire("<LikeButton postId={42} />")
+        expect(wire).to have_ruact_component("LikeButton").with_props(a_hash_including("postId" => 42))
+      end
+      it "passes with a bare key-presence include matcher" do
+        wire = render_wire("<LikeButton postId={42} />")
+        expect(wire).to have_ruact_component("LikeButton").with_props(including("postId"))
+      end
+      it "fails with a legible message when props mismatch" do
+        wire = render_wire("<LikeButton postId={42} />")
+        expect do
+          expect(wire).to have_ruact_component("LikeButton").with_props(a_hash_including("postId" => 99))
+        end.to raise_error(RSpec::Expectations::ExpectationNotMetError,
+                           /props matching.*serialized wire form.*"postId".*42/m)
+      end
+      it "supports negation with props" do
+        wire = render_wire("<LikeButton postId={42} />")
+        expect(wire).not_to have_ruact_component("LikeButton").with_props(a_hash_including("postId" => 99))
+      end
+    end
+    describe "input shapes (D2)" do
+      it "accepts a response object exposing #body (raw wire)" do
+        wire = render_wire("<LikeButton postId={7} />")
+        response = response_double(wire, content_type: "text/x-component")
+        expect(response).to have_ruact_component("LikeButton").with_props(a_hash_including("postId" => 7))
+      end
+      it "extracts Flight from an HTML shell embedding __FLIGHT_DATA" do
+        wire = render_wire("<LikeButton postId={5} />")
+        html = html_shell(wire)
+        expect(html).to have_ruact_component("LikeButton").with_props(a_hash_including("postId" => 5))
+      end
+      it "ignores an unrelated earlier .push and anchors to __FLIGHT_DATA" do
+        wire = render_wire("<LikeButton postId={5} />")
+        shell = html_shell(wire)
+        # A realistic layout has other scripts BEFORE the ruact bootstrap.
+        noise = %(<script>window.dataLayer=window.dataLayer||[];dataLayer.push("not flight");</script>)
+        html = shell.sub("<div id=\"root\"></div>", "<div id=\"root\"></div>#{noise}")
+        expect(html).to have_ruact_component("LikeButton").with_props(a_hash_including("postId" => 5))
+      end
+      it "extracts Flight from an HTML-response object (content_type text/html)" do
+        wire = render_wire("<LikeButton postId={5} />")
+        response = response_double(html_shell(wire), content_type: "text/html; charset=utf-8")
+        expect(response).to have_ruact_component("LikeButton")
+      end
+      it "raises a clear error on a plain-JSON function-call body" do
+        json = response_double(%({"id":1,"title":"Hi"}), content_type: "application/json")
+        expect do
+          expect(json).to have_ruact_component("PostCard")
+        end.to raise_error(Ruact::Testing::NotAFlightResponseError, /plain-JSON response.*JSON\.parse/m)
+      end
+      it "raises a clear error on an empty (204) body" do
+        empty = response_double("", content_type: nil)
+        expect do
+          expect(empty).to have_ruact_component("PostCard")
+        end.to raise_error(Ruact::Testing::NotAFlightResponseError, /empty response body/m)
+      end
+      it "raises a clear error when handed an HTML doc with no Flight payload" do
+        html = "<!DOCTYPE html><html><body><h1>Nothing here</h1></body></html>"
+        expect do
+          expect(html).to have_ruact_component("PostCard")
+        end.to raise_error(Ruact::Testing::NotAFlightResponseError, /no `__FLIGHT_DATA` payload/m)
+      end
+    end
+    describe "escape round-trip through the HTML shell" do
+      it "recovers a payload containing quotes and interpolation-like sequences" do
+        # Props whose serialized form contains characters Ruby's #inspect
+        # escapes (`"`, `#{`, newlines) must survive extraction from the shell.
+        wire = render_wire("<LikeButton label={@label} />", label: %(a "quoted" \#{literal}\nvalue))
+        html = html_shell(wire)
+        expect(html).to have_ruact_component("LikeButton")
+          .with_props(a_hash_including("label" => a_string_matching(/quoted/)))
+      end
+    end
+  end
+end

data/spec/ruact/testing/no_production_load_spec.rb ADDED Viewed

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+require "spec_helper"
+require "English"
+require "shellwords"
+# Story 15.4 (FR108), AC4c + AC2 — the public test surface must not load in a
+# production boot, and the promoted parser/diff must be the SINGLE shipped
+# implementation the internal `Ruact::Spec` matchers share (wrap, not fork).
+module Ruact
+  RSpec.describe "Ruact::Testing load boundary", :story_15_4 do
+    it "a bare `require \"ruact\"` does NOT define the public test surface" do
+      # Shell out to a pristine Ruby process so nothing this suite already
+      # loaded (spec/support requires `ruact/testing/*`) pollutes the check.
+      lib = File.expand_path("../../../lib", __dir__)
+      script = <<~RUBY
+        $LOAD_PATH.unshift(#{lib.inspect})
+        require "ruact"
+        defined = Ruact.const_defined?(:Testing, false)
+        # `have_ruact_component` must not be registered on the RSpec matcher surface either.
+        rspec_loaded = $LOADED_FEATURES.any? { |f| f.include?("rspec/expectations") }
+        print [defined, rspec_loaded].inspect
+      RUBY
+      output = `#{RbConfig.ruby} -e #{Shellwords.escape(script)} 2>&1`
+      expect($CHILD_STATUS).to be_success, "subprocess failed: #{output}"
+      expect(output).to eq("[false, false]"),
+                        "expected `require \"ruact\"` to leave Ruact::Testing undefined and " \
+                        "RSpec unloaded, got: #{output}"
+    end
+    it "shares ONE implementation with the internal matchers (no fork)" do
+      require "ruact/testing"
+      require_relative "../../support/flight_wire_parser"
+      require_relative "../../support/matchers/flight_fixture_matcher"
+      expect(Ruact::Spec::FlightWireParser).to equal(Ruact::Testing::FlightWireParser)
+      expect(Ruact::Spec::FlightStructureDiff).to equal(Ruact::Testing::FlightStructureDiff)
+    end
+  end
+end

data/spec/support/flight_wire_parser.rb CHANGED Viewed

@@ -1,135 +1,21 @@
 # frozen_string_literal: true
-require "strscan"
-require "json"
+# Story 15.4 (FR108) — the pure Flight wire parser was PROMOTED onto the gem's
+# `lib/` load path as `Ruact::Testing::FlightWireParser` so the new public
+# `have_ruact_component` matcher and the gem's own internal matchers share ONE
+# implementation (wrap, not fork). This file is now a thin shim: it loads the
+# promoted implementation and re-exports it under the historical test-only
+# `Ruact::Spec` namespace so the existing internal matcher wrappers and their
+# self-tests keep working unchanged.
+require "ruact/testing/flight_wire_parser"
 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.
+  # shape across stories without a deprecation cycle. The parser/diff it names
+  # are aliases for the shipped `Ruact::Testing::*` implementation.
   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
+    FlightWireParser = Ruact::Testing::FlightWireParser
+    FlightWireParseError = Ruact::Testing::FlightWireParseError
   end
 end

data/spec/support/matchers/flight_fixture_matcher.rb CHANGED Viewed

@@ -1,267 +1,16 @@
 # frozen_string_literal: true
 require_relative "../flight_wire_parser"
+require "ruact/testing/flight_structure_diff"
 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
+    # Story 15.4 (FR108) — the structural diff engine was PROMOTED onto the
+    # gem's `lib/` load path as `Ruact::Testing::FlightStructureDiff` (shared,
+    # single implementation — wrap, not fork). This test-only `Ruact::Spec`
+    # alias keeps the internal matcher wrappers below and their self-tests
+    # working unchanged.
+    FlightStructureDiff = Ruact::Testing::FlightStructureDiff
   end
 end

data/vendor/javascript/ruact-server-functions-runtime/index.d.ts CHANGED Viewed

@@ -151,11 +151,36 @@ export const __RUNTIME_VERSION__: number;
  *
  * The gem's own headers (`Accept`, `Content-Type`, `X-CSRF-Token`)
  * win over `defaultHeaders` — CSRF cannot be silently overridden.
+ *
+ * Story 15.6 (FR110) — `autoRevalidate` (default `false`) is the app-wide
+ * auto-revalidate default: when `true`, every successful, non-redirecting
+ * mutation `await`s an in-place Flight refresh of the current path (via
+ * `revalidate()`) before resolving with the action's JSON result. A per-call
+ * `withRefresh(accessor)` wins over this global default.
  */
 export function configureRuactRuntime(options: {
   defaultHeaders?: Record<string, string> | (() => Record<string, string>) | null;
+  autoRevalidate?: boolean;
 }): void;
+/**
+ * Story 15.6 (FR110) — per-call auto-revalidate wrapper. Wraps a generated
+ * server-function accessor and returns a new accessor that forces an in-place
+ * Flight refresh of the current path after a successful, non-redirecting call —
+ * regardless of the app-wide `autoRevalidate` default (per-call explicit wins).
+ * Runtime-only: it does not change the codegen or the wire.
+ *
+ * A `$redirect` response still wins (the refresh is skipped); a failed mutation
+ * still throws before any refresh; and if no router is installed the descriptive
+ * `revalidate()` error surfaces (a successful mutation whose refresh rejects
+ * rejects the returned promise).
+ *
+ * The wrapped accessor keeps its own call signature (the same
+ * `(arg1?, arg2?) => Promise<unknown>` / `(formData) => Promise<void>`
+ * intersection the codegen emits).
+ */
+export function withRefresh<F extends (...args: never[]) => Promise<unknown>>(accessor: F): F;
 /**
  * Re-run-4 (2026-05-15) — structured error thrown for 4xx/5xx responses.
  * Callers can branch on `status` and inspect `body` (already