rhales 0.4.0 → 0.5.4

data/lib/rhales/parsers/handlebars_parser.rb

@@ -1,4 +1,6 @@
 # lib/rhales/parsers/handlebars_parser.rb
+#
+# frozen_string_literal: true
 
 module Rhales
   # Hand-rolled recursive descent parser for Handlebars template syntax

data/lib/rhales/parsers/rue_format_parser.rb

@@ -1,4 +1,6 @@
 # lib/rhales/parsers/rue_format_parser.rb
+#
+# frozen_string_literal: true
 
 require 'strscan'
 require_relative 'handlebars_parser'
@@ -9,7 +11,7 @@ module Rhales
   # This parser implements .rue file parsing rules in Ruby code and produces
   # an Abstract Syntax Tree (AST) for .rue file processing. It handles:
   #
-  # - Section-based parsing: <data>, <template>, <logic>
+  # - Section-based parsing: <schema>, <template>, <logic>
   # - Attribute extraction from section tags
   # - Delegation to HandlebarsParser for template content
   # - Validation of required sections
@@ -21,7 +23,7 @@ module Rhales
   # File format structure:
   # rue_file := section+
   # section := '<' tag_name attributes? '>' content '</' tag_name '>'
-  # tag_name := 'data' | 'template' | 'logic'
+  # tag_name := 'schema' | 'template' | 'logic'
   # attributes := attribute+
   # attribute := key '=' quoted_value
   # content := (text | handlebars_expression)*
@@ -29,9 +31,9 @@ module Rhales
   class RueFormatParser
     # At least one of these sections must be present
     unless defined?(REQUIRES_ONE_OF_SECTIONS)
-      REQUIRES_ONE_OF_SECTIONS = %w[data template].freeze
+      REQUIRES_ONE_OF_SECTIONS = %w[schema template].freeze
 
-      KNOWN_SECTIONS = %w[data template logic].freeze
+      KNOWN_SECTIONS = %w[schema template logic].freeze
       ALL_SECTIONS = KNOWN_SECTIONS.freeze
 
       # Regular expression to match HTML/XML comments outside of sections
@@ -204,7 +206,7 @@ module Rhales
           handlebars_parser.parse!
           handlebars_parser.ast.children
         else
-          # For data and logic sections, keep as simple text
+          # For schema and logic sections, keep as simple text
           raw_content.empty? ? [] : [Node.new(:text, current_location, value: raw_content)]
         end
       else
@@ -380,10 +382,10 @@ module Rhales
         when scanner.scan(/<!--.*?-->/m)
           # Comment token - non-greedy match for complete comments
           { type: :comment, content: scanner.matched }
-        when scanner.scan(/<(data|template|logic)(\s[^>]*)?>/m)
+        when scanner.scan(/<(schema|template|logic)(\s[^>]*)?>/m)
           # Section start token - matches opening tags with optional attributes
           { type: :section_start, content: scanner.matched }
-        when scanner.scan(%r{</(data|template|logic)>}m)
+        when scanner.scan(%r{</(schema|template|logic)>}m)
           # Section end token - matches closing tags
           { type: :section_end, content: scanner.matched }
         when scanner.scan(/[^<]+/)

data/lib/rhales/parsers.rb

@@ -0,0 +1,9 @@
+# lib/rhales/parsers.rb
+#
+# frozen_string_literal: true
+
+# Dependencies
+require_relative 'errors'
+
+require_relative 'parsers/handlebars_parser'
+require_relative 'parsers/rue_format_parser'

data/lib/rhales/{csp.rb → security/csp.rb}

@@ -1,4 +1,6 @@
 # lib/rhales/csp.rb
+#
+# frozen_string_literal: true
 
 module Rhales
   # Content Security Policy (CSP) header generation and management
@@ -11,6 +13,8 @@ module Rhales
   #   header = csp.build_header
   #   # => "default-src 'self'; script-src 'self' 'nonce-abc123'; ..."
   class CSP
+    include Rhales::Utils::LoggingHelpers
+
     attr_reader :config, :nonce
 
     def initialize(config, nonce: nil)
@@ -23,6 +27,7 @@ module Rhales
       return nil unless @config.csp_enabled
 
       policy_directives = []
+      nonce_used = false
 
       @config.csp_policy.each do |directive, sources|
         if sources.empty?
@@ -30,18 +35,37 @@ module Rhales
           policy_directives << directive
         else
           # Process sources and interpolate nonce if present
-          processed_sources = sources.map { |source| interpolate_nonce(source) }
+          processed_sources = sources.map do |source|
+            interpolated = interpolate_nonce(source)
+            nonce_used = true if interpolated != source
+            interpolated
+          end
           directive_string = "#{directive} #{processed_sources.join(' ')}"
           policy_directives << directive_string
         end
       end
 
