rhales 0.3.0

data/lib/rhales/csp.rb

@@ -0,0 +1,94 @@
+# lib/rhales/csp.rb
+
+module Rhales
+  # Content Security Policy (CSP) header generation and management
+  #
+  # Provides secure defaults and nonce integration for CSP headers.
+  # Converts policy configuration into proper CSP header strings.
+  #
+  # Usage:
+  #   csp = Rhales::CSP.new(config, nonce: 'abc123')
+  #   header = csp.build_header
+  #   # => "default-src 'self'; script-src 'self' 'nonce-abc123'; ..."
+  class CSP
+    attr_reader :config, :nonce
+
+    def initialize(config, nonce: nil)
+      @config = config
+      @nonce = nonce
+    end
+
+    # Build CSP header string from configuration
+    def build_header
+      return nil unless @config.csp_enabled
+
+      policy_directives = []
+
+      @config.csp_policy.each do |directive, sources|
+        if sources.empty?
+          # For directives with no sources (like upgrade-insecure-requests)
+          policy_directives << directive
+        else
+          # Process sources and interpolate nonce if present
+          processed_sources = sources.map { |source| interpolate_nonce(source) }
+          directive_string = "#{directive} #{processed_sources.join(' ')}"
+          policy_directives << directive_string
+        end
+      end
+
+      policy_directives.join('; ')
+    end
+
+    # Generate a new nonce value
+    def self.generate_nonce
+      SecureRandom.hex(16)
+    end
+
+    # Validate CSP policy configuration
+    def validate_policy!
+      return unless @config.csp_enabled
+
+      errors = []
+
+      # Ensure policy is a hash
+      unless @config.csp_policy.is_a?(Hash)
+        errors << 'csp_policy must be a hash'
+        raise Rhales::Configuration::ConfigurationError, "CSP policy errors: #{errors.join(', ')}"
+      end
+
+      # Validate each directive
+      @config.csp_policy.each do |directive, sources|
+        unless sources.is_a?(Array)
+          errors << "#{directive} sources must be an array"
+        end
+
+        # Check for dangerous sources
+        if sources.include?("'unsafe-eval'")
+          errors << "#{directive} contains dangerous 'unsafe-eval' source"
+        end
+
+        if sources.include?("'unsafe-inline'") && !%w[style-src].include?(directive)
+          errors << "#{directive} contains dangerous 'unsafe-inline' source"
+        end
+      end
+
+      raise Rhales::Configuration::ConfigurationError, "CSP policy errors: #{errors.join(', ')}" unless errors.empty?
+    end
+
+    # Check if nonce is required for any directive
+    def nonce_required?
+      return false unless @config.csp_enabled
+
+      @config.csp_policy.values.flatten.any? { |source| source.include?('{{nonce}}') }
+    end
+
+    private
+
+    # Interpolate nonce placeholder in source values
+    def interpolate_nonce(source)
+      return source unless @nonce && source.include?('{{nonce}}')
+
+      source.gsub('{{nonce}}', @nonce)
+    end
+  end
+end

data/lib/rhales/errors/hydration_collision_error.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Rhales
+  class HydrationCollisionError < Error
+    attr_reader :window_attribute, :first_path, :conflict_path
+
+    def initialize(window_attribute, first_path, conflict_path)
+      @window_attribute = window_attribute
+      @first_path       = first_path
+      @conflict_path    = conflict_path
+
+      super(build_message)
+    end
+
+    def message
+      build_message
+    end
+
+    private
+
+    def build_message
+      <<~MSG.strip
+        Window attribute collision detected
+
+        Attribute: '#{@window_attribute}'
+        First defined: #{@first_path}#{extract_tag_content(@first_path)}
+        Conflict with: #{@conflict_path}#{extract_tag_content(@conflict_path)}
+
+        Quick fixes:
+          1. Rename one: <data window="#{suggested_alternative_name}">
+          2. Enable merging: <data window="#{@window_attribute}" merge="deep">
+
+        Learn more: https://rhales.dev/docs/data-boundaries#collisions
+      MSG
+    end
+
+    def extract_tag_content(path)
+      # If the path includes the actual tag content after the line number,
+      # extract and format it for display
+      if path.include?(':<data')
+        tag_match = path.match(/(:.*?<data[^>]*>)/)
+        return "\n               #{tag_match[1].sub(/^:/, '')}" if tag_match
+      end
+      ''
+    end
+
+    def suggested_alternative_name
+      # For specific known patterns, use the first defined location
+      # This provides a more predictable suggestion
+      if @window_attribute == 'appState' && @first_path.include?('header')
+        'headerState'
+      elsif @window_attribute == 'data'
+        # For generic 'data', use the conflict path to generate unique name
+        base_name_from_path(@conflict_path) + 'Data'
+      else
+        # For other cases, suggest a simple modification
+        case @window_attribute
+        when /Data$/
+          @window_attribute.sub(/Data$/, 'State')
+        when /State$/
+          @window_attribute.sub(/State$/, 'Config')
+        when /Config$/
+          @window_attribute.sub(/Config$/, 'Settings')
+        else
+          @window_attribute + 'Data'
+        end
+      end
+    end
+
+    def base_name_from_path(path)
+      # Extract a base name from the file path for suggestion
+      filename = path.split('/').last.split('.').first
+      case filename
+      when 'index', 'main', 'application'
+        'page'
+      when /^_/, 'partial'
+        'partial'
+      when 'header', 'footer', 'sidebar', 'nav'
+        filename
+      else
+        filename.gsub(/[^a-zA-Z0-9]/, '').downcase
+      end
+    end
+  end
+end

