ruact 0.0.1 → 0.0.3

data/spec/ruact/server_functions/error_payload_spec.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "ruact/server_functions/error_payload"
+
+module Ruact
+  module ServerFunctions
+    RSpec.describe ErrorPayload, :story_8_4 do
+      let(:gem_root) { "/tmp/ruact-test-gem" }
+
+      before { allow(Ruact).to receive(:gem_path).and_return(gem_root) }
+
+      # Build an exception whose `.class.name` is spoofed so the spec can
+      # exercise the RecordInvalid path without requiring ActiveRecord.
+      def build_record_invalid(full_messages: ["Title can't be blank"])
+        record = Object.new
+        errors = Object.new
+        record.define_singleton_method(:errors) { errors }
+        errors.define_singleton_method(:full_messages) { full_messages }
+
+        klass = Class.new(StandardError) do
+          attr_reader :record
+          define_singleton_method(:name) { "ActiveRecord::RecordInvalid" }
+          def initialize(record, message)
+            super(message)
+            @record = record
+          end
+        end
+        err = klass.new(record, "Validation failed: Title can't be blank")
+        err.set_backtrace([
+                            "/Users/dev/host/app/controllers/posts_controller.rb:12:in `create'",
+                            "#{gem_root}/lib/ruact/server_functions/endpoint_controller.rb:111:in `dispatch'"
+                          ])
+        err
+      end
+
+      describe ".build in :development mode" do
+        let(:error) { build_record_invalid }
+
+        subject(:payload) do
+          described_class.build(action_name: :create_post, error: error, mode: :development)
+        end
+
+        it "carries the discriminator" do
+          expect(payload["_ruact_server_action_error"]).to be(true)
+        end
+
+        it "exposes the action name as a string (symbol input is coerced)" do
+          expect(payload["action_name"]).to eq("create_post")
+        end
+
+        it "exposes the error class as a string" do
+          expect(payload["error_class"]).to eq("ActiveRecord::RecordInvalid")
+        end
+
+        it "exposes the error message" do
+          expect(payload["message"]).to eq("Validation failed: Title can't be blank")
+        end
+
+        it "splits the backtrace into app_frames and gem_frames" do
+          expect(payload["app_frames"]).to contain_exactly(
+            a_string_including("posts_controller.rb:12")
+          )
+          expect(payload["gem_frames"]).to contain_exactly(
+            a_string_including("endpoint_controller.rb:111")
+          )
+        end
+
+        it "extracts validation_errors from the record" do
+          expect(payload["validation_errors"]).to eq(["Title can't be blank"])
+        end
+
+        it "extracts the contextual suggestion" do
+          expect(payload["suggestion"]).to eq("Validation failed — check the model's `validates` rules")
+        end
+      end
+
+      describe ".build in :production mode" do
+        let(:error) { build_record_invalid }
+
+        subject(:payload) do
+          described_class.build(action_name: :create_post, error: error, mode: :production)
+        end
+
+        it "carries the four baseline keys" do
+          expect(payload.keys).to contain_exactly(
+            "_ruact_server_action_error",
+            "action_name",
+            "error_class",
+            "message"
+          )
+        end
+
+        it "shares the four baseline values with the dev-mode payload" do
+          dev = described_class.build(action_name: :create_post, error: error, mode: :development)
+          payload.each_key do |key|
+            expect(payload[key]).to eq(dev[key])
+          end
+        end
+
+        it "ABSENT (not null): app_frames, gem_frames, suggestion, validation_errors" do
+          expect(payload).not_to have_key("app_frames")
+          expect(payload).not_to have_key("gem_frames")
+          expect(payload).not_to have_key("suggestion")
+          expect(payload).not_to have_key("validation_errors")
+        end
+      end
+
+      describe "validation_errors edge cases (dev mode)" do
+        it "is [] when RecordInvalid was constructed without a record" do
+          klass = Class.new(StandardError) do
+            attr_reader :record
+            define_singleton_method(:name) { "ActiveRecord::RecordInvalid" }
+            def initialize
+              super("boom")
+              @record = nil
+            end
+          end
+          payload = described_class.build(action_name: :x, error: klass.new, mode: :development)
+          expect(payload["validation_errors"]).to eq([])
+        end
+
+        it "is ABSENT (no key) when the error class is not RecordInvalid" do
+          payload = described_class.build(
+            action_name: :x,
+            error: RuntimeError.new("boom"),
+            mode: :development
+          )
+          expect(payload).not_to have_key("validation_errors")
+        end
+      end
+
+      describe "suggestion is null for unknown error classes (dev mode)" do
+        it "produces suggestion: nil for RuntimeError" do
+          payload = described_class.build(
+            action_name: :x,
+            error: RuntimeError.new("boom"),
+            mode: :development
+          )
+          expect(payload["suggestion"]).to be_nil
+        end
+      end
+
+      describe "Pitfall #5 — frozen-string error message safety" do
+        it "does not raise FrozenError when the error message is frozen" do
+          err = StandardError.new("frozen msg".freeze)
+          expect do
+            described_class.build(action_name: :x, error: err, mode: :development)
+          end.not_to raise_error
+        end
+
+        it "stores a mutable dup of the message in the payload" do
+          err = StandardError.new("frozen msg".freeze)
+          payload = described_class.build(action_name: :x, error: err, mode: :development)
+          expect(payload["message"]).to eq("frozen msg")
+          expect(payload["message"]).not_to be_frozen
+        end
+      end
+
+      describe "Story 8.5 — UploadTooLargeError gets a dev-only upload_limit block", :story_8_5 do
+        let(:error) { Ruact::UploadTooLargeError.new(received_bytes: 11_534_336, limit_bytes: 10_485_760) }
+
+        it "exposes received_bytes and limit_bytes under upload_limit (dev mode)" do
+          payload = described_class.build(action_name: :upload_post, error: error, mode: :development)
+          expect(payload["upload_limit"]).to eq(
+            "received_bytes" => 11_534_336,
+            "limit_bytes" => 10_485_760
+          )
+        end
+
+        it "carries error_class as Ruact::UploadTooLargeError" do
+          payload = described_class.build(action_name: :upload_post, error: error, mode: :development)
+          expect(payload["error_class"]).to eq("Ruact::UploadTooLargeError")
+        end
+
+        it "extracts the upload-too-large suggestion from ErrorSuggestion" do
+          payload = described_class.build(action_name: :upload_post, error: error, mode: :development)
+          expect(payload["suggestion"]).to include("Increase Ruact.config.max_upload_bytes")
+        end
+
+        it "does NOT include upload_limit in :production mode (four baseline keys only)" do
+          payload = described_class.build(action_name: :upload_post, error: error, mode: :production)
+          expect(payload).not_to have_key("upload_limit")
+          expect(payload.keys).to contain_exactly(
+            "_ruact_server_action_error",
+            "action_name",
+            "error_class",
+            "message"
+          )
+        end
+
+        it "is ABSENT (no key) when the error class is not UploadTooLargeError" do
+          payload = described_class.build(
+            action_name: :x,
+            error: RuntimeError.new("boom"),
+            mode: :development
+          )
+          expect(payload).not_to have_key("upload_limit")
+        end
+      end
+
+      describe "backtrace edge cases (dev mode)" do
+        it "is { app_frames: [], gem_frames: [] } when backtrace is nil" do
+          err = StandardError.new("boom") # never raised => backtrace is nil
+          payload = described_class.build(action_name: :x, error: err, mode: :development)
+          expect(payload["app_frames"]).to eq([])
+          expect(payload["gem_frames"]).to eq([])
+        end
+
+        it "caps each bucket at MAX_FRAMES_PER_BUCKET frames" do
+          app_frames = Array.new(40) { |i| "/Users/dev/host/app/file_#{i}.rb:#{i}" }
+          gem_frames = Array.new(40) { |i| "#{gem_root}/lib/ruact/file_#{i}.rb:#{i}" }
+          err = StandardError.new("boom")
+          err.set_backtrace(app_frames + gem_frames)
+          payload = described_class.build(action_name: :x, error: err, mode: :development)
+          expect(payload["app_frames"].size).to eq(ErrorPayload::MAX_FRAMES_PER_BUCKET)
+          expect(payload["gem_frames"].size).to eq(ErrorPayload::MAX_FRAMES_PER_BUCKET)
+        end
+      end
+    end
+  end
+end

