ruact 0.0.4 → 0.0.6

data/lib/ruact/client_manifest.rb

@@ -19,6 +19,24 @@ module Ruact
   #       "name":   "default"
   #     }
   #   }
+  #
+  # Story 13.5 (FR100) — an entry MAY carry an optional, purely additive
+  # +contract+ field when the component opts in by exporting +__ruactContract+
+  # from its +.tsx+ (the Vite plugin extracts it names-only). Shape:
+  #
+  #   "LikeButton": {
+  #     "id": ..., "name": ..., "chunks": [...],
+  #     "contract": {
+  #       "props":       { "postId" => "required", "initialCount" => "optional" },
+  #       "slots":       { "header" => "optional" },          # optional
+  #       "passthrough": false                                 # optional
+  #     }
+  #   }
+  #
+  # A component without the export has NO +contract+ key (back-compatible: every
+  # existing manifest + reader is unaffected). {#contract_for} reads it for the
+  # Story 13.5 preprocess-time call-site validator; +nil+ means "no contract →
+  # no validation" (fail open).
   class ClientManifest
     # Used by Flight::Serializer to produce I rows.
     # Returns the metadata array the client expects: [id, name, chunks]
@@ -62,6 +80,24 @@ module Ruact
       end
     end
 
+    # Story 13.5 (FR100) — return the optional component +contract+ Hash for
+    # +name+, or +nil+ when the component declared none (or is absent from the
+    # manifest). Honors the same co-located/shared +resolve_key+ precedence as
+    # {#reference_for}, so a co-located component's contract is found when the
+    # call site's +controller_path+ is known. A pure read (no memoization, no
+    # mutation) — safe on the frozen manifest, never raises for an unknown name
+    # (the validator fails open). Consumed by {Ruact::ComponentContract} from
+    # the ERB preprocessor.
+    #
+    # @param name [String] PascalCase component name (e.g. "LikeButton")
+    # @param controller_path [String, nil] e.g. "posts" — biases toward a
+    #   co-located key ("posts/_like_button") when present.
+    # @return [Hash, nil] the contract Hash, or nil when none is declared.
+    def contract_for(name, controller_path: nil)
+      entry = entries_by_name[resolve_key(name, controller_path)]
+      entry && entry["contract"]
+    end
+
     # Load from a file path (JSON).
     # Pre-warms the reference cache and freezes the manifest so it cannot be
     # mutated at runtime (AC#5). Pre-warming is required because Ruby's freeze
@@ -131,7 +167,7 @@ module Ruact
 
       pool.each do |key|
         comparable = comparable_name_for(key).downcase
-        distance = self.class.send(:damerau_levenshtein_distance, target, comparable)
+        distance = StringDistance.damerau_levenshtein(target, comparable)
         next if distance > 2
 
         in_scope = controller_path && key.start_with?("#{controller_path}/")
@@ -155,41 +191,6 @@ module Ruact
       basename.split("_").map(&:capitalize).join
     end
 
-    # Damerau-Levenshtein distance — like classic Levenshtein but treats
-    # an adjacent transposition (e.g. "ke"↔"ek") as a single edit. Component
-    # names are short (≤ 30 chars in practice) so the full O(m·n) DP table
-    # is fine; the readability win over the two-row Levenshtein trick is
-    # worth the extra ~30 cells of allocation in the failure path.
-    # rubocop:disable Metrics/AbcSize
-    def self.damerau_levenshtein_distance(left, right)
-      return right.length if left.empty?
-      return left.length if right.empty?
-
-      m = left.length
-      n = right.length
-      d = Array.new(m + 1) { Array.new(n + 1, 0) }
-      (0..m).each { |i| d[i][0] = i }
-      (0..n).each { |j| d[0][j] = j }
-
-      (1..m).each do |i|
-        (1..n).each do |j|
-          cost = left[i - 1] == right[j - 1] ? 0 : 1
-          d[i][j] = [
-            d[i - 1][j] + 1,        # deletion
-            d[i][j - 1] + 1,        # insertion
-            d[i - 1][j - 1] + cost  # substitution
-          ].min
-          if i > 1 && j > 1 && left[i - 1] == right[j - 2] && left[i - 2] == right[j - 1]
-            d[i][j] = [d[i][j], d[i - 2][j - 2] + cost].min
-          end
-        end
-      end
-
-      d[m][n]
-    end
-    # rubocop:enable Metrics/AbcSize
-    private_class_method :damerau_levenshtein_distance
-
     # Returns the manifest key to use for +name+ given an optional +controller_path+.
     # Co-located key format: "<controller_path>/_<underscored_name>" (e.g. "posts/_like_button").
     # Co-located takes precedence when both keys exist.