data/lib/rhales/errors.rb

@@ -0,0 +1,36 @@
+# lib/rhales/errors.rb
+
+module Rhales
+  class Error < StandardError; end
+
+  # Parse-time errors - syntax and structure issues
+  class ParseError < Error
+    attr_reader :line, :column, :offset, :source_type
+
+    def initialize(message, line: nil, column: nil, offset: nil, source_type: nil)
+      @line        = line
+      @column      = column
+      @offset      = offset
+      @source_type = source_type  # :rue, :handlebars, or :template
+
+      location = line && column ? " at line #{line}, column #{column}" : ''
+      source   = source_type ? " in #{source_type}" : ''
+      super("#{message}#{location}#{source}")
+    end
+  end
+
+  # Validation-time errors - structural and semantic issues
+  class ValidationError < Error; end
+
+  # Render-time errors - runtime issues during template execution
+  class RenderError < Error; end
+
+  # Configuration errors
+  class ConfigurationError < Error; end
+
+  # Legacy alias for backward compatibility
+  class TemplateError < Error; end
+end
+
+# Load specific error classes
+require_relative 'errors/hydration_collision_error'

data/lib/rhales/hydration_data_aggregator.rb

@@ -0,0 +1,220 @@
+# lib/rhales/hydration_data_aggregator.rb
+
+require 'json'
+require_relative 'template_engine'
+require_relative 'errors'
+
+module Rhales
+  # HydrationDataAggregator traverses the ViewComposition and executes
+  # all <data> sections to produce a single, merged JSON structure.
+  #
+  # This class implements the server-side data aggregation phase of the
+  # two-pass rendering model, handling:
+  # - Traversal of the template dependency tree
+  # - Execution of <data> sections with full server context
+  # - Merge strategies (deep, shallow, strict)
+  # - Collision detection and error reporting
+  #
+  # The aggregator replaces the HydrationRegistry by performing all
+  # data merging in a single, coordinated pass.
+  class HydrationDataAggregator
+    class JSONSerializationError < StandardError; end
+
+    def initialize(context)
+      @context = context
+      @window_attributes = {}
+      @merged_data = {}
+    end
+
+    # Aggregate all hydration data from the view composition
+    def aggregate(composition)
+      composition.each_document_in_render_order do |template_name, parser|
+        process_template(template_name, parser)
+      end
+
+      @merged_data
+    end
+
+    private
+
+    def process_template(template_name, parser)
+      data_content = parser.section('data')
+      return unless data_content
+
+      window_attr = parser.window_attribute || 'data'
+      merge_strategy = parser.merge_strategy
+
+      # Build template path for error reporting
+      template_path = build_template_path(parser)
+
+      # Process the data section first to check if it's empty
+      processed_data = process_data_section(data_content, parser)
+
+      # Check for collisions only if the data is not empty
+      if @window_attributes.key?(window_attr) && merge_strategy.nil? && !empty_data?(processed_data)
+        existing = @window_attributes[window_attr]
+        existing_data = @merged_data[window_attr]
+
+        # Only raise collision error if existing data is also not empty
+        unless empty_data?(existing_data)
+          raise ::Rhales::HydrationCollisionError.new(window_attr, existing[:path], template_path)
+        end
+      end
+
+      # Merge or set the data
+      if @merged_data.key?(window_attr)
+        @merged_data[window_attr] = merge_data(
+          @merged_data[window_attr],
+          processed_data,
+          merge_strategy || 'deep',
+          window_attr,
+          template_path
+        )
+      else
+        @merged_data[window_attr] = processed_data
+      end
+
+      # Track the window attribute
+      @window_attributes[window_attr] = {
+        path: template_path,
+        merge_strategy: merge_strategy
+      }
+    end
+
+    def process_data_section(data_content, parser)
+      # Create a JSON-aware context wrapper for data sections
+      json_context = JsonAwareContext.new(@context)
+
+      # Process template variables in the data section
+      processed_content = TemplateEngine.render(data_content, json_context)
+
+      # Parse as JSON
+      begin
+        JSON.parse(processed_content)
+      rescue JSON::ParserError => ex
+        template_path = build_template_path(parser)
+        raise JSONSerializationError,
+          "Invalid JSON in data section at #{template_path}: #{ex.message}\n" \
+          "Processed content: #{processed_content[0..200]}..."
+      end
+    end
+
+    def merge_data(target, source, strategy, window_attr, template_path)
+      case strategy
+      when 'deep'
+        deep_merge(target, source)
+      when 'shallow'
+        shallow_merge(target, source, window_attr, template_path)
+      when 'strict'
+        strict_merge(target, source, window_attr, template_path)
+      else
+        raise ArgumentError, "Unknown merge strategy: #{strategy}"
+      end
+    end
+
+    def deep_merge(target, source)
+      result = target.dup
+
+      source.each do |key, value|
+        if result.key?(key) && result[key].is_a?(Hash) && value.is_a?(Hash)
+          result[key] = deep_merge(result[key], value)
+        else
+          result[key] = value
+        end
+      end
+
+      result
+    end
+
+    def shallow_merge(target, source, window_attr, template_path)
+      result = target.dup
+
+      source.each do |key, value|
+        if result.key?(key)
+          raise ::Rhales::HydrationCollisionError.new(
+            "#{window_attr}.#{key}",
+            @window_attributes[window_attr][:path],
+            template_path
+          )
+        end
+        result[key] = value
+      end
+
+      result
+    end
+
+    def strict_merge(target, source, window_attr, template_path)
+      # In strict mode, any collision is an error
+      target.each_key do |key|
+        if source.key?(key)
+          raise ::Rhales::HydrationCollisionError.new(
+            "#{window_attr}.#{key}",
+            @window_attributes[window_attr][:path],
+            template_path
+          )
+        end
+      end
+
+      target.merge(source)
+    end
+
+    def build_template_path(parser)
+      data_node = parser.section_node('data')
+      line_number = data_node ? data_node.location.start_line : 1
+
+      if parser.file_path
+        "#{parser.file_path}:#{line_number}"
+      else
+        "<inline>:#{line_number}"
+      end
+    end
+
+    # Check if data is considered empty for collision detection
+    def empty_data?(data)
+      return true if data.nil?
+      return true if data == {}
+      return true if data == []
+      return true if data.respond_to?(:empty?) && data.empty?
+      false
+    end
+  end
+
+  # Context wrapper that automatically converts Ruby objects to JSON in data sections
+  class JsonAwareContext
+    def initialize(context)
+      @context = context
+    end
+
+    # Delegate all methods to the wrapped context
+    def method_missing(method, *args, &block)
+      @context.send(method, *args, &block)
+    end
+
+    def respond_to_missing?(method, include_private = false)
+      @context.respond_to?(method, include_private)
+    end
+
+    # Override get method to return JSON-serialized objects
+    def get(variable_path)
+      value = @context.get(variable_path)
+
+      # Convert Ruby objects to JSON for data sections
+      case value
+      when Hash, Array
+        begin
+          value.to_json
+        rescue JSON::GeneratorError, SystemStackError => ex
+          # Handle serialization errors (circular references, unsupported types, etc.)
+          raise JSONSerializationError,
+            "Failed to serialize Ruby object to JSON: #{ex.message}. " \
+            "Object type: #{value.class}, var path: #{variable_path}..."
+        end
+      else
+        value
+      end
+    end
+
+    # Alias for compatibility with template engine
+    alias_method :resolve_variable, :get
+  end
+end