data/spec/ruact/server_functions/error_suggestion_spec.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "ruact/server_functions/error_suggestion"
+
+module Ruact
+  module ServerFunctions
+    RSpec.describe ErrorSuggestion, :story_8_4 do
+      # Test fixtures using class-name spoofing so the module can be exercised
+      # without requiring ActiveRecord or ActionController to be loaded
+      # (Pitfall #4).
+      def error_with_class_name(name)
+        klass = Class.new(StandardError) do
+          define_singleton_method(:name) { name }
+        end
+        klass.new("fixture")
+      end
+
+      describe "Story 8.4 — .for returns the NFR30-mandated suggestion" do
+        it "returns the RecordInvalid suggestion for ActiveRecord::RecordInvalid" do
+          err = error_with_class_name("ActiveRecord::RecordInvalid")
+          expect(described_class.for(err))
+            .to eq("Validation failed — check the model's `validates` rules")
+        end
+
+        it "returns the CSRF suggestion for ActionController::InvalidAuthenticityToken" do
+          err = error_with_class_name("ActionController::InvalidAuthenticityToken")
+          expect(described_class.for(err))
+            .to eq(
+              "CSRF token mismatch — ensure the page was rendered after the most recent server restart and the session cookie is intact"
+            )
+        end
+
+        it "returns nil for StandardError" do
+          expect(described_class.for(StandardError.new("boom"))).to be_nil
+        end
+
+        it "returns nil for RuntimeError" do
+          expect(described_class.for(RuntimeError.new("boom"))).to be_nil
+        end
+
+        it "returns nil for ArgumentError" do
+          expect(described_class.for(ArgumentError.new("boom"))).to be_nil
+        end
+
+        it "returns nil for a custom user exception class" do
+          custom_class = Class.new(StandardError) { define_singleton_method(:name) { "MyApp::PaymentDeclined" } }
+          expect(described_class.for(custom_class.new("declined"))).to be_nil
+        end
+      end
+
+      describe "Story 8.5 — UploadTooLargeError suggestion", :story_8_5 do
+        it "returns the upload-too-large suggestion for Ruact::UploadTooLargeError" do
+          err = Ruact::UploadTooLargeError.new(received_bytes: 11_000_000, limit_bytes: 10_485_760)
+          expect(described_class.for(err))
+            .to eq(
+              "Upload exceeded the configured size limit. " \
+              "Increase Ruact.config.max_upload_bytes or use Active Storage Direct Upload / " \
+              "a presigned S3 URL for large files."
+            )
+        end
+
+        it "has a SUGGESTIONS entry keyed by the exception class name" do
+          expect(described_class::SUGGESTIONS).to have_key("Ruact::UploadTooLargeError")
+        end
+      end
+
+      describe "Story 8.4 — SUGGESTIONS constant" do
+        it "is frozen so runtime mutation cannot extend the table" do
+          expect(described_class::SUGGESTIONS).to be_frozen
+        end
+
+        it "uses class-name strings as keys (not constants)" do
+          expect(described_class::SUGGESTIONS.keys).to all(be_a(String))
+        end
+      end
+    end
+  end
+end

