orfeas_lyra 0.6.0

data/lib/lyra/schema/generator.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Lyra
+  module Schema
+    # Generates event schemas from monitored ActiveRecord models
+    class Generator
+      STANDARD_DATA_FIELDS = %w[model_class model_id operation attributes changes timestamp].freeze
+      STANDARD_METADATA_FIELDS = %w[user_id request_id correlation_id causation_id source].freeze
+
+      class << self
+        def generate
+          new.generate
+        end
+      end
+
+      def generate
+        schema = {
+          version: next_version,
+          created_at: Time.current.iso8601,
+          lyra_version: Lyra::VERSION,
+          rails_version: rails_version,
+          models: generate_models_schema,
+          configuration: generate_configuration_schema,
+          summary: nil  # Placeholder, filled after models generated
+        }
+
+        schema[:summary] = generate_summary(schema[:models])
+        schema[:fingerprint] = compute_fingerprint(schema)
+
+        schema
+      end
+
+      private
+
+      def generate_models_schema
+        Lyra.config.monitored_models.each_with_object({}) do |model_class, hash|
+          hash[model_class.name] = generate_model_schema(model_class)
+        end
+      end
+
+      def generate_model_schema(model_class)
+        config = Lyra.config.model_config(model_class)
+
+        schema = {
+          table_name: safe_table_name(model_class),
+          event_prefix: config.event_prefix,
+          aggregate_class: config.aggregate_class&.name,
+          columns: generate_columns_schema(model_class),
+          events: generate_events_schema(model_class, config),
+          custom_events: extract_custom_events(config),
+          privacy_policy: config.privacy_policy&.to_s
+        }
+
+        schema
+      end
+
+      def generate_columns_schema(model_class)
+        return {} unless model_class.respond_to?(:columns)
+
+        model_class.columns.each_with_object({}) do |column, hash|
+          pii_info = detect_pii_for_column(column.name)
+
+          hash[column.name] = {
+            type: column.type.to_s,
+            nullable: column.null,
+            limit: column.limit,
+            default: safe_default(column.default),
+            primary_key: column.name == safe_primary_key(model_class),
+            pii: pii_info[:is_pii],
+            pii_type: pii_info[:type]&.to_s
+          }
+        end
+      end
+
+      def generate_events_schema(model_class, config)
+        [:created, :updated, :destroyed].each_with_object({}) do |operation, hash|
+          event_name = config.event_name_for(operation)
+          pii_fields = detect_pii_fields(model_class)
+
+          hash[event_name] = {
+            operation: operation.to_s,
+            data_fields: STANDARD_DATA_FIELDS,
+            metadata_fields: STANDARD_METADATA_FIELDS,
+            attribute_fields: safe_column_names(model_class),
+            pii_fields: pii_fields
+          }
+        end
+      end
+
+      def extract_custom_events(config)
+        # Access private instance variable for custom event mappings
+        custom_mapping = config.instance_variable_get(:@custom_event_mapping) || {}
+        custom_mapping.transform_keys(&:to_s).transform_values(&:to_s)
+      end
+
+      def detect_pii_for_column(column_name)
+        return { is_pii: false, type: nil } unless Lyra.privacy_features_available?
+
+        is_pii = Lyra::Privacy::PIIDetector.contains_pii?(column_name)
+
+        if is_pii
+          # Get the PII type by detecting on a dummy hash
+          pii_info = Lyra::Privacy::PIIDetector.detect({ column_name.to_sym => nil })
+          type = pii_info.dig(column_name.to_sym, :type)
+          { is_pii: true, type: type }
+        else
+          { is_pii: false, type: nil }
+        end
+      end
+
+      def detect_pii_fields(model_class)
+        return [] unless Lyra.privacy_features_available?
+        return [] unless model_class.respond_to?(:column_names)
+
+        model_class.column_names.select do |name|
+          Lyra::Privacy::PIIDetector.contains_pii?(name)
+        end
+      end
+
+      def generate_configuration_schema
+        config = Lyra.config
+        {
+          mode: config.mode.to_s,
+          strict_schema: config.strict_schema,
+          projection_mode: config.projection_mode.to_s,
+          retention_policy: config.retention_policy
+        }
+      end
+
+      def generate_summary(models)
+        total_columns = 0
+        total_pii = 0
+        total_events = 0
+
+        models.each_value do |model|
+          total_columns += model[:columns]&.size || 0
+          total_pii += model[:columns]&.count { |_, c| c[:pii] } || 0
+          total_events += model[:events]&.size || 0
+        end
+
+        {
+          models_count: models.size,
+          total_columns: total_columns,
+          pii_fields_count: total_pii,
+          events_count: total_events
+        }
+      end
+
+      def compute_fingerprint(schema)
+        # Exclude version, timestamps, and fingerprint from hash calculation
+        content = schema.except(:fingerprint, :version, :created_at).to_yaml
+        "sha256:#{Digest::SHA256.hexdigest(content)}"
+      end
+
+      def next_version
+        Store.latest_version + 1
+      end
+
+      def rails_version
+        defined?(Rails::VERSION::STRING) ? Rails::VERSION::STRING : "unknown"
+      end
+
+      def safe_table_name(model_class)
+        model_class.respond_to?(:table_name) ? model_class.table_name : nil
+      end
+
+      def safe_primary_key(model_class)
+        model_class.respond_to?(:primary_key) ? model_class.primary_key : "id"
+      end
+
+      def safe_column_names(model_class)
+        model_class.respond_to?(:column_names) ? model_class.column_names : []
+      end
+
+      def safe_default(default_value)
+        # Convert Proc defaults to string representation
+        case default_value
+        when Proc
+          "(dynamic)"
+        when nil
+          nil
+        else
+          default_value.to_s
+        end
+      end
+    end
+  end
+end

