lutaml 0.10.18 → 0.11.2

data/lib/lutaml/uml_repository/lazy_repository.rb

@@ -1,236 +0,0 @@
-# frozen_string_literal: true
-
-module Lutaml
-  module UmlRepository
-    # LazyRepository provides lazy loading optimization for very large
-    # UML models
-    #
-    # For extremely large models (1000+ classes), LazyRepository optimizes
-    # memory usage and initial load time by building indexes on-demand rather
-    # than upfront. Indexes are built only when first accessed, reducing the
-    # initial load time significantly.
-    #
-    # @example Using lazy loading from XMI
-    #   repo = Lutaml::Xmi::Repository.from_xmi_lazy('large-model.xmi')
-    #   # Only metadata loaded at this point
-    #
-    #   klass = repo.find_class("ModelRoot::MyClass")
-    #   # Now qualified_names index is built
-    #
-    # @example Building all indexes manually
-    #   repo = Lutaml::Xmi::Repository.from_xmi_lazy('model.xmi')
-    #   repo.build_all_indexes
-    #   # All indexes are now available
-    class LazyRepository < Repository
-      # Initialize a new LazyRepository with lazy index building.
-      #
-      # @param document [Lutaml::Uml::Document] The UML document to wrap
-      # @param indexes [Hash, nil] Pre-built indexes, or nil to build lazily
-      # @param lazy [Boolean] Whether to enable lazy loading (default: true)
-      # @return [LazyRepository] A new repository instance (not frozen)
-      def initialize(document:, indexes: nil, lazy: true) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
-        @document = document
-        @indexes = indexes || {}
-        @lazy_mode = lazy
-        @index_builders_pending = Set.new(%i[
-                                            package_paths
-                                            qualified_names
-                                            stereotypes
-                                            inheritance_graph
-                                            diagram_index
-                                          ])
-
-        # Initialize runtime query services (not serialized to LUR)
-        # These are lightweight wrappers that operate on @document and @indexes
-        @package_query = Queries::PackageQuery.new(@document, @indexes)
-        @class_query = Queries::ClassQuery.new(@document, @indexes)
-        @inheritance_query = Queries::InheritanceQuery.new(@document, @indexes)
-        @association_query = Queries::AssociationQuery.new(@document, @indexes)
-        @diagram_query = Queries::DiagramQuery.new(@document, @indexes)
-        @search_query = Queries::SearchQuery.new(@document, @indexes)
-
-        # Initialize statistics calculator (lazily computed)
-        @statistics_calculator = StatisticsCalculator.new(@document, @indexes)
-
-        # Initialize error handler for helpful error messages
-        @error_handler = ErrorHandler.new(self)
-
-        # Don't freeze - we build indexes on demand
-      end
-
-      # Find a class by its qualified name.
-      #
-      # Ensures the qualified_names index is built before querying.
-      #
-      # @param qualified_name [String] The qualified name
-      # @param raise_on_error [Boolean] Whether to raise an error if not found
-      # @return [Lutaml::Uml::Class, Lutaml::Uml::DataType,
-      # Lutaml::Uml::Enum, nil]
-      def find_class(qualified_name, raise_on_error: false)
-        ensure_index(:qualified_names)
-        super
-      end
-
-      # Find a package by its path.
-      #
-      # Ensures the package_paths index is built before querying.
-      #
-      # @param path [String] The package path
-      # @param raise_on_error [Boolean] Whether to raise an error if not found
-      # @return [Lutaml::Uml::Package, Lutaml::Uml::Document, nil]
-      def find_package(path, raise_on_error: false)
-        ensure_index(:package_paths)
-        super
-      end
-
-      # Find all classes with a specific stereotype.
-      #
-      # Ensures the stereotypes index is built before querying.
-      #
-      # @param stereotype [String] The stereotype to search for
-      # @return [Array] Array of class objects with the stereotype
-      def find_classes_by_stereotype(stereotype)
-        ensure_index(:stereotypes)
-        super
-      end
-
-      # Get the direct parent class (supertype).
-      #
-      # Ensures the qualified_names and inheritance_graph indexes are built.
-      #
-      # @param class_or_qname [Lutaml::Uml::Class, String] The class object
-      #   or qualified name string
-      # @return [Lutaml::Uml::Class, nil] The parent class, or nil if no parent
-      def supertype_of(class_or_qname)
-        ensure_index(:qualified_names)
-        ensure_index(:inheritance_graph)
-        super
-      end
-
-      # Get direct child classes (subtypes).
-      #
-      # Ensures the inheritance_graph index is built before querying.
-      #
-      # @param class_or_qname [Lutaml::Uml::Class, String] The class object
-      #   or qualified name string
-      # @param recursive [Boolean] Whether to include all descendants
-      # @return [Array] Array of child class objects
-      def subtypes_of(class_or_qname, recursive: false)
-        ensure_index(:inheritance_graph)
-        super
-      end
-
-      # Get all ancestor classes up to the root.
-      #
-      # Ensures the qualified_names and inheritance_graph indexes are built.
-      #
-      # @param class_or_qname [Lutaml::Uml::Class, String] The class object
-      #   or qualified name string
-      # @return [Array] Array of ancestor class objects
-      def ancestors_of(class_or_qname)
-        ensure_index(:qualified_names)
-        ensure_index(:inheritance_graph)
-        super
-      end
-
-      # Get all descendant classes.
-      #
-      # Ensures the inheritance_graph index is built before querying.
-      #
-      # @param class_or_qname [Lutaml::Uml::Class, String] The class object
-      #   or qualified name string
-      # @param max_depth [Integer, nil] Maximum depth to traverse
-      # @return [Array] Array of descendant class objects
-      def descendants_of(class_or_qname, max_depth: nil)
-        ensure_index(:inheritance_graph)
-        super
-      end
-
-      # Get diagrams in a specific package.
-      #
-      # Ensures the diagram_index is built before querying.
-      #
-      # @param package_path [String] The package path or package ID
-      # @return [Array<Lutaml::Uml::Diagram>] Array of diagram objects
-      def diagrams_in_package(package_path)
-        ensure_index(:diagram_index)
-        super
-      end
-
-      # Manually build all remaining indexes.
-      #
-      # This method can be called to force building all indexes at once,
-      # rather than waiting for them to be built on-demand.
-      #
-      # @return [LazyRepository] Returns self for method chaining
-      # @example
-      #   repo = Repository.from_xmi_lazy('model.xmi')
-      #   repo.build_all_indexes
-      #   # All indexes are now built
-      def build_all_indexes
-        @index_builders_pending.each { |index_name| ensure_index(index_name) }
-        self
-      end
-
-      # Check if an index is built.
-      #
-      # @param index_name [Symbol] The name of the index to check
-      # @return [Boolean] True if the index is built, false otherwise
-      # @example
-      #   repo.index_built?(:qualified_names)  # => false
-      #   repo.find_class("ModelRoot::MyClass")
-      #   repo.index_built?(:qualified_names)  # => true
-      def index_built?(index_name)
-        @indexes.key?(index_name) && !@indexes[index_name].nil?
-      end
-
-      # Get list of pending indexes.
-      #
-      # Returns the names of indexes that have not yet been built.
-      #
-      # @return [Array<Symbol>] Array of pending index names
-      # @example
-      #   repo.pending_indexes  # => [:package_paths, :qualified_names, ...]
-      def pending_indexes
-        @index_builders_pending.to_a
-      end
-
-      private
-
-      # Ensure an index is built.
-      #
-      # If the index is already built, this method returns immediately.
-      # Otherwise, it builds the index and removes it from the pending list.
-      #
-      # @param index_name [Symbol] The name of the index to ensure
-      # @return [void]
-      def ensure_index(index_name) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength
-        return if index_built?(index_name)
-
-        puts "Building #{index_name} index..." if $VERBOSE
-
-        case index_name
-        when :package_paths
-          @indexes[:package_paths] = IndexBuilder.build_package_paths(@document)
-        when :qualified_names
-          @indexes[:qualified_names] =
-            IndexBuilder.build_qualified_names(@document)
-        when :stereotypes
-          @indexes[:stereotypes] = IndexBuilder.build_stereotypes(@document)
-        when :inheritance_graph
-          # Requires qualified_names first
-          ensure_index(:qualified_names)
-          @indexes[:inheritance_graph] =
-            IndexBuilder.build_inheritance_graph(@document, @indexes)
-        when :diagram_index
-          # Requires package_paths first
-          ensure_index(:package_paths)
-          @indexes[:diagram_index] =
-            IndexBuilder.build_diagram_index(@document, @indexes)
-        end
-
-        @index_builders_pending.delete(index_name)
-      end
-    end
-  end
-end