data/lib/ruact/component_contract.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Ruact
+  # Story 13.5 (FR100) — compile-time component contract (HEEx-style `attr`/
+  # `slot`). Validates a `<Component .../>` ERB call site against the
+  # component's OPT-IN contract at preprocess time, so a missing required prop,
+  # a typo'd prop name, or a missing required slot surfaces an error at the call
+  # site (file:line) BEFORE the page renders — not as a silent `undefined` in
+  # the browser.
+  #
+  # This is the CONSUMER-side mirror of `ruact_props` (which validates the
+  # PRODUCER side at class-load, +serializable.rb+). It is NAME-level only:
+  # prop VALUES are arbitrary render-time Ruby expressions the preprocessor
+  # never evaluates, so only names + presence + slots are checkable here (value
+  # typing for the server boundary already landed in Story 13.4).
+  #
+  # The contract Hash is the one the Vite plugin extracted into the manifest:
+  #
+  #   {
+  #     "props"       => { "postId" => "required", "initialCount" => "optional" },
+  #     "slots"       => { "header" => "optional" },   # optional
+  #     "passthrough" => false                          # optional
+  #   }
+  #
+  # Pure + stateless (explicit class methods) so it is trivially testable in
+  # isolation and carries no global state.
+  module ComponentContract
+    # Validate a call site's prop NAMES against +contract+. Raises
+    # {Ruact::ComponentContractError} (a {Ruact::PreprocessorError}) on the
+    # first violation. A +nil+ contract is a no-op (fail open / opt-in).
+    #
+    # @param component_name [String] e.g. "LikeButton"
+    # @param prop_names [Array<String>] names parsed from the call site (e.g.
+    #   `["postId", "initialCount"]` for a `<LikeButton>` tag with those props)
+    # @param contract [Hash, nil] the manifest contract Hash, or nil
+    # @param at [Hash] call-site location for the message with optional keys
+    #   +file+ (from `template.identifier`), +line+ (the 1-based call-site
+    #   line), and +snippet+ (the offending tag text)
+    # @return [void]
+    # @raise [Ruact::ComponentContractError] on a contract violation
+    def self.validate(component_name:, prop_names:, contract:, at: {})
+      return if contract.nil?
+
+      props = normalize(contract["props"])
+      slots = normalize(contract["slots"])
+      given = Array(prop_names).map(&:to_s)
+      where = { component: component_name, file: at[:file], line: at[:line], snippet: at[:snippet] }
+      unknown = contract["passthrough"] == true ? [] : (given - (props.keys + slots.keys))
+
+      # Priority order so the highest-signal message wins. A near-miss typo is
+      # reported FIRST even when it leaves a required prop "missing" — e.g.
+      # `<LikeButton postID={1} />` (postID typo of the required postId) should
+      # say "unknown prop \"postID\" — did you mean \"postId\"?", not the less
+      # helpful "missing required prop \"postId\"" (FR100's canonical typo case).
+      check_typo(unknown, props.keys + slots.keys, where: where)
+      check_missing_required(props, given, kind: "prop", where: where)
+      check_missing_required(slots, given, kind: "slot", where: where)
+      check_unknown(unknown.first, where: where) if unknown.any?
+    end
+
+    # Normalize a contract sub-section into a { "name" => "required"|"optional" }
+    # Hash. Accepts the manifest's Hash form, an Array (all optional — the JS
+    # extractor already collapses array slots to a Hash, but be defensive), or
+    # nil/garbage (→ {}).
+    def self.normalize(section)
+      case section
+      when Hash  then section
+      when Array then section.to_h { |name| [name.to_s, "optional"] }
+      else {}
+      end
+    end
+
+    # An unknown prop whose closest declared match is within edit distance is a
+    # likely typo — report it (with the suggestion) ahead of any missing-required
+    # message. Returns/raises on the first such prop; a no-op when none qualify.
+    def self.check_typo(unknown, declared, where:)
+      unknown.each do |name|
+        suggestion = StringDistance.closest_match(name, declared)
+        next unless suggestion
+
+        raise_error("got unknown prop #{name.inspect} — did you mean #{suggestion.inspect}?", where)
+      end
+    end
+
+    def self.check_missing_required(spec, given, kind:, where:)
+      required = spec.select { |_, requiredness| requiredness == "required" }.keys
+      missing = required - given
+      return if missing.empty?
+
+      name = missing.first
+      raise_error("is missing required #{kind} #{name.inspect} — add the required #{kind} #{name.inspect}", where)
+    end
+
+    def self.check_unknown(name, where:)
+      raise_error("got unknown prop #{name.inspect}", where)
+    end
+
+    # Build + raise the {Ruact::ComponentContractError} with the full message:
+    # component name + file:line + the offending prop/slot + the corrective
+    # suggestion. The message is self-contained (the preprocessor re-raises it
+    # as-is, no generic line/snippet tail appended).
+    #
+    # @param detail [String] the violation clause
+    # @param where [Hash] keys +component+, +file+, +line+, +snippet+
+    def self.raise_error(detail, where)
+      location = [where[:file], where[:line]].compact.join(":")
+      location = "(unknown location)" if location.empty?
+      message = "ruact: <#{where[:component]}> at #{location} #{detail}."
+      message += "\n  in: #{where[:snippet]}" if where[:snippet] && !where[:snippet].empty?
+      raise ComponentContractError, message
+    end
+
+    private_class_method :normalize, :check_typo, :check_missing_required, :check_unknown, :raise_error
+  end
+end

