ruact 0.0.2 → 0.0.3

data/spec/ruact/server_functions/route_source_spec.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "active_support/all"
+require "action_dispatch"
+require "ruact/server_functions/route_source"
+
+module Ruact
+  module ServerFunctions
+    # Story 9.3 — route introspection: Rails.application.routes (filtered to
+    # non-GET routes on controllers that include Ruact::Server) → v2 mutation
+    # entries with the derivation table locked in the 2026-06-09 ADR addendum.
+    RSpec.describe RouteSource, :story_9_3 do
+      # Builds an isolated RouteSet so specs never depend on a host app's routes.
+      def route_set(&blk)
+        rs = ActionDispatch::Routing::RouteSet.new
+        rs.draw(&blk)
+        rs
+      end
+
+      # All controllers count as Ruact::Server hosts (isolates the derivation
+      # table from constant-resolution); the filter behaviour is tested
+      # separately below.
+      def collect(routes, overrides: {})
+        described_class.collect(
+          routes,
+          host_predicate: ->(_controller) { true },
+          overrides_for: ->(controller) { overrides.fetch(controller, {}) }
+        )
+      end
+
+      def ids(entries) = entries.map { |e| e["js_identifier"] }
+
+      describe "derivation table (AC3)" do
+        it "names the RESTful collection create as singular verb+resource" do
+          rs = route_set { resources :posts, only: %i[create] }
+          entry = collect(rs).fetch(0)
+          expect(entry["js_identifier"]).to eq("createPost")
+          expect(entry["http_method"]).to eq("POST")
+          expect(entry["path"]).to eq("/posts")
+          expect(entry["segments"]).to eq([])
+          expect(entry["kind"]).to eq("action")
+        end
+
+        it "names update (member) singular and prefers PATCH over the PUT alias" do
+          rs = route_set { resources :posts, only: %i[update] }
+          entries = collect(rs)
+          expect(entries.size).to eq(1) # PATCH + PUT collapse to one entry
+          entry = entries.fetch(0)
+          expect(entry["js_identifier"]).to eq("updatePost")
+          expect(entry["http_method"]).to eq("PATCH")
+          expect(entry["path"]).to eq("/posts/:id")
+          expect(entry["segments"]).to eq(["id"])
+        end
+
+        it "names destroy (member) singular" do
+          rs = route_set { resources :posts, only: %i[destroy] }
+          entry = collect(rs).fetch(0)
+          expect(entry["js_identifier"]).to eq("destroyPost")
+          expect(entry["http_method"]).to eq("DELETE")
+          expect(entry["path"]).to eq("/posts/:id")
+        end
+
+        it "skips the GET RESTful actions (index/show/new/edit)" do
+          rs = route_set { resources :posts }
+          expect(ids(collect(rs))).to match_array(%w[createPost updatePost destroyPost])
+        end
+
+        it "names a custom member route singular (verb-action + singular resource)" do
+          rs = route_set do
+            resources :posts do
+              member { post :publish }
+            end
+          end
+          entry = collect(rs).find { |e| e["js_identifier"] == "publishPost" }
+          expect(entry).not_to be_nil
+          expect(entry["http_method"]).to eq("POST")
+          expect(entry["path"]).to eq("/posts/:id/publish")
+          expect(entry["segments"]).to eq(["id"])
+        end
+
+        it "names a custom collection route plural" do
+          rs = route_set do
+            resources :posts do
+              collection { post :publish_all }
+            end
+          end
+          entry = collect(rs).find { |e| e["js_identifier"] == "publishAllPosts" }
+          expect(entry).not_to be_nil
+          expect(entry["path"]).to eq("/posts/publish_all")
+          expect(entry["segments"]).to eq([])
+        end
+
+        it "names singular-resource create/destroy singular" do
+          rs = route_set { resource :session, only: %i[create destroy] }
+          expect(ids(collect(rs))).to match_array(%w[createSession destroySession])
+        end
+
+        it "prefixes namespaced controllers (verb + Namespace + Resource)" do
+          rs = route_set { namespace(:admin) { resources :posts, only: %i[create update] } }
+          expect(ids(collect(rs))).to match_array(%w[createAdminPost updateAdminPost])
+        end
+
+        it "deep-prefixes multi-level namespaces" do
+          rs = route_set do
+            namespace(:admin) { namespace(:reports) { resources :posts, only: %i[create] } }
+          end
+          expect(ids(collect(rs))).to eq(%w[createAdminReportsPost])
+        end
+
+        it "sorts entries by js_identifier for deterministic output" do
+          rs = route_set { resources :posts }
+          expect(ids(collect(rs))).to eq(%w[createPost destroyPost updatePost])
+        end
+
+        it "classifies a custom-param member route (param: :slug) as member → singular" do
+          rs = route_set do
+            resources :posts, param: :slug do
+              member { post :publish }
+            end
+          end
+          entry = collect(rs).find { |e| e["action"] == "publish" }
+          expect(entry["js_identifier"]).to eq("publishPost")
+          expect(entry["segments"]).to eq(["slug"])
+        end
+
+        it "classifies a nested collection route (only parent :id present) as collection → plural" do
+          rs = route_set do
+            resources :posts, only: [] do
+              resources :comments, only: [] do
+                collection { post :flag_all }
+              end
+            end
+          end
+          entry = collect(rs).find { |e| e["action"] == "flag_all" }
+          expect(entry["js_identifier"]).to eq("flagAllComments")
+        end
+      end
+
+      describe "rename override (AC4 input)" do
+        it "uses the per-controller override identifier when present" do
+          rs = route_set do
+            resources :posts do
+              collection { post :publish_all }
+            end
+          end
+          entries = collect(rs, overrides: { "posts" => { "publish_all" => "publishEverything" } })
+          expect(ids(entries)).to include("publishEverything")
+          expect(ids(entries)).not_to include("publishAllPosts")
+        end
+      end
+
+      describe "collision detection (AC4)" do
+        it "fails loudly naming BOTH origins when two routes map to the same identifier" do
+          rs = route_set do
+            resources :posts, only: %i[create]
+            resources :comments, only: %i[create]
+          end
+          # Force a collision: comments#create is renamed onto posts#create's name.
+          overrides = { "comments" => { "create" => "createPost" } }
+          expect do
+            collect(rs, overrides: overrides)
+          end.to raise_error(Ruact::ConfigurationError, /naming collision/) { |err|
+            expect(err.message).to include("posts#create")
+            expect(err.message).to include("comments#create")
+            expect(err.message).to include("createPost")
+          }
+        end
+
+        it "boot succeeds once the colliding route is renamed to a free identifier (full cycle)" do
+          rs = route_set do
+            resources :posts, only: %i[create]
+            resources :comments, only: %i[create]
+          end
+          overrides = { "comments" => { "create" => "createComment" } }
+          ids_out = ids(collect(rs, overrides: overrides))
+          expect(ids_out).to eq(%w[createComment createPost])
+        end
+      end
+
+      describe "host filter (Ruact::Server only)" do
+        it "skips routes whose controller is not a Ruact::Server host" do
+          rs = route_set do
+            resources :posts, only: %i[create]
+            resources :widgets, only: %i[create]
+          end
+          entries = described_class.collect(
+            rs,
+            host_predicate: ->(controller) { controller == "posts" },
+            overrides_for: ->(_c) { {} }
+          )
+          expect(ids(entries)).to eq(%w[createPost])
+        end
+
+        it "skips GET/HEAD routes even on a host controller" do
+          rs = route_set { get "/posts/search", to: "posts#search" }
+          expect(collect(rs)).to be_empty
+        end
+      end
+    end
+  end
+end