data/lib/lyra/schema/reporter.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module Lyra
+  module Schema
+    # Generates human-readable reports of model->event mappings
+    class Reporter
+      class << self
+        def generate
+          new.generate
+        end
+
+        def to_s
+          new.to_s
+        end
+      end
+
+      def generate
+        schema = Store.load_current || Generator.generate
+
+        {
+          header: generate_header(schema),
+          models: generate_models_report(schema),
+          events: generate_events_report(schema),
+          pii: generate_pii_report(schema),
+          configuration: schema[:configuration]
+        }
+      end
+
+      def to_s
+        report = generate
+        format_report(report)
+      end
+
+      private
+
+      def format_report(report)
+        lines = []
+
+        # Header
+        lines << "=" * 70
+        lines << center_text("Lyra Event Schema Report", 70)
+        lines << "=" * 70
+        lines << ""
+
+        # Version info
+        if report[:header][:version]
+          lines << "Schema Version: v#{report[:header][:version]}"
+          lines << "Created: #{report[:header][:created_at]}"
+        else
+          lines << "Schema: (not yet saved - showing current configuration)"
+        end
+        lines << "Lyra Version: #{report[:header][:lyra_version]}"
+        lines << ""
+
+        # Configuration
+        lines << "-" * 70
+        lines << "CONFIGURATION"
+        lines << "-" * 70
+        config = report[:configuration] || {}
+        lines << "  Mode: #{config[:mode] || 'unknown'}"
+        lines << "  Strict Schema: #{config[:strict_schema]}"
+        lines << "  Projection Mode: #{config[:projection_mode]}"
+        lines << ""
+
+        # Model mappings
+        lines << "-" * 70
+        lines << "MODEL -> EVENT MAPPINGS"
+        lines << "-" * 70
+
+        report[:models].each do |model_name, model_info|
+          lines << ""
+          lines << "#{model_name}"
+          lines << "  Table: #{model_info[:table_name]}"
+          lines << "  Event Prefix: #{model_info[:event_prefix]}"
+          lines << "  Columns: #{model_info[:column_count]}"
+
+          if model_info[:pii_fields].any?
+            lines << "  PII Fields: #{model_info[:pii_fields].join(', ')}"
+          end
+
+          lines << ""
+          lines << "  Events:"
+          model_info[:events].each do |event_name, event_info|
+            pii_note = event_info[:pii_fields]&.any? ? " [PII]" : ""
+            lines << "    -> #{event_name} (#{event_info[:operation]})#{pii_note}"
+          end
+        end
+
+        # PII Summary
+        if report[:pii].any?
+          lines << ""
+          lines << "-" * 70
+          lines << "PII SUMMARY BY TYPE"
+          lines << "-" * 70
+          lines << ""
+
+          report[:pii].each do |type, fields|
+            lines << "  #{type}:"
+            fields.each { |f| lines << "    - #{f}" }
+          end
+        end
+
+        # Events Summary
+        lines << ""
+        lines << "-" * 70
+        lines << "ALL EVENTS"
+        lines << "-" * 70
+        lines << ""
+        lines << "  %-30s %-20s %-12s" % ["Event Name", "Model", "Operation"]
+        lines << "  " + "-" * 62
+
+        report[:events].each do |event|
+          lines << "  %-30s %-20s %-12s" % [
+            event[:event_name],
+            event[:model],
+            event[:operation]
+          ]
+        end
+
+        lines << ""
+        lines << "=" * 70
+
+        lines.join("\n")
+      end
+
+      def generate_header(schema)
+        {
+          version: schema[:version],
+          created_at: schema[:created_at],
+          lyra_version: schema[:lyra_version],
+          fingerprint: schema[:fingerprint]
+        }
+      end
+
+      def generate_models_report(schema)
+        (schema[:models] || {}).transform_values do |model|
+          pii_fields = (model[:columns] || {}).select { |_, c| c[:pii] }.keys
+
+          {
+            table_name: model[:table_name],
+            event_prefix: model[:event_prefix],
+            aggregate_class: model[:aggregate_class],
+            column_count: model[:columns]&.size || 0,
+            pii_fields: pii_fields,
+            events: model[:events] || {}
+          }
+        end
+      end
+
+      def generate_events_report(schema)
+        events = []
+
+        (schema[:models] || {}).each do |model_name, model|
+          (model[:events] || {}).each do |event_name, event_info|
+            events << {
+              event_name: event_name,
+              model: model_name,
+              operation: event_info[:operation],
+              pii_fields: event_info[:pii_fields]
+            }
+          end
+        end
+
+        events.sort_by { |e| [e[:model], e[:operation]] }
+      end
+
+      def generate_pii_report(schema)
+        pii_by_type = Hash.new { |h, k| h[k] = [] }
+
+        (schema[:models] || {}).each do |model_name, model|
+          (model[:columns] || {}).each do |col_name, col_info|
+            next unless col_info[:pii]
+
+            pii_type = col_info[:pii_type] || "unknown"
+            pii_by_type[pii_type] << "#{model_name}.#{col_name}"
+          end
+        end
+
+        pii_by_type.sort.to_h
+      end
+
+      def center_text(text, width)
+        padding = [(width - text.length) / 2, 0].max
+        " " * padding + text
+      end
+    end
+  end
+end

