ruact 0.0.1 → 0.0.3

data/spec/fixtures/flight/README.md

@@ -38,19 +38,62 @@ Expected output (`client_reference.txt`):
 
 ---
 
-## How `match_flight_fixture` Works
+## How to assert on Flight output
 
-The custom RSpec matcher is defined in `spec/support/matchers/flight_fixture_matcher.rb`:
+Three RSpec matcher modes live in `spec/support/matchers/flight_fixture_matcher.rb`. Pick the mode that names what you actually care about — defaulting to `match_flight_structure` for new specs avoids the cosmetic-change brittleness that bit Phase 1 (a `JSON.generate` tweak broke 30+ specs at once).
+
+| Mode | When to use | What it tolerates | Failure shape |
+|---|---|---|---|
+| `match_flight_fixture(name)` | The wire format itself is the contract — bytes-for-bytes guard. Use for serializer escape rules, ordering invariants, or any test where "the output looks exactly like this" is the assertion. | Nothing — exact `==` against the fixture file. | Inspected expected vs. actual strings (whitespace and escapes visible). |
+| `match_flight_structure(expected)` | The parsed semantics are the contract — change-tolerant. Use for round-tripping tests, scaffolding, end-to-end render tests, and any case where JSON key reordering or whitespace tweaks should not break the spec. | JSON key insertion order inside payload hashes; whitespace inside JSON; relative ordering among `:import` rows (which Flight treats as an unordered set). Cross-class row order (imports → models → deferred → errors) is **preserved** because the wire protocol depends on it. | Row-indexed diff naming the differing field path (e.g. `Row 0 (model) differs at .payload[0]:`). |
+| `include_flight_row(predicate)` | A specific shape must appear regardless of order or siblings. Use for concurrency tests, partial assertions in multi-row outputs, or "this row exists somewhere" checks. | Sibling rows; ordering. Predicate is subset-matched (only the keys you list are compared). | Predicate inspect + a list of every parsed row with id/class/payload preview. |
+
+### Worked examples
+
+Each example is a complete RSpec assertion you can paste into a spec file (above `RSpec.describe` blocks where the matchers are autoloaded by `spec_helper`).
+
+**`match_flight_fixture` — wire-format contract guard:**
+```ruby
+serialized = "0:\"$$danger\"\n"
+expect(serialized).to match_flight_fixture("string_dollar_escape")
+# Asserts byte-for-byte against `string_dollar_escape.txt` — proves the `$` → `$$` escape rule.
+```
+
+**`match_flight_structure` — parsed-semantics assertion:**
+```ruby
+wire = %(1:I["/LikeButton.jsx","LikeButton",["/LikeButton.jsx"]]\n) +
+       %(0:["$","$L1",null,{"postId":42}]\n)
+
+expect(wire).to match_flight_structure([
+  { id: 1, class: :import, payload: ["/LikeButton.jsx", "LikeButton", ["/LikeButton.jsx"]] },
+  { id: 0, class: :model,  payload: ["$", "$L1", nil, { "postId" => 42 }] }
+])
+# Passes even if `JSON.generate` re-orders props later — what matters is that postId=42 round-trips.
+```
+
+**`include_flight_row` — ordering-independent presence check:**
+```ruby
+wire = %(0:["$","CounterButton",null,{"initialCount":0}]\n)
+
+expect(wire).to include_flight_row(
+  class: :model,
+  payload: hash_including("initialCount" => 0)
+)
+# Used in concurrency specs where multiple threads emit interleaved rows; only the row's shape matters.
+```
+
+### ❌ Avoid / ✅ Prefer
 
 ```ruby
-expect(output).to match_flight_fixture("nil")
+❌ expect(output).to include('"postId":42')   # cosmetic-change brittle
+✅ expect(output).to include_flight_row(class: :model, payload: hash_including("postId" => 42))
 ```
 
-This reads `spec/fixtures/flight/nil.txt` and performs an **exact string comparison** against `output`. There is no normalisation — whitespace, newlines, and ordering must match exactly.
+A future `JSON.generate` change that emits keys in different insertion order (`{"label":"x","postId":42}` instead of `{"postId":42,"label":"x"}`) breaks the literal substring match. The structural form parses the row and compares hashes by key-set, so it survives the cosmetic change.
 
-### Failure output
+### When a fixture spec fails after a serializer change
 