-      policy_directives.join('; ')
+      header = policy_directives.join('; ')
+
+      # Log CSP header generation for security audit
+      log_with_metadata(Rhales.logger, :debug, "CSP header generated",
+        nonce_used: nonce_used,
+        nonce: @nonce,
+        directive_count: policy_directives.size,
+        header_length: header.length
+      )
+
+      header
     end
 
     # Generate a new nonce value
     def self.generate_nonce
-      SecureRandom.hex(16)
+      nonce = SecureRandom.hex(16)
+
+      # Log nonce generation for security audit trail
+      Rhales.logger.debug("CSP nonce generated: nonce=#{nonce} length=#{nonce.length} entropy_bits=#{nonce.length * 4}")
+
+      nonce
     end
 
     # Validate CSP policy configuration

data/lib/rhales/utils/json_serializer.rb

@@ -0,0 +1,114 @@
+# lib/rhales/utils/json_serializer.rb
+#
+# frozen_string_literal: true
+
+module Rhales
+  # Centralized JSON serialization with optional Oj support
+  #
+  # This module provides a unified interface for JSON operations with automatic
+  # Oj optimization when available. Oj is 10-20x faster than stdlib JSON for
+  # parsing and 5-10x faster for generation.
+  #
+  # The serializer backend is determined once at load time for optimal performance.
+  # If you want to use Oj, require it before requiring Rhales:
+  #
+  # @example Ensuring Oj is used
+  #   require 'oj'
+  #   require 'rhales'
+  #
+  # @example Basic usage
+  #   Rhales::JSONSerializer.dump({ user: 'Alice' })
+  #   # => "{\"user\":\"Alice\"}"
+  #
+  #   Rhales::JSONSerializer.parse('{"user":"Alice"}')
+  #   # => {"user"=>"Alice"}
+  #
+  # @example Pretty printing
+  #   Rhales::JSONSerializer.pretty_dump({ user: 'Alice', count: 42 })
+  #   # => "{\n  \"user\": \"Alice\",\n  \"count\": 42\n}"
+  #
+  # @example Check backend
+  #   Rhales::JSONSerializer.backend
+  #   # => :oj (if available) or :json (stdlib)
+  #
+  module JSONSerializer
+    class << self
+      # Serialize Ruby object to JSON string
+      #
+      # Uses the serializer backend determined at load time (Oj or stdlib JSON).
+      #
+      # @param obj [Object] Ruby object to serialize
+      # @return [String] JSON string (compact format)
+      # @raise [TypeError] if object contains non-serializable types
+      def dump(obj)
+        @json_dumper.call(obj)
+      end
+
+      # Serialize Ruby object to pretty-printed JSON string
+      #
+      # Uses the serializer backend determined at load time (Oj or stdlib JSON).
+      # Output is formatted with indentation for readability.
+      #
+      # @param obj [Object] Ruby object to serialize
+      # @return [String] Pretty-printed JSON string with 2-space indentation
+      # @raise [TypeError] if object contains non-serializable types
+      def pretty_dump(obj)
+        @json_pretty_dumper.call(obj)
+      end
+
+      # Parse JSON string to Ruby object
+      #
+      # Uses the parser backend determined at load time (Oj or stdlib JSON).
+      # Always returns hashes with string keys (not symbols) for consistency.
+      #
+      # @param json_string [String] JSON string to parse
+      # @return [Object] parsed Ruby object (Hash with string keys)
+      # @raise [JSON::ParserError, Oj::ParseError] if JSON is malformed
+      def parse(json_string)
+        @json_loader.call(json_string)
+      end
+
+      # Returns the active JSON backend
+      #
+      # @return [Symbol] :oj or :json
+      def backend
+        @backend
+      end
+
+      # Reset backend detection (useful for testing)
+      #
+      # @api private
+      def reset!
+        detect_backend!
+      end
+
+      private
+
+      # Detect and configure JSON backend at load time
+      def detect_backend!
+        oj_available = begin
+          require 'oj'
+          true
+        rescue LoadError
+          false
+        end
+
+        if oj_available
+          @backend = :oj
+          @json_dumper = ->(obj) { Oj.dump(obj, mode: :strict) }
+          @json_pretty_dumper = ->(obj) { Oj.dump(obj, mode: :strict, indent: 2) }
+          @json_loader = ->(json_string) { Oj.load(json_string, mode: :strict, symbol_keys: false) }
+        else
+          require 'json'
+          @backend = :json
+          @json_dumper = ->(obj) { JSON.generate(obj) }
+          @json_pretty_dumper = ->(obj) { JSON.pretty_generate(obj) }
+          @json_loader = ->(json_string) { JSON.parse(json_string) }
+        end
+      end
+    end
+
+    # Initialize backend on load
+    detect_backend!
+  end
+end

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'