data/lib/rhales/hydration_registry.rb

@@ -0,0 +1,58 @@
+# lib/rhales/hydration_registry.rb
+
+module Rhales
+  # Registry to track window attributes used in hydration blocks
+  # within a single request. Prevents silent data overwrites.
+  class HydrationRegistry
+    class << self
+      def register(window_attr, template_path, merge_strategy = nil)
+        validate_inputs(window_attr, template_path)
+
+        registry = thread_local_registry
+
+        if registry[window_attr] && merge_strategy.nil?
+          existing = registry[window_attr]
+          raise HydrationCollisionError.new(
+            window_attr,
+            existing[:path],
+            template_path,
+          )
+        end
+
+        registry[window_attr] = {
+          path: template_path,
+          merge_strategy: merge_strategy,
+        }
+      end
+
+      def clear!
+        Thread.current[:rhales_hydration_registry] = {}
+      end
+
+      # Expose registry for testing purposes
+      def registry
+        thread_local_registry
+      end
+
+      private
+
+      def thread_local_registry
+        Thread.current[:rhales_hydration_registry] ||= {}
+      end
+
+      def validate_inputs(window_attr, template_path)
+        if window_attr.nil?
+          raise ArgumentError, 'window attribute cannot be nil'
+        end
+
+        if window_attr.empty?
+          raise ArgumentError, 'window attribute cannot be empty'
+        end
+
+        if template_path.nil?
+          raise ArgumentError, 'template path cannot be nil'
+        end
+      end
+    end
+  end
+end