data/lib/lyra/schema/store.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Lyra
+  module Schema
+    # Handles schema file persistence and versioning
+    # Schemas are stored in db/lyra_schemas/ (like AR migrations)
+    class Store
+      DEFAULT_PATH = "db/lyra_schemas"
+
+      class << self
+        def schema_path
+          return @schema_path if @schema_path
+
+          custom_path = Lyra.config.schema_path
+          base_path = custom_path || DEFAULT_PATH
+
+          if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+            Rails.root.join(base_path)
+          else
+            Pathname.new(base_path)
+          end
+        end
+
+        def schema_path=(path)
+          @schema_path = path ? Pathname.new(path) : nil
+        end
+
+        def reset_path!
+          @schema_path = nil
+        end
+
+        def ensure_directory!
+          FileUtils.mkdir_p(schema_path)
+        end
+
+        # Load the current (latest) schema
+        def load_current
+          current_file = schema_path.join("current.yml")
+          return nil unless current_file.exist?
+
+          load_yaml(current_file)
+        end
+
+        # Load a specific version
+        def load_version(version)
+          file = find_version_file(version)
+          return nil unless file&.exist?
+
+          load_yaml(file)
+        end
+
+        # Save a new schema version
+        def save(schema)
+          ensure_directory!
+
+          version = schema[:version]
+          timestamp = Time.current.strftime("%Y%m%d%H%M%S")
+          filename = "v#{version}_#{timestamp}.yml"
+
+          file_path = schema_path.join(filename)
+          file_path.write(schema.deep_stringify_keys.to_yaml)
+
+          # Update current.yml
+          update_current(filename)
+
+          file_path
+        end
+
+        # List all schema versions
+        def versions
+          return [] unless schema_path.exist?
+
+          schema_path.glob("v*.yml")
+            .reject { |f| f.basename.to_s == "current.yml" }
+            .map { |f| extract_version(f) }
+            .compact
+            .sort
+        end
+
+        def latest_version
+          versions.max || 0
+        end
+
+        # Get version history with metadata
+        def history
+          return [] unless schema_path.exist?
+
+          schema_path.glob("v*.yml")
+            .reject { |f| f.basename.to_s == "current.yml" }
+            .map do |file|
+              schema = load_yaml(file)
+              next nil unless schema
+
+              {
+                version: schema[:version],
+                created_at: schema[:created_at],
+                lyra_version: schema[:lyra_version],
+                fingerprint: schema[:fingerprint],
+                file: file.basename.to_s,
+                models_count: schema.dig(:summary, :models_count)
+              }
+            end
+            .compact
+            .sort_by { |h| h[:version] }
+        end
+
+        # Check if any schema exists
+        def exists?
+          schema_path.exist? && schema_path.join("current.yml").exist?
+        end
+
+        private
+
+        def find_version_file(version)
+          return nil unless schema_path.exist?
+
+          schema_path.glob("v#{version}_*.yml").first
+        end
+
+        def extract_version(file)
+          match = file.basename.to_s.match(/^v(\d+)_/)
+          match ? match[1].to_i : nil
+        end
+
+        def update_current(filename)
+          current_path = schema_path.join("current.yml")
+          source_path = schema_path.join(filename)
+
+          # Use copy instead of symlink for Windows compatibility
+          FileUtils.cp(source_path, current_path)
+        end
+
+        def load_yaml(file)
+          YAML.safe_load(
+            file.read,
+            permitted_classes: [Time, Date, DateTime, Symbol, ActiveSupport::Duration],
+            symbolize_names: true
+          )
+        rescue Psych::DisallowedClass => e
+          # Fallback: try loading with unsafe_load for schema files only
+          # This handles custom classes like ActiveSupport::Duration in retention_policy
+          Rails.logger.debug("Lyra: Schema file contains unknown class, using unsafe load: #{e.message}") if defined?(Rails)
+          begin
+            YAML.unsafe_load(file.read, symbolize_names: true)
+          rescue => inner_e
+            Rails.logger.warn("Lyra: Failed to load schema file #{file}: #{inner_e.message}") if defined?(Rails)
+            nil
+          end
+        rescue => e
+          Rails.logger.warn("Lyra: Failed to load schema file #{file}: #{e.message}") if defined?(Rails)
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/lyra/schema/validator.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Lyra
+  module Schema
+    # Validates current schema against stored schema
+    class Validator
+      attr_reader :current_schema, :stored_schema, :differences
+
+      def initialize
+        @current_schema = nil
+        @stored_schema = nil
+        @differences = []
+        @validated = false
+      end
+
+      # Check if schema is valid (no differences)
+      def valid?
+        validate! unless @validated
+        @differences.empty?
+      end
+
+      # Check if stored schema exists
+      def schema_exists?
+        Store.exists?
+      end
+
+      # Check if there are breaking changes
+      def breaking_changes?
+        validate! unless @validated
+        @differences.any? { |d| d[:severity] == :breaking }
+      end
+
+      # Generate human-readable report
+      def report
+        validate! unless @validated
+        Diff.format_report(@differences)
+      end
+
+      # Perform validation
+      def validate!
+        @validated = true
+        @stored_schema = Store.load_current
+        @current_schema = Generator.generate
+
+        return true if @stored_schema.nil?  # No schema yet = valid
+
+        @differences = Diff.compare(@stored_schema, @current_schema)
+        @differences.empty?
+      end
+
+      # Validate and enforce strict mode if configured
+      def enforce!
+        return true if valid?
+
+        if Lyra.config.strict_schema
+          raise SchemaValidationError.new(report, @differences)
+        else
+          log_warning
+          false
+        end
+      end
+
+      private
+
+      def log_warning
+        message = "Lyra: Schema drift detected\n#{report}"
+        if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+          Rails.logger.warn(message)
+        else
+          warn message
+        end
+      end
+    end
+
+    # Custom error for schema validation failures
+    class SchemaValidationError < StandardError
+      attr_reader :differences
+
+      def initialize(message, differences = [])
+        @differences = differences
+        super(build_message(message))
+      end
+
+      private
+
+      def build_message(report)
+        <<~MSG
+          Lyra Event Schema Validation Failed!
+
+          #{report}
+
+          To fix this issue, either:
+          1. Run 'rake lyra:schema:update' to create a new schema version
+          2. Set 'Lyra.config.strict_schema = false' to allow schema drift
+          3. Review the changes and ensure they are intentional
+        MSG
+      end
+    end
+  end
+end