ruact 0.0.2 → 0.0.4

data/spec/support/matchers/flight_fixture_matcher_spec.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# Specs for the three Flight wire matcher modes added in Story 7.5
+# (`match_flight_fixture`, `match_flight_structure`, `include_flight_row`).
+RSpec.describe "Flight wire matchers" do
+  # Captures an `ExpectationNotMetError` raised by the inner block so the
+  # spec can make multiple assertions on its message without resorting to a
+  # multi-line block chained off `raise_error`.
+  def capture_failure
+    yield
+    nil
+  rescue RSpec::Expectations::ExpectationNotMetError => e
+    e
+  end
+
+  describe "match_flight_fixture (existing snapshot mode)" do
+    let(:nil_wire) { "0:null\n" }
+
+    it "passes against canonical fixture content (regression check)" do
+      expect(nil_wire).to match_flight_fixture("nil")
+    end
+  end
+
+  describe "match_flight_structure" do
+    let(:simple_wire) { %(0:{"className":"box"}\n) }
+    let(:two_row_wire) { %(1:I["/L.jsx","L",["/L.jsx"]]\n0:["$","$L1",null,{}]\n) }
+
+    it "passes when the actual wire matches a single-row expected structure" do
+      expect(simple_wire).to match_flight_structure([
+                                                      { id: 0, class: :model, payload: { "className" => "box" } }
+                                                    ])
+    end
+
+    it "passes for a two-row mixed import + model sequence" do
+      expect(two_row_wire).to match_flight_structure([
+                                                       { id: 1, class: :import, payload: ["/L.jsx", "L", ["/L.jsx"]] },
+                                                       { id: 0, class: :model, payload: ["$", "$L1", nil, {}] }
+                                                     ])
+    end
+
+    it "fails with a missing-row message when actual has fewer rows than expected" do
+      err = capture_failure do
+        expect(simple_wire).to match_flight_structure([
+                                                        { id: 0, class: :model, payload: { "className" => "box" } },
+                                                        { id: 1, class: :import, payload: [] }
+                                                      ])
+      end
+
+      expect(err.message).to include("Expected row 1 (import) was not produced.")
+      expect(err.message).to include("expected: {")
+    end
+
+    it "produces the AC3 verbatim row-indexed diff for a single-field semantic regression" do
+      broken_wire = %(0:["$X","div",null,{"className":"box","children":"hi"}]\n)
+      expected_payload = ["$", "div", nil, { "className" => "box", "children" => "hi" }]
+      got_payload      = ["$X", "div", nil, { "className" => "box", "children" => "hi" }]
+      expected_structure = [{ id: 0, class: :model, payload: expected_payload }]
+
+      # Hash#inspect changed between Ruby 3.3 (`{"a"=>"b"}`) and Ruby 3.4
+      # (`{"a" => "b"}`). The AC3 contract is "values shown via .inspect" —
+      # so we render the expected message with the same .inspect the matcher
+      # uses at runtime, keeping the spec stable across the CI Ruby matrix.
+      expected_message = <<~MSG.strip
+        Expected Flight output to match structure.
+
+        Row 0 (model) differs at .payload[0]:
+          expected: "$"
+          got:      "$X"
+
+        Row 0 (model) full diff:
+          expected: #{expected_payload.inspect}
+          got:      #{got_payload.inspect}
+      MSG
+
+      expect do
+        expect(broken_wire).to match_flight_structure(expected_structure)
+      end.to raise_error(RSpec::Expectations::ExpectationNotMetError, expected_message)
+    end
+
+    it "fails with an unexpected-row message when actual has extra rows" do
+      err = capture_failure do
+        expect(two_row_wire).to match_flight_structure([
+                                                         { id: 1, class: :import,
+                                                           payload: ["/L.jsx", "L", ["/L.jsx"]] }
+                                                       ])
+      end
+
+      expect(err.message).to include("Got unexpected row 1 (model)")
+    end
+
+    it "tolerates cosmetic JSON key reordering in payload hashes (AC4)" do
+      canonical = %(0:{"a":1,"b":2}\n)
+      perturbed = %(0:{"b":2,"a":1}\n)
+      expected_structure = [{ id: 0, class: :model, payload: { "a" => 1, "b" => 2 } }]
+
+      expect(canonical).to match_flight_structure(expected_structure)
+      expect(perturbed).to match_flight_structure(expected_structure)
+    end
+
+    it "passes negation when the structure does not match" do
+      expect(simple_wire).not_to match_flight_structure([
+                                                          { id: 0, class: :model, payload: { "className" => "circle" } }
+                                                        ])
+    end
+
+    # AC1: "multiple I rows are an unordered set". The expected list below
+    # reverses the import order vs the wire — the structural matcher must
+    # still consider this a match because import-row ordering is not
+    # protocol-significant within the import class.
+    it "treats import rows as an unordered set (AC1)" do
+      wire = %(1:I["/A.jsx","A",["/A.jsx"]]\n2:I["/B.jsx","B",["/B.jsx"]]\n0:["$","$L1",null,{}]\n)
+
+      expect(wire).to match_flight_structure([
+                                               { id: 2, class: :import, payload: ["/B.jsx", "B", ["/B.jsx"]] },
+                                               { id: 1, class: :import, payload: ["/A.jsx", "A", ["/A.jsx"]] },
+                                               { id: 0, class: :model, payload: ["$", "$L1", nil, {}] }
+                                             ])
+    end
+
+    # Defends against incomplete expected rows silently passing when actual
+    # payload happens to be nil (e.g. `{ id: 0, class: :model }` without
+    # `:payload` would otherwise satisfy any row whose payload is nil).
+    it "raises ArgumentError when an expected row is missing :payload" do
+      expect do
+        expect(simple_wire).to match_flight_structure([{ id: 0, class: :model }])
+      end.to raise_error(ArgumentError, /missing required keys.*:payload/)
+    end
+
+    it "raises ArgumentError when an expected row is missing :class" do
+      expect do
+        expect(simple_wire).to match_flight_structure([{ id: 0, payload: {} }])
+      end.to raise_error(ArgumentError, /missing required keys.*:class/)
+    end
+
+    # Multi-row failure message: the count, AC3 wording for missing/extra,
+    # plus a "✓" line for every matching row so the reader can confirm
+    # which rows passed (AC3 — "Other rows that match are summarized as
+    # `Row N (<class>): ✓`").
+    it "shows matching-row checkmarks alongside multi-row diffs" do
+      wire = %(1:I["/A.jsx","A",["/A.jsx"]]\n0:["$X","div",null,{}]\n)
+
+      err = capture_failure do
+        expect(wire).to match_flight_structure([
+                                                 { id: 1, class: :import, payload: ["/A.jsx", "A", ["/A.jsx"]] },
+                                                 { id: 0, class: :model, payload: ["$", "div", nil, {}] },
+                                                 { id: 2, class: :model, payload: ["$", "span", nil, {}] }
+                                               ])
+      end
+
+      expect(err.message).to include("Expected Flight output to match structure. 2 rows differ:")
+      expect(err.message).to include("Row 0 (import): ✓")
+      expect(err.message).to include("Row 1 (model) differs at .payload[0]:")
+      expect(err.message).to include("Expected row 2 (model) was not produced.")
+    end
+  end
+
+  describe "include_flight_row" do
+    let(:wire_with_post_id) do
+      %(1:I["/L.jsx","L",["/L.jsx"]]\n0:["$","$L1",null,{"postId":42}]\n)
+    end
+
+    it "matches when at least one row satisfies a hash_including payload predicate" do
+      expect(wire_with_post_id).to include_flight_row(
+        class: :model,
+        payload: include("postId" => 42)
+      )
+    end
+
+    it "fails listing parsed rows when no row matches the predicate" do
+      err = capture_failure do
+        expect(wire_with_post_id).to include_flight_row(
+          class: :model,
+          payload: include("postId" => 999)
+        )
+      end
+
+      expect(err.message).to include("Expected Flight output to include a row matching")
+      expect(err.message).to include("[0] id=1, class=import")
+      expect(err.message).to include("[1] id=0, class=model")
+    end
+
+    it "supports negation with not_to" do
+      expect(wire_with_post_id).not_to include_flight_row(class: :error)
+    end
+
+    it "fails negation when a row matches, naming the offending row index" do
+      expect do
+        expect(wire_with_post_id).not_to include_flight_row(class: :import)
+      end.to raise_error(RSpec::Expectations::ExpectationNotMetError, /but row 0 matched/)
+    end
+
+    it "supports array_including for the payload key" do
+      expect(wire_with_post_id).to include_flight_row(
+        class: :import,
+        payload: include("/L.jsx")
+      )
+    end
+
+    # AC4 fixture-mode failure proof. The structural matcher tolerates the
+    # cosmetic perturbation; the fixture matcher fails *positively* with the
+    # expected-vs-got diff visible — confirming fixture mode is the wire-
+    # format contract guard. This spec verifies the failure message rather
+    # than relying on a `not_to` shortcut (which would prove only that the
+    # matcher returned false, not that the failure is loud and informative).
+    it "demonstrates cosmetic-vs-fixture asymmetry — structure tolerates re-ordering, fixture fails loudly (AC4)" do
+      canonical_wire = %(0:{"debug":true,"count":5,"label":"x"}\n)
+      perturbed_wire = %(0:{"label":"x","count":5,"debug":true}\n)
+      expected_structure = [
+        { id: 0, class: :model, payload: { "debug" => true, "count" => 5, "label" => "x" } }
+      ]
+
+      err = capture_failure do
+        expect(perturbed_wire).to match_flight_fixture("hash")
+      end
+
+      aggregate_failures do
+        # Structural mode: both pass — JSON key reordering is cosmetic.
+        expect(canonical_wire).to match_flight_structure(expected_structure)
+        expect(perturbed_wire).to match_flight_structure(expected_structure)
+
+        # Fixture mode: canonical passes — the fixture file is the canonical
+        # wire bytes.
+        expect(canonical_wire).to match_flight_fixture("hash")
+
+        # Fixture mode against the perturbed wire fails *loudly* with the
+        # bytes-for-bytes diff so a human reviewer can see the cosmetic drift.
+        expect(err).to be_a(RSpec::Expectations::ExpectationNotMetError)
+        expect(err.message).to include("Expected output to match fixture at", "hash.txt", "Expected:", "Got:")
+        expect(err.message).to include(perturbed_wire.inspect)
+      end
+    end
+
+    # Predicate validation: an unknown key (typo) must raise immediately.
+    # Otherwise `row[:payloed]` returns nil and `nil == nil` would silently
+    # match every row, hiding broken specs.
+    it "raises ArgumentError when the predicate has an unknown key" do
+      expect do
+        expect(wire_with_post_id).to include_flight_row(payloed: { "postId" => 42 })
+      end.to raise_error(ArgumentError, /unknown keys.*:payloed/)
+    end
+
+    it "raises ArgumentError when given an empty predicate" do
+      expect do
+        expect(wire_with_post_id).to include_flight_row({})
+      end.to raise_error(ArgumentError, /predicate cannot be empty/)
+    end
+  end
+end

