ruact 0.0.6 → 0.0.8

data/lib/ruact/erb_preprocessor.rb

@@ -28,6 +28,29 @@ module Ruact
     SUSPENSE_OPEN_RE  = /<Suspense\b([^>]*?)>/m
     SUSPENSE_CLOSE_RE = %r{</Suspense>}
 
+    # Story 15.2 (FR106) — matches ANY PascalCase component tag: opening
+    # (`<Card>`), self-closing (`<Card />`), or closing (`</Card>`). Capture 1 is
+    # the leading slash (present only on a closing tag); capture 2 is the name.
+    # The loud-children detection scans these left-to-right with a stack: an
+    # opening pushes, a self-closing (`/>`) is ignored, and a closing that pops a
+    # matching opening means that opening had children (paired usage) → loud
+    # error. A single linear pass (no backreference/lazy backtracking) keeps the
+    # component-dense fast path linear regardless of how many tags go unclosed.
+    COMPONENT_ANY_TAG_RE = %r{<(/)?([A-Z][A-Za-z0-9]*)(?:\s[^>]*)?>}
+
+    # Cheap allocation-free probe (`String#match?`) for "is there ANY PascalCase
+    # closing tag at all?". The loud-children scan only matters when one exists,
+    # so this gates the (copy-heavy) mask/scan work off the common all-self-
+    # closing fast path. `</Suspense>` matches too — harmless, it gets masked.
+    CLOSING_TAG_PROBE_RE = %r{</[A-Z][A-Za-z0-9]*>}
+
+    # Newline-preserving mask for ERB islands (`<% … %>`, `<%= … %>`, `<%# … %>`).
+    # The loud-children scan blanks these first so a `</Card>` that lives inside
+    # Ruby/ERB string or comment text can never be mistaken for a real component
+    # closing tag (a valid bare `<Dialog>` opening must not error because some
+    # unrelated `<% "</Dialog>" %>` appears later).
+    ERB_ISLAND_RE = /<%.*?%>/m
+
     # Matches a +{ruby_expr}+ attribute value — captures everything between the braces.
     # We use a simple bracket-depth counter approach during scanning instead of regex
     # because expressions can contain nested braces: {foo.bar({ a: 1 })}.
@@ -66,6 +89,16 @@ module Ruact
                end
         .gsub(SUSPENSE_CLOSE_RE, "</ruact-suspense>")
 
+      # Step 1.5 (Story 15.2 / FR106): before the general component pass, fail
+      # loudly if any PascalCase component tag is used with children (a matching
+      # closing tag). Silent degradation of `<Card>Hello</Card>` — the #1
+      # predictable JSX-habit mistake — becomes a self-contained, re-raised-as-is
+      # PreprocessorError naming the fix. It scans the ORIGINAL +source+ (so
+      # file:line is exact) and masks Suspense (the one legitimate paired
+      # PascalCase tag) newline-for-newline, so `<Suspense>...</Suspense>` can
+      # never trip and every reported line matches the template verbatim.
+      detect_children!(source, identifier)
+
       # Step 2: transform remaining PascalCase self-closing / opening component tags.
       result.gsub(COMPONENT_TAG_RE) do |match|
         component_name = ::Regexp.last_match(1)
@@ -74,7 +107,13 @@ module Ruact
         line           = result[0...match_start].count("\n") + 1
 
         begin
-          registry = Ruact.manifest if registry == :default # lazy — only when a tag exists
+          # lazy — only when a tag exists. `resolve_soft` returns the dev-fetched
+          # manifest (same source the render path uses, so the boot-race doesn't
+          # silence FR100 contract checks in dev) and FAILS OPEN to nil when the
+          # manifest is unresolvable (contract validation is opt-in/fail-open;
+          # the render path surfaces the clear error). In prod this is the
+          # boot-loaded Ruact.manifest, unchanged.
+          registry = ManifestResolver.resolve_soft if registry == :default
           pairs = parse_prop_pairs(attrs_string)
           validate_contract(registry, component_name, pairs.map(&:first),
                             at: { file: identifier, line: line, snippet: match.strip })
