ruact 0.0.1 → 0.0.3

data/lib/ruact/server_functions/route_source.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/string/inflections"
+require "ruact/server_functions/name_bridge"
+
+module Ruact
+  module ServerFunctions
+    # Story 9.3 — derives v2 server-function entries from the Rails route table.
+    #
+    # The route table is the single source of truth (FR61): every non-GET routed
+    # action on a controller that includes {Ruact::Server} is a callable server
+    # function. This module is the route-driven replacement for the v1 registry
+    # source consumed by {Ruact::ServerFunctions::Snapshot} — it reads routes,
+    # not `ruact_action` declarations.
+    #
+    # Pure by construction: {.collect} takes the route set and two resolver
+    # callables (host predicate + override lookup). The railtie passes the real
+    # constant-resolving implementations; unit specs inject lambdas so the
+    # derivation table is testable without booting controllers.
+    #
+    # ## Derivation table (locked, ADR addendum 2026-06-09)
+    #
+    # `js_identifier = lowerCamel(action) + Namespace*(Pascal) + Resource(Pascal)`
+    #
+    # - **Resource word** — singular for the RESTful writes (`create`/`update`/
+    #   `destroy`) and for any member route (path carries `:id`); plural for a
+    #   custom collection route. Examples: `posts#create` → `createPost`,
+    #   `posts#publish` (member) → `publishPost`, `posts#publish_all`
+    #   (collection) → `publishAllPosts`, `resource :session` `#create` →
+    #   `createSession`.
+    # - **Namespace** — PascalCased and inserted between verb and resource
+    #   (prefix, NOT flat): `admin/posts#create` → `createAdminPost`,
+    #   `admin/reports/posts#create` → `createAdminReportsPost`. Prefixing keeps
+    #   the merged JS namespace collision-free by construction (a flat scheme
+    #   would force `admin/posts#create` and `posts#create` to collide).
+    # - **PATCH/PUT** — `resources` emits both verbs for `update`; they collapse
+    #   to one entry with `http_method: "PATCH"` (Rails' primary verb).
+    #
+    # @see docs/internal/decisions/server-functions-api.md "Story 9.3"
+    module RouteSource
+      # Verbs that expose a callable server function. GET/HEAD are pages.
+      MUTATION_VERBS = %w[POST PUT PATCH DELETE].freeze
+
+      # The RESTful writes whose JS name uses the SINGULAR resource even though
+      # `create` is technically a collection route.
+      RESTFUL_WRITES = %w[create update destroy].freeze
+
+      # When the same controller#action is routed under several verbs (the
+      # `update` PATCH/PUT pair), keep the first by this priority.
+      VERB_PRIORITY = { "PATCH" => 0, "PUT" => 1, "POST" => 2, "DELETE" => 3 }.freeze
+
+      class << self
+        # Collects v2 mutation entries from +route_set+.
+        #
+        # @param route_set [#routes] anything exposing `#routes` (a
+        #   `ActionDispatch::Routing::RouteSet`, or `Rails.application.routes`).
+        # @param host_predicate [#call] `controller_path(String) -> Boolean` —
+        #   true when that controller includes {Ruact::Server}. Defaults to real
+        #   constant resolution.
+        # @param overrides_for [#call] `controller_path(String) -> Hash{String=>String}`
+        #   — the `ruact_function_name` override map (action name → js identifier)
+        #   for that controller. Defaults to real constant resolution.
+        # @return [Array<Hash>] entries (string keys) sorted by `js_identifier`;
+        #   shape: `js_identifier`, `kind` (always `"action"`), `http_method`,
+        #   `path`, `segments` (Array<String>), `controller`, `action`.
+        def collect(route_set, host_predicate: nil, overrides_for: nil)
+          host_predicate ||= method(:default_host?)
+          overrides_for  ||= method(:default_overrides_for)
+
+          by_key = {}
+          route_set.routes.each do |route|
+            verb = route.verb.to_s
+            next unless MUTATION_VERBS.include?(verb)
+
+            controller = route.defaults[:controller]
+            action = route.defaults[:action]
+            next if controller.nil? || action.nil?
+            next unless host_predicate.call(controller)
+
+            key = [controller, action]
+            existing = by_key[key]
+            # PATCH/PUT collapse: keep the higher-priority verb only.
+            next if existing && verb_rank(verb) >= verb_rank(existing["http_method"])
+
+            by_key[key] = build_entry(route, verb, controller, action, overrides_for)
+          end
+
+          entries = by_key.values.sort_by { |entry| entry["js_identifier"] }
+          detect_collisions!(entries)
+          entries
+        end
+
+        private
+
+        # Story 9.3 AC4 — two distinct routes that map to the same JS identifier
+        # (after rename overrides) would emit two `export const` lines the same
+        # name; fail loudly at boot naming BOTH origins so the dev knows exactly
+        # which routes to disambiguate (via `ruact_function_name`). Mirrors the
+        # cross-registry collision raise in {Ruact::ServerFunctions::Snapshot}.
+        def detect_collisions!(entries)
+          entries.group_by { |entry| entry["js_identifier"] }.each do |js_id, group|
+            next if group.size < 2
+
+            origins = group.map { |entry| "#{entry['controller']}##{entry['action']}" }
+            raise Ruact::ConfigurationError,
+                  "server-function naming collision: #{origins.join(' and ')} " \
+                  "both map to JS identifier \"#{js_id}\" — disambiguate with " \
+                  "`ruact_function_name :<action>, as: \"<other-name>\"`"
+          end
+        end
+
+        def build_entry(route, verb, controller, action, overrides_for)
+          override = overrides_for.call(controller)[action.to_s]
+          {
+            "js_identifier" => override || derive_identifier(controller, action, route),
+            "kind" => "action",
+            "http_method" => verb,
+            "path" => clean_path(route),
+            "segments" => route.required_parts.map(&:to_s),
+            "controller" => controller,
+            "action" => action
+          }
+        end
+
+        # `lowerCamel(action) + Namespace*(Pascal) + Resource(Pascal)`.
+        def derive_identifier(controller, action, route)
+          segments = controller.split("/")
+          resource_base = segments.last
+          namespace = segments[0..-2]
+
+          singular = RESTFUL_WRITES.include?(action) || member_route?(route, resource_base)
+          resource_word = singular ? resource_base.singularize : resource_base
+
+          lower_camel(action) +
+            namespace.map { |part| pascal(part) }.join +
+            pascal(resource_word)
+        end
+
+        # A route is a MEMBER route when its path carries a dynamic segment for
+        # THIS resource — i.e. the resource's own basename is immediately
+        # followed by a `:param` in the path (`/posts/:id/publish`,
+        # `/posts/:slug` under `param: :slug`). This is more robust than checking
+        # `required_parts.include?(:id)`: it honors custom `param:` names AND
+        # correctly classifies a NESTED collection route (`/posts/:post_id/
+        # comments/flag_all` — whose only dynamic part is the PARENT `:post_id`)
+        # as a collection, not a member.
+        def member_route?(route, resource_base)
+          route.path.spec.to_s.match?(%r{/#{Regexp.escape(resource_base)}/:[^/(]+})
+        end
+
+        # snake_case → lowerCamel, leading underscore preserved (mirrors
+        # {NameBridge}'s rule for the action portion). Not run through NameBridge
+        # directly: NameBridge validates the WHOLE symbol against reserved words,
+        # but here the action is only a fragment of the final identifier.
+        def lower_camel(str)
+          str = str.to_s
+          leading = str.start_with?("_") ? "_" : ""
+          body = str.sub(/\A_+/, "")
+          leading + body.gsub(/_+([a-z0-9])/) { Regexp.last_match(1).upcase }
+        end
+
+        # snake_case → PascalCase.
+        def pascal(str)
+          camel = lower_camel(str).sub(/\A_+/, "")
+          camel.empty? ? camel : camel[0].upcase + camel[1..]
+        end
+
+        # `/posts/:id(.:format)` → `/posts/:id`. Drops the trailing format
+        # optional; defensively strips any remaining optional `( … )` group.
+        def clean_path(route)
+          spec = route.path.spec.to_s
+          spec = spec.delete_suffix("(.:format)")
+          spec.gsub(/\([^)]*\)/, "")
+        end
+
+        def verb_rank(verb)
+          VERB_PRIORITY.fetch(verb, 99)
+        end
+
+        # Real resolvers — used in the railtie/rake paths.
+        def default_host?(controller)
+          klass = host_class(controller)
+          !klass.nil? && klass.include?(Ruact::Server)
+        end
+
+        def default_overrides_for(controller)
+          klass = host_class(controller)
+          return {} unless klass.respond_to?(:__ruact_function_name_overrides)
+
+          klass.__ruact_function_name_overrides
+        end
+
+        def host_class(controller)
+          "#{controller}_controller".camelize.safe_constantize
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/ruact/server_functions/snapshot.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module Ruact
+  module ServerFunctions
+    # Pure functions that build the JSON-shaped Hash representing both server-
+    # function registries. Serialized to `tmp/cache/ruact/server-functions.json`
+    # by {.generate!}; the Vite plugin reads that file and emits the TS module.
+    #
+    # The "functions" array is sorted by `ruby_symbol` for deterministic output
+    # so that fingerprint comparisons (used by the write-if-changed guard) are
+    # stable across runs. Cross-registry JS-identifier collisions are detected
+    # here (the per-registry `Registry#register` only sees its own entries; a
+    # `ruact_action :foo` colliding with a `ruact_query :foo` is invisible to
+    # both registries in isolation).
+    module Snapshot
+      # Bump only when the on-disk schema changes incompatibly. The Vite plugin
+      # must be updated in lockstep.
+      VERSION = 1
+
+      # Story 9.3 — the route-driven snapshot schema. v2 entries are produced by
+      # {Ruact::ServerFunctions::RouteSource} (route table), not the registries.
+      VERSION_V2 = 2
+
+      class << self
+        # Builds the snapshot Hash for both registries. Pure. See also
+        # {.generate!} (writes to disk) and {.functions_payload} (fingerprint
+        # surface).
+        #
+        # @param action_registry [Ruact::ServerFunctions::Registry]
+        # @param query_registry  [Ruact::ServerFunctions::Registry]
+        # @param now [Time] timestamp to stamp into `generated_at` (UTC, ISO-8601).
+        # @return [Hash] the serializable snapshot.
+        # @raise [Ruact::ConfigurationError] when a JS identifier is registered
+        #   in both registries (cross-registry collision; see {.functions_payload}).
+        def dump(action_registry, query_registry, now: Time.now.utc)
+          {
+            version: VERSION,
+            generated_at: now.utc.iso8601,
+            functions: functions_payload(action_registry, query_registry)
+          }
+        end
+
+        # Returns the payload-only array of function entries, sorted by
+        # `ruby_symbol`. Used both inside {.dump} and as the fingerprint surface
+        # by {.generate!}'s short-circuit (so timestamp churn alone never causes
+        # a rewrite). Detects cross-registry JS-identifier collisions and
+        # raises before emitting — a `ruact_action :foo` and `ruact_query :foo`
+        # would emit two `export const foo` lines at codegen, which `tsc` rejects.
+        #
+        # @return [Array<Hash>] each entry has string keys per the JSON contract.
+        # @raise [Ruact::ConfigurationError] when the action and query registries
+        #   both contain entries that map to the same JS identifier.
+        def functions_payload(action_registry, query_registry)
+          combined = action_registry.entries.values + query_registry.entries.values
+          detect_cross_registry_collision!(combined)
+          combined.sort_by { |entry| entry.ruby_symbol.to_s }.map do |entry|
+            {
+              "ruby_symbol" => entry.ruby_symbol.to_s,
+              "js_identifier" => entry.js_identifier,
+              "kind" => entry.kind.to_s,
+              "controller" => describe_controller(entry.controller)
+            }
+          end
+        end
+
+        # Builds the snapshot and writes it to +path+, but only if the
+        # functions list differs from the on-disk snapshot. This is the central
+        # short-circuit that prevents `config.to_prepare` from rewriting the
+        # file on every request (Story 8.0a pitfall #1): the JSON's
+        # `generated_at` is freshly stamped only when the registry actually
+        # changed; otherwise the on-disk content stays byte-identical.
+        #
+        # The short-circuit compares **both** `version` and `functions` against
+        # the on-disk snapshot — a schema bump (`VERSION` increment) forces a
+        # rewrite even when the registry payload is unchanged, so the Vite
+        # plugin never reads a stale-version snapshot after a gem upgrade.
+        #
+        # @param action_registry [Ruact::ServerFunctions::Registry]
+        # @param query_registry  [Ruact::ServerFunctions::Registry]
+        # @param path [String, Pathname] absolute path to the snapshot JSON.
+        # @param now [Time] timestamp used when (and only when) the file is rewritten.
+        # @return [Boolean] true if the file was written; false if no change.
+        def generate!(action_registry:, query_registry:, path:, now: Time.now.utc)
+          new_functions = functions_payload(action_registry, query_registry)
+
+          existing_version, existing_functions = read_existing_snapshot(path)
+          return false if existing_version == VERSION && existing_functions == new_functions
+
+          snapshot = {
+            version: VERSION,
+            generated_at: now.utc.iso8601,
+            functions: new_functions
+          }
+          SnapshotWriter.write_if_changed!(path: path, content: "#{JSON.pretty_generate(snapshot)}\n")
+        end
+
+        # Story 9.3 — wraps route-derived +entries+ into a version-2 snapshot
+        # Hash (the shape {Codegen.render} dispatches on). Pure.
+        #
+        # @param entries [Array<Hash>] from {RouteSource.collect}.
+        # @return [Hash]
+        def dump_v2(entries, now: Time.now.utc)
+          {
+            version: VERSION_V2,
+            generated_at: now.utc.iso8601,
+            functions: entries
+          }
+        end
+
+        # Story 9.3 — write-if-changed for the route-driven (v2) bridge. Mirrors
+        # {.generate!}: `generated_at` is freshly stamped only when the entries
+        # changed, so a stable route table never churns the file (and never
+        # re-triggers downstream TS rendering). A schema mismatch (`version`)
+        # forces a rewrite even when entries are unchanged.
+        #
+        # @param entries [Array<Hash>] from {RouteSource.collect}.
+        # @param path [String, Pathname] absolute path to the v2 bridge JSON.
+        # @return [Boolean] true if written, false if unchanged.
+        def generate_v2!(entries:, path:, now: Time.now.utc)
+          existing_version, existing_functions = read_existing_snapshot(path)
+          return false if existing_version == VERSION_V2 && existing_functions == entries
+
+          snapshot = { version: VERSION_V2, generated_at: now.utc.iso8601, functions: entries }
+          SnapshotWriter.write_if_changed!(path: path, content: "#{JSON.pretty_generate(snapshot)}\n")
+        end
+
+        # Story 9.3 — the Decision-#6 ownership primitive. True when the app has
+        # ANY v1 declaration (`ruact_action` / `ruact_query`). Story 9.8 consults
+        # this to decide whether route-driven codegen takes over the real
+        # `server-functions.ts`; in Story 9.3 the v2 codegen always writes the
+        # parallel `.next` target regardless, so this is informational here.
+        #
+        # @return [Boolean]
+        def v1_declarations?(action_registry, query_registry)
+          !(action_registry.entries.empty? && query_registry.entries.empty?)
+        end
+
+        private
+
+        def detect_cross_registry_collision!(entries)
+          by_js_id = entries.group_by(&:js_identifier).select { |_, group| group.size >= 2 }
+          return if by_js_id.empty?
+
+          # If both rows are the same Ruby symbol it is a within-registry duplicate
+          # (caught by Registry#register's own collision detection). A genuine
+          # cross-registry collision is any group whose entries span more than
+          # one kind — i.e. one action + one query share the same js_identifier.
+          cross = by_js_id.find do |_, group|
+            kinds = group.map(&:kind).uniq
+            kinds.size > 1
+          end
+          return unless cross
+
+          js_id, group = cross
+          # AC7 exact shape: `:foo_bar (in FooController) and :foo__bar (in BarController)`
+          # — no `kind:` annotation. The kind differentiation is implicit in
+          # the cross-registry collision being detected at all.
+          parts = group.map do |entry|
+            ":#{entry.ruby_symbol} (in #{describe_controller(entry.controller)})"
+          end
+          # AC7 shape: "[ruact] error: server-function naming collision: ..."
+          # The rake task wraps the bare message with "[ruact] error: " — keep
+          # the prefix in sync with the within-registry message in
+          # Registry#detect_collision! so the rake stdout reads identically
+          # for both kinds of collision.
+          raise Ruact::ConfigurationError,
+                "server-function naming collision: " \
+                "#{parts.join(' and ')} both map to JS identifier \"#{js_id}\""
+        end
+
+        def describe_controller(controller)
+          return nil if controller.nil?
+
+          controller.respond_to?(:name) && controller.name ? controller.name : controller.inspect
+        end
+
+        # Reads `(version, functions)` from the on-disk snapshot. Returns
+        # `[nil, nil]` when the file is missing, vanished between the stat and
+        # the read (TOCTOU race fix — `File.exist?` removed; we catch `ENOENT`
+        # from `File.read` directly), or malformed.
+        def read_existing_snapshot(path)
+          parsed = JSON.parse(File.read(path))
+          return [nil, nil] unless parsed.is_a?(Hash)
+
+          [parsed["version"], parsed["functions"]]
+        rescue Errno::ENOENT, JSON::ParserError
+          [nil, nil]
+        end
+      end
+    end
+  end
+end

data/lib/ruact/server_functions/snapshot_writer.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "securerandom"
+
+module Ruact
+  module ServerFunctions
+    # Atomic, byte-aware file writer used by both the JSON snapshot bridge and
+    # the Ruby-side TypeScript codegen. Two responsibilities:
+    #
+    # 1. **Write-if-changed**: compare the SHA-256 of the desired bytes with the
+    #    on-disk bytes; if equal, no-op. This is the leg of the dev-reload
+    #    pitfall mitigation (Story 8.0a pitfall #1) — paired with the
+    #    payload-only fingerprint inside `Snapshot.generate!`, it guarantees
+    #    that a request without registry changes produces zero writes.
+    # 2. **Atomic publication**: write to a tmpfile in the same directory, then
+    #    rename. Readers (the Vite-plugin chokidar watcher) never observe a
+    #    half-written file.
+    #
+    # Parent directories are created as needed.
+    module SnapshotWriter
+      class << self
+        # @param path [String, Pathname] absolute destination path.
+        # @param content [String] bytes to write.
+        # @return [Boolean] true if the file was written; false if unchanged.
+        # @raise [Ruact::ConfigurationError] when the parent directory cannot be
+        #   created (typically a read-only filesystem mounted into the app).
+        def write_if_changed!(path:, content:) # rubocop:disable Naming/PredicateMethod
+          path = path.to_s
+          # TOCTOU-safe read: catch `ENOENT` from `File.read` rather than
+          # gating on `File.exist?` — between the stat and the read the file
+          # may be removed by another process (e.g. `rails tmp:clear`).
+          existing = begin
+            File.read(path)
+          rescue StandardError
+            nil
+          end
+          return false if existing == content
+
+          dir = File.dirname(path)
+          ensure_writable!(dir)
+
+          # Random suffix so two same-process writes of identical content do
+          # not race over the same temp filename (e.g. JSON-snapshot writer
+          # + Ruby TS codegen running back-to-back inside the rake task on
+          # an unchanged registry — the digest-prefix-only tmp name was
+          # deterministic, which collided).
+          tmp = "#{path}.tmp.#{Process.pid}.#{SecureRandom.hex(8)}"
+          File.binwrite(tmp, content)
+          File.rename(tmp, path)
+          true
+        end
+
+        private
+
+        def ensure_writable!(dir)
+          FileUtils.mkdir_p(dir)
+        rescue SystemCallError => e
+          raise Ruact::ConfigurationError,
+                "ruact: cannot create #{dir} for server-functions snapshot: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/ruact/server_functions/standalone_context.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Ruact
+  module ServerFunctions
+    # Story 8.3 — per-dispatch execution context for a standalone server
+    # action. The dispatcher allocates a fresh instance per request,
+    # `instance_exec`s the action block against it, and discards the
+    # instance once the response is written.
+    #
+    # Exposes:
+    #   - `params`   — the action-call args, as `ActionController::Parameters`
+    #     (same shape as the controller-hosted path from Story 8.1).
+    #   - `request`  — the live `ActionDispatch::Request`.
+    #   - `session`  — the host middleware's session.
+    #   - `cookies`  — the live `ActionDispatch::Cookies::CookieJar`.
+    #   - `headers`  — `request.headers`.
+    #   - `current_user` — memoized; reads `request.env['ruact.current_user']`
+    #     when present, otherwise invokes
+    #     {Ruact::Configuration#current_user_resolver} (a lambda taking
+    #     `request.env`). Raises {Ruact::CurrentUserNotConfiguredError} when
+    #     neither path yields a value AND the block actually reads it.
+    #
+    # Does NOT expose `render` / `redirect_to` / `head` — those are
+    # controller-context methods. The block's return value IS the response;
+    # raise {Ruact::ActionError} for non-2xx returns.
+    class StandaloneContext
+      attr_reader :params, :request
+
+      # @param params [ActionController::Parameters] action-call args.
+      # @param request [ActionDispatch::Request] the live request.
+      def initialize(params:, request:)
+        @params = params
+        @request = request
+        @current_user_read = false
+        @current_user_memo = nil
+        @current_user_resolved = false
+      end
+
+      def session
+        @request.session
+      end
+
+      def cookies
+        @request.cookie_jar
+      end
+
+      def headers
+        @request.headers
+      end
+
+      # Memoized current_user accessor. Sets a flag so the dispatcher can
+      # emit a dev-only warning when a block never reads `current_user`
+      # (Pitfall #4 in the story spec).
+      def current_user
+        @current_user_read = true
+        return @current_user_memo if @current_user_resolved
+
+        env = @request.env
+        if env.key?("ruact.current_user")
+          @current_user_memo = env["ruact.current_user"]
+          @current_user_resolved = true
+          return @current_user_memo
+        end
+
+        resolver = Ruact.config.current_user_resolver
+        raise Ruact::CurrentUserNotConfiguredError unless resolver
+
+        @current_user_memo = resolver.call(env)
+        @current_user_resolved = true
+        @current_user_memo
+      end
+
+      # @api private — Pitfall #4 dev-mode warning flag.
+      def __ruact_current_user_read?
+        @current_user_read
+      end
+
+      # Inhibits accidental controller-context calls inside a standalone
+      # block. The error message names the supported alternatives so the
+      # developer can immediately fix the call.
+      def render(*_args, **_kwargs)
+        raise NoMethodError,
+              "StandaloneContext does not expose `render` — return a value from " \
+              "the block (it becomes the JSON response) or raise " \
+              "`Ruact::ActionError.new(status:, body:)` for non-2xx responses."
+      end
+
+      def redirect_to(*_args, **_kwargs)
+        raise NoMethodError,
+              "StandaloneContext does not expose `redirect_to` — return a value " \
+              "from the block (it becomes the JSON response) or raise " \
+              "`Ruact::ActionError.new(status:, body:)` for non-2xx responses."
+      end
+
+      def head(*_args, **_kwargs)
+        raise NoMethodError,
+              "StandaloneContext does not expose `head` — return `nil` to render " \
+              "204 No Content, or raise `Ruact::ActionError.new(status:, body:)` " \
+              "for other non-2xx responses."
+      end
+    end
+  end
+end