data/spec/support/rails_stub.rb

@@ -1,11 +1,81 @@
 # frozen_string_literal: true
 
-# Minimal Rails stub for specs that need Rails without it being in the bundle.
-# Loaded automatically by spec_helper. Does nothing if Rails is already defined.
-return if defined?(Rails)
+# Spec-only Rails bootstrap for tests that need a `Rails` constant. Two modes:
+#
+# 1. **Augment** (default since Story 7.9): when the `rails` gem is in the
+#    bundle, load its core (`rails.rb` — just `Rails::VERSION`,
+#    `Rails::Railtie`, `ActiveSupport::StringInquirer`, etc., *not*
+#    `action_controller` / `action_view`) and add test-only writers
+#    (`Rails.root=`, `Rails.env=`, `Rails.logger=`) on top. Specs that need
+#    the full Rails request cycle (e.g. controller_request_spec.rb) require
+#    `action_controller/railtie` and `action_view/railtie` themselves — the
+#    rest of the suite never pays that cost.
+#
+# 2. **Full stub** (fallback): when `rails` is not in the bundle (e.g. a
+#    matrix run that pruned it), provide a minimal `Rails` module + a
+#    `Rails::Railtie` class with no-op class methods so `gem/lib/ruact/railtie.rb`
+#    can `class Railtie < Rails::Railtie` without crashing. `$LOADED_FEATURES`
+#    is patched so `require "rails"` inside loaded files no-ops.
+#
+# Loaded automatically by spec_helper.
+#
+# Augmentation is idempotent (each `Rails.define_singleton_method` is guarded
+# by `unless Rails.singleton_class.method_defined?(...)`), so we run through
+# this file every time it loads — even when Rails was already required by
+# another spec file (e.g. controller_request_spec.rb pre-loads
+# `action_controller/railtie`). Skipping with `return if defined?(Rails)`
+# would leave doctor_spec / railtie_spec without the test-only writers when
+# the request spec runs first.
 
