rhales 0.3.0 → 0.4.0

data/lib/rhales/link_based_injection_detector.rb

@@ -0,0 +1,191 @@
+require 'strscan'
+require_relative 'safe_injection_validator'
+
+module Rhales
+  # Generates link-based hydration strategies that use browser resource hints
+  # and API endpoints instead of inline scripts
+  #
+  # ## Supported Strategies
+  #
+  # - **`:link`** - Basic link reference: `<link href="/api/hydration/template">`
+  # - **`:prefetch`** - Background prefetch: `<link rel="prefetch" href="..." as="fetch">`
+  # - **`:preload`** - High priority preload: `<link rel="preload" href="..." as="fetch">`
+  # - **`:modulepreload`** - ES module preload: `<link rel="modulepreload" href="..."`
+  # - **`:lazy`** - Lazy loading with intersection observer
+  #
+  # All strategies generate both link tags and accompanying JavaScript
+  # for data fetching and assignment to window objects.
+  class LinkBasedInjectionDetector
+    def initialize(hydration_config)
+      @hydration_config = hydration_config
+      @api_endpoint_path = hydration_config.api_endpoint_path || '/api/hydration'
+      @crossorigin_enabled = hydration_config.link_crossorigin.nil? ? true : hydration_config.link_crossorigin
+    end
+
+    def generate_for_strategy(strategy, template_name, window_attr, nonce = nil)
+      case strategy
+      when :link
+        generate_basic_link(template_name, window_attr, nonce)
+      when :prefetch
+        generate_prefetch_link(template_name, window_attr, nonce)
+      when :preload
+        generate_preload_link(template_name, window_attr, nonce)
+      when :modulepreload
+        generate_modulepreload_link(template_name, window_attr, nonce)
+      when :lazy
+        generate_lazy_loading(template_name, window_attr, nonce)
+      else
+        raise ArgumentError, "Unsupported link strategy: #{strategy}"
+      end
+    end
+
+    private
+
+    def generate_basic_link(template_name, window_attr, nonce)
+      endpoint_url = "#{@api_endpoint_path}/#{template_name}"
+
+      link_tag = %(<link href="#{endpoint_url}" type="application/json">)
+
+      script_tag = <<~HTML.strip
+        <script#{nonce_attribute(nonce)} data-hydration-target="#{window_attr}">
+        // Load hydration data for #{window_attr}
+        window.__rhales__ = window.__rhales__ || {};
+        if (!window.__rhales__.loadData) {
+          window.__rhales__.loadData = function(target, url) {
+            fetch(url)
+              .then(r => r.json())
+              .then(data => window[target] = data);
+          };
+        }
+        window.__rhales__.loadData('#{window_attr}', '#{endpoint_url}');
+        </script>
+      HTML
+
+      "#{link_tag}\n#{script_tag}"
+    end
+
+    def generate_prefetch_link(template_name, window_attr, nonce)
+      endpoint_url = "#{@api_endpoint_path}/#{template_name}"
+      crossorigin_attr = @crossorigin_enabled ? ' crossorigin' : ''
+
+      link_tag = %(<link rel="prefetch" href="#{endpoint_url}" as="fetch"#{crossorigin_attr}>)
+
+      script_tag = <<~HTML.strip
+        <script#{nonce_attribute(nonce)} data-hydration-target="#{window_attr}">
+        // Prefetch hydration data for #{window_attr}
+        window.__rhales__ = window.__rhales__ || {};
+        if (!window.__rhales__.loadPrefetched) {
+          window.__rhales__.loadPrefetched = function(target, url) {
+            fetch(url)
+              .then(r => r.json())
+              .then(data => window[target] = data);
+          };
+        }
+        window.__rhales__.loadPrefetched('#{window_attr}', '#{endpoint_url}');
+        </script>
+      HTML
+
+      "#{link_tag}\n#{script_tag}"
+    end
+
+    def generate_preload_link(template_name, window_attr, nonce)
+      endpoint_url = "#{@api_endpoint_path}/#{template_name}"
+      crossorigin_attr = @crossorigin_enabled ? ' crossorigin' : ''
+
+      link_tag = %(<link rel="preload" href="#{endpoint_url}" as="fetch"#{crossorigin_attr}>)
+
+      script_tag = <<~HTML.strip
+        <script#{nonce_attribute(nonce)} data-hydration-target="#{window_attr}">
+        // Preload strategy - high priority fetch
+        fetch('#{endpoint_url}')
+          .then(r => r.json())
+          .then(data => {
+            window['#{window_attr}'] = data;
+            // Dispatch ready event
+            window.dispatchEvent(new CustomEvent('rhales:hydrated', {
+              detail: { target: '#{window_attr}', data: data }
+            }));
+          })
+          .catch(err => console.error('Rhales hydration error:', err));
+        </script>
+      HTML
+
+      "#{link_tag}\n#{script_tag}"
+    end
+
+    def generate_modulepreload_link(template_name, window_attr, nonce)
+      endpoint_url = "#{@api_endpoint_path}/#{template_name}.js"
+
+      link_tag = %(<link rel="modulepreload" href="#{endpoint_url}">)
+
+      script_tag = <<~HTML.strip
+        <script type="module"#{nonce_attribute(nonce)} data-hydration-target="#{window_attr}">
+        // Module preload strategy
+        import data from '#{endpoint_url}';
+        window['#{window_attr}'] = data;
+
+        // Dispatch ready event
+        window.dispatchEvent(new CustomEvent('rhales:hydrated', {
+          detail: { target: '#{window_attr}', data: data }
+        }));
+        </script>
+      HTML
+
+      "#{link_tag}\n#{script_tag}"
+    end
+
+    def generate_lazy_loading(template_name, window_attr, nonce)
+      endpoint_url = "#{@api_endpoint_path}/#{template_name}"
+      mount_selector = @hydration_config.lazy_mount_selector || '#app'
+
+      # No link tag for lazy loading - purely script-driven
+      script_tag = <<~HTML.strip
+        <script#{nonce_attribute(nonce)} data-hydration-target="#{window_attr}" data-lazy-src="#{endpoint_url}">
+        // Lazy loading strategy with intersection observer
+        window.__rhales__ = window.__rhales__ || {};
+        window.__rhales__.initLazyLoading = function() {
+          const mountElement = document.querySelector('#{mount_selector}');
+          if (!mountElement) {
+            console.warn('Rhales: Mount element "#{mount_selector}" not found for lazy loading');
+            return;
+          }
+
+          const observer = new IntersectionObserver((entries) => {
+            entries.forEach(entry => {
+              if (entry.isIntersecting) {
+                fetch('#{endpoint_url}')
+                  .then(r => r.json())
+                  .then(data => {
+                    window['#{window_attr}'] = data;
+                    window.dispatchEvent(new CustomEvent('rhales:hydrated', {
+                      detail: { target: '#{window_attr}', data: data }
+                    }));
+                  })
+                  .catch(err => console.error('Rhales lazy hydration error:', err));
+
+                observer.unobserve(entry.target);
+              }
+            });
+          });
+
+          observer.observe(mountElement);
+        };
+
+        // Initialize when DOM is ready
+        if (document.readyState === 'loading') {
+          document.addEventListener('DOMContentLoaded', window.__rhales__.initLazyLoading);
+        } else {
+          window.__rhales__.initLazyLoading();
+        }
+        </script>
+      HTML
+
+      script_tag
+    end
+
+    def nonce_attribute(nonce)
+      require 'erb'
+      nonce ? " nonce=\"#{ERB::Util.html_escape(nonce)}\"" : ''
+    end
+  end
+end

data/lib/rhales/mount_point_detector.rb

@@ -0,0 +1,105 @@
+require 'strscan'
+require_relative 'safe_injection_validator'
+
+module Rhales
+  # Detects frontend application mount points in HTML templates
+  # Used to determine optimal hydration script injection points
+  #
+  # ## Mount Point Detection Order
+  #
+  # 1. **Selector Priority**: All selectors (default + custom) are checked in parallel
+  # 2. **Position Priority**: Returns the earliest mount point by position in HTML (not selector order)
+  # 3. **Safety Validation**: Validates injection points are outside unsafe contexts (scripts/styles/comments)
+  # 4. **Safe Position Search**: If original position unsafe, searches for nearest safe alternative:
+  #    - First tries positions before the mount point (maintains earlier injection)
+  #    - Then tries positions after the mount point (fallback)
+  #    - Returns nil if no safe position found
+  #
+  # Default selectors are checked: ['#app', '#root', '[data-rsfc-mount]', '[data-mount]']
+  # Custom selectors can be added via configuration and are combined with defaults.
+  class MountPointDetector
+    DEFAULT_SELECTORS = ['#app', '#root', '[data-rsfc-mount]', '[data-mount]'].freeze
+
+    def detect(template_html, custom_selectors = [])
+      selectors = (DEFAULT_SELECTORS + Array(custom_selectors)).uniq
+      scanner = StringScanner.new(template_html)
+      validator = SafeInjectionValidator.new(template_html)
+      mount_points = []
+
+      selectors.each do |selector|
+        scanner.pos = 0
+        pattern = build_pattern(selector)
+
+        while scanner.scan_until(pattern)
+          # Calculate position where the full tag starts
+          tag_start_pos = find_tag_start(scanner, template_html)
+
+          # Only include mount points that are safe for injection
+          safe_position = find_safe_injection_position(validator, tag_start_pos)
+
+          if safe_position
+            mount_points << {
+              selector: selector,
+              position: safe_position,
+              original_position: tag_start_pos,
+              matched: scanner.matched
+            }
+          end
+        end
+      end
+
+      # Return earliest mount point by position
+      mount_points.min_by { |mp| mp[:position] }
+    end
+
+    private
+
+    def build_pattern(selector)
+      case selector
+      when /^#(.+)$/
+        # ID selector: <tag id="value">
+        id_name = Regexp.escape($1)
+        /id\s*=\s*["']#{id_name}["']/i
+      when /^\.(.+)$/
+        # Class selector: <tag class="... value ...">
+        class_name = Regexp.escape($1)
+        /class\s*=\s*["'][^"']*\b#{class_name}\b[^"']*["']/i
+      when /^\[([^\]]+)\]$/
+        # Attribute selector: <tag data-attr> or <tag data-attr="value">
+        attr_name = Regexp.escape($1)
+        /#{attr_name}(?:\s*=\s*["'][^"']*["'])?/i
+      else
+        # Invalid selector, match nothing
+        /(?!.*)/
+      end
+    end
+
+    def find_tag_start(scanner, template_html)
+      # Work backwards from current position to find the opening <
+      pos = scanner.pos - scanner.matched.length
+
+      while pos > 0 && template_html[pos - 1] != '<'
+        pos -= 1
+      end
+
+      # Return position of the < character
+      pos > 0 ? pos - 1 : 0
+    end
+
+    def find_safe_injection_position(validator, preferred_position)
+      # First check if the preferred position is safe
+      return preferred_position if validator.safe_injection_point?(preferred_position)
+
+      # Try to find a safe position before the preferred position
+      safe_before = validator.nearest_safe_point_before(preferred_position)
+      return safe_before if safe_before
+
+      # As a last resort, try after the preferred position
+      safe_after = validator.nearest_safe_point_after(preferred_position)
+      return safe_after if safe_after
+
+      # No safe position found
+      nil
+    end
+  end
+end

data/lib/rhales/parsers/rue_format_parser.rb

@@ -28,12 +28,15 @@ module Rhales
   # handlebars_expression := '{{' expression '}}'
   class RueFormatParser
     # At least one of these sections must be present
-    REQUIRES_ONE_OF_SECTIONS = %w[data template].freeze
-    KNOWN_SECTIONS = %w[data template logic].freeze
-    ALL_SECTIONS = KNOWN_SECTIONS.freeze
+    unless defined?(REQUIRES_ONE_OF_SECTIONS)
+      REQUIRES_ONE_OF_SECTIONS = %w[data template].freeze
 
-    # Regular expression to match HTML/XML comments outside of sections
-    COMMENT_REGEX = /<!--.*?-->/m
+      KNOWN_SECTIONS = %w[data template logic].freeze
+      ALL_SECTIONS = KNOWN_SECTIONS.freeze
+
+      # Regular expression to match HTML/XML comments outside of sections
+      COMMENT_REGEX = /<!--.*?-->/m
+    end
 
     class ParseError < ::Rhales::ParseError
       def initialize(message, line: nil, column: nil, offset: nil)
@@ -145,7 +148,7 @@ module Rhales
     def parse_tag_name
       start_pos = @position
 
-      advance while !at_end? && current_char.match?(/[a-zA-Z]/)
+      advance while !at_end? && current_char.match?(/[a-zA-Z0-9_]/)
 
       if start_pos == @position
         parse_error('Expected tag name')
@@ -178,30 +181,42 @@ module Rhales
       attributes
     end
 
+    # Uses StringScanner to parse "content" in <section>content</section>
     def parse_section_content(tag_name)
-      start_pos     = @position
       content_start = @position
+      closing_tag = "</#{tag_name}>"
 
-      # Extract the raw content between section tags
-      raw_content = ''
-      while !at_end? && !peek_closing_tag?(tag_name)
-        raw_content << current_char
-        advance
-      end
+      # Create scanner from remaining content
+      scanner = StringScanner.new(@content[content_start..])
 
-      # For template sections, use HandlebarsParser to parse the content
-      if tag_name == 'template'
-        handlebars_parser = HandlebarsParser.new(raw_content)
-        handlebars_parser.parse!
-        handlebars_parser.ast.children
-      else
-        # For data and logic sections, keep as simple text
-        return [Node.new(:text, current_location, value: raw_content)] unless raw_content.empty?
+      # Find the closing tag position
+      if scanner.scan_until(/(?=#{Regexp.escape(closing_tag)})/)
+        # Calculate content length (scanner.charpos gives us position right before closing tag)
+        content_length = scanner.charpos
+        raw_content = @content[content_start, content_length]
 
-        []
+        # Advance position tracking to end of content
+        advance_to_position(content_start + content_length)
+
+        # Process content based on tag type
+        if tag_name == 'template'
+          handlebars_parser = HandlebarsParser.new(raw_content)
+          handlebars_parser.parse!
+          handlebars_parser.ast.children
+        else
+          # For data and logic sections, keep as simple text
+          raw_content.empty? ? [] : [Node.new(:text, current_location, value: raw_content)]
+        end
+      else
+        parse_error("Expected '#{closing_tag}' to close section")
       end
     end
 
+    # Add this helper method to advance position tracking to a specific offset
+    def advance_to_position(target_position)
+      advance while @position < target_position && !at_end?
+    end
+
     def parse_quoted_string
       quote_char = current_char
       unless ['"', "'"].include?(quote_char)
@@ -209,7 +224,7 @@ module Rhales
       end
 
       advance # Skip opening quote
-      value = ''
+      value = []
 
       while !at_end? && current_char != quote_char
         value << current_char
@@ -217,7 +232,11 @@ module Rhales
       end
 
       consume(quote_char) || parse_error('Unterminated quoted string')
-      value
+
+      # NOTE: Character-by-character parsing is acceptable here since attribute values
+      # in section tags (e.g., <tag attribute="value">) are typically short strings.
+      # Using StringScanner would be overkill for this use case.
+      value.join
     end
 
     def parse_identifier
@@ -350,8 +369,6 @@ module Rhales
       result_parts.join
     end
 
-    private
-
     # Tokenize content into structured tokens for pattern matching
     # Uses StringScanner for better performance and cleaner code
     def tokenize_content(content)
@@ -359,23 +376,23 @@ module Rhales
       tokens = []
 
       until scanner.eos?
-        case
+        tokens << case
         when scanner.scan(/<!--.*?-->/m)
           # Comment token - non-greedy match for complete comments
-          tokens << { type: :comment, content: scanner.matched }
+          { type: :comment, content: scanner.matched }
         when scanner.scan(/<(data|template|logic)(\s[^>]*)?>/m)
           # Section start token - matches opening tags with optional attributes
-          tokens << { type: :section_start, content: scanner.matched }
-        when scanner.scan(/<\/(data|template|logic)>/m)
+          { type: :section_start, content: scanner.matched }
+        when scanner.scan(%r{</(data|template|logic)>}m)
           # Section end token - matches closing tags
-          tokens << { type: :section_end, content: scanner.matched }
+          { type: :section_end, content: scanner.matched }
         when scanner.scan(/[^<]+/)
           # Text token - consolidates runs of non-< characters for efficiency
-          tokens << { type: :text, content: scanner.matched }
+          { type: :text, content: scanner.matched }
         else
           # Fallback for single characters (< that don't match patterns)
           # This maintains compatibility with the original character-by-character behavior
-          tokens << { type: :text, content: scanner.getch }
+          { type: :text, content: scanner.getch }
         end
       end
 

data/lib/rhales/refinements/require_refinements.rb

@@ -111,11 +111,7 @@ module Rhales
 
         parser
       rescue StandardError => ex
-        if defined?(OT) && OT.respond_to?(:le)
-          OT.le "[RSFC] Failed to process .rue file #{path}: #{ex.message}"
-        else
-          puts "[RSFC] Failed to process .rue file #{path}: #{ex.message}"
-        end
+        puts "[RSFC] Failed to process .rue file #{path}: #{ex.message}"
         raise
       end
 
@@ -130,7 +126,7 @@ module Rhales
         return File.expand_path(path) if File.exist?(path)
 
         # Search in templates directory
-        boot_root      = defined?(OT) && OT.respond_to?(:boot_root) ? OT.boot_root : File.expand_path('../../..', __dir__)
+        boot_root      = File.expand_path('../../..', __dir__)
         templates_path = File.join(boot_root, 'templates', path)
         return templates_path if File.exist?(templates_path)
 
@@ -197,9 +193,7 @@ module Rhales
               current_mtime = File.mtime(full_path)
 
               if current_mtime > last_mtime
-                if defined?(OT) && OT.respond_to?(:ld)
-                  OT.ld "[RSFC] File changed, clearing cache: #{full_path}"
-                end
+                puts "[RSFC] File changed, clearing cache: #{full_path}"
 
                 # Thread-safe cache removal
                 Rhales::Ruequire.instance_variable_get(:@cache_mutex).synchronize do
@@ -210,9 +204,7 @@ module Rhales
               end
             rescue StandardError => ex
               # File might have been deleted
-              if defined?(OT) && OT.respond_to?(:ld)
-                OT.ld "[RSFC] File watcher error for #{full_path}: #{ex.message}"
-              end
+              puts "[RSFC] File watcher error for #{full_path}: #{ex.message}"
 
               # Clean up watcher entry on error
               watchers_mutex.synchronize do

data/lib/rhales/rue_document.rb

@@ -163,11 +163,11 @@ module Rhales
 
     private
 
-    def extract_partials_from_node(node, partials)
+    def extract_partials_from_node(_node, partials)
       return unless @ast
 
       # Extract from all sections
-      @grammar.sections.each do |section_name, section_node|
+      @grammar.sections.each do |_section_name, section_node|
         content_nodes = section_node.value[:content]
         next unless content_nodes.is_a?(Array)
 
@@ -243,8 +243,6 @@ module Rhales
       end
     end
 
-    private
-
     def extract_variables_from_text(text, variables, exclude_partials: false)
       # Find all handlebars expressions in text content
       text.scan(/\{\{(.+?)\}\}/) do |match|
@@ -284,7 +282,7 @@ module Rhales
     end
 
     def warn_unknown_attribute(attribute)
-      file_info = @file_path ? " in #{@file_path}" : ""
+      file_info = @file_path ? " in #{@file_path}" : ''
       warn "Warning: data section encountered '#{attribute}' attribute - not yet supported, ignoring#{file_info}"
     end
 

data/lib/rhales/safe_injection_validator.rb

@@ -0,0 +1,99 @@
+require 'strscan'
+
+module Rhales
+  # Validates whether a hydration injection point is safe within HTML context
+  # Prevents injection inside script tags, style tags, comments, or other unsafe locations
+  class SafeInjectionValidator
+    UNSAFE_CONTEXTS = [
+      { start: /<script\b[^>]*>/i, end: /<\/script>/i },
+      { start: /<style\b[^>]*>/i, end: /<\/style>/i },
+      { start: /<!--/, end: /-->/ },
+      { start: /<!\[CDATA\[/, end: /\]\]>/ }
+    ].freeze
+
+    def initialize(html)
+      @html = html
+      @unsafe_ranges = calculate_unsafe_ranges
+    end
+
+    # Check if the given position is safe for injection
+    def safe_injection_point?(position)
+      return false if position < 0 || position > @html.length
+
+      # Check if position falls within any unsafe range
+      @unsafe_ranges.none? { |range| range.cover?(position) }
+    end
+
+    # Find the nearest safe injection point before the given position
+    def nearest_safe_point_before(position)
+      # Work backwards from position to find a safe point
+      (0...position).reverse_each do |pos|
+        return pos if safe_injection_point?(pos) && at_tag_boundary?(pos)
+      end
+
+      # If no safe point found before, return nil
+      nil
+    end
+
+    # Find the nearest safe injection point after the given position
+    def nearest_safe_point_after(position)
+      # Work forwards from position to find a safe point
+      (position...@html.length).each do |pos|
+        return pos if safe_injection_point?(pos) && at_tag_boundary?(pos)
+      end
+
+      # If no safe point found after, return nil
+      nil
+    end
+
+    private
+
+    def calculate_unsafe_ranges
+      ranges = []
+      scanner = StringScanner.new(@html)
+
+      UNSAFE_CONTEXTS.each do |context|
+        scanner.pos = 0
+
+        while scanner.scan_until(context[:start])
+          start_pos = scanner.pos - scanner.matched.length
+
+          # Find the corresponding end tag
+          if scanner.scan_until(context[:end])
+            end_pos = scanner.pos
+            ranges << (start_pos...end_pos)
+          else
+            # If no closing tag found, consider rest of document unsafe
+            ranges << (start_pos...@html.length)
+            break
+          end
+        end
+      end
+
+      ranges
+    end
+
+    # Check if position is at a tag boundary (before < or after >)
+    def at_tag_boundary?(position)
+      return true if position == 0 || position == @html.length
+
+      char_before = position > 0 ? @html[position - 1] : nil
+      char_at = @html[position]
+
+      # Safe positions:
+      # - Right after a closing >
+      # - Right before an opening <
+      # - At whitespace boundaries between tags
+      char_before == '>' || char_at == '<' || (char_at&.match?(/\s/) && next_non_whitespace_is_tag?(position))
+    end
+
+    def next_non_whitespace_is_tag?(position)
+      pos = position
+      while pos < @html.length && @html[pos].match?(/\s/)
+        pos += 1
+      end
+
+      pos < @html.length && @html[pos] == '<'
+    end
+  end
+end