@@ -93,6 +132,86 @@ module Ruact
 
     private
 
+    # Story 15.2 (FR106) — raise a loud, self-contained {ChildrenNotSupportedError}
+    # on the FIRST PascalCase component tag used with children (a matching closing
+    # tag). +source+ is the ORIGINAL template text; +identifier+ is the template
+    # path (from {ErbPreprocessorHook}). Suspense — the one legitimate paired
+    # PascalCase tag — is masked newline-for-newline first, so it never trips AND
+    # every byte position (hence every reported line) still lines up with the raw
+    # template. The line uses the same idiom as Step 2 (`count("\n") + 1`) on the
+    # OPENING tag's offset. Message mirrors {ComponentContract.raise_error} shape
+    # so both loud preprocess errors read identically. A no-op when no pair is
+    # present — the fast path stays byte-identical.
+    def detect_children!(source, identifier)
+      # Fast path: a children pair REQUIRES a literal PascalCase closing tag, so
+      # a source without one (the common all-self-closing case) can never trip —
+      # bail before allocating anything. `match?` builds no MatchData, and this
+      # skips the mask/scan copies entirely, keeping the hot render/preprocess
+      # path's allocation profile flat (the benchmark renders only self-closing
+      # components, so it must stay at baseline).
+      return unless source.match?(CLOSING_TAG_PROBE_RE)
+
+      # ERB islands first, then Suspense — both blank their text newline-for-
+      # newline so byte offsets (hence reported lines) still match the raw
+      # template, while neither ERB string text nor the legitimate Suspense pair
+      # can be seen by the tag scan.
+      scan = mask_suspense(mask_erb(source))
+      # PER-NAME open stacks (name → [offsets]) so a closing tag checks for a
+      # matching open in O(1) via `open_ats[name].last`, keeping the whole scan
+      # linear even under thousands of stray/unmatched PascalCase closing tags
+      # (a global stack + `rindex` was quadratic — Codex Round 3).
+      open_ats = Hash.new { |h, k| h[k] = [] }
+
+      scan.scan(COMPONENT_ANY_TAG_RE) do
+        m    = ::Regexp.last_match
+        name = m[2]
+
+        if m[1] # a closing tag `</Name>`
+          at = open_ats[name].last
+          next unless at # stray close with no open → literal text, ignore
+
+          raise_children_error(name, identifier, scan, at)
+        elsif m[0].end_with?("/>") # self-closing → carries no children
+          next
+        else # an opening tag `<Name ...>` — record the NEAREST open of this name
+          open_ats[name] << m.begin(0)
+        end
+      end
+
+      nil
+    end
+
+    # Raise the self-contained {ChildrenNotSupportedError}. +at+ is the OPENING
+    # tag's byte offset in +scan+ (position-faithful to the raw source), so the
+    # line uses the same idiom as Step 2. Message mirrors
+    # {ComponentContract.raise_error} so both loud preprocess errors read alike.
+    def raise_children_error(component, identifier, scan, at)
+      line     = scan[0...at].count("\n") + 1
+      location = [identifier, line].compact.join(":")
+      location = "(unknown location)" if location.empty?
+      raise ChildrenNotSupportedError,
+            "ruact: <#{component}> at #{location} children are not supported " \
+            "— pass content as a prop, e.g. `<#{component} content={...} />`."
+    end
+
+    # Blank out Suspense open/close tags (the one legitimate paired PascalCase
+    # tag) while preserving EVERY newline and byte offset, so the loud-children
+    # scan neither trips on `<Suspense>...</Suspense>` nor mis-reports a line when
+    # a multi-line Suspense opening precedes the offending tag. Non-newline chars
+    # → spaces (same length); newlines kept verbatim.
+    def mask_suspense(source)
+      source
+        .gsub(SUSPENSE_OPEN_RE)  { |m| m.gsub(/[^\n]/, " ") }
+        .gsub(SUSPENSE_CLOSE_RE) { |m| m.gsub(/[^\n]/, " ") }
+    end
+
+    # Blank ERB islands (position-faithful, see {mask_suspense}) so component
+    # tags that appear only inside Ruby/ERB string or comment text are invisible
+    # to the loud-children tag scan.
+    def mask_erb(source)
+      source.gsub(ERB_ISLAND_RE) { |m| m.gsub(/[^\n]/, " ") }
+    end
+
     # Extract a string attribute value (double or single quoted) from an attrs string.
     def extract_string_attr(attrs, name)
       m = attrs.match(/\b#{Regexp.escape(name)}\s*=\s*"([^"]*)"/) ||

data/lib/ruact/errors.rb

@@ -22,6 +22,22 @@ module Ruact
   # re-wrapping it with the generic "at line N: snippet" tail.
   class ComponentContractError < PreprocessorError; end
 
+  # Story 15.2 (FR106) — raised by {Ruact::ErbPreprocessor} at preprocess time
+  # when a PascalCase component tag is used with children (a matching closing
+  # tag, e.g. `<Card>Hello</Card>`). ruact component tags are self-closing only:
+  # a component receives a props Hash, never a children element tree. This is the
+  # #1 predictable JSX-habit mistake, and it used to degrade silently (the
+  # children leaked into the surrounding HTML while the component rendered with
+  # none). Subclasses {PreprocessorError} so it flows through the same dev error
+  # overlay (NFR30 lineage) and the hook treats it uniformly — but the distinct
+  # class (mirroring {ComponentContractError}) lets the preprocessor re-raise it
+  # AS-IS (its message already carries the component name + file:line + the exact
+  # fix) and lets the 15.7 capstone assert this trap fails loudly by class. The
+  # sole legitimate paired PascalCase tag, `<Suspense>...</Suspense>`, is
+  # normalized to `<ruact-suspense>` in Step 1 before this detection runs, so it
+  # never trips.
+  class ChildrenNotSupportedError < PreprocessorError; end
+
   # Raised when application code attempts to mutate Ruact::Configuration outside
   # of a Ruact.configure block. The configuration is frozen after initialization
   # to prevent runtime drift; see Story 7.3 for the rationale and the decision

data/lib/ruact/manifest_resolver.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ruact
+  # Resolves the {Ruact::ClientManifest} to use for the current render /
+  # ERB-preprocess.
+  #
+  # PRODUCTION (unchanged): returns the boot-loaded +Ruact.manifest+ (set once by
+  # the Railtie's +config.to_prepare+; the Railtie raises at boot when the file is
+  # absent). No per-request I/O.
+  #
+  # DEVELOPMENT (the fix): the boot-time +to_prepare+ read of
+  # +public/react-client-manifest.json+ RACES the Vite dev server's first write —
+  # on a fresh app Rails can boot (and read the missing file) BEFORE Vite writes
+  # it, leaving +Ruact.manifest+ nil even though Vite is running and serving a
+  # current manifest. +public/+ is not watched, so +to_prepare+ never re-fires and
+  # the first request to a view with a component hits +nil.reference_for+ → 500.
+  #
+  # To kill that race, dev resolution fetches the LIVE manifest the Vite plugin
+  # serves in memory at +GET {vite_dev_server}/__ruact/manifest+ (always fresh,
+  # reflects HMR rebuilds), with graceful fallbacks:
+  #
+  #   1. HTTP fetch from the Vite dev server (short timeout).
+  #   2. Fallback: read +public/react-client-manifest.json+ from disk (the Vite
+  #      plugin still writes it — prod needs it for the build, and it is the
+  #      fallback when the dev server is down).
+  #   3. Neither available → a clear, actionable error (never a cryptic
+  #      +NoMethodError+ on nil).
+  #
+  # Memoization grain: the resolver fetches ONCE PER CALL. The two call sites each
+  # invoke it once per their scope and reuse the result for every component —
+  # +RenderPipeline+ holds the returned manifest in +@manifest+ for the whole
+  # render, and +ErbPreprocessor#transform+ resolves it lazily into a local that
+  # is reused across every tag in the template. So a render does NOT re-fetch per
+  # component (the bug was many +reference_for+ calls all needing a manifest); at
+  # most one fetch for the render and one for a (re)compiled template.
+  module ManifestResolver
+    DEV_MANIFEST_PATH = "/__ruact/manifest"
+    # Dev is localhost; fail fast to the file/clear-error fallback. A refused
+    # connection (Vite simply down) raises immediately, so this timeout only
+    # bounds the pathological "listening but not answering" case.
+    HTTP_OPEN_TIMEOUT = 1
+    HTTP_READ_TIMEOUT = 1
+
+    # Resolve the manifest for a render. In dev, raises a clear
+    # {Ruact::ManifestError} when neither the dev server nor the on-disk file is
+    # available. In any non-development environment, returns +Ruact.manifest+
+    # verbatim (production behaviour is untouched).
+    #
+    # @return [Ruact::ClientManifest, nil]
+    def self.resolve
+      return Ruact.manifest unless development?
+
+      dev_manifest(soft: false)
+    end
+
+    # Like {.resolve} but FAIL-OPEN in dev: returns +nil+ (rather than raising)
+    # when nothing is resolvable. Used by the ERB preprocessor's opt-in FR100
+    # contract validation, which is fail-open by design — a missing manifest must
+    # not crash template compilation; the render path then surfaces the clear
+    # error from {.resolve}.
+    #
+    # @return [Ruact::ClientManifest, nil]
+    def self.resolve_soft
+      return Ruact.manifest unless development?
+
+      dev_manifest(soft: true)
+    end
+
+    # @return [Ruact::ClientManifest, nil]
+    def self.dev_manifest(soft:)
+      manifest = fetch_over_http
+      return manifest if manifest
+
+      manifest = load_from_file
+      return manifest if manifest
+
+      return nil if soft
+
+      raise ManifestError, <<~MSG.strip
+        [ruact] Vite dev server unreachable at #{base_url} and no \
+        react-client-manifest.json found at #{file_path} — run `bin/dev`.
+      MSG
+    end
+
+    # Fetch + parse the live manifest from the Vite dev server, or +nil+ when the
+    # server is unreachable / returns a non-200 / unparseable body. Never raises:
+    # any failure degrades to the file fallback.
+    #
+    # @return [Ruact::ClientManifest, nil]
+    def self.fetch_over_http
+      require "net/http"
+      require "uri"
+
+      # `chomp("/")` so a base configured WITH a trailing slash
+      # ("http://localhost:5173/") does not yield a double-slashed
+      # "//__ruact/manifest" that misses the Vite middleware mount.
+      uri = URI.parse("#{base_url.chomp('/')}#{DEV_MANIFEST_PATH}")
+      response = Net::HTTP.start(
+        uri.host, uri.port,
+        use_ssl: uri.scheme == "https",
+        open_timeout: HTTP_OPEN_TIMEOUT, read_timeout: HTTP_READ_TIMEOUT
+      ) { |http| http.get(uri.request_uri) }
+
+      return nil unless response.is_a?(Net::HTTPSuccess)
+
+      ClientManifest.from_hash(JSON.parse(response.body))
+    rescue StandardError
+      nil
+    end
+
+    # Fallback: load the on-disk manifest the Vite plugin also writes, or +nil+
+    # when it is absent (the boot-race window) / unreadable.
+    #
+    # @return [Ruact::ClientManifest, nil]
+    def self.load_from_file
+      path = file_path
+      return nil unless path && File.exist?(path)
+
+      ClientManifest.load(path)
+    rescue StandardError
+      nil
+    end
+
+    # @return [String] the configured Vite dev-server base URL.
+    def self.base_url
+      Ruact.config.vite_dev_server
+    end
+
+    # @return [String, nil] the on-disk manifest path (config override or default).
+    def self.file_path
+      configured = Ruact.config.manifest_path
+      return configured.to_s if configured
+
+      return nil unless defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+
+      Rails.root.join("public", "react-client-manifest.json").to_s
+    end
+
+    # @return [Boolean] true only in a real Rails development environment. Any
+    #   other env (production, test, or no Rails at all) takes the untouched
+    #   +Ruact.manifest+ path.
+    def self.development?
+      defined?(Rails) && Rails.respond_to?(:env) && Rails.env.respond_to?(:development?) &&
+        Rails.env.development?
+    end
+  end
+end

data/lib/ruact/railtie.rb

@@ -100,9 +100,20 @@ module Ruact
     # Extracted as a class method for direct testability without a full Rails app.
     def self.check_vite!
       require "socket"
-      TCPSocket.new("localhost", 5173).close
-    rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH
-      Rails.logger.warn "[ruact] Vite dev server not detected at localhost:5173 " \
+      require "uri"
+      uri  = URI.parse(Ruact.config.vite_dev_server)
+      host = uri.host || "localhost"
+      port = uri.port || 5173
+      # `connect_timeout` so a blackholed/remote configured host can't stall dev
+      # boot from `after_initialize` until the OS TCP timeout (matches
+      # ViewHelper#vite_dev_running?).
+      TCPSocket.new(host, port, connect_timeout: 1).close
+    rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH, Errno::ETIMEDOUT, SocketError
+      # Broad rescue (incl. SocketError) because the host is now configurable: a
+      # misconfigured/unresolvable `vite_dev_server` must downgrade to this dev
+      # warning, never crash boot from `after_initialize`. `host`/`port` are
+      # assigned before the connect attempt, so they are always in scope here.
+      Rails.logger.warn "[ruact] Vite dev server not detected at #{host}:#{port} " \
                         "— run npm run dev for HMR"
     end
 

data/lib/ruact/render_pipeline.rb

@@ -166,7 +166,14 @@ module Ruact
     def render_erb_enum(erb_source, binding_context, streaming:)
       Enumerator.new do |y|
         render_context = RenderContext.new
-        transformed    = ErbPreprocessor.transform(erb_source)
+        # `registry: nil` → fail-open, no FR100 contract validation for this
+        # low-level programmatic render path (contract checking lives on the
+        # ActionView preprocessor hook used by real controllers). This keeps the
+        # path off `Ruact::ManifestResolver` entirely — historically it read the
+        # global `Ruact.manifest` (typically nil here, so already no validation),
+        # so passing nil is byte-for-byte equivalent while avoiding any dev HTTP
+        # fetch / test-double dispatch inside callers that measure this path.
+        transformed    = ErbPreprocessor.transform(erb_source, registry: nil)
         receiver       = binding_context.eval("self")
         prev_ctx       = receiver.instance_variable_get(:@__ruact_render_context__)
         inject_helper!(binding_context, render_context)

data/lib/ruact/serializable.rb

@@ -5,32 +5,71 @@ module Ruact
   # client component. Declare which attributes are safe to serialize with
   # +ruact_props+; only those attributes will be included in the wire payload.
   #
-  # @example
+  # Works on POROs and on ActiveRecord models alike. For a PORO the loud check
+  # fires at class-load; for an ActiveRecord model (whose attribute readers are
+  # defined lazily) the same loud check is deferred to the first
+  # +ruact_serialize+ — see {ClassMethods#ruact_props}.
+  #
+  # @example PORO
   #   class Post
   #     include Ruact::Serializable
   #     attr_reader :id, :title, :secret
   #     ruact_props :id, :title   # :secret is never sent to the client
   #   end
+  #
+  # @example ActiveRecord model
+  #   class Post < ApplicationRecord
+  #     include Ruact::Serializable
+  #     ruact_props :id, :title   # other columns never cross to the client
+  #   end
   module Serializable
     def self.included(base)
       base.extend(ClassMethods)
       base.instance_variable_set(:@ruact_props, [])
+      base.instance_variable_set(:@ruact_deferred_props, [])
     end
 
     module ClassMethods
       # Declare which instance methods should be included in the serialized
-      # payload. Raises +ArgumentError+ at class-load time if any name has no
-      # corresponding method defined on the class.
+      # payload.
+      #
+      # The loud-omission guarantee is preserved: a name with no corresponding
+      # method still raises a clean +ArgumentError+. Only the *timing* of that
+      # check depends on the class:
+      #
+      # * **PORO** — checked eagerly at class-load (macro-invocation) time, as
+      #   before. A typo'd/absent prop raises immediately.
+      # * **ActiveRecord model** — ActiveRecord defines its attribute reader
+      #   methods lazily (on first instance access), so at macro-invocation time
+      #   +method_defined?(:title)+ is +false+ even for a real column. Checking
+      #   eagerly would either reject a valid model at boot or require a live DB
+      #   connection at class-load (a Rails anti-pattern). So for a lazy-attribute
+      #   class the not-yet-defined names are recorded and their loud check is
+      #   deferred to the first +ruact_serialize+ (via +respond_to?+ on the
+      #   instance), where the DB is up. A genuine typo still raises the same
+      #   clean +ArgumentError+ — just at first render of that model, not at boot.
       #
       # @param attrs [Array<Symbol>]
+      # @raise [ArgumentError] immediately for an undefined prop on a PORO; at
+      #   first +ruact_serialize+ for an undefined prop on an ActiveRecord model.
       def ruact_props(*attrs)
+        deferred = []
         attrs.each do |attr|
-          unless method_defined?(attr)
-            raise ArgumentError,
-                  "ruact_props: method `#{attr}` is not defined on #{self}"
+          next if method_defined?(attr)
+
+          # Lazy-attribute (ActiveRecord) class: the reader may still appear on
+          # first instance access. Record it and check loudly on first serialize
+          # instead of failing a valid model at boot.
+          if ruact_lazy_attribute_class?
+            deferred << attr
+            next
           end
+
+          raise ArgumentError,
+                "ruact_props: method `#{attr}` is not defined on #{self}"
         end
         @ruact_props = attrs
+        @ruact_deferred_props = deferred
       end
 
       # Returns the list of declared prop names as symbols.
@@ -46,12 +85,65 @@ module Ruact
         end
         []
       end
+
+      # Names whose eager loud check was deferred to first serialize (lazy
+      # ActiveRecord attributes). Read from the same class that declared the
+      # props, so subclasses share the parent declaration.
+      #
+      # @return [Array<Symbol>]
+      def ruact_deferred_props_list
+        klass = self
+        while klass
+          if klass.instance_variable_defined?(:@ruact_props)
+            return klass.instance_variable_get(:@ruact_deferred_props) || []
+          end
+
+          klass = klass.superclass
+        end
+        []
+      end
+
+      # Run the deferred loud check once, on first +ruact_serialize+. A recorded
+      # name that the instance does not +respond_to?+ (a typo, or a genuinely
+      # absent column) raises the same clean +ArgumentError+ the eager path would.
+      #
+      # Memoization keys on the *validated deferred list itself* (not a bare
+      # boolean), so any change to the effective declaration — a re-declaration
+      # on this class OR on an ancestor whose props a subclass inherits — is
+      # detected and re-validated loudly on the next serialize. Once a given
+      # list has been validated it costs one array comparison per serialize.
+      #
+      # @param instance [Object]
+      # @raise [ArgumentError]
+      def ruact_validate_deferred_props!(instance)
+        deferred = ruact_deferred_props_list
+        return if @ruact_deferred_props_validated == deferred
+
+        deferred.each do |attr|
+          next if instance.respond_to?(attr)
+
+          raise ArgumentError,
+                "ruact_props: method `#{attr}` is not defined on #{self}"
+        end
+        @ruact_deferred_props_validated = deferred
+      end
+
+      # True when this class defines its attribute reader methods lazily, i.e.
+      # an ActiveRecord model. Detected WITHOUT a hard ActiveRecord dependency
+      # (the gem stays single-dep +nokogiri+): the constant is only referenced
+      # when it is already defined in the host.
+      #
+      # @return [Boolean]
+      def ruact_lazy_attribute_class?
+        !!(defined?(ActiveRecord::Base) && self < ActiveRecord::Base)
+      end
     end
 
     # Serialize only the attributes declared with +ruact_props+.
     #
     # @return [Hash{String => Object}]
     def ruact_serialize
+      self.class.ruact_validate_deferred_props!(self)
       self.class.ruact_props_list.to_h { |attr| [attr.to_s, public_send(attr)] }
     end
   end