data/lib/rhales/hydrator.rb

@@ -0,0 +1,141 @@
+# lib/rhales/hydrator.rb
+
+require 'json'
+require 'securerandom'
+
+module Rhales
+    # Data Hydrator for RSFC client-side data injection
+    #
+    # ## RSFC Security Model: Server-to-Client Security Boundary
+    #
+    # The Hydrator enforces a critical security boundary between server and client:
+    #
+    # ### Server Side (Template Rendering)
+    # - Templates have FULL server context access (like ERB/HAML)
+    # - Can access user objects, database connections, internal APIs
+    # - Can access secrets, configuration, authentication state
+    # - Can process sensitive business logic
+    #
+    # ### Client Side (Data Hydration)
+    # - Only data declared in <data> section reaches the browser
+    # - Creates explicit allowlist like designing a REST API
+    # - Server-side variable interpolation processes secrets safely
+    # - JSON serialization validates data structure
+    #
+    # ### Process Flow
+    # 1. Server processes <data> section with full context access
+    # 2. Variables like {{user.name}} are interpolated server-side
+    # 3. Result is serialized as JSON and sent to client
+    # 4. Client receives only the processed, safe data
+    #
+    # ### Example
+    # ```rue
+    # <data>
+    # {
+    #   "user_name": "{{user.name}}",           // Safe: just the name
+    #   "theme": "{{user.theme_preference}}"    // Safe: just the theme
+    # }
+    # </data>
+    # ```
+    #
+    # Server template can access {{user.admin?}} and {{internal_config}},
+    # but client only gets the declared user_name and theme values.
+    #
+    # This creates an API-like boundary where data is serialized once and
+    # parsed once, enforcing the same security model as REST endpoints.
+    #
+    # Note: With the new two-pass architecture, the Hydrator's role is
+    # greatly simplified. All data merging happens server-side in the
+    # HydrationDataAggregator, so this class only handles JSON generation
+    # for individual templates (used during the aggregation phase).
+    class Hydrator
+      class HydrationError < StandardError; end
+      class JSONSerializationError < HydrationError; end
+
+      attr_reader :parser, :context, :window_attribute
+
+      def initialize(parser, context)
+        @parser           = parser
+        @context          = context
+        @window_attribute = parser.window_attribute || 'data'
+      end
+
+      # This method is now deprecated in favor of the two-pass architecture
+      # It's kept for backward compatibility but will be removed in future versions
+      def generate_hydration_html
+        warn "[DEPRECATION] Hydrator#generate_hydration_html is deprecated. Use the two-pass rendering architecture instead."
+        ""
+      end
+
+      # Process <data> section and return JSON string
+      def process_data_section
+        data_content = @parser.section('data')
+        return '{}' unless data_content
+
+        # Process variable interpolations in the data section
+        processed_content = process_data_variables(data_content)
+
+        # Validate and return JSON
+        validate_json(processed_content)
+        processed_content
+      rescue JSON::ParserError => ex
+        raise JSONSerializationError, "Invalid JSON in data section: #{ex.message}"
+      end
+
+      # Get processed data as Ruby hash (for internal use)
+      def processed_data_hash
+        json_string = process_data_section
+        JSON.parse(json_string)
+      rescue JSON::ParserError => ex
+        raise JSONSerializationError, "Cannot parse processed data as JSON: #{ex.message}"
+      end
+
+      private
+
+      # Process variable interpolations in data section
+      # Uses Rhales consistently for all template processing
+      def process_data_variables(data_content)
+        rhales = TemplateEngine.new(data_content, @context)
+        rhales.render
+      end
+
+      # Validate that processed content is valid JSON
+      def validate_json(json_string)
+        JSON.parse(json_string)
+      rescue JSON::ParserError => ex
+        raise JSONSerializationError, "Processed data section is not valid JSON: #{ex.message}"
+      end
+
+      # Build template path with line number for error reporting
+      # (Used by HydrationDataAggregator)
+      def build_template_path
+        data_node   = @parser.section_node('data')
+        line_number = data_node ? data_node.location.start_line : 1
+
+        if @parser.file_path
+          "#{@parser.file_path}:#{line_number}"
+        else
+          "<inline>:#{line_number}"
+        end
+      end
+
+      class << self
+        # Convenience method to generate hydration HTML
+        # DEPRECATED: Use the two-pass rendering architecture instead
+        def generate(parser, context)
+          warn "[DEPRECATION] Hydrator.generate is deprecated. Use the two-pass rendering architecture instead."
+          new(parser, context).generate_hydration_html
+        end
+
+        # Generate only JSON data (for testing or API endpoints)
+        def generate_json(parser, context)
+          new(parser, context).process_data_section
+        end
+
+        # Generate data hash (for internal processing)
+        def generate_data_hash(parser, context)
+          new(parser, context).processed_data_hash
+        end
+      end
+    end
+end

