lutaml 0.10.18 → 0.11.2

data/lib/lutaml/model_transformations/parsers/base_parser.rb

@@ -1,464 +0,0 @@
-# frozen_string_literal: true
-
-module Lutaml
-  module ModelTransformations
-    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 self.class.method_defined?(:content_patterns) && 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
-
-        # 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
-
-        protected
-
-        # 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
-
-        # 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
-
-        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
-
-        # Validate input file exists and is readable
-        #
-        # @param file_path [String] Path to validate
-        # @raise [ArgumentError] if file is invalid
-        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
-
-        # Clear accumulated errors and warnings
-        #
-        # @return [void]
-        def clear_errors_and_warnings
-          @errors.clear
-          @warnings.clear
-        end
-
-        # Validate parsing output
-        #
-        # @param document [Lutaml::Uml::Document] Document to validate
-        # @raise [ValidationError] if document is invalid
-        def validate_output!(document)
-          unless document.is_a?(Lutaml::Uml::Document)
-            raise ArgumentError, "Parser must return a Lutaml::Uml::Document"
-          end
-
-          # Basic validation - subclasses can override for format-specific
-          # validation
-          if document.packages.nil? && document.classes.nil?
-            add_warning("Document contains no packages or classes")
-          end
-        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 < Lutaml::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