rhales 0.3.0 → 0.5.3

data/lib/rhales/utils/logging_helpers.rb

@@ -0,0 +1,75 @@
+# lib/rhales/utils/logging_helpers.rb
+#
+# frozen_string_literal: true
+
+module Rhales
+  module Utils
+    # Helper methods for consistent logging and timing instrumentation across Rhales components
+    module LoggingHelpers
+      include Rhales::Utils
+
+      # Log with timing for an operation
+      #
+      # @param logger [Logger] The logger instance to use
+      # @param level [Symbol] The log level (:debug, :info, :warn, :error)
+      # @param message [String] The log message
+      # @param metadata [Hash] Additional metadata to include in the log
+      # @yield The block to execute and time
+      # @return The result of the block
+      #
+      # Logs the operation with timing information in microseconds.
+      def log_timed_operation(logger, level, message, **metadata)
+        start_time = now_in_μs
+        result = yield
+        duration = now_in_μs - start_time
+
+        log_with_metadata(logger, level, message, metadata.merge(duration: duration))
+
+        result
+      rescue StandardError => ex
+        duration = now_in_μs - start_time
+        log_with_metadata(logger, :error, "#{message} failed",
+          metadata.merge(
+            duration: duration,
+            error: ex.message,
+            error_class: ex.class.name,
+          )
+        )
+        raise
+      end
+
+      # Log a message with structured metadata
+      def log_with_metadata(logger, level, message, metadata = {})
+        return logger.public_send(level, message) if metadata.empty?
+
+        metadata_str = metadata.map { |k, v| "#{k}=#{format_value(v)}" }.join(' ')
+        logger.public_send(level, "#{message}: #{metadata_str}")
+      end
+
+      private
+
+      # Format individual log values
+      def format_value(value)
+        case value
+        when String
+          value.include?(' ') ? "\"#{value}\"" : value
+        when Symbol, Numeric, true, false, nil
+          value.to_s
+        when Array
+          # For arrays longer than 5 items, show count + first/last items
+          if value.size > 5
+            first_three = value.first(3).join(', ')
+            last_two = value.last(2).join(', ')
+            "[#{value.size} items: #{first_three} ... #{last_two}]"
+          elsif value.empty?
+            '[]'
+          else
+            "[#{value.join(', ')}]"
+          end
+        else
+          value.to_s
+        end
+      end
+    end
+  end
+end

data/lib/rhales/utils/schema_extractor.rb