-When a fixture does not match, the failure message shows both the expected (fixture file content) and actual (serializer output) as inspected strings, making it easy to spot differences in whitespace or character escaping.
+If `match_flight_fixture` fails after touching `Ruact::Flight::Serializer`, that's by design — the wire format **is** the contract for those fixtures. Either the change is intentional (update the fixture file and the CHANGELOG) or it isn't (revert). Don't switch the spec to `match_flight_structure` to "make it green"; that hides the regression that fixture mode is designed to catch.
 
 ---
 
@@ -63,6 +106,11 @@ When a fixture does not match, the failure message shows both the expected (fixt
 | `boolean_false.txt` | Ruby `false` serializes to the JSON `false` literal |
 | `number_integer.txt` | Ruby integer (e.g. `42`) serializes to a bare JSON number |
 | `number_float.txt` | Ruby float (e.g. `3.14`) serializes to a bare JSON float |
+| `bigint.txt` | Ruby integer above `MAX_SAFE_INTEGER` (`2**53`) serializes to `"$n<decimal>"` so the JS client can rebuild a `BigInt` |
+| `nan.txt` | `Float::NAN` serializes to `"$NaN"` (JSON has no NaN literal; Flight uses the `$`-prefix sentinel) |
+| `infinity.txt` | `Float::INFINITY` serializes to `"$Infinity"` |
+| `negative_infinity.txt` | `-Float::INFINITY` serializes to `"$-Infinity"` |
+| `undefined.txt` | The `:undefined` symbol sentinel serializes to `"$undefined"` so the JS client decodes it as `undefined` (JSON has no undefined literal) |
 | `string_basic.txt` | Plain Ruby string serializes to a JSON double-quoted string |
 | `string_dollar_escape.txt` | Strings starting with `$` are escaped to `$$…` to avoid collision with Flight's `$L` reference syntax |
 | `array.txt` | Ruby array serializes to a JSON array in row 0 |
@@ -71,7 +119,7 @@ When a fixture does not match, the failure message shows both the expected (fixt
 | `client_component_with_props.txt` | A `ClientReference` with props passes them as the fourth element of the root array |
 | `react_element_no_props.txt` | A `ReactElement` with no props produces `["$","<tag>",null,{}]` in row 0 |
 | `as_json_object.txt` | An object responding to `as_json` is serialized via that method; if it resolves to a `ClientReference`, import + root rows are emitted |
-| `serializable_object.txt` | An object including `Ruact::Serializable` and declaring `rsc_props` serializes only the declared props |
+| `serializable_object.txt` | An object including `Ruact::Serializable` and declaring `ruact_props` serializes only the declared props |
 | `redirect_row.txt` | A redirect instruction serializes to a JSON object with `redirectUrl` and `redirectType` keys in row 0 |
 
 ---

data/spec/fixtures/flight/bigint.txt

@@ -0,0 +1 @@
+0:"$n9007199254740992"

data/spec/fixtures/flight/infinity.txt

@@ -0,0 +1 @@
+0:"$Infinity"

data/spec/fixtures/flight/nan.txt

@@ -0,0 +1 @@
+0:"$NaN"

data/spec/fixtures/flight/negative_infinity.txt

@@ -0,0 +1 @@
+0:"$-Infinity"

data/spec/fixtures/flight/undefined.txt

@@ -0,0 +1 @@
+0:"$undefined"

data/spec/fixtures/story_7_9_views/controller_request_spec_support/demo/show.html.erb

@@ -0,0 +1,3 @@
+<div>
+  <DemoButton label={"hello"} />
+</div>

data/spec/ruact/client_manifest_spec.rb

@@ -122,5 +122,113 @@ module Ruact
         expect(manifest).not_to be_frozen
       end
     end
+
+    describe "#reference_for closest-match suggestion (Story 7.4)" do
+      let(:shared_only_manifest) { described_class.from_hash(manifest_data) }
+      let(:dual_manifest)        { described_class.from_hash(dual_manifest_data) }
+
+      it "suggests the shared key for a one-character typo" do
+        expect { shared_only_manifest.reference_for("LikeButtonn") }
+          .to raise_error(Ruact::ManifestError, /Did you mean "LikeButton"\?/)
+      end
+
+      it "suggests the shared key for a two-character typo (boundary)" do
+        # "LiekButtoon" is the AC7 spec 13 boundary case (transposition + one
+        # insertion); under Damerau-Levenshtein its distance from "LikeButton"
+        # is 2, so the suggestion fires.
+        expect { shared_only_manifest.reference_for("LiekButtoon") }
+          .to raise_error(Ruact::ManifestError, /Did you mean "LikeButton"\?/)
+      end
+
+      it "falls back to the file-path hint when the typo is over distance 2" do
+        expect { shared_only_manifest.reference_for("LkkButttn") }
+          .to raise_error(Ruact::ManifestError) do |error|
+            expect(error.message)
+              .to match(%r{Did you mean to add app/javascript/components/LkkButttn\.jsx and rebuild Vite\?})
+            expect(error.message).not_to match(/Did you mean "LikeButton"\?/)
+          end
+      end
+
+      it "falls back to the file-path hint for a totally unrelated name" do
+        expect { shared_only_manifest.reference_for("Whatever") }
+          .to raise_error(Ruact::ManifestError,
+                          %r{Did you mean to add app/javascript/components/Whatever\.jsx and rebuild Vite\?})
+      end
+
+      it "suggests a co-located key (with original key shown) when it is the closest match" do
+        co_located_only = described_class.from_hash(
+          "posts/_like_button" => {
+            "id" => "/posts/_like_button.jsx",
+            "name" => "default",
+            "chunks" => ["/posts/_like_button.jsx"]
+          }
+        )
+        expect { co_located_only.reference_for("LikeButtoon") }
+          .to raise_error(Ruact::ManifestError, %r{Did you mean "posts/_like_button"\?})
+      end
+
+      it "biases the suggestion toward co-located keys when controller_path is given" do
+        # Both "LikeButton" (shared) and "posts/_like_button" (co-located) tie
+        # at distance 1 from "LikeButtoon". Without controller_path the first
+        # one encountered wins (hash-iteration order); with controller_path:"posts"
+        # the co-located key is preferred so the suggestion is contextual.
+        expect { dual_manifest.reference_for("LikeButtoon", controller_path: "posts") }
+          .to raise_error(Ruact::ManifestError, %r{Did you mean "posts/_like_button"\?})
+      end
+
+      it "preserves the existing 'Did you run the Vite build?' hint in every variant" do
+        vite_hint = /Did you run the Vite build\? Run 'npm run build' or start the Vite dev server\./
+        expect { shared_only_manifest.reference_for("LikeButtonn") }
+          .to raise_error(Ruact::ManifestError, vite_hint)
+        expect { shared_only_manifest.reference_for("Whatever") }
+          .to raise_error(Ruact::ManifestError, vite_hint)
+      end
+
+      it "uses the AC3 verbatim multi-line 'ruact:' message shape" do
+        expect { shared_only_manifest.reference_for("LikeButtonn") }
+          .to raise_error(Ruact::ManifestError) do |error|
+            expect(error.message).to eq(<<~MSG.strip)
+              ruact: Component "LikeButtonn" not found in manifest.
+                Did you mean "LikeButton"?
+                Did you run the Vite build? Run 'npm run build' or start the Vite dev server.
+            MSG
+          end
+      end
+    end
+
+    describe "edge cases (Story 7.4)" do
+      it "does not raise FrozenError when an empty loaded manifest looks up an unknown component" do
+        empty_manifest = Tempfile.create(["empty_manifest", ".json"]) do |f|
+          f.write("{}")
+          f.flush
+          described_class.load(f.path)
+        end
+
+        expect(empty_manifest).to be_frozen
+        expect { empty_manifest.reference_for("LikeButton") }
+          .to raise_error(Ruact::ManifestError, /not found in manifest/)
+      end
+
+      it "uses entry['name'] (not the lookup key) for ClientReference#export_name" do
+        manifest = described_class.from_hash(
+          "LikeButton" => {
+            "id" => "/LikeButton.jsx",
+            "name" => "LikeButton",
+            "chunks" => ["/LikeButton.jsx"]
+          },
+          "posts/_like_button" => {
+            "id" => "/posts/_like_button.jsx",
+            "name" => "default",
+            "chunks" => ["/posts/_like_button.jsx"]
+          }
+        )
+
+        shared_ref     = manifest.reference_for("LikeButton")
+        co_located_ref = manifest.reference_for("LikeButton", controller_path: "posts")
+
+        expect(shared_ref.export_name).to eq("LikeButton")
+        expect(co_located_ref.export_name).to eq("default")
+      end
+    end
   end
 end