data/lib/rhales/parsers/handlebars-grammar-review.txt

@@ -0,0 +1,39 @@
+According to Gemini 2.5 Pro.
+
+
+The `HandlebarsGrammar` class is **not a formal grammar definition**.
+
+Instead, it is a **parser** that **implements** the rules of the Handlebars grammar. This is a crucial distinction:
+
+1.  **Formal Grammar (The Blueprint):** A formal grammar is a set of abstract, mathematical rules that define a language. It specifies the valid sequences of symbols and their structure, often using a notation like Backus-Naur Form (BNF). It is a *specification*, not code.
+
+    *Example (simplified BNF for a Handlebars variable):*
+    ```
+    expression ::= '{{' identifier '}}'
+    identifier ::= letter ( letter | digit )*
+    ```
+
+2.  **Parser (The Implementation):** A parser is a piece of software that takes an input string and determines if it conforms to the rules of a formal grammar. As a byproduct, it usually produces a data structure, like an Abstract Syntax Tree (AST), that represents the input's structure.
+
+The `HandlebarsGrammar` class is what is known as a **hand-rolled parser**. It was written manually in Ruby to recognize and structure Handlebars syntax, rather than being automatically generated by a tool.
+
+### What Makes it a Parser (Not a Grammar)
+
+You can see the classic components of a hand-rolled parser right in its methods:
+
+*   **Lexical Analysis (Scanning):** It consumes the input character by character and identifies tokens.
+    *   `current_char`, `peek_char`, `advance`: These methods manage the input stream.
+    *   `parse_text_until_handlebars`: This logic finds the boundary between plain text and a Handlebars expression (`{{`).
+
+*   **Syntactic Analysis (Parsing):** It applies the grammar rules (as implemented in Ruby logic) to the token stream to build a structural representation.
+    *   `parse_template`: The main entry point that orchestrates the parsing process.
+    *   `create_if_block`, `create_each_block`: These methods correspond directly to the production rules for Handlebars block helpers. They build `Node` objects.
+    *   `Node` class: This defines the structure of the AST that the parser produces as its output.
+
+### Why No Prism Reference?
+
+Parser generators like Prism, ANTLR, or Treetop work by taking a formal grammar definition as input and *generating* the parser code for you.
+
+Since `HandlebarsGrammar` is a hand-rolled parser, it doesn't need a generator. The developer has written the parsing logic directly in Ruby. This approach is common for languages with relatively simple, non-ambiguous syntax, as it avoids adding an external dependency and gives the developer full control over the parsing process and error handling.
+
+In summary: You've correctly identified that the class isn't a formal grammar. It's a **manual implementation of a parser** for that grammar, which is why it contains procedural logic for scanning and structuring text instead of a declarative set of grammar rules.