@@ -0,0 +1,132 @@
+# lib/rhales/schema_extractor.rb
+#
+# frozen_string_literal: true
+
+require 'pathname'
+require_relative '../core/rue_document'
+
+module Rhales
+  # Extracts schema definitions from .rue files
+  #
+  # This class scans template directories for .rue files containing <schema>
+  # sections and extracts the schema code along with metadata (attributes).
+  #
+  # Usage:
+  #   extractor = SchemaExtractor.new('./templates')
+  #   schemas = extractor.extract_all
+  #   schemas.each do |schema_info|
+  #     puts "#{schema_info[:template_name]}: #{schema_info[:lang]}"
+  #   end
+  class SchemaExtractor
+    class ExtractionError < StandardError; end
+
+    attr_reader :templates_dir
+
+    def initialize(templates_dir)
+      @templates_dir = File.expand_path(templates_dir)
+      validate_directory!
+    end
+
+    # Extract all schemas from .rue files in the templates directory
+    #
+    # @return [Array<Hash>] Array of schema information hashes
+    # @example
+    #   [
+    #     {
+    #       template_name: 'dashboard',
+    #       template_path: '/path/to/dashboard.rue',
+    #       schema_code: 'const schema = z.object({...});',
+    #       lang: 'ts-zod',
+    #       version: '2',
+    #       envelope: 'SuccessEnvelope',
+    #       window: 'appData',
+    #       merge: 'deep',
+    #       layout: 'layouts/main',
+    #       extends: nil
+    #     }
+    #   ]
+    def extract_all
+      rue_files = find_rue_files
+      schemas = []
+
+      rue_files.each do |file_path|
+        begin
+          schema_info = extract_from_file(file_path)
+          schemas << schema_info if schema_info
+        rescue => e
+          warn "Warning: Failed to extract schema from #{file_path}: #{e.message}"
+        end
+      end
+
+      schemas
+    end
+
+    # Extract schema from a single .rue file
+    #
+    # @param file_path [String] Path to the .rue file
+    # @return [Hash, nil] Schema information hash or nil if no schema section
+    def extract_from_file(file_path)
+      doc = RueDocument.parse_file(file_path)
+
+      return nil unless doc.section?('schema')
+
+      template_name = derive_template_name(file_path)
+      schema_code = doc.section('schema')
+
+      {
+        template_name: template_name,
+        template_path: file_path,
+        schema_code: schema_code.strip,
+        lang: doc.schema_lang,
+        version: doc.schema_version,
+        envelope: doc.schema_envelope,
+        window: doc.schema_window,
+        merge: doc.schema_merge_strategy,
+        layout: doc.schema_layout,
+        extends: doc.schema_extends
+      }
+    end
+
+    # Find all .rue files in the templates directory (recursive)
+    #
+    # @return [Array<String>] Array of absolute file paths
+    def find_rue_files
+      pattern = File.join(@templates_dir, '**', '*.rue')
+      Dir.glob(pattern).sort
+    end
+
+    # Count how many .rue files have schema sections
+    #
+    # @return [Hash] Count information
+    def schema_stats
+      all_files = find_rue_files
+      schemas = extract_all
+
+      {
+        total_files: all_files.count,
+        files_with_schemas: schemas.count,
+        files_without_schemas: all_files.count - schemas.count,
+        schemas_by_lang: schemas.group_by { |s| s[:lang] }.transform_values(&:count)
+      }
+    end
+
+    private
+
+    def validate_directory!
+      unless File.directory?(@templates_dir)
+        raise ExtractionError, "Templates directory does not exist: #{@templates_dir}"
+      end
+    end
+
+    # Derive template name from file path
+    # Examples:
+    #   /path/to/templates/dashboard.rue => 'dashboard'
+    #   /path/to/templates/pages/user/profile.rue => 'pages/user/profile'
+    def derive_template_name(file_path)
+      templates_pathname = Pathname.new(@templates_dir)
+      file_pathname = Pathname.new(file_path)
+      relative_path = file_pathname.relative_path_from(templates_pathname)
+      relative_path.to_s.sub(/\.rue$/, '')
+    end
+  end
+end

data/lib/rhales/utils/schema_generator.rb