data/spec/ruact/server_functions/name_bridge_spec.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+module Ruact
+  module ServerFunctions
+    RSpec.describe NameBridge, :story_8_0a do
+      describe ".to_js_identifier (Story 8.0a — Ruby symbol → JS identifier)" do
+        # Six canonical edge cases locked by the Story 8.0 ADR.
+
+        it "translates standard snake_case to camelCase" do
+          expect(described_class.to_js_identifier(:create_post)).to eq("createPost")
+        end
+
+        it "passes a single word through unchanged" do
+          expect(described_class.to_js_identifier(:categories)).to eq("categories")
+        end
+
+        it "preserves a single leading underscore" do
+          expect(described_class.to_js_identifier(:_internal_dump)).to eq("_internalDump")
+        end
+
+        it "collapses consecutive underscores" do
+          expect(described_class.to_js_identifier(:foo__bar)).to eq("fooBar")
+        end
+
+        it "raises ConfigurationError for SCREAMING_SNAKE" do
+          expect { described_class.to_js_identifier(:RECALCULATE) }
+            .to raise_error(Ruact::ConfigurationError) do |error|
+              expect(error.message).to include(":RECALCULATE")
+              expect(error.message).to include("/^[a-z_][a-z0-9_]*$/")
+            end
+        end
+
+        it "raises ConfigurationError for PascalCase" do
+          expect { described_class.to_js_identifier(:CreatePost) }
+            .to raise_error(Ruact::ConfigurationError) do |error|
+              expect(error.message).to include(":CreatePost")
+              expect(error.message).to include("ruact_action / ruact_query")
+            end
+        end
+
+        describe "additional shape guards" do
+          it "rejects symbols starting with a digit" do
+            expect { described_class.to_js_identifier(:"1foo") }
+              .to raise_error(Ruact::ConfigurationError, /must match/)
+          end
+
+          it "rejects symbols containing a dash" do
+            expect { described_class.to_js_identifier(:"foo-bar") }
+              .to raise_error(Ruact::ConfigurationError, /must match/)
+          end
+
+          it "rejects empty string" do
+            expect { described_class.to_js_identifier(:"") }
+              .to raise_error(Ruact::ConfigurationError, /must match/)
+          end
+
+          it "accepts a string argument identical to its symbol form" do
+            expect(described_class.to_js_identifier("create_post")).to eq("createPost")
+          end
+
+          it "preserves a leading underscore followed by digits" do
+            expect(described_class.to_js_identifier(:_2fa_check)).to eq("_2faCheck")
+          end
+        end
+
+        describe "underscore-only symbols (Story 8.0 review patch 2026-05-13)" do
+          it "rejects a single underscore" do
+            expect { described_class.to_js_identifier(:_) }
+              .to raise_error(Ruact::ConfigurationError) do |error|
+                expect(error.message).to include(":_")
+                expect(error.message).to include("entirely of underscores")
+              end
+          end
+
+          it "rejects a run of underscores" do
+            expect { described_class.to_js_identifier(:____) }
+              .to raise_error(Ruact::ConfigurationError, /entirely of underscores/)
+          end
+
+          it "still accepts a leading underscore followed by alphanumeric" do
+            expect(described_class.to_js_identifier(:_x)).to eq("_x")
+          end
+        end
+
+        describe "JS reserved words (Story 8.0 review patch 2026-05-13)" do
+          # Spot-check a handful of representative classes: keyword (`class`),
+          # module-level reserved (`export`), strict-mode reserved (`let`),
+          # contextually-reserved (`await`, `async`), literal (`true`).
+          it "rejects :class" do
+            expect { described_class.to_js_identifier(:class) }
+              .to raise_error(Ruact::ConfigurationError) do |error|
+                expect(error.message).to include(":class")
+                expect(error.message).to include("JS reserved word")
+                expect(error.message).to include('"class"')
+              end
+          end
+
+          it "rejects :export" do
+            expect { described_class.to_js_identifier(:export) }
+              .to raise_error(Ruact::ConfigurationError, /JS reserved word.*"export"/)
+          end
+
+          it "rejects :let, :await, :async, :true (representative coverage)" do
+            %i[let await async true].each do |sym|
+              expect { described_class.to_js_identifier(sym) }
+                .to raise_error(Ruact::ConfigurationError, /JS reserved word/),
+                    "expected :#{sym} to raise as a reserved word"
+            end
+          end
+
+          it "rejects :eval and :arguments (strict-mode invalid binding names — " \
+             "Story 8.0 Re-run patch 2026-05-13)" do
+            # ES module code runs in strict mode, where `eval` and `arguments`
+            # cannot be used as identifier names. The 8.0a codegen emits a
+            # `"type": "module"` file, so these guards apply unconditionally.
+            %i[eval arguments].each do |sym|
+              expect { described_class.to_js_identifier(sym) }
+                .to raise_error(Ruact::ConfigurationError, /JS reserved word/),
+                    "expected :#{sym} to raise as strict-mode invalid binding name"
+            end
+          end
+
+          it "accepts multi-word symbols whose camelCased output is not reserved" do
+            # No real Ruby snake_case maps to a single reserved word post-
+            # camelCasing (reserved words are themselves single-word), but the
+            # check happens AFTER camelCasing so a hypothetical degenerate
+            # input is still caught.
+            expect { described_class.to_js_identifier(:cl_ass) }
+              .not_to raise_error # "clAss" is not reserved — sanity guard
+            expect(described_class.to_js_identifier(:cl_ass)).to eq("clAss")
+          end
+
+          it "ACCEPTS reserved words that survive only with the leading-underscore prefix" do
+            # `:_class` → "_class" — not reserved (the underscore is a literal
+            # character); intentional escape hatch for devs whose domain
+            # vocabulary collides with JS keywords.
+            expect(described_class.to_js_identifier(:_class)).to eq("_class")
+            expect(described_class.to_js_identifier(:_export)).to eq("_export")
+          end
+
+          it "ACCEPTS the suffix-shaped escape hint from the error message" do
+            # The error message suggests `:class_action`; assert that hint
+            # produces a valid identifier — guards against a regression where
+            # the suggested fix would also fail validation.
+            expect(described_class.to_js_identifier(:class_action)).to eq("classAction")
+          end
+        end
+
+        describe "Ruact-reserved names (Story 8.2 review patch R2 — 2026-05-17)", :story_8_2 do
+          # The codegen unconditionally re-exports certain runtime helpers
+          # from `@/.ruact/server-functions` (e.g. `revalidate`). A
+          # `ruact_action :revalidate` would emit `export const revalidate`
+          # next to the helper re-export and crash at module load with a
+          # duplicate-export error. Reject at controller load instead.
+          it "rejects :revalidate because it collides with the unconditional helper re-export" do
+            expect { described_class.to_js_identifier(:revalidate) }
+              .to raise_error(Ruact::ConfigurationError) do |error|
+                expect(error.message).to include(":revalidate")
+                expect(error.message).to include("duplicate export")
+              end
+          end
+
+          it "accepts :revalidate_post (suffix escape hatch — same convention as JS reserved-word path)" do
+            expect(described_class.to_js_identifier(:revalidate_post)).to eq("revalidatePost")
+          end
+
+          it "accepts :_revalidate (leading-underscore escape hatch)" do
+            expect(described_class.to_js_identifier(:_revalidate)).to eq("_revalidate")
+          end
+
+          it "R12 — rejects :_make_ref because it collides with the codegen's runtime import" do
+            expect { described_class.to_js_identifier(:_make_ref) }
+              .to raise_error(Ruact::ConfigurationError) do |error|
+                expect(error.message).to include(":_make_ref")
+                expect(error.message).to include("duplicate export")
+              end
+          end
+
+          it "R12 — accepts :_make_ref_action (suffix escape hatch keeps working)" do
+            expect(described_class.to_js_identifier(:_make_ref_action)).to eq("_makeRefAction")
+          end
+        end
+      end
+    end
+  end
+end