-# Prevent `require "rails"` inside loaded files from failing.
-$LOADED_FEATURES << "rails.rb" unless $LOADED_FEATURES.any? { |f| f.end_with?("/rails.rb") }
+unless defined?(Rails)
+  begin
+    # Loads Rails core only — not the request-cycle subsystem. Cheap.
+    require "rails"
+  rescue LoadError
+    # Rails not available; fall through to the full stub below.
+  end
+end
+
+if defined?(Rails) && Rails.respond_to?(:application)
+  # Augment-mode: real Rails is present. Add test-only writers that the
+  # existing suite (doctor_spec, railtie_spec) relies on, without clobbering
+  # real Rails's behaviour outside the test override.
+  unless Rails.singleton_class.method_defined?(:root=)
+    original_root = Rails.method(:root) if Rails.respond_to?(:root)
+
+    Rails.define_singleton_method(:root=) { |v| @_test_root = v }
+    Rails.define_singleton_method(:root) do
+      return @_test_root if defined?(@_test_root) && @_test_root
+
+      original_root&.call
+    end
+  end
+
+  unless Rails.singleton_class.method_defined?(:env=)
+    Rails.define_singleton_method(:env=) { |v| @_test_env = v }
+    original_env = Rails.method(:env) if Rails.respond_to?(:env)
+    Rails.define_singleton_method(:env) do
+      return @_test_env if defined?(@_test_env) && @_test_env
+
+      original_env ? original_env.call : ActiveSupport::StringInquirer.new("test")
+    end
+  end
+
+  unless Rails.singleton_class.method_defined?(:logger=)
+    Rails.define_singleton_method(:logger=) { |v| @_test_logger = v }
+    original_logger = Rails.method(:logger) if Rails.respond_to?(:logger)
+    Rails.define_singleton_method(:logger) do
+      return @_test_logger if defined?(@_test_logger) && @_test_logger
+
+      original_logger&.call
+    end
+  end
+
+  return
+end
+
+# Full-stub fallback: rails gem is not in the bundle.
+$LOADED_FEATURES << "rails.rb"
 
 module Rails
   class Railtie

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