@@ -0,0 +1,194 @@
+# lib/rhales/schema_generator.rb
+#
+# frozen_string_literal: true
+
+require 'open3'
+require 'tempfile'
+require 'fileutils'
+require_relative 'schema_extractor'
+require_relative 'json_serializer'
+
+module Rhales
+  # Generates JSON Schemas from Zod schemas using TypeScript execution
+  #
+  # This class uses pnpm exec tsx to execute Zod schema code and convert it
+  # to JSON Schema format. The generated schemas are saved to disk for use
+  # by the validation middleware.
+  #
+  # Usage:
+  #   generator = SchemaGenerator.new(
+  #     templates_dir: './templates',
+  #     output_dir: './public/schemas'
+  #   )
+  #   results = generator.generate_all
+  class SchemaGenerator
+    class GenerationError < StandardError; end
+
+    attr_reader :templates_dir, :output_dir
+
+    # @param templates_dir [String] Directory containing .rue files
+    # @param output_dir [String] Directory to save generated JSON schemas
+    #   Defaults to './public/schemas' (implementing project's public directory)
+    def initialize(templates_dir:, output_dir: nil)
+      @templates_dir = File.expand_path(templates_dir)
+
+      # Smart default: place schemas in public/schemas relative to current working directory
+      # This ensures schemas are generated in the implementing project, not the gem directory
+      @output_dir = if output_dir
+        File.expand_path(output_dir)
+      else
+        # Default to public/schemas in current working directory
+        File.expand_path('./public/schemas')
+      end
+
+      validate_setup!
+      ensure_output_directory!
+    end
+
+    # Generate JSON Schemas for all templates with <schema> sections
+    #
+    # @return [Hash] Generation results with stats
+    def generate_all
+      extractor = SchemaExtractor.new(@templates_dir)
+      schemas = extractor.extract_all
+
+      if schemas.empty?
+        return {
+          success: true,
+          generated: 0,
+          failed: 0,
+          message: 'No schemas found in templates'
+        }
+      end
+
+      results = {
+        success: true,
+        generated: 0,
+        failed: 0,
+        errors: []
+      }
+
+      schemas.each do |schema_info|
+        begin
+          generate_schema(schema_info)
+          results[:generated] += 1
+          puts "✓ Generated schema for: #{schema_info[:template_name]}"
+        rescue => e
+          results[:failed] += 1
+          results[:success] = false
+          error_msg = "Failed to generate schema for #{schema_info[:template_name]}: #{e.message}"
+          results[:errors] << error_msg
+          warn error_msg
+        end
+      end
+
+      results
+    end
+
+    # Generate JSON Schema for a single template
+    #
+    # @param schema_info [Hash] Schema information from SchemaExtractor
+    # @return [Hash] Generated JSON Schema
+    def generate_schema(schema_info)
+      # Create temp file in project directory so Node.js can resolve modules
+      temp_dir = File.join(Dir.pwd, 'tmp')
+      FileUtils.mkdir_p(temp_dir) unless Dir.exist?(temp_dir)
+
+      temp_file = Tempfile.new(['schema', '.mts'], temp_dir)
+
+      begin
+        # Write TypeScript script
+        temp_file.write(build_typescript_script(schema_info))
+        temp_file.close
+
+        # Execute with tsx via pnpm
+        stdout, stderr, status = Open3.capture3('pnpm', 'exec', 'tsx', temp_file.path)
+
+        unless status.success?
+          raise GenerationError, "TypeScript execution failed: #{stderr}"
+        end
+
+        # Parse JSON Schema from stdout
+        json_schema = JSONSerializer.parse(stdout)
+
+        # Save to disk
+        save_schema(schema_info[:template_name], json_schema)
+
+        json_schema
+      ensure
+        temp_file.unlink if temp_file
+      end
+    end
+
+    private
+
+    def build_typescript_script(schema_info)
+      # Escape single quotes in template name for TypeScript string
+      safe_name = schema_info[:template_name].gsub("'", "\\'")
+
+      <<~TYPESCRIPT
+        // Auto-generated schema generator for #{safe_name}
+        import { z } from 'zod/v4';
+
+        // Schema code from .rue template
+        #{schema_info[:schema_code].strip}
+
+        // Generate JSON Schema
+        try {
+          const jsonSchema = z.toJSONSchema(schema, {
+            target: 'draft-2020-12',
+            unrepresentable: 'any',
+            cycles: 'ref',
+            reused: 'inline',
+          });
+
+          // Add metadata
+          const schemaWithMeta = {
+            $schema: 'https://json-schema.org/draft/2020-12/schema',
+            $id: `https://rhales.dev/schemas/#{safe_name}.json`,
+            title: '#{safe_name}',
+            description: 'Schema for #{safe_name} template',
+            ...jsonSchema,
+          };
+
+          // Output JSON to stdout
+          console.log(JSON.stringify(schemaWithMeta, null, 2));
+        } catch (error) {
+          console.error('Schema generation error:', error.message);
+          process.exit(1);
+        }
+      TYPESCRIPT
+    end
+
+    def save_schema(template_name, json_schema)
+      # Create subdirectories if template name contains paths
+      schema_file = File.join(@output_dir, "#{template_name}.json")
+      schema_dir = File.dirname(schema_file)
+      FileUtils.mkdir_p(schema_dir) unless File.directory?(schema_dir)
+
+      File.write(schema_file, JSONSerializer.dump(json_schema))
+    end
+
+    def validate_setup!
+      unless File.directory?(@templates_dir)
+        raise GenerationError, "Templates directory does not exist: #{@templates_dir}"
+      end
+
+      # Check pnpm is available
+      stdout, stderr, status = Open3.capture3('pnpm', '--version')
+      unless status.success?
+        raise GenerationError, "pnpm not found. Install pnpm to generate schemas: npm install -g pnpm"
+      end
+
+      # Check tsx is available (will be installed by pnpm if needed)
+      stdout, stderr, status = Open3.capture3('pnpm', 'exec', 'tsx', '--version')
+      unless status.success?
+        raise GenerationError, "tsx not found. Run: pnpm install tsx --save-dev"
+      end
+    end
+
+    def ensure_output_directory!
+      FileUtils.mkdir_p(@output_dir) unless File.directory?(@output_dir)
+    end
+  end
+end

data/lib/rhales/utils.rb