data/spec/ruact/server_functions/snapshot_spec.rb

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "tmpdir"
+
+module Ruact
+  module ServerFunctions
+    RSpec.describe Snapshot, :story_8_0a do
+      let(:posts_controller) { Class.new { def self.name = "PostsController" } }
+      let(:cats_controller)  { Class.new { def self.name = "CategoriesController" } }
+      let(:actions)          { Registry.new }
+      let(:queries)          { Registry.new }
+      let(:frozen_time)      { Time.utc(2026, 5, 13, 12, 34, 56) }
+
+      describe ".dump (Story 8.0a — pure snapshot builder)" do
+        it "returns the empty payload when both registries are empty" do
+          snapshot = described_class.dump(actions, queries, now: frozen_time)
+
+          expect(snapshot).to eq(
+            version: 1,
+            generated_at: "2026-05-13T12:34:56Z",
+            functions: []
+          )
+        end
+
+        it "merges action + query entries into a single functions array" do
+          actions.register(:create_post, kind: :action, controller: posts_controller)
+          queries.register(:categories, kind: :query, controller: cats_controller)
+
+          snapshot = described_class.dump(actions, queries, now: frozen_time)
+
+          expect(snapshot[:functions]).to contain_exactly(
+            { "ruby_symbol" => "create_post", "js_identifier" => "createPost",
+              "kind" => "action", "controller" => "PostsController" },
+            { "ruby_symbol" => "categories", "js_identifier" => "categories",
+              "kind" => "query", "controller" => "CategoriesController" }
+          )
+        end
+
+        it "sorts functions by ruby_symbol for deterministic output (Story 8.0a)" do
+          actions.register(:zeta, kind: :action, controller: posts_controller)
+          actions.register(:alpha, kind: :action, controller: posts_controller)
+          queries.register(:mike, kind: :query, controller: posts_controller)
+
+          symbols = described_class.dump(actions, queries, now: frozen_time)[:functions]
+                                   .map { |fn| fn["ruby_symbol"] }
+          expect(symbols).to eq(%w[alpha mike zeta])
+        end
+
+        it "stringifies controller class names; falls back to nil for nil controllers" do
+          actions.register(:demo_ping, kind: :action, controller: nil)
+          snapshot = described_class.dump(actions, queries, now: frozen_time)
+          expect(snapshot[:functions].first["controller"]).to be_nil
+        end
+      end
+
+      describe ".functions_payload — cross-registry collision (Chunk1 Blocker 2026-05-13)" do
+        it "raises Ruact::ConfigurationError shaped per AC7 when an action and a query " \
+           "share a JS identifier (Re-run patch 2026-05-14 — message prefix aligned with " \
+           "within-registry collision)",
+           :aggregate_failures do
+          actions.register(:foo, kind: :action, controller: posts_controller)
+          queries.register(:foo, kind: :query, controller: cats_controller)
+          expect { described_class.functions_payload(actions, queries) }
+            .to raise_error(Ruact::ConfigurationError) do |error|
+              # AC7 exact shape: rake wraps to "[ruact] error: server-function naming collision: :foo (in PostsController) and :foo (in CategoriesController) both map to JS identifier \"foo\""
+              expect(error.message).to start_with("server-function naming collision:")
+              expect(error.message).to include(":foo (in PostsController)")
+              expect(error.message).to include(":foo (in CategoriesController)")
+              expect(error.message).to include('"foo"')
+              # No "kind:" annotation per Pass-2 patch 2026-05-14
+              expect(error.message).not_to include("kind:")
+            end
+        end
+
+        it "raises when different Ruby symbols cross-collide via the naming bridge" do
+          # `:foo_bar` action + `:foo__bar` query both → "fooBar"
+          actions.register(:foo_bar, kind: :action, controller: posts_controller)
+          queries.register(:foo__bar, kind: :query, controller: cats_controller)
+          expect { described_class.functions_payload(actions, queries) }
+            .to raise_error(Ruact::ConfigurationError, /server-function naming collision.*"fooBar"/m)
+        end
+
+        it "raises when both registries contain the same Ruby symbol with matching " \
+           "js_identifier (one js_identifier per emitted export is the design intent)" do
+          actions.register(:categories, kind: :action, controller: posts_controller)
+          queries.register(:categories, kind: :query, controller: cats_controller)
+          expect { described_class.functions_payload(actions, queries) }
+            .to raise_error(Ruact::ConfigurationError, /server-function naming collision/)
+        end
+      end
+
+      describe ".functions_payload (Story 8.0a — fingerprint surface)" do
+        it "excludes the generated_at timestamp so registry-equivalent calls match" do
+          actions.register(:create_post, kind: :action, controller: posts_controller)
+
+          first = described_class.functions_payload(actions, queries)
+          sleep 0.01
+          second = described_class.functions_payload(actions, queries)
+
+          expect(first).to eq(second)
+        end
+      end
+
+      describe ".generate! (Story 8.0a — write-if-changed orchestration)" do
+        around do |example|
+          Dir.mktmpdir do |dir|
+            @tmpdir = dir
+            example.run
+          end
+        end
+
+        let(:path) { File.join(@tmpdir, "server-functions.json") }
+
+        it "writes the file on first call and returns true" do
+          result = described_class.generate!(
+            action_registry: actions, query_registry: queries, path: path, now: frozen_time
+          )
+
+          expect(result).to be(true)
+          expect(File).to exist(path)
+          parsed = JSON.parse(File.read(path))
+          expect(parsed.fetch("version")).to eq(1)
+          expect(parsed.fetch("functions")).to eq([])
+        end
+
+        it "does NOT rewrite the file when the registry is unchanged " \
+           "(Story 8.0a — pitfall #1 mitigation)", :aggregate_failures do
+          actions.register(:create_post, kind: :action, controller: posts_controller)
+          described_class.generate!(action_registry: actions, query_registry: queries,
+                                    path: path, now: frozen_time)
+
+          original_mtime  = File.mtime(path)
+          original_bytes  = File.read(path)
+          original_time   = JSON.parse(original_bytes)["generated_at"]
+          sleep 1.05 # ensure mtime resolution is exceeded if we DID rewrite
+
+          result = described_class.generate!(
+            action_registry: actions, query_registry: queries,
+            path: path, now: Time.now.utc # different now
+          )
+
+          expect(result).to be(false)
+          expect(File.mtime(path)).to eq(original_mtime)
+          expect(JSON.parse(File.read(path))["generated_at"]).to eq(original_time)
+        end
+
+        it "rewrites the file when a function is added" do
+          described_class.generate!(action_registry: actions, query_registry: queries,
+                                    path: path, now: frozen_time)
+          actions.register(:create_post, kind: :action, controller: posts_controller)
+
+          result = described_class.generate!(
+            action_registry: actions, query_registry: queries, path: path, now: frozen_time
+          )
+
+          expect(result).to be(true)
+          expect(JSON.parse(File.read(path))["functions"].size).to eq(1)
+        end
+
+        it "creates the parent directory if missing" do
+          nested = File.join(@tmpdir, "deep", "nest", "server-functions.json")
+          expect do
+            described_class.generate!(action_registry: actions, query_registry: queries,
+                                      path: nested, now: frozen_time)
+          end
+            .to change { File.exist?(nested) }.from(false).to(true)
+        end
+
+        it "recovers from a corrupted existing file by overwriting it" do
+          File.write(path, "not json")
+          result = described_class.generate!(
+            action_registry: actions, query_registry: queries, path: path, now: frozen_time
+          )
+          expect(result).to be(true)
+          expect { JSON.parse(File.read(path)) }.not_to raise_error
+        end
+
+        it "rewrites the file when the on-disk snapshot has a different version " \
+           "(Chunk1 Major 2026-05-13 — version mismatch must not be treated as unchanged)" do
+          File.write(path, JSON.pretty_generate(version: 99, generated_at: "2020-01-01T00:00:00Z", functions: []))
+          result = described_class.generate!(
+            action_registry: actions, query_registry: queries, path: path, now: frozen_time
+          )
+          expect(result).to be(true)
+          expect(JSON.parse(File.read(path))["version"]).to eq(1)
+        end
+      end
+
+      describe "route-driven (v2) snapshot (Story 9.3)", :story_9_3 do
+        let(:entries) do
+          [
+            { "js_identifier" => "createPost", "kind" => "action", "http_method" => "POST",
+              "path" => "/posts", "segments" => [], "controller" => "posts", "action" => "create" }
+          ]
+        end
+
+        describe ".dump_v2" do
+          it "wraps entries in a version-2 snapshot Hash" do
+            snap = described_class.dump_v2(entries, now: frozen_time)
+            expect(snap[:version]).to eq(2)
+            expect(snap[:generated_at]).to eq(frozen_time.iso8601)
+            expect(snap[:functions]).to eq(entries)
+          end
+        end
+
+        describe ".generate_v2! (write-if-changed)" do
+          around do |example|
+            Dir.mktmpdir do |dir|
+              @tmpdir = dir
+              example.run
+            end
+          end
+
+          let(:path) { File.join(@tmpdir, "server-functions.next.json") }
+
+          it "writes a version-2 bridge on first call" do
+            expect(described_class.generate_v2!(entries: entries, path: path, now: frozen_time)).to be(true)
+            parsed = JSON.parse(File.read(path))
+            expect(parsed.fetch("version")).to eq(2)
+            expect(parsed.fetch("functions").first.fetch("js_identifier")).to eq("createPost")
+          end
+
+          it "short-circuits when entries are unchanged (no timestamp churn)" do
+            described_class.generate_v2!(entries: entries, path: path, now: frozen_time)
+            expect(described_class.generate_v2!(entries: entries, path: path, now: Time.now.utc)).to be(false)
+          end
+
+          it "rewrites when entries change" do
+            described_class.generate_v2!(entries: entries, path: path, now: frozen_time)
+            more = entries + [{ "js_identifier" => "destroyPost", "kind" => "action",
+                                "http_method" => "DELETE", "path" => "/posts/:id",
+                                "segments" => ["id"], "controller" => "posts", "action" => "destroy" }]
+            expect(described_class.generate_v2!(entries: more, path: path, now: frozen_time)).to be(true)
+          end
+        end
+
+        describe ".v1_declarations? (Decision-#6 ownership primitive)" do
+          it "is false when both registries are empty" do
+            expect(described_class.v1_declarations?(Registry.new, Registry.new)).to be(false)
+          end
+
+          it "is true when the action registry has any entry" do
+            actions.register(:create_post, kind: :action, controller: posts_controller)
+            expect(described_class.v1_declarations?(actions, Registry.new)).to be(true)
+          end
+
+          it "is true when the query registry has any entry" do
+            queries.register(:categories, kind: :query, controller: cats_controller)
+            expect(described_class.v1_declarations?(Registry.new, queries)).to be(true)
+          end
+        end
+      end
+    end
+  end
+end

