ea 0.1.0 → 0.1.4

data/lib/ea/transformations/parsers/base_parser.rb

@@ -0,0 +1,482 @@
+# frozen_string_literal: true
+
+module Ea
+  module Transformations
+    module Parsers
+      # Base parser interface defining the contract for all model format
+      # parsers.
+      #
+      # This abstract base class implements the Template Method pattern and
+      # follows the Liskov Substitution Principle - all concrete parsers
+      # must be substitutable for this base class.
+      #
+      # Concrete parsers must implement:
+      # - parse_internal: Core parsing logic
+      # - supported_extensions: List of supported file extensions
+      # - format_name: Human-readable format name
+      #
+      # @abstract Subclass and implement the abstract methods
+      class BaseParser
+        # @return [Configuration] Parser configuration
+        attr_reader :configuration
+
+        # @return [Hash] Parsing options
+        attr_reader :options
+
+        # @return [Float, nil] Duration of last parse in seconds
+        attr_reader :last_duration
+
+        # Initialize parser with configuration and options
+        #
+        # @param configuration [Configuration] Transformation configuration
+        # @param options [Hash] Parsing options
+        def initialize(configuration: nil, options: {})
+          @configuration = configuration
+          @options = default_options.merge(options)
+          @errors = []
+          @warnings = []
+          @parse_stats = {
+            total_parses: 0,
+            successful_parses: 0,
+            failed_parses: 0,
+            total_duration: 0,
+            durations: [],
+          }
+          @last_duration = nil
+          @stats_mutex = Mutex.new
+        end
+
+        # Parse a model file into a UML document
+        #
+        # This is the main public interface method that implements the
+        # Template Method pattern. It handles common concerns like validation,
+        # error handling, and post-processing.
+        #
+        # @param file_path [String] Path to the model file
+        # @return [Lutaml::Uml::Document] Parsed UML document
+        # @raise [ParseError] if parsing fails
+        def parse(file_path)
+          start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          @stats_mutex.synchronize { @parse_stats[:total_parses] += 1 }
+          parse_succeeded = false
+          parse_handled = false
+
+          begin
+            validate_file!(file_path) if should_validate_input?
+            clear_errors_and_warnings
+
+            parse_succeeded, result = execute_parse(file_path)
+            parse_handled = !parse_succeeded
+            result
+          ensure
+            record_parse_stats(parse_succeeded, parse_handled, start_time)
+          end
+        end
+
+        def execute_parse(file_path)
+          before_parse(file_path)
+          document = parse_internal(file_path)
+          document = after_parse(document, file_path)
+          validate_output!(document) if should_validate_output?
+
+          @stats_mutex.synchronize { @parse_stats[:successful_parses] += 1 }
+          [true, document]
+        rescue StandardError => e
+          [false, handle_parsing_error(e, file_path)]
+        end
+
+        def record_parse_stats(succeeded, handled, start_time)
+          unless succeeded || handled
+            @stats_mutex.synchronize { @parse_stats[:failed_parses] += 1 }
+          end
+          duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+          @last_duration = duration
+          @stats_mutex.synchronize do
+            @parse_stats[:total_duration] += duration
+            @parse_stats[:durations] << duration
+          end
+        end
+
+        # Check if this parser can handle the given file
+        #
+        # @param file_path [String] Path to the file
+        # @return [Boolean] true if parser can handle the file
+        def can_parse?(file_path) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+          extension = File.extname(file_path).downcase
+          return true if supported_extensions.include?(extension)
+
+          if File.exist?(file_path)
+            File.open(file_path, "rb") do |file|
+              header = file.read(1024) # Read first 1KB
+              return false if header.nil? || header.empty?
+
+              content_patterns.each do |pattern|
+                return true if header.match?(pattern)
+              end
+            end
+          end
+
+          false
+        end
+
+        # Get parser format name
+        #
+        # @return [String] Human-readable format name
+        # @abstract Implement in subclass
+        def format_name
+          raise NotImplementedError, "Subclasses must implement #format_name"
+        end
+
+        # Get list of supported file extensions
+        #
+        # @return [Array<String>] List of extensions (e.g., [".xmi", ".xml"])
+        # @abstract Implement in subclass
+        def supported_extensions
+          raise NotImplementedError,
+                "Subclasses must implement #supported_extensions"
+        end
+
+        # Default parser priority
+        def priority
+          100
+        end
+
+        def content_patterns
+          []
+        end
+        # Check if parser has any errors
+        #
+        # @return [Boolean] true if there are parsing errors
+        def has_errors?
+          !@errors.empty?
+        end
+
+        # Check if parser has any warnings
+        #
+        # @return [Boolean] true if there are parsing warnings
+        def has_warnings?
+          !@warnings.empty?
+        end
+
+        # Get all parsing errors
+        #
+        # @return [Array<String>] List of error messages
+        def errors
+          @errors.dup
+        end
+
+        # Get all parsing warnings
+        #
+        # @return [Array<String>] List of warning messages
+        def warnings
+          @warnings.dup
+        end
+
+        # Get parsing statistics
+        #
+        # @return [Hash] Statistics about the parsing process
+        def statistics
+          stats = @stats_mutex.synchronize { @parse_stats.dup }
+          durations = stats[:durations]
+          {
+            format: format_name,
+            errors: @errors.size,
+            warnings: @warnings.size,
+            options: @options,
+            total_parses: stats[:total_parses],
+            successful_parses: stats[:successful_parses],
+            failed_parses: stats[:failed_parses],
+            success_rate: calculate_success_rate(stats),
+            average_duration: calculate_average_duration(durations),
+            total_duration: stats[:total_duration],
+          }
+        end
+
+        # Reset all parsing statistics
+        #
+        # @return [void]
+        def reset_statistics
+          @stats_mutex.synchronize do
+            @parse_stats = {
+              total_parses: 0,
+              successful_parses: 0,
+              failed_parses: 0,
+              total_duration: 0,
+              durations: [],
+            }
+          end
+          @last_duration = nil
+        end
+
+        # Core parsing implementation
+        #
+        # @param file_path [String] Path to the file to parse
+        # @return [Lutaml::Uml::Document] Parsed UML document
+        # @abstract Implement in subclass
+        def parse_internal(file_path)
+          raise NotImplementedError, "Subclasses must implement #parse_internal"
+        end
+
+        # Hook called before parsing starts
+        #
+        # @param file_path [String] Path to the file being parsed
+        # @return [void]
+        def before_parse(file_path)
+          # Default implementation does nothing
+          # Subclasses can override for pre-processing
+        end
+
+        # Hook called after parsing completes
+        #
+        # @param document [Lutaml::Uml::Document] Parsed document
+        # @param file_path [String] Path to the source file
+        # @return [Lutaml::Uml::Document] Processed document
+        def after_parse(document, _file_path)
+          # Default implementation returns document unchanged
+          # Subclasses can override for post-processing
+          document
+        end
+
+        # Get default parsing options
+        #
+        # @return [Hash] Default options hash
+        def default_options
+          {
+            validate_input: true,
+            validate_output: false,
+            include_diagrams: true,
+            preserve_ids: true,
+            resolve_references: true,
+            strict_mode: false,
+          }
+        end
+
+        # Add an error message
+        #
+        # @param message [String] Error message
+        # @param context [Hash] Additional context information
+        # @return [void]
+        def add_error(message, context = {})
+          error_entry = {
+            message: message,
+            context: context,
+            timestamp: Time.now,
+          }
+          @errors << error_entry
+
+          # Log error if configuration allows
+          log_error(error_entry) if should_log_errors?
+        end
+
+        # Add a warning message
+        #
+        # @param message [String] Warning message
+        # @param context [Hash] Additional context information
+        # @return [void]
+        def add_warning(message, context = {})
+          warning_entry = {
+            message: message,
+            context: context,
+            timestamp: Time.now,
+          }
+          @warnings << warning_entry
+
+          # Log warning if configuration allows
+          log_warning(warning_entry) if should_log_errors?
+        end
+
+        def add_info(message, context = {})
+          add_warning(message, context)
+        end
+
+        def assign_if_supported(target, setter, value)
+          target.public_send(setter, value)
+        rescue NoMethodError
+          nil
+        end
+        def format_file_size(size)
+          units = %w[B KB MB GB]
+          size = size.to_f
+          unit_index = 0
+
+          while size >= 1024 && unit_index < units.length - 1
+            size /= 1024
+            unit_index += 1
+          end
+
+          "#{size.round(1)} #{units[unit_index]}"
+        end
+
+        def format_statistics(stats)
+          parts = stats.map { |key, value| "#{value} #{key}" }
+          parts.join(", ")
+        end
+
+        # Check if input validation is enabled
+        #
+        # @return [Boolean] true if input should be validated
+        def should_validate_input?
+          @options[:validate_input]
+        end
+
+        # Check if output validation is enabled
+        #
+        # @return [Boolean] true if output should be validated
+        def should_validate_output?
+          @options[:validate_output] ||
+            @configuration&.transformation_options&.validate_output
+        end
+
+        # Check if errors should be logged
+        #
+        # @return [Boolean] true if errors should be logged
+        def should_log_errors?
+          @configuration&.error_handling&.log_errors != false
+        end
+
+        # Check if parser should fail fast on errors
+        #
+        # @return [Boolean] true if parser should fail on first error
+        def should_fail_fast?
+          @configuration&.error_handling&.fail_fast == true
+        end
+
+
+        public
+
+        def validate_file!(file_path)
+          if file_path.nil? || file_path.empty?
+            raise ArgumentError, "File path cannot be nil"
+          end
+
+          unless File.exist?(file_path)
+            raise ArgumentError, "File does not exist: \#{file_path}"
+          end
+
+          unless File.readable?(file_path)
+            raise ArgumentError, "File is not readable: \#{file_path}"
+          end
+        end
+
+        def clear_errors_and_warnings
+          @errors.clear
+          @warnings.clear
+        end
+
+        def validate_output!(document)
+          unless document.is_a?(Lutaml::Uml::Document)
+            raise ArgumentError, "Parser must return a Lutaml::Uml::Document"
+          end
+
+          if document.packages.nil? && document.classes.nil?
+            add_warning("Document contains no packages or classes")
+          end
+        end
+
+        private
+
+        # Calculate success rate percentage
+        #
+        # @param stats [Hash] Stats hash
+        # @return [Float] Success rate as percentage
+        def calculate_success_rate(stats)
+          return 0.0 if stats[:total_parses].zero?
+
+          (stats[:successful_parses].to_f / stats[:total_parses]) * 100.0
+        end
+
+        # Calculate average parse duration
+        #
+        # @param durations [Array<Float>] List of parse durations
+        # @return [Float] Average duration
+        def calculate_average_duration(durations)
+          return 0.0 if durations.empty?
+
+          durations.sum / durations.size
+        end
+
+        # Handle parsing errors according to configuration
+        #
+        # @param error [StandardError] The error that occurred
+        # @param file_path [String] Path to the file being parsed
+        # @raise [ParseError] Wrapped parsing error
+        def handle_parsing_error(error, file_path) # rubocop:disable Metrics/MethodLength
+          error_context = {
+            file_path: file_path,
+            parser: self.class.name,
+            original_error: error.class.name,
+          }
+
+          add_error("Failed to parse #{file_path}: #{error.message}",
+                    error_context)
+
+          # Re-raise as ParseError with additional context
+          raise ParseError.new(
+            "Parsing failed for #{file_path}",
+            original_error: error,
+            parser: self,
+            file_path: file_path,
+          )
+        end
+
+        # Log error entry
+        #
+        # @param error_entry [Hash] Error entry to log
+        # @return [void]
+        def log_error(error_entry)
+          warn "[#{self.class.name}] ERROR: #{error_entry[:message]}"
+        end
+
+        # Log warning entry
+        #
+        # @param warning_entry [Hash] Warning entry to log
+        # @return [void]
+        def log_warning(warning_entry)
+          warn "[#{self.class.name}] WARNING: #{warning_entry[:message]}"
+        end
+      end
+
+      # Custom error class for parsing failures
+      class ParseError < Ea::Error
+        # @return [StandardError] Original error that caused parsing failure
+        attr_reader :original_error
+
+        # @return [BaseParser] Parser instance that failed
+        attr_reader :parser
+
+        # @return [String] Path to file that failed to parse
+        attr_reader :file_path
+
+        # Initialize parsing error
+        #
+        # @param message [String] Error message
+        # @param original_error [StandardError] Original error
+        # @param parser [BaseParser] Parser that failed
+        # @param file_path [String] File that failed to parse
+        def initialize(
+          message, original_error: nil, parser: nil,
+          file_path: nil
+        )
+          super(message)
+          @original_error = original_error
+          @parser = parser
+          @file_path = file_path
+        end
+
+        # Get detailed error information
+        #
+        # @return [Hash] Error details
+        def details # rubocop:disable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+          {
+            message: message,
+            file_path: @file_path,
+            parser: @parser&.class&.name,
+            original_error: @original_error&.class&.name,
+            original_message: @original_error&.message,
+            backtrace: @original_error&.backtrace&.first(5),
+          }
+        end
+      end
+    end
+  end
+end