@@ -0,0 +1,40 @@
+# lib/rhales/utils.rb
+#
+# frozen_string_literal: true
+
+require 'pathname'
+
+module Rhales
+  module Utils
+    # Utility modules and classes
+
+    # @return [Time] Current time in UTC
+    def now
+      Time.now.utc
+    end
+
+    # Returns the current time in microseconds.
+    # This is used to measure the duration of Database commands.
+    #
+    # Alias: now_in_microseconds
+    #
+    # @return [Integer] The current time in microseconds.
+    def now_in_μs
+      Process.clock_gettime(Process::CLOCK_MONOTONIC, :microsecond)
+    end
+    alias now_in_microseconds now_in_μs
+
+    # @param filepath [String, nil] The file path to prettify
+    # @return [String, nil] The expanded absolute path, or nil if input is
+    def pretty_path(filepath)
+      return nil if filepath.nil?
+
+      Pathname.new(filepath).expand_path.to_s
+    end
+  end
+end
+
+require_relative 'utils/json_serializer'
+require_relative 'utils/schema_generator'
+require_relative 'utils/schema_extractor'
+require_relative 'utils/logging_helpers'

data/lib/rhales/version.rb

@@ -1,6 +1,10 @@
 # lib/rhales/version.rb
+#
+# frozen_string_literal: true
 
 module Rhales
   # Version information for the RSFC gem
-  VERSION = '0.3.0'
+  unless defined?(Rhales::VERSION)
+    VERSION = '0.5.3'
+  end
 end

data/lib/rhales.rb

@@ -1,20 +1,25 @@
 # lib/rhales.rb
+#
+# frozen_string_literal: true
+
+require 'logger'
 
+# Core framework files
 require_relative 'rhales/version'
-require_relative 'rhales/errors'
 require_relative 'rhales/configuration'
-require_relative 'rhales/adapters/base_auth'
-require_relative 'rhales/adapters/base_session'
-require_relative 'rhales/context'
-require_relative 'rhales/rue_document'
-require_relative 'rhales/parsers/handlebars_parser'
-require_relative 'rhales/parsers/rue_format_parser'
-require_relative 'rhales/template_engine'
-require_relative 'rhales/hydrator'
-require_relative 'rhales/view_composition'
-require_relative 'rhales/hydration_data_aggregator'
-require_relative 'rhales/refinements/require_refinements'
-require_relative 'rhales/view'
+require_relative 'rhales/errors'
+
+# Load components in dependency order
+require_relative 'rhales/adapters'
+require_relative 'rhales/parsers'
+require_relative 'rhales/utils'
+
+# Security (depends on utils)
+require_relative 'rhales/security/csp'
+require_relative 'rhales/core'
+require_relative 'rhales/hydration'
+require_relative 'rhales/integrations'
+require_relative 'rhales/middleware'
 
 # Ruby Single File Components (RSFC)
 #
@@ -28,19 +33,42 @@ require_relative 'rhales/view'
 # - Pluggable authentication and session adapters
 # - Security-first design with XSS protection and CSP support
 #
+# Modular Loading:
+#   require 'rhales'           # Loads everything (default)
+#   require 'rhales/core'      # Core engine only
+#   require 'rhales/hydration' # Hydration system only
+#   require 'rhales/parsers'   # Template parsers only
+#   require 'rhales/utils'     # Utilities only
+#   require 'rhales/all'       # Explicit full load
+#
 # Usage:
 #   Rhales.configure do |config|
-#     config.default_localhas_role?e = 'en'
+#     config.default_locale = 'en'
 #     config.template_paths = ['app/templates']
 #     config.features = { dark_mode: true }
+#
+#     # Hydration configuration
+#     config.hydration.injection_strategy = :early  # :early or :late (default)
+#     config.hydration.mount_point_selectors = ['#app', '#root', '[data-mount]']
+#     config.hydration.fallback_to_late = true
 #   end
 #
-#   view = Rhales::View.new(request, session, user)
+#   view = Rhales::View.new(request)
 #   html = view.render('my_component')
 module Rhales
+  extend Utils
+
+  class << self
+    attr_writer :logger
+
+    def logger
+      @logger ||= Logger.new($stdout)
+    end
+  end
+
   # Convenience method to create a view with props
-  def self.render(template_name, request: nil, session: nil, user: nil, locale: nil, **props)
-    view = View.new(request, session, user, locale, props: props)
+  def self.render(template_name, request: nil, locale: nil, **props)
+    view = View.new(request, locale, props: props)
     view.render(template_name)
   end
 
@@ -51,7 +79,7 @@ module Rhales
   end
 
   # Create context with props (for advanced usage)
-  def self.create_context(request: nil, session: nil, user: nil, locale: nil, **props)
-    Context.for_view(request, session, user, locale, **props)
+  def self.create_context(request: nil, locale: nil, **props)
+    Context.for_view(request, locale, **props)
   end
 end