data/lib/lutaml/uml_repository/package_exporter.rb

@@ -1,334 +0,0 @@
-# frozen_string_literal: true
-
-require "zip"
-require "yaml"
-require "time"
-
-module Lutaml
-  module UmlRepository
-    # PackageExporter handles exporting UmlRepository instances to LUR
-    # (LutaML UML Repository) package files.
-    #
-    # LUR packages are ZIP archives containing:
-    # - Serialized Document model
-    # - Serialized indexes for fast loading
-    # - Metadata about the package
-    # - Statistics about the model
-    #
-    # @example Export with defaults
-    #   exporter = PackageExporter.new(repository)
-    #   exporter.export("model.lur")
-    #
-    # @example Export with PackageMetadata
-    #   metadata = PackageMetadata.new(
-    #     name: "Urban Model",
-    #     version: "2.0",
-    #     publisher: "City Planning",
-    #     license: "CC-BY-4.0"
-    #   )
-    #   exporter = PackageExporter.new(repository, metadata: metadata)
-    #   exporter.export("model.lur")
-    #
-    # @example Export with metadata hash (backward compatible)
-    #   exporter = PackageExporter.new(repository,
-    #     name: "My Model",
-    #     version: "2.0",
-    #     serialization_format: :yaml
-    #   )
-    #   exporter.export("model.lur")
-    class PackageExporter
-      # @return [UmlRepository] The repository being exported
-      attr_reader :repository
-
-      # @return [Hash] Export options
-      attr_reader :options
-
-      # @return [PackageMetadata] The package metadata
-      attr_reader :metadata
-
-      # Initialize a new PackageExporter.
-      #
-      # @param repository [UmlRepository] The repository to export
-      # @param options [Hash] Export options
-      # @option options [PackageMetadata, Hash] :metadata Package metadata
-      #   (can be PackageMetadata object or Hash)
-      # @option options [Symbol] :serialization_format (:yaml) Format for
-      #   Document serialization (:yaml)
-      # @option options [Boolean] :include_xmi (false) Include source XMI
-      #   in package
-      # @option options [Integer] :compression_level (6) ZIP compression level
-      #   (0-9)
-      # @option options [String] :name ("UML Model") Package name
-      #   (deprecated, use :metadata)
-      # @option options [String] :version ("1.0") Package version
-      #   (deprecated, use :metadata)
-      def initialize(repository, options = {})
-        @repository = repository
-        @options = default_options.merge(options)
-        @metadata = build_metadata(@options)
-      end
-
-      # Export the repository to a LUR package file.
-      #
-      # @param output_path [String] Path for the output .lur file
-      # @return [void]
-      # @raise [ArgumentError] If serialization format is invalid
-      # @example
-      #   exporter.export("model.lur")
-      def export(output_path) # rubocop:disable Metrics/MethodLength
-        validate_options!
-
-        retries = 0
-        begin
-          write_lur_package(output_path)
-        rescue Errno::EACCES
-          retries += 1
-          retry if retries < 3
-          raise
-        end
-      end
-
-      private
-
-      def write_lur_package(output_path)
-        Zip::File.open(output_path, create: true) do |zip|
-          write_metadata(zip)
-          write_document(zip)
-          write_indexes(zip)
-          write_index_tree(zip)
-          write_statistics(zip)
-        end
-      end
-
-      # Get default export options.
-      #
-      # @return [Hash] Default options
-      def default_options
-        {
-          serialization_format: :yaml,
-          include_xmi: false,
-          compression_level: 6,
-          name: "UML Model",
-          version: "1.0",
-        }
-      end
-
-      # Build PackageMetadata from options.
-      #
-      # Handles three cases:
-      # 1. :metadata is a PackageMetadata object - use directly
-      # 2. :metadata is a Hash - build from hash
-      # 3. Old-style :name/:version options - build from those
-      #
-      # @param options [Hash] Export options
-      # @return [PackageMetadata] Package metadata
-      def build_metadata(options) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
-        # Case 1: metadata is already a PackageMetadata object
-        if options[:metadata].is_a?(PackageMetadata)
-          return options[:metadata]
-        end
-
-        # Case 2: metadata is a Hash
-        if options[:metadata].is_a?(Hash)
-          metadata_hash = options[:metadata].dup
-          # Ensure serialization_format is set
-          metadata_hash[:serialization_format] ||=
-            options[:serialization_format]
-          # Normalize keys to symbols and create directly
-          normalized = metadata_hash.transform_keys(&:to_sym)
-          return PackageMetadata.new(**normalized)
-        end
-
-        # Case 3: Old-style options (backward compatibility)
-        PackageMetadata.new(
-          name: options[:name],
-          version: options[:version],
-          serialization_format: options[:serialization_format].to_s,
-        )
-      end
-
-      # Validate export options.
-      #
-      # @return [void]
-      # @raise [ArgumentError] If options are invalid
-      def validate_options!
-        format = @options[:serialization_format]
-        unless format == :yaml
-          raise ArgumentError,
-                "Invalid serialization format: #{format}. Must be :yaml"
-        end
-      end
-
-      # Write metadata.yaml to the package.
-      #
-      # Converts PackageMetadata to YAML hash, then adds operational
-      # metadata (created_at, created_by, etc.).
-      #
-      # @param zip [Zip::File] The ZIP archive
-      # @return [void]
-      def write_metadata(zip) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
-        # Convert PackageMetadata to hash via YAML round-trip
-        metadata_hash = YAML.safe_load(@metadata.to_yaml)
-
-        # Add operational metadata (not in PackageMetadata model)
-        metadata_hash["created_at"] = Time.now.utc.iso8601
-        metadata_hash["created_by"] = "lutaml-xmi v#{Lutaml::VERSION}"
-        metadata_hash["lutaml_version"] = Lutaml::VERSION
-        metadata_hash["statistics"] = @repository.statistics
-
-        # Ensure serialization_format is set
-        metadata_hash["serialization_format"] ||=
-          @options[:serialization_format].to_s
-
-        zip.get_output_stream("metadata.yaml") do |io|
-          io.write(YAML.dump(metadata_hash))
-        end
-      end
-
-      # Write the Document to the package.
-      #
-      # @param zip [Zip::File] The ZIP archive
-      # @return [void]
-      def write_document(zip)
-        zip.get_output_stream("repository.yaml") do |io|
-          io.write(@repository.document.to_yaml)
-        end
-      end
-
-      # Write indexes to the package.
-      #
-      # @param zip [Zip::File] The ZIP archive
-      # @return [void]
-      def write_indexes(zip)
-        zip.get_output_stream("indexes/all.yaml") do |io|
-          io.write(YAML.dump(@repository.indexes))
-        end
-      end
-
-      # Write index tree (searchable list of all model elements) to the package.
-      #
-      # @param zip [Zip::File] The ZIP archive
-      # @return [void]
-      def write_index_tree(zip)
-        tree = build_index_tree
-
-        zip.get_output_stream("index_tree.yaml") do |io|
-          io.write(YAML.dump(tree))
-        end
-      end
-
-      # Build a complete index tree of all model elements
-      #
-      # @return [Hash] Index tree structure
-      def build_index_tree # rubocop:disable Metrics/MethodLength
-        {
-          "format" => "lutaml_index_tree_v1",
-          "generated_at" => Time.now.utc.iso8601,
-          "packages" => build_packages_index,
-          "classes" => build_classes_index,
-          "summary" => {
-            "total_packages" => @repository.indexes[:package_paths].size,
-            "total_classes" => @repository.indexes[:qualified_names].size,
-            "total_attributes" => count_all_attributes,
-          },
-        }
-      end
-
-      # Build packages index
-      #
-      # @return [Hash] Packages indexed by path
-      def build_packages_index # rubocop:disable Metrics/MethodLength
-        packages = {}
-        @repository.indexes[:package_paths].each do |path, package|
-          next unless package.is_a?(Lutaml::Uml::Package)
-
-          packages[path] = {
-            "name" => package.name,
-            "xmi_id" => package.xmi_id,
-            "classes_count" => @repository
-              .classes_in_package(path, recursive: false).size,
-            "diagrams_count" => package.diagrams&.size || 0,
-          }
-        end
-        packages
-      end
-
-      # Build classes index
-      #
-      # @return [Hash] Classes indexed by qualified name
-      def build_classes_index # rubocop:disable Metrics/MethodLength
-        classes = {}
-        @repository.indexes[:qualified_names].each do |qname, klass|
-          classes[qname] = {
-            "name" => klass.name,
-            "xmi_id" => klass.xmi_id,
-            "type" => klass.class.name.split("::").last, # Class, DataType, Enum
-            "stereotype" => format_stereotype(klass.stereotype),
-            "attributes" => build_attributes_list(klass),
-            "package_path" => extract_package_path(qname),
-          }
-        end
-        classes
-      end
-
-      # Build attributes list for a class
-      #
-      # @param klass [Object] The class object
-      # @return [Array<Hash>] List of attributes
-      def build_attributes_list(klass)
-        return [] unless klass.is_a?(Lutaml::Uml::Classifier) && klass.attributes
-
-        klass.attributes.map do |attr|
-          {
-            "name" => attr.name,
-            "type" => attr.type,
-            "visibility" => attr.visibility,
-          }.compact
-        end
-      end
-
-      # Format stereotype for consistent output
-      #
-      # @param stereotype [String, Array, nil] Stereotype value
-      # @return [String, Array, nil] Formatted stereotype
-      def format_stereotype(stereotype)
-        return nil if stereotype.nil?
-        return stereotype if stereotype.is_a?(String)
-
-        stereotype.is_a?(Array) && stereotype.empty? ? nil : stereotype
-      end
-
-      # Extract package path from qualified name
-      #
-      # @param qname [String] Qualified name
-      # @return [String] Package path
-      def extract_package_path(qname)
-        parts = qname.split("::")
-        parts.size > 1 ? parts[0..-2].join("::") : "ModelRoot"
-      end
-
-      # Count all attributes across all classes
-      #
-      # @return [Integer] Total attribute count
-      def count_all_attributes
-        total = 0
-        @repository.indexes[:qualified_names].each_value do |klass|
-          if klass.is_a?(Lutaml::Uml::Classifier) && klass.attributes
-            total += klass.attributes.size
-          end
-        end
-        total
-      end
-
-      # Write statistics to the package.
-      #
-      # @param zip [Zip::File] The ZIP archive
-      # @return [void]
-      def write_statistics(zip)
-        zip.get_output_stream("statistics.yaml") do |io|
-          io.write(YAML.dump(@repository.statistics))
-        end
-      end
-    end
-  end
-end