@@ -0,0 +1,173 @@
+// Story 8.1 — TypeScript declarations for the real server-functions runtime.
+// Mirrors the JS exports in `index.js` so the generated module's
+// `import { _makeRef } from "ruact/server-functions-runtime"` resolves under
+// `tsc --noEmit` (AC10's import guarantee).
+//
+// The generated module's per-export signature is
+// `(args?: Record<string, unknown>) => Promise<unknown>` per the 8.0a
+// codegen contract; the runtime accepts a wider `FormData` argument too
+// (Story 8.2 owns the codegen signature widening if it picks the FormData
+// path). Devs writing call sites against the 8.0a-emitted module continue
+// to see the conservative Record<string, unknown> signature; the FormData
+// branch only fires through Story 8.2's `<form action={fn}>` wiring.
+
+/**
+ * Re-run-3 (2026-05-15), refined Re-run-4 (2026-05-15) — local alias
+ * for the FormData INSTANCE type that does NOT require `lib: ["dom"]`
+ * in the consumer's tsconfig.
+ *
+ * Re-run-4 fix: pre-batch this inferred `F = typeof FormData` (the
+ * constructor), so DOM consumers passing `new FormData()` were typed
+ * against the constructor signature and `tsc` would reject the call.
+ * The conditional below now extracts the INSTANCE type from the
+ * constructor (`new (...args) => I`) when DOM lib is loaded, and
+ * falls back to a minimal structural shape in non-DOM targets.
+ */
+type RuactFormData = typeof globalThis extends { FormData: new (...args: never[]) => infer Instance }
+  ? Instance
+  : { append(name: string, value: unknown): void };
+
+/**
+ * Re-run-4 (2026-05-15) — same conditional-typeof pattern for the
+ * fetch `Response` type so the declaration compiles without DOM lib.
+ */
+type RuactResponse = typeof globalThis extends { Response: new (...args: never[]) => infer Instance }
+  ? Instance
+  : unknown;
+
+/**
+ * Returns a callable accessor for a server function registered with the
+ * given Ruby symbol name. The accessor, when invoked, POSTs the args to
+ * `/__ruact/fn/${name}`.
+ *
+ * Story 8.2 (refined 2026-05-17 per review patch R1) — the return type
+ * is an intersection of FOUR call signatures so the same exported
+ * reference is usable from every call site:
+ *
+ *   1. `()` / `(args)` / `(prevState, formData)` — direct callers and
+ *      `useActionState`'s two-arg invocation; returns `Promise<unknown>`.
+ *   2. `(formData: FormData)` — assignable to React 19's `<form action>`
+ *      prop, which is typed as `(formData: FormData) => void | Promise<void>`.
+ *      Promise generics are invariant in TS, so `Promise<unknown>` is
+ *      NOT assignable to `Promise<void>` even via the void-discard rule;
+ *      the intersection lets `<form action={createPost}>` typecheck
+ *      DIRECTLY against the emitted module without a call-site cast.
+ *
+ * Runtime behavior is unchanged — `_makeRef` always resolves with the
+ * JSON-decoded value. The `Promise<void>` overload is a TYPE-ONLY
+ * surface: when React invokes the function from a `<form action>` prop,
+ * the return value is discarded by React anyway.
+ */
+export function _makeRef(
+  name: string,
+): ((
+  arg1?: Record<string, unknown> | RuactFormData,
+  arg2?: RuactFormData | Record<string, unknown>,
+) => Promise<unknown>) &
+  ((formData: RuactFormData) => Promise<void>);
+
+/**
+ * Story 9.3 — the route-driven (v2) accessor. The codegen emits
+ * `_makeServerFunction({ method, path, segments })` for every non-GET routed
+ * action on a `Ruact::Server` controller. The returned callable targets the
+ * REAL Rails route + verb (e.g. `POST /posts`, `PUT /posts/:id`), interpolating
+ * dynamic path segments by name from the single call argument, and follows a
+ * Bucket-2 `{ "$redirect": "<path>" }` response client-side.
+ *
+ * Shares the same intersection call-signature contract as {@link _makeRef} so
+ * `<form action={createPost}>` and `useActionState` keep type-checking.
+ */
+export function _makeServerFunction(descriptor: {
+  method: string;
+  path: string;
+  segments?: string[];
+}): ((
+  arg1?: Record<string, unknown> | RuactFormData,
+  arg2?: RuactFormData | Record<string, unknown>,
+) => Promise<unknown>) &
+  ((formData: RuactFormData) => Promise<void>);
+
+/**
+ * Story 9.5 — the read-side (query) accessor. The codegen emits
+ * `_makeQuery({ path, kind: "query" })` for every method on a mounted
+ * `Ruact::Query` subclass. The returned callable issues a GET to the named
+ * query route (`GET /q/<jsId>`), serializing `params` into the query string
+ * (FR88: string / number / boolean / null only). Reads are CSRF-free: no
+ * body, no `X-CSRF-Token`.
+ *
+ * Usually consumed through {@link useQuery}, but callable directly in
+ * imperative code. The emitted module narrows the param surface per query
+ * (`() => Promise<unknown>` when the Ruby method declares no kwargs;
+ * `(params: Record<string, unknown>) => Promise<unknown>` when it does).
+ */
+export function _makeQuery(descriptor: {
+  path: string;
+  kind?: string;
+}): (params?: Record<string, unknown>) => Promise<unknown>;
+
+/**
+ * Story 9.5 — React hook for reading a server query. Pass a query reference
+ * (the codegen-emitted `_makeQuery` accessor) and optional params; issues
+ * `GET /q/<jsId>` on mount (and whenever the serialized params change) and
+ * returns `{ data, loading, error }`. `loading` is true until the first
+ * resolution; `error` carries the structured {@link RuactActionError} on
+ * failure. A superseded in-flight response is dropped.
+ *
+ * Request de-duplication across components is Story 9.6; this hook fetches
+ * once per mount.
+ */
+export function useQuery<T = unknown>(
+  reference: (params?: Record<string, unknown>) => Promise<unknown>,
+  params?: Record<string, unknown>,
+): { data: T | undefined; loading: boolean; error: unknown };
+
+/**
+ * Story 8.2 — issues a Flight refetch of the supplied path (or the
+ * current URL when omitted) and swaps the React tree in place. Mirrors
+ * Next.js' `revalidatePath` ergonomic: call it after a server action
+ * settles when local React state is not enough to reflect the server
+ * mutation.
+ *
+ * Requires the ruact router to be installed (`setupRouter()` publishes
+ * `globalThis.__ruact_revalidate`). Throws a descriptive error when
+ * called without an installed router so the failure mode is loud rather
+ * than a silent no-op.
+ */
+export function revalidate(path?: string): Promise<void>;
+
+/** Numeric sentinel downstream tooling can read to confirm the real
+ * runtime is in place (the Story 8.0a placeholder exported
+ * `__PLACEHOLDER__: true`; that export is removed in Story 8.1). */
+export const __RUNTIME_VERSION__: number;
+
+/**
+ * Re-run-5 (2026-05-15) — app-wide runtime configuration. Hosts in
+ * API mode (no CSRF meta tag) call this once at boot to register a
+ * default-headers function that supplies the `Authorization: Bearer …`
+ * (or similar) header on every server-function call.
+ *
+ * `defaultHeaders` accepts:
+ *   - a plain object → merged on every call
+ *   - a `() => object` function → called on every call (for tokens
+ *     that may refresh at runtime)
+ *   - `null` → clears any previously-registered default
+ *
+ * The gem's own headers (`Accept`, `Content-Type`, `X-CSRF-Token`)
+ * win over `defaultHeaders` — CSRF cannot be silently overridden.
+ */
+export function configureRuactRuntime(options: {
+  defaultHeaders?: Record<string, string> | (() => Record<string, string>) | null;
+}): void;
+
+/**
+ * Re-run-4 (2026-05-15) — structured error thrown for 4xx/5xx responses.
+ * Callers can branch on `status` and inspect `body` (already
+ * JSON-decoded if the server's Content-Type indicated JSON) instead
+ * of scraping the `message` string.
+ */
+export class RuactActionError extends Error {
+  readonly actionName: string;
+  readonly status: number;
+  readonly body: unknown;
+  readonly response: RuactResponse;
+}