rhales 0.3.0 → 0.5.3

data/lib/rhales/context.rb

@@ -1,240 +0,0 @@
-# lib/rhales/context.rb
-
-require_relative 'configuration'
-require_relative 'adapters/base_auth'
-require_relative 'adapters/base_session'
-require_relative 'adapters/base_request'
-require_relative 'csp'
-
-module Rhales
-    # RSFCContext provides a clean interface for RSFC templates to access
-    # server-side data. Follows the established pattern from InitScriptContext
-    # and EnvironmentContext for focused, single-responsibility context objects.
-    #
-    # The context provides two layers of data:
-    # 1. App: Framework-provided data (CSRF tokens, authentication, config)
-    # 2. Props: Application data passed to the view (user, content, features)
-    #
-    # App data is accessible as both direct variables and through the app.* namespace.
-    # Props take precedence over app data for variable resolution.
-    #
-    # One RSFCContext instance is created per page render and shared across
-    # the main template and all partials to maintain security boundaries.
-    class Context
-      attr_reader :req, :sess, :cust, :locale, :props, :config, :app_data
-
-      def initialize(req, sess = nil, cust = nil, locale_override = nil, props: {}, config: nil)
-        @req           = req
-        @sess          = sess || default_session
-        @cust          = cust || default_customer
-        @config        = config || Rhales.configuration
-        @locale        = locale_override || @config.default_locale
-
-        # Normalize props keys to strings for consistent access
-        @props = normalize_keys(props).freeze
-
-        # Build context layers (two-layer model: app + props)
-        @app_data = build_app_data.freeze
-
-        # Pre-compute all_data before freezing
-        # Props take precedence over app data, and add app namespace
-        @all_data = @app_data.merge(@props).merge({ 'app' => @app_data }).freeze
-
-        # Make context immutable after creation
-        freeze
-      end
-
-      # Get variable value with dot notation support (e.g., "user.id", "features.account_creation")
-      def get(variable_path)
-        path_parts    = variable_path.split('.')
-        current_value = all_data
-
-        path_parts.each do |part|
-          case current_value
-          when Hash
-            if current_value.key?(part)
-              current_value = current_value[part]
-            elsif current_value.key?(part.to_sym)
-              current_value = current_value[part.to_sym]
-            else
-              return nil
-            end
-          when Object
-            if current_value.respond_to?(part)
-              current_value = current_value.public_send(part)
-            elsif current_value.respond_to?("#{part}?")
-              current_value = current_value.public_send("#{part}?")
-            else
-              return nil
-            end
-          else
-            return nil
-          end
-
-          return nil if current_value.nil?
-        end
-
-        current_value
-      end
-
-      # Get all available data (runtime + business + computed)
-      attr_reader :all_data
-
-      # Check if variable exists
-      def variable?(variable_path)
-        !get(variable_path).nil?
-      end
-
-      # Get list of all available variable paths (for validation)
-      def available_variables
-        collect_variable_paths(all_data)
-      end
-
-      # Resolve variable (alias for get method for hydrator compatibility)
-      def resolve_variable(variable_path)
-        get(variable_path)
-      end
-
-    private
-
-
-      # Build consolidated app data (replaces runtime_data + computed_data)
-      def build_app_data
-        app = {}
-
-        # Request context (from current runtime_data)
-        if req && req.respond_to?(:env) && req.env
-          app['csrf_token'] = req.env.fetch(@config.csrf_token_name, nil)
-          app['nonce'] = get_or_generate_nonce
-          app['request_id'] = req.env.fetch('request_id', nil)
-          app['domain_strategy'] = req.env.fetch('domain_strategy', :default)
-          app['display_domain'] = req.env.fetch('display_domain', nil)
-        else
-          # Generate nonce even without request if CSP is enabled
-          app['nonce'] = get_or_generate_nonce
-        end
-
-        # Configuration (from both layers)
-        app['environment'] = @config.app_environment
-        app['api_base_url'] = @config.api_base_url
-        app['features'] = @config.features
-        app['development'] = @config.development?
-
-        # Authentication & UI (from current computed_data)
-        app['authenticated'] = authenticated?
-        app['theme_class'] = determine_theme_class
-
-        app
-      end
-
-      # Build API base URL from configuration (deprecated - moved to config)
-      def build_api_base_url
-        @config.api_base_url
-      end
-
-      # Determine theme class for CSS
-      def determine_theme_class
-        # Default theme logic - can be overridden by business data
-        if props['theme']
-          "theme-#{props['theme']}"
-        elsif cust && cust.respond_to?(:theme_preference)
-          "theme-#{cust.theme_preference}"
-        else
-          'theme-light'
-        end
-      end
-
-      # Check if user is authenticated
-      def authenticated?
-        sess && sess.authenticated? && cust && !cust.anonymous?
-      end
-
-      # Get default session instance
-      def default_session
-        Rhales::Adapters::AnonymousSession.new
-      end
-
-      # Get default customer instance
-      def default_customer
-        Rhales::Adapters::AnonymousAuth.new
-      end
-
-      # Normalize hash keys to strings recursively
-      def normalize_keys(data)
-        case data
-        when Hash
-          data.each_with_object({}) do |(key, value), result|
-            result[key.to_s] = normalize_keys(value)
-          end
-        when Array
-          data.map { |item| normalize_keys(item) }
-        else
-          data
-        end
-      end
-
-      # Recursively collect all variable paths from nested data
-      def collect_variable_paths(data, prefix = '')
-        paths = []
-
-        case data
-        when Hash
-          data.each do |key, value|
-            current_path = prefix.empty? ? key.to_s : "#{prefix}.#{key}"
-            paths << current_path
-
-            if value.is_a?(Hash) || value.is_a?(Object)
-              paths.concat(collect_variable_paths(value, current_path))
-            end
-          end
-        when Object
-          # For objects, collect method names that look like attributes
-          data.public_methods(false).each do |method|
-            method_name = method.to_s
-            next if method_name.end_with?('=') # Skip setters
-            next if method_name.start_with?('_') # Skip private-ish methods
-
-            current_path = prefix.empty? ? method_name : "#{prefix}.#{method_name}"
-            paths << current_path
-          end
-        end
-
-        paths
-      end
-
-      # Get or generate nonce for CSP
-      def get_or_generate_nonce
-        # Try to get existing nonce from request env
-        if req && req.respond_to?(:env) && req.env
-          existing_nonce = req.env.fetch(@config.nonce_header_name, nil)
-          return existing_nonce if existing_nonce
-        end
-
-        # Generate new nonce if auto_nonce is enabled or CSP is enabled
-        return CSP.generate_nonce if @config.auto_nonce || (@config.csp_enabled && csp_nonce_required?)
-
-        # Return nil if nonce is not needed
-        nil
-      end
-
-      # Check if CSP policy requires nonce
-      def csp_nonce_required?
-        return false unless @config.csp_enabled
-
-        csp = CSP.new(@config)
-        csp.nonce_required?
-      end
-
-      class << self
-        # Create context with business data for a specific view
-        def for_view(req, sess, cust, locale, config: nil, **props)
-          new(req, sess, cust, locale, props: props, config: config)
-        end
-
-        # Create minimal context for testing
-        def minimal(props: {}, config: nil)
-          new(nil, nil, nil, 'en', props: props, config: config)
-        end
-      end
-  end
-end

data/lib/rhales/hydration_data_aggregator.rb

@@ -1,220 +0,0 @@
-# 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/hydrator.rb

@@ -1,141 +0,0 @@
-# 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

@@ -1,39 +0,0 @@
-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.