ruact 0.0.2 → 0.0.4

data/spec/ruact/server_functions/codegen_spec.rb

@@ -0,0 +1,508 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "tmpdir"
+
+module Ruact
+  module ServerFunctions
+    RSpec.describe Codegen, :story_8_0a do
+      let(:base_snapshot) do
+        {
+          version: 1,
+          generated_at: "2026-05-13T12:34:56Z",
+          functions: []
+        }
+      end
+
+      describe ".render — empty registry (Story 8.0a AC4)" do
+        it "emits a valid module with import line and the empty-registry comment" do
+          # Story 8.2 — the empty-registry branch also emits the
+          # `export { revalidate } from "..."` re-export so
+          # `import { revalidate } from "@/.ruact/server-functions"` works in
+          # projects that have not yet declared any server actions.
+          result = described_class.render(base_snapshot)
+
+          expect(result).to eq(<<~TS)
+            // AUTO-GENERATED by vite-plugin-ruact (Story 8.0a). DO NOT EDIT.
+            // Source: tmp/cache/ruact/server-functions.json (version 1)
+            // Generated at: 2026-05-13T12:34:56Z
+            import { _makeRef } from "ruact/server-functions-runtime";
+
+            // (no server functions registered yet — Stories 8.1 / 9.1 populate)
+            void _makeRef;
+
+            export { revalidate } from "ruact/server-functions-runtime";
+          TS
+        end
+
+        it "ends with exactly one trailing newline" do
+          result = described_class.render(base_snapshot)
+          expect(result).to end_with("\n")
+          expect(result).not_to end_with("\n\n")
+        end
+
+        it "references _makeRef even when empty so noUnusedLocals stays green " \
+           "(Re-run patch 2026-05-13)" do
+          # Strictly checks that the import is "touched" — the canonical
+          # `void _makeRef;` is the lightweight discard pattern.
+          expect(described_class.render(base_snapshot)).to include("void _makeRef;")
+        end
+      end
+
+      describe ".render — single action (Story 8.0a AC4 + Story 8.2 intersection)" do
+        it "emits an action export typed as a TS intersection of direct-call + <form action> shapes" do
+          # Story 8.2 (refined 2026-05-17 per review patch R1) — the
+          # intersection makes `<form action={createPost}>` typecheck
+          # directly against React 19's
+          # `(formData: FormData) => void | Promise<void>` while preserving
+          # `Promise<unknown>` for direct callers. See the 2026-05-17 entry
+          # in `gem/docs/internal/decisions/server-functions-api.md`.
+          snapshot = base_snapshot.merge(functions: [
+                                           {
+                                             "ruby_symbol" => "create_post",
+                                             "js_identifier" => "createPost",
+                                             "kind" => "action",
+                                             "controller" => "PostsController"
+                                           }
+                                         ])
+
+          expect(described_class.render(snapshot)).to eq(<<~TS)
+            // AUTO-GENERATED by vite-plugin-ruact (Story 8.0a). DO NOT EDIT.
+            // Source: tmp/cache/ruact/server-functions.json (version 1)
+            // Generated at: 2026-05-13T12:34:56Z
+            import { _makeRef } from "ruact/server-functions-runtime";
+
+            export const createPost: ((args?: FormData | Record<string, unknown>) => Promise<unknown>) & ((formData: FormData) => Promise<void>) =
+              _makeRef("create_post");
+
+            export { revalidate } from "ruact/server-functions-runtime";
+          TS
+        end
+
+        it "Story 8.2 — query signatures do NOT widen (regression guard)" do
+          snapshot = base_snapshot.merge(functions: [
+                                           {
+                                             "ruby_symbol" => "categories",
+                                             "js_identifier" => "categories",
+                                             "kind" => "query",
+                                             "controller" => "CategoriesController"
+                                           }
+                                         ])
+
+          out = described_class.render(snapshot)
+          # Action-style FormData widening must not bleed into the query export
+          expect(out).not_to match(/export const categories:[^=]*FormData/)
+          expect(out).to include("export const categories: () => Promise<unknown> =")
+        end
+      end
+
+      describe ".render — single query (Story 8.0a AC4)" do
+        it "emits a query export with the no-args signature" do
+          snapshot = base_snapshot.merge(functions: [
+                                           {
+                                             "ruby_symbol" => "categories",
+                                             "js_identifier" => "categories",
+                                             "kind" => "query",
+                                             "controller" => "CategoriesController"
+                                           }
+                                         ])
+
+          expect(described_class.render(snapshot)).to include(
+            "export const categories: () => Promise<unknown> =\n  _makeRef(\"categories\");\n"
+          )
+        end
+      end
+
+      describe ".render — mixed action and query (Story 8.0a)" do
+        it "emits both shapes in the order provided by the snapshot" do
+          snapshot = base_snapshot.merge(functions: [
+                                           { "ruby_symbol" => "create_post",
+                                             "js_identifier" => "createPost",
+                                             "kind" => "action",
+                                             "controller" => "PostsController" },
+                                           { "ruby_symbol" => "categories",
+                                             "js_identifier" => "categories",
+                                             "kind" => "query",
+                                             "controller" => "CategoriesController" }
+                                         ])
+
+          out = described_class.render(snapshot)
+          expect(out).to include("export const createPost:")
+          expect(out).to include("export const categories:")
+          expect(out.index("createPost")).to be < out.index("categories")
+        end
+      end
+
+      describe ".render — byte-stable across calls (Story 8.0a)" do
+        it "produces byte-identical output for identical snapshots" do
+          first  = described_class.render(base_snapshot)
+          second = described_class.render(base_snapshot.dup)
+          expect(first).to eq(second)
+        end
+      end
+
+      describe ".render — accepts symbol-keyed and string-keyed function entries" do
+        it "tolerates either key style" do
+          string_keys = base_snapshot.merge(functions: [
+                                              { "ruby_symbol" => "demo_ping",
+                                                "js_identifier" => "demoPing",
+                                                "kind" => "action" }
+                                            ])
+          symbol_keys = base_snapshot.merge(functions: [
+                                              { ruby_symbol: "demo_ping",
+                                                js_identifier: "demoPing",
+                                                kind: "action" }
+                                            ])
+          expect(described_class.render(string_keys)).to eq(described_class.render(symbol_keys))
+        end
+      end
+
+      describe ".render — snapshot trust-boundary guards (Re-run patch 2026-05-13)" do
+        it "rejects a snapshot entry whose js_identifier is not a valid JS identifier " \
+           "(would otherwise inject TS at module top level)" do
+          snapshot = base_snapshot.merge(functions: [
+                                           { "ruby_symbol" => "create_post",
+                                             "js_identifier" => ");\nevil();_makeRef(\"x",
+                                             "kind" => "action" }
+                                         ])
+          expect { described_class.render(snapshot) }
+            .to raise_error(Ruact::ConfigurationError) do |error|
+              expect(error.message).to include("snapshot")
+              expect(error.message).to include("valid JS identifier")
+            end
+        end
+
+        it "rejects an entry with a non-String js_identifier" do
+          snapshot = base_snapshot.merge(functions: [
+                                           { "ruby_symbol" => "create_post",
+                                             "js_identifier" => nil,
+                                             "kind" => "action" }
+                                         ])
+          expect { described_class.render(snapshot) }
+            .to raise_error(Ruact::ConfigurationError, /valid JS identifier/)
+        end
+
+        it "JSON-escapes the ruby_symbol argument to _makeRef so backslashes / quotes " \
+           "in a (hand-edited or corrupted) snapshot cannot break out of the string literal" do
+          # The js_identifier still has to be a valid identifier — only the
+          # ruby_symbol can carry arbitrary string content. Escape it.
+          snapshot = base_snapshot.merge(functions: [
+                                           { "ruby_symbol" => "weird\"\\name",
+                                             "js_identifier" => "weirdName",
+                                             "kind" => "action" }
+                                         ])
+          out = described_class.render(snapshot)
+          expect(out).to include('_makeRef("weird\"\\\\name");')
+        end
+      end
+
+      describe ".render — snapshot trust-boundary guards (Re-run patch 2026-05-14)" do
+        # The Ruby renderer reads the same on-disk JSON bridge as the JS-side
+        # renderer (rake task path + Railtie path), so the same guards must
+        # apply on both sides. Mirrors the JS-side `validateSnapshot`.
+
+        it "rejects a snapshot whose version contains a line break" do
+          evil = base_snapshot.merge(version: "1\n// injected")
+          expect { described_class.render(evil) }
+            .to raise_error(Ruact::ConfigurationError, /version.*line break/)
+        end
+
+        it "rejects a snapshot whose generated_at contains a line break" do
+          evil = base_snapshot.merge(generated_at: "2026-05-14\n// injected")
+          expect { described_class.render(evil) }
+            .to raise_error(Ruact::ConfigurationError, /generated_at.*line break/)
+        end
+
+        it "rejects a snapshot whose functions field is not an Array" do
+          evil = base_snapshot.merge(functions: "oops")
+          expect { described_class.render(evil) }
+            .to raise_error(Ruact::ConfigurationError, /functions must be an Array/)
+        end
+
+        it "rejects a snapshot entry whose kind is not in the allowlist" do
+          evil = base_snapshot.merge(functions: [
+                                       { "ruby_symbol" => "foo",
+                                         "js_identifier" => "foo",
+                                         "kind" => "mutation" }
+                                     ])
+          expect { described_class.render(evil) }
+            .to raise_error(Ruact::ConfigurationError, /invalid kind/)
+        end
+
+        it "rejects a snapshot whose entries duplicate a js_identifier" do
+          evil = base_snapshot.merge(functions: [
+                                       { "ruby_symbol" => "foo",
+                                         "js_identifier" => "foo",
+                                         "kind" => "action" },
+                                       { "ruby_symbol" => "bar",
+                                         "js_identifier" => "foo",
+                                         "kind" => "query" }
+                                     ])
+          expect { described_class.render(evil) }
+            .to raise_error(Ruact::ConfigurationError, /duplicate js_identifier "foo"/)
+        end
+
+        it "rejects a snapshot whose js_identifier is a JS reserved word" do
+          evil = base_snapshot.merge(functions: [
+                                       { "ruby_symbol" => "delete",
+                                         "js_identifier" => "delete",
+                                         "kind" => "action" }
+                                     ])
+          expect { described_class.render(evil) }
+            .to raise_error(Ruact::ConfigurationError, /reserved JS word/)
+        end
+
+        it "rejects a snapshot whose version contains a U+2028 line separator " \
+           "(Pass-2 patch 2026-05-14 — JS LineTerminator parity)" do
+          evil = base_snapshot.merge(version: "1
// injected")
+          expect { described_class.render(evil) }
+            .to raise_error(Ruact::ConfigurationError, /line break.*U\+2028/)
+        end
+
+        it "rejects a snapshot whose generated_at contains a U+2029 paragraph separator " \
+           "(Pass-2 patch 2026-05-14 — JS LineTerminator parity)" do
+          evil = base_snapshot.merge(generated_at: "2026-05-14
// injected")
+          expect { described_class.render(evil) }
+            .to raise_error(Ruact::ConfigurationError, /line break.*U\+2029/)
+        end
+
+        it "wraps Hash#fetch KeyError as Ruact::ConfigurationError when a root key is " \
+           "missing (Pass-2 patch 2026-05-14)" do
+          evil = { generated_at: "2026-05-14T00:00:00Z", functions: [] } # no :version
+          expect { described_class.render(evil) }
+            .to raise_error(Ruact::ConfigurationError, /missing required key/)
+        end
+
+        it "rejects an entry with empty ruby_symbol so we never emit _makeRef(\"\") " \
+           "(Pass-2 patch 2026-05-14)" do
+          evil = base_snapshot.merge(functions: [
+                                       { "ruby_symbol" => "",
+                                         "js_identifier" => "foo",
+                                         "kind" => "action" }
+                                     ])
+          expect { described_class.render(evil) }
+            .to raise_error(Ruact::ConfigurationError, /missing or empty ruby_symbol/)
+        end
+
+        it "rejects an entry with nil ruby_symbol (Pass-2 patch 2026-05-14)" do
+          evil = base_snapshot.merge(functions: [
+                                       { "ruby_symbol" => nil,
+                                         "js_identifier" => "foo",
+                                         "kind" => "action" }
+                                     ])
+          expect { described_class.render(evil) }
+            .to raise_error(Ruact::ConfigurationError, /missing or empty ruby_symbol/)
+        end
+
+        it "rejects when snapshot is not a Hash" do
+          expect { described_class.render("oops") }
+            .to raise_error(Ruact::ConfigurationError, /snapshot must be a Hash/)
+        end
+      end
+
+      describe ".generate_ts! (Story 8.0a — write-if-changed wrapper)" do
+        around do |example|
+          Dir.mktmpdir do |dir|
+            @tmpdir = dir
+            example.run
+          end
+        end
+
+        let(:path) { File.join(@tmpdir, "server-functions.ts") }
+
+        it "writes the file on first call and returns true" do
+          expect(described_class.generate_ts!(snapshot: base_snapshot, output_path: path))
+            .to be(true)
+          expect(File.read(path)).to include("// AUTO-GENERATED by vite-plugin-ruact")
+        end
+
+        it "does NOT rewrite when the content is byte-identical (Story 8.0a)" do
+          described_class.generate_ts!(snapshot: base_snapshot, output_path: path)
+          expect(described_class.generate_ts!(snapshot: base_snapshot, output_path: path))
+            .to be(false)
+        end
+      end
+
+      describe ".render — route-driven v2 snapshot (Story 9.3)", :story_9_3 do
+        let(:v2_snapshot) do
+          {
+            version: 2,
+            generated_at: "2026-06-09T00:00:00Z",
+            functions: [
+              { "js_identifier" => "createPost", "kind" => "action",
+                "http_method" => "POST", "path" => "/posts", "segments" => [],
+                "controller" => "posts", "action" => "create" },
+              { "js_identifier" => "updatePost", "kind" => "action",
+                "http_method" => "PATCH", "path" => "/posts/:id", "segments" => ["id"],
+                "controller" => "posts", "action" => "update" }
+            ]
+          }
+        end
+
+        it "dispatches on version 2 and emits _makeServerFunction with real path+verb" do
+          out = described_class.render(v2_snapshot)
+          expect(out).to include('import { _makeServerFunction } from "ruact/server-functions-runtime";')
+          expect(out).to include('_makeServerFunction({ method: "POST", path: "/posts", segments: [] });')
+          expect(out).to include('_makeServerFunction({ method: "PATCH", path: "/posts/:id", segments: ["id"] });')
+          expect(out).to include('export { revalidate } from "ruact/server-functions-runtime";')
+        end
+
+        it "keeps the Story 8.2 intersection signature on v2 actions (form action support)" do
+          out = described_class.render(v2_snapshot)
+          expect(out).to include("& ((formData: FormData) => Promise<void>)")
+        end
+
+        it "emits the empty-v2 module when no routes are exposed" do
+          out = described_class.render(version: 2, generated_at: "2026-06-09T00:00:00Z", functions: [])
+          expect(out).to include("void _makeServerFunction;")
+          expect(out).to include("(no server functions exposed yet")
+          expect(out).to end_with("export { revalidate } from \"ruact/server-functions-runtime\";\n")
+        end
+
+        it "rejects a v2 entry with an invalid http_method" do
+          evil = v2_snapshot.merge(functions: [
+                                     { "js_identifier" => "createPost", "kind" => "action",
+                                       "http_method" => "GET", "path" => "/posts", "segments" => [] }
+                                   ])
+          expect { described_class.render(evil) }
+            .to raise_error(Ruact::ConfigurationError, /invalid http_method/)
+        end
+
+        it "rejects a v2 entry declaring a segment absent from the path" do
+          evil = v2_snapshot.merge(functions: [
+                                     { "js_identifier" => "updatePost", "kind" => "action",
+                                       "http_method" => "PATCH", "path" => "/posts", "segments" => ["id"] }
+                                   ])
+          expect { described_class.render(evil) }
+            .to raise_error(Ruact::ConfigurationError, /absent from path/)
+        end
+
+        it "rejects a v2 entry with an unknown kind (Story 9.5 — action/query only)" do
+          evil = v2_snapshot.merge(functions: [
+                                     { "js_identifier" => "createPost", "kind" => "mutation",
+                                       "http_method" => "POST", "path" => "/posts", "segments" => [] }
+                                   ])
+          expect { described_class.render(evil) }
+            .to raise_error(Ruact::ConfigurationError, /v2 entries are "action" or "query"/)
+        end
+
+        it "rejects a v2 entry whose js_identifier is reserved" do
+          evil = v2_snapshot.merge(functions: [
+                                     { "js_identifier" => "revalidate", "kind" => "action",
+                                       "http_method" => "POST", "path" => "/posts", "segments" => [] }
+                                   ])
+          expect { described_class.render(evil) }
+            .to raise_error(Ruact::ConfigurationError, /reserved/)
+        end
+
+        it "rejects a v2 entry named after the v2 runtime accessor (_makeServerFunction)" do
+          evil = v2_snapshot.merge(functions: [
+                                     { "js_identifier" => "_makeServerFunction", "kind" => "action",
+                                       "http_method" => "POST", "path" => "/posts", "segments" => [] }
+                                   ])
+          expect { described_class.render(evil) }
+            .to raise_error(Ruact::ConfigurationError, /reserved/)
+        end
+
+        it "rejects a v2 path with an undeclared dynamic segment (bidirectional guard)" do
+          evil = v2_snapshot.merge(functions: [
+                                     { "js_identifier" => "updatePost", "kind" => "action",
+                                       "http_method" => "PATCH", "path" => "/posts/:id",
+                                       "segments" => [] }
+                                   ])
+          expect { described_class.render(evil) }
+            .to raise_error(Ruact::ConfigurationError, /not declared in segments/)
+        end
+
+        it "rejects a v2 segment that only substring-matches a longer path token" do
+          evil = v2_snapshot.merge(functions: [
+                                     { "js_identifier" => "updatePost", "kind" => "action",
+                                       "http_method" => "PATCH", "path" => "/posts/:id_extra",
+                                       "segments" => ["id"] }
+                                   ])
+          expect { described_class.render(evil) }
+            .to raise_error(Ruact::ConfigurationError, /absent from path/)
+        end
+      end
+
+      describe ".render — v2 query entries (Story 9.5)", :story_9_5 do
+        def query_entry(js_id, path, accepts_params:)
+          {
+            "js_identifier" => js_id, "kind" => "query", "http_method" => "GET",
+            "path" => path, "segments" => [], "accepts_params" => accepts_params,
+            "controller" => "CatalogQuery", "action" => js_id
+          }
+        end
+
+        it "emits a no-param query as _makeQuery with the () signature + useQuery re-export" do
+          out = described_class.render(version: 2, generated_at: "t", functions: [
+                                         query_entry("categories", "/q/categories", accepts_params: false)
+                                       ])
+          expect(out).to include('import { _makeQuery } from "ruact/server-functions-runtime";')
+          expect(out).to include("export const categories: () => Promise<unknown> =")
+          expect(out).to include('_makeQuery({ path: "/q/categories", kind: "query" });')
+          expect(out).to include('export { useQuery } from "ruact/server-functions-runtime";')
+          expect(out).to include('export { revalidate } from "ruact/server-functions-runtime";')
+        end
+
+        it "emits a param-declaring query with the (params) signature" do
+          out = described_class.render(version: 2, generated_at: "t", functions: [
+                                         query_entry("searchUsers", "/q/searchUsers", accepts_params: true)
+                                       ])
+          expect(out).to include("export const searchUsers: (params: Record<string, unknown>) => Promise<unknown> =")
+          expect(out).to include('_makeQuery({ path: "/q/searchUsers", kind: "query" });')
+        end
+
+        it "imports both accessors and re-exports useQuery for a mixed action+query snapshot" do
+          out = described_class.render(version: 2, generated_at: "t", functions: [
+                                         { "js_identifier" => "createPost", "kind" => "action",
+                                           "http_method" => "POST", "path" => "/posts", "segments" => [] },
+                                         query_entry("categories", "/q/categories", accepts_params: false)
+                                       ])
+          expect(out).to include('import { _makeServerFunction, _makeQuery } from "ruact/server-functions-runtime";')
+          expect(out).to include("_makeServerFunction({ method: \"POST\"")
+          expect(out).to include("_makeQuery({ path: \"/q/categories\", kind: \"query\" })")
+          expect(out).to include('export { useQuery } from "ruact/server-functions-runtime";')
+        end
+
+        it "accepts GET for a query entry (queries are GET-only)" do
+          expect do
+            described_class.render(version: 2, generated_at: "t", functions: [
+                                     query_entry("categories", "/q/categories", accepts_params: false)
+                                   ])
+          end.not_to raise_error
+        end
+
+        it "rejects a non-GET verb on a query entry" do
+          evil = { "js_identifier" => "categories", "kind" => "query", "http_method" => "POST",
+                   "path" => "/q/categories", "segments" => [] }
+          expect { described_class.render(version: 2, generated_at: "t", functions: [evil]) }
+            .to raise_error(Ruact::ConfigurationError, /invalid http_method/)
+        end
+
+        it "rejects a query entry whose js_identifier is the useQuery re-export name" do
+          evil = { "js_identifier" => "useQuery", "kind" => "query", "http_method" => "GET",
+                   "path" => "/q/useQuery", "segments" => [], "accepts_params" => false }
+          expect { described_class.render(version: 2, generated_at: "t", functions: [evil]) }
+            .to raise_error(Ruact::ConfigurationError, /reserved/)
+        end
+
+        it "rejects a query entry whose js_identifier is the _makeQuery import name" do
+          evil = { "js_identifier" => "_makeQuery", "kind" => "query", "http_method" => "GET",
+                   "path" => "/q/_makeQuery", "segments" => [], "accepts_params" => false }
+          expect { described_class.render(version: 2, generated_at: "t", functions: [evil]) }
+            .to raise_error(Ruact::ConfigurationError, /reserved/)
+        end
+
+        it "does NOT re-export useQuery for an action-only snapshot (byte-stable with 9.3)" do
+          out = described_class.render(version: 2, generated_at: "t", functions: [
+                                         { "js_identifier" => "createPost", "kind" => "action",
+                                           "http_method" => "POST", "path" => "/posts", "segments" => [] }
+                                       ])
+          expect(out).not_to include("useQuery")
+          expect(out).to end_with("export { revalidate } from \"ruact/server-functions-runtime\";\n")
+        end
+      end
+    end
+  end
+end