data/lib/ruact/configuration.rb

@@ -17,11 +17,13 @@ module Ruact
       strict_serialization
       suspense_timeout
       vite_dev_server
-      current_user_resolver
       dev_error_payload_enabled
       max_upload_bytes
       query_route_prefix
       query_parent_controller
+      signed_global_id_default_purpose
+      signed_global_id_default_expires_in
+      shadcn_compatible_versions
     ].freeze
 
     # @!attribute [r] manifest_path
@@ -38,17 +40,6 @@ module Ruact
     # @!attribute [r] vite_dev_server
     #   @return [String] Base URL of the Vite dev server. Default: "http://localhost:5173".
     #
-    # @!attribute [r] current_user_resolver
-    #   @return [Proc, nil] Story 8.3 — Lambda invoked by the standalone
-    #     server-action dispatcher when a block reads `current_user`. Receives
-    #     `request.env` (Hash) and returns the authenticated user (or nil).
-    #     Memoized per-dispatch; left nil by default so apps that don't use
-    #     standalone actions never get a phantom `current_user` resolver.
-    #   @example Devise
-    #     Ruact.configure { |c| c.current_user_resolver = ->(env) { env['warden']&.user } }
-    #   @example Hand-rolled session
-    #     Ruact.configure { |c| c.current_user_resolver = ->(env) { User.find_by(id: env['rack.session'][:user_id]) } }
-    #
     # @!attribute [r] dev_error_payload_enabled
     #   @return [Boolean, nil] Story 8.4 — When true, server-action failures
     #     respond with a verbose JSON payload (action name, error class,
@@ -56,8 +47,8 @@ module Ruact
     #     When false, the wire body carries only the four baseline fields
     #     (`_ruact_server_action_error`, `action_name`, `error_class`,
     #     `message`) so React components can render their own UI without