data/spec/ruact/server_functions/snapshot_writer_spec.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "tmpdir"
+
+module Ruact
+  module ServerFunctions
+    RSpec.describe SnapshotWriter, :story_8_0a do
+      around do |example|
+        Dir.mktmpdir do |dir|
+          @tmpdir = dir
+          example.run
+        end
+      end
+
+      let(:path) { File.join(@tmpdir, "out.txt") }
+
+      describe ".write_if_changed! (Story 8.0a — atomic, byte-aware writer)" do
+        it "writes the file when it does not yet exist and returns true" do
+          expect(described_class.write_if_changed!(path: path, content: "hello\n"))
+            .to be(true)
+          expect(File.read(path)).to eq("hello\n")
+        end
+
+        it "skips writing when the existing content matches byte-for-byte" do
+          File.write(path, "hello\n")
+          original_mtime = File.mtime(path)
+          sleep 1.05
+
+          expect(described_class.write_if_changed!(path: path, content: "hello\n"))
+            .to be(false)
+          expect(File.mtime(path)).to eq(original_mtime)
+        end
+
+        it "writes when the existing content differs by even a single byte" do
+          File.write(path, "hello\n")
+          expect(described_class.write_if_changed!(path: path, content: "hello!\n"))
+            .to be(true)
+          expect(File.read(path)).to eq("hello!\n")
+        end
+
+        it "creates missing parent directories" do
+          nested = File.join(@tmpdir, "a", "b", "c", "out.txt")
+          described_class.write_if_changed!(path: nested, content: "x")
+          expect(File.read(nested)).to eq("x")
+        end
+
+        it "writes via a same-directory tmpfile so partial reads never see " \
+           "a torn file (Story 8.0a)" do
+          described_class.write_if_changed!(path: path, content: "atomic\n")
+          # After the write the temp sibling must not linger.
+          siblings = Dir.children(@tmpdir)
+          expect(siblings).to eq(["out.txt"])
+        end
+
+        it "raises Ruact::ConfigurationError when the parent directory is unwritable " \
+           "(Story 8.0a)" do
+          read_only = File.join(@tmpdir, "ro")
+          FileUtils.mkdir_p(read_only)
+          FileUtils.chmod(0o500, read_only)
+          target = File.join(read_only, "nested", "out.txt")
+
+          expect { described_class.write_if_changed!(path: target, content: "x") }
+            .to raise_error(Ruact::ConfigurationError, /cannot create/)
+        ensure
+          FileUtils.chmod(0o700, read_only) if read_only && File.exist?(read_only)
+        end
+      end
+    end
+  end
+end