data/spec/ruact/server_functions/query_context_spec.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+# Story 9.4 — unit spec for the per-request query context (D3). The context
+# wraps the DISPATCHING controller instance and delegates to it: because the
+# internal dispatch controller inherits `Ruact.config.query_parent_controller`,
+# `controller.current_user` IS the host's own method (Devise / Pundit /
+# hand-rolled). No Rails boot needed here — a plain stub controller suffices.
+require "spec_helper"
+
+module Ruact
+  module ServerFunctions
+    RSpec.describe QueryContext, :story_9_4 do
+      describe "Story 9.4 — delegation to the dispatching controller (AC3 / D3)" do
+        let(:controller_class) do
+          Class.new do
+            def params  = { "q" => "x" }
+            def request = :the_request
+            def session = { "sid" => 1 }
+
+            def current_user
+              { "id" => 7 }
+            end
+          end
+        end
+
+        subject(:context) { described_class.new(controller: controller_class.new) }
+
+        it "delegates params" do
+          expect(context.params).to eq("q" => "x")
+        end
+
+        it "delegates request" do
+          expect(context.request).to eq(:the_request)
+        end
+
+        it "delegates session" do
+          expect(context.session).to eq("sid" => 1)
+        end
+
+        it "delegates current_user to the host's own method" do
+          expect(context.current_user).to eq("id" => 7)
+        end
+      end
+
+      describe "Story 9.4 — current_user reaches a PRIVATE host helper too" do
+        let(:controller_class) do
+          Class.new do
+            private
+
+            def current_user
+              :private_user
+            end
+          end
+        end
+
+        it "resolves it (hand-rolled apps commonly define current_user private)" do
+          context = described_class.new(controller: controller_class.new)
+          expect(context.current_user).to eq(:private_user)
+        end
+      end
+
+      describe "Story 9.4 — clear error when the host defines no current_user (D3)" do
+        it "raises NoMethodError naming the parent controller and the fix" do
+          context = described_class.new(controller: Class.new.new)
+          expect { context.current_user }.to raise_error(NoMethodError, /current_user/) do |error|
+            expect(error.message).to include("query_parent_controller")
+          end
+        end
+      end
+    end
+  end
+end