-    #     accidental backtrace leakage. Default `nil` — the endpoint
-    #     controller resolves nil to `Rails.env.development? || Rails.env.test?`,
+    #     accidental backtrace leakage. Default `nil` — the error-rendering
+    #     layer resolves nil to `Rails.env.development? || Rails.env.test?`,
     #     keeping the Configuration trivially constructible in non-Rails specs.
     #   @example Force production-shape errors in development
     #     Ruact.configure { |c| c.dev_error_payload_enabled = false }
@@ -65,9 +56,9 @@ module Ruact
     # @!attribute [r] max_upload_bytes
     #   @return [Integer, nil] Story 8.5 — upper bound (in bytes) on the
     #     `Content-Length` of `multipart/form-data` and
-    #     `application/x-www-form-urlencoded` requests dispatched through
-    #     `POST /__ruact/fn/:name`. When the inbound `Content-Length` exceeds
-    #     this value, the endpoint controller raises
+    #     `application/x-www-form-urlencoded` requests dispatched to a
+    #     `Ruact::Server` mutation route. When the inbound `Content-Length`
+    #     exceeds this value, the server concern raises
     #     `Ruact::UploadTooLargeError` BEFORE Rack's multipart parser runs,
     #     producing a 413 with the Story 8.4 structured error body.
     #     Default: `10 * 1024 * 1024` (10 MB). Set to `nil` to disable the
@@ -105,6 +96,45 @@ module Ruact
     #     scoping, Pundit) runs before any query class is instantiated (FR89).
     #   @example Dispatch queries through an API base controller
     #     Ruact.configure { |c| c.query_parent_controller = "Api::BaseController" }
+    #
+    # @!attribute [r] signed_global_id_default_purpose
+    #   @return [Symbol, String, nil] Story 13.2 (FR96) — the default `for:`
+    #     purpose `Ruact.signed_global_id` / `Ruact.locate_signed` use when the
+    #     call omits `for:`. A purpose scopes a signed reference to one
+    #     use-site so a token minted for editing a post cannot be replayed
+    #     against, say, a delete endpoint. Default `nil` — when neither the
+    #     call nor this config supplies a purpose, the helper raises
+    #     `Ruact::Error` rather than sign an unscoped token (the "developer
+    #     forgot" path is a loud error, never a silent insecure default).
+    #     Prefer a per-call `for:` when use-sites differ; set this only for an
+    #     app-wide default purpose.
+    #   @example Set an app-wide default purpose
+    #     Ruact.configure { |c| c.signed_global_id_default_purpose = :ruact_ref }
+    #
+    # @!attribute [r] signed_global_id_default_expires_in
+    #   @return [ActiveSupport::Duration, nil] Story 13.2 (FR96) — the default
+    #     `expires_in:` `Ruact.signed_global_id` uses when the call omits
+    #     `expires_in:`. Must be an `ActiveSupport::Duration` (e.g. `15.minutes`)
+    #     — globalid calls `#from_now` on it. Default `nil` — when neither the
+    #     call nor this config supplies an expiry, the helper raises
+    #     `Ruact::Error` rather than mint a non-expiring token. To deliberately
+    #     mint a non-expiring token, pass an explicit `expires_in: nil` at the
+    #     call site (a reviewed per-call choice), never via this default.
+    #   @example Set an app-wide default expiry
+    #     Ruact.configure { |c| c.signed_global_id_default_expires_in = 1.hour }
+    #
+    # @!attribute [r] shadcn_compatible_versions
+    #   @return [Array<Integer>] Story 10.5 — the shadcn/ui MAJOR versions the
+    #     `ruact:scaffold` generator is regression-tested against. When the
+    #     generator detects an installed shadcn major (best-effort, from the
+    #     host `package.json`) that is NOT in this list, it emits a warning
+    #     (never a hard stop) that the generated components may import from
+    #     outdated `@/components/ui/*` paths. Must be a non-empty Array of
+    #     Integers. Default `[1, 2]` (the majors tested at gem-release time).
+    #     A dev who has manually verified a newer major adds it here to
+    #     suppress the warning — the documented "override" path.
+    #   @example Allow shadcn v3 once you have verified it
+    #     Ruact.configure { |c| c.shadcn_compatible_versions = [1, 2, 3] }
     ATTRIBUTES.each do |attr|
       attr_reader attr
 
@@ -135,11 +165,10 @@ module Ruact
       if template
         ATTRIBUTES.each do |attr|
           value = template.public_send(attr)
-          # Procs are immutable from the outside (Story 8.3 — current_user_resolver).
-          # Duping creates a different Proc instance, breaking identity comparisons
-          # across re-configurations. Procs are inherently re-entrant safe (no
-          # mutable internal state surface) so the dup is unnecessary; the freeze
-          # at seal! time is enough.
+          # Procs are immutable from the outside. Duping creates a different Proc
+          # instance, breaking identity comparisons across re-configurations.
+          # Procs are inherently re-entrant safe (no mutable internal state
+          # surface) so the dup is unnecessary; the freeze at seal! time is enough.
           cloned = value.is_a?(Proc) ? value : value.dup
           instance_variable_set("@#{attr}", cloned)
         end
@@ -152,11 +181,13 @@ module Ruact
         end
         @suspense_timeout     = 5.0
         @vite_dev_server      = "http://localhost:5173"
-        @current_user_resolver = nil
         @dev_error_payload_enabled = nil
         @max_upload_bytes = 10 * 1024 * 1024
         @query_route_prefix = "/q"
         @query_parent_controller = "ApplicationController"
+        @signed_global_id_default_purpose = nil
+        @signed_global_id_default_expires_in = nil
+        @shadcn_compatible_versions = [1, 2]
       end
     end
 
@@ -186,11 +217,10 @@ module Ruact
 
         # Story 8.3 review — Procs CAN be frozen (`.freeze` flips the frozen
         # flag; no operational effect on `.call`). Freezing in place preserves
-        # object identity (vital for code that compares the resolver across
-        # re-configurations) AND keeps the deep-freeze contract honest —
-        # `Ruact.config.current_user_resolver.freeze` later would otherwise
-        # silently no-op an already-frozen reference, but a caller probing
-        # `frozen?` would see the right answer.
+        # object identity (vital for code that compares a Proc-valued attribute
+        # across re-configurations) AND keeps the deep-freeze contract honest —
+        # a later `.freeze` would otherwise silently no-op an already-frozen
+        # reference, but a caller probing `frozen?` would see the right answer.
         if value.is_a?(Proc)
           value.freeze
         else
@@ -218,6 +248,7 @@ module Ruact
       when :max_upload_bytes        then validate_max_upload_bytes!(value)
       when :query_route_prefix      then validate_query_route_prefix!(value)
       when :query_parent_controller then validate_query_parent_controller!(value)
+      when :shadcn_compatible_versions then validate_shadcn_compatible_versions!(value)
       end
     end
 
@@ -261,6 +292,27 @@ module Ruact
             "got #{value.inspect} (#{value.class.name})."
     end
 
+    # Story 10.5 — the scaffold generator validates the detected shadcn major
+    # against this list (`Array#include?`), so a non-Array would raise at the
+    # first scaffold run instead of at boot, and an empty Array would make every
+    # detected major "incompatible" (a global false warning). Both are
+    # configuration-time errors. Element-type strictness (Integer-only majors)
+    # is enforced too — a `["2"]` typo would silently never match a detected
+    # Integer major and warn on every run.
+    def validate_shadcn_compatible_versions!(value)
+      unless value.is_a?(Array) && !value.empty?
+        raise Ruact::ConfigurationError,
+              "Ruact::Configuration#shadcn_compatible_versions must be a non-empty Array " \
+              "of major-version Integers (e.g. [1, 2]); " \
+              "got #{value.inspect} (#{value.class.name})."
+      end
+      return if value.all?(Integer)
+
+      raise Ruact::ConfigurationError,
+            "Ruact::Configuration#shadcn_compatible_versions must contain only Integer " \
+            "major versions (e.g. [1, 2]); got #{value.inspect}."
+    end
+
     def build_error_message(attr, location)
       <<~MSG.strip
         ruact: cannot mutate Ruact::Configuration##{attr} after initialization.