lutaml 0.9.43 → 0.10.1

data/lib/lutaml/uml_repository/package_loader.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+require "zip"
+require "yaml"
+require_relative "../uml"
+require_relative "package_metadata"
+
+module Lutaml
+  module UmlRepository
+    # PackageLoader handles loading UmlRepository instances from LUR
+    # (LutaML UML Repository) package files.
+    #
+    # LUR packages are ZIP archives that contain pre-serialized repositories
+    # for fast loading without re-parsing XMI files.
+    #
+    # @example Load from package
+    #   repository = PackageLoader.load("model.lur")
+    #   klass = repository.find_class("ModelRoot::MyClass")
+    class PackageLoader
+      # Load a UmlRepository from a LUR package file.
+      #
+      # @param lur_path [String] Path to the .lur package file
+      # @return [UmlRepository] A loaded repository instance
+      # @raise [ArgumentError] If the package file doesn't exist
+      # @raise [RuntimeError] If the package is invalid or corrupted
+      # @example
+      #   repo = PackageLoader.load("model.lur")
+      def self.load(lur_path) # rubocop:disable Metrics/MethodLength
+        unless File.exist?(lur_path)
+          raise ArgumentError, "Package file not found: #{lur_path}"
+        end
+
+        document = nil
+        indexes = nil
+        metadata = nil
+
+        begin
+          Zip::File.open(lur_path) do |zip|
+            # Read metadata (now returns PackageMetadata)
+            metadata = load_metadata(zip)
+
+            # Load Document based on format
+            document = load_document(zip, metadata)
+
+            # Load indexes
+            indexes = load_indexes(zip)
+          end
+        rescue Zip::Error => e
+          raise "Invalid LUR package: #{e.message}"
+        rescue StandardError => e
+          raise "Failed to load package: #{e.message}"
+        end
+
+        # Create repository with loaded data and metadata
+        Repository.new(document: document, indexes: indexes, metadata: metadata)
+      end
+
+      # Load only the document from a LUR package without building indexes.
+      #
+      # This method loads the document but does not load or build indexes,
+      # returning a LazyRepository instance that will build indexes on-demand.
+      #
+      # @param lur_path [String] Path to the .lur package file
+      # @return [LazyRepository] A lazy repository instance
+      # @raise [ArgumentError] If the package file doesn't exist
+      # @raise [RuntimeError] If the package is invalid or corrupted
+      # @example
+      #   repo = PackageLoader.load_document_only("model.lur")
+      def self.load_document_only(lur_path) # rubocop:disable Metrics/MethodLength
+        unless File.exist?(lur_path)
+          raise ArgumentError, "Package file not found: #{lur_path}"
+        end
+
+        document = nil
+        metadata = nil
+
+        begin
+          Zip::File.open(lur_path) do |zip|
+            # Read metadata (now returns PackageMetadata)
+            metadata = load_metadata(zip)
+
+            # Load Document based on format
+            document = load_document(zip, metadata)
+          end
+        rescue Zip::Error => e
+          raise "Invalid LUR package: #{e.message}"
+        rescue StandardError => e
+          raise "Failed to load package: #{e.message}"
+        end
+
+        # Create lazy repository without indexes but with metadata
+        require_relative "../lazy_repository"
+        LazyRepository.new(document: document, lazy: true, metadata: metadata)
+      end
+
+      # Load metadata from the package.
+      #
+      # @param zip [Zip::File] The ZIP archive
+      # @return [PackageMetadata] The package metadata object
+      # @raise [RuntimeError] If metadata is missing or invalid
+      def self.load_metadata(zip) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength
+        metadata_entry = zip.find_entry("metadata.yaml")
+        unless metadata_entry
+          raise "Invalid LUR package: missing metadata.yaml"
+        end
+
+        # Permit all Lutaml::Uml classes for safe loading
+        uml_constants = Lutaml::Uml.constants
+        uml_classes = uml_constants.filter_map do |const_name|
+          constant_value = Lutaml::Uml.const_get(const_name)
+          constant_value if constant_value.is_a?(Class)
+        end
+        permitted_classes = [Symbol, Time, Date, DateTime, uml_classes].flatten
+
+        # Load full metadata hash (includes operational fields)
+        metadata_hash = YAML.safe_load(
+          metadata_entry.get_input_stream.read,
+          permitted_classes: permitted_classes,
+          aliases: true,
+        )
+
+        # Extract only PackageMetadata fields and normalize to symbols
+        package_fields = %w[
+          name version publisher license description keywords
+          homepage authors maintainers serialization_format
+        ]
+
+        metadata_attrs = {}
+        package_fields.each do |field|
+          if metadata_hash.key?(field)
+            metadata_attrs[field.to_sym] =
+              metadata_hash[field]
+          end
+        end
+
+        # Create PackageMetadata using lutaml-model constructor
+        PackageMetadata.new(**metadata_attrs)
+      rescue Psych::SyntaxError => e
+        raise "Invalid metadata format: #{e.message}"
+      end
+
+      # Load the Document from the package.
+      #
+      # @param zip [Zip::File] The ZIP archive
+      # @param metadata [PackageMetadata] The package metadata
+      # @return [Lutaml::Uml::Document] The loaded document
+      # @raise [RuntimeError] If document is missing or format is unknown
+      def self.load_document(zip, metadata) # rubocop:disable Metrics/MethodLength
+        # Handle both PackageMetadata object and Hash (backward compatibility)
+        format = if metadata.respond_to?(:serialization_format)
+                   metadata.serialization_format
+                 else
+                   metadata["serialization_format"] ||
+                     metadata[:serialization_format]
+                 end
+
+        case format.to_s
+        when "yaml"
+          load_yaml_document(zip)
+        when "marshal"
+          load_marshal_document(zip)
+        else
+          raise "Unknown serialization format: #{format}"
+        end
+      end
+
+      # Load Document from YAML format.
+      #
+      # @param zip [Zip::File] The ZIP archive
+      # @return [Lutaml::Uml::Document] The loaded document
+      # @raise [RuntimeError] If document file is missing
+      def self.load_yaml_document(zip)
+        entry = zip.find_entry("repository.yaml")
+        unless entry
+          raise "Invalid LUR package: missing repository.yaml"
+        end
+
+        Lutaml::Uml::Document.from_yaml(entry.get_input_stream.read)
+      rescue StandardError => e
+        raise "Failed to load YAML document: #{e.message}"
+      end
+
+      # Load Document from Marshal format.
+      #
+      # @param zip [Zip::File] The ZIP archive
+      # @return [Lutaml::Uml::Document] The loaded document
+      # @raise [RuntimeError] If document file is missing
+      def self.load_marshal_document(zip)
+        entry = zip.find_entry("repository.marshal")
+        unless entry
+          raise "Invalid LUR package: missing repository.marshal"
+        end
+
+        Marshal.load(entry.get_input_stream.read)
+      rescue StandardError => e
+        raise "Failed to load Marshal document: #{e.message}"
+      end
+
+      # Load indexes from the package.
+      #
+      # @param zip [Zip::File] The ZIP archive
+      # @return [Hash] The loaded indexes
+      # @raise [RuntimeError] If indexes are missing
+      def self.load_indexes(zip)
+        entry = zip.find_entry("indexes/all.marshal")
+        unless entry
+          raise "Invalid LUR package: missing indexes/all.marshal"
+        end
+
+        Marshal.load(entry.get_input_stream.read)
+      rescue StandardError => e
+        raise "Failed to load indexes: #{e.message}"
+      end
+
+      private_class_method :load_metadata, :load_document,
+                           :load_yaml_document, :load_marshal_document,
+                           :load_indexes
+    end
+  end
+end

data/lib/lutaml/uml_repository/package_metadata.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Lutaml
+  module UmlRepository
+    # PackageMetadata holds metadata about a LUR package.
+    #
+    # This class provides structured metadata that can be embedded in LUR
+    # (LutaML UML Repository) packages, including information about the package
+    # name, version, publisher, licensing, and other descriptive information.
+    #
+    # Metadata is stored in the package's metadata.yaml file and can be
+    # specified when building packages via CLI or API.
+    #
+    # @example Creating metadata programmatically
+    #   metadata = PackageMetadata.new(
+    #     name: "Urban Planning Model",
+    #     version: "2.3.0",
+    #     publisher: "City Planning Department",
+    #     license: "CC-BY-4.0",
+    #     description: "UML model for urban planning workflows",
+    #     keywords: "urban, planning, infrastructure",
+    #     homepage: "https://example.com/urban-model",
+    #     authors: ["Jane Doe", "John Smith"],
+    #     maintainers: "planning-team@example.com"
+    #   )
+    #
+    # @example Validating metadata
+    #   metadata.validate!  # Raises error if name or version missing
+    #
+    # @example Serializing to YAML
+    #   yaml = metadata.to_yaml
+    #
+    # @example Loading from YAML
+    #   metadata = PackageMetadata.from_yaml(yaml_string)
+    class PackageMetadata < Lutaml::Model::Serializable
+      attribute :name, :string
+      attribute :version, :string
+      attribute :publisher, :string
+      attribute :license, :string
+      attribute :description, :string
+      attribute :keywords, :string
+      attribute :homepage, :string
+      attribute :authors, :string, collection: true, default: -> { [] }
+      attribute :maintainers, :string
+      attribute :serialization_format, :string
+
+      key_value do
+        map "name", to: :name
+        map "version", to: :version
+        map "publisher", to: :publisher
+        map "license", to: :license
+        map "description", to: :description
+        map "keywords", to: :keywords
+        map "homepage", to: :homepage
+        map "authors", to: :authors
+        map "maintainers", to: :maintainers
+        map "serialization_format", to: :serialization_format
+      end
+
+      # Validate that required fields are present.
+      #
+      # @return [Array<Lutaml::Model::Error>] Array of validation errors
+      def validate(*)
+        errors = []
+        if name.nil? || name.empty?
+          errors << Lutaml::Model::Error.new("name is required")
+        end
+        if version.nil? || version.empty?
+          errors << Lutaml::Model::Error.new("version is required")
+        end
+        errors
+      end
+    end
+  end
+end

data/lib/lutaml/uml_repository/presenters/association_presenter.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "element_presenter"
+require_relative "presenter_factory"
+
+module Lutaml
+  module UmlRepository
+    module Presenters
+      # Presenter for UML Association elements.
+      #
+      # Formats association information including source, target, and roles.
+      class AssociationPresenter < ElementPresenter
+        def initialize(element, repository = nil, context = nil)
+          super
+        end
+
+        def to_text # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+          lines = []
+          lines << "Association: #{element.name || '(unnamed)'}"
+          lines << ("=" * 50)
+          lines << ""
+          lines << "Name:          #{element.name || '(unnamed)'}"
+          if element.respond_to?(:xmi_id)
+            lines << "XMI ID:        #{element.xmi_id}"
+          end
+          if element.respond_to?(:xmi_type)
+            lines << "Type:          #{element.xmi_type}"
+          end
+          lines << ""
+          lines << "Source:        #{source_display}"
+          lines << "Target:        #{target_display}"
+          lines.join("\n")
+        end
+
+        def to_table_row
+          {
+            type: "Association",
+            name: element.name || "(unnamed)",
+            details: "#{source_display} → #{target_display}",
+          }
+        end
+
+        def to_hash
+          data = {
+            type: "Association",
+            name: element.name,
+            source: source_display,
+            target: target_display,
+          }
+
+          data[:xmi_id] = element.xmi_id if element.respond_to?(:xmi_id)
+          data[:xmi_type] = element.xmi_type if element.respond_to?(:xmi_type)
+
+          data
+        end
+
+        private
+
+        def source_display
+          @context["source"] || @context[:source] ||
+            element.owner_end || "Unknown"
+        end
+
+        def target_display # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+          # Check string key first (from search),
+          # then symbol key (from show command)
+          if @context["target"] || @context[:target]
+            @context["target"] || @context[:target]
+          elsif element.respond_to?(:member_end) && element.member_end
+            member_end = element.member_end.first
+            if member_end.is_a?(Hash)
+              member_end[:xmi_type] || "Unknown"
+            else
+              member_end.to_s
+            end
+          else
+            "Unknown"
+          end
+        end
+      end
+
+      # Register with factory
+      PresenterFactory.register(Lutaml::Uml::Association, AssociationPresenter)
+    end
+  end
+end

data/lib/lutaml/uml_repository/presenters/attribute_presenter.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require_relative "element_presenter"
+require_relative "presenter_factory"
+
+module Lutaml
+  module UmlRepository
+    module Presenters
+      # Presenter for UML Attribute elements.
+      #
+      # Formats attribute information including type, cardinality, and owning
+      # class.
+      class AttributePresenter < ElementPresenter
+        def initialize(element, repository = nil, context = nil)
+          super
+        end
+
+        def to_text # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength
+          lines = []
+          lines << "Attribute: #{qualified_name}"
+          lines << ("=" * 50)
+          lines << ""
+          lines << "Name:          #{element.name}"
+          lines << "Class:         #{class_name}"
+          lines << "Type:          #{element.type || 'Unknown'}"
+          lines << "Cardinality:   #{format_cardinality(element)}"
+          if element.respond_to?(:visibility) && element.visibility
+            lines << "Visibility:    #{element.visibility}"
+          end
+          if element.respond_to?(:stereotype) && element.stereotype
+            lines << "Stereotype:    #{element.stereotype}"
+          end
+          if element.respond_to?(:is_derived)
+            lines << "Is Derived:    #{element.is_derived}"
+          end
+          lines.join("\n")
+        end
+
+        def to_table_row
+          {
+            type: "Attribute",
+            name: element.name || "(unnamed)",
+            details: "#{class_name}::#{element.name} : #{element.type}",
+          }
+        end
+
+        def to_hash # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+          data = {
+            type: "Attribute",
+            name: element.name,
+            class_name: class_name,
+            attr_type: element.type,
+            cardinality: format_cardinality(element),
+          }
+
+          if element.respond_to?(:visibility)
+            data[:visibility] = element.visibility
+          end
+          if element.respond_to?(:stereotype)
+            data[:stereotype] = element.stereotype
+          end
+          if element.respond_to?(:is_derived)
+            data[:is_derived] = element.is_derived
+          end
+
+          data
+        end
+
+        private
+
+        def class_name
+          @context["class_name"] ||
+            @context[:class_name] || extract_class_from_qname
+        end
+
+        def qualified_name
+          @context["qualified_name"] ||
+            @context[:qualified_name] || "#{class_name}::#{element.name}"
+        end
+
+        def extract_class_from_qname
+          qname = @context["class_qname"] || @context[:class_qname]
+          return "Unknown" unless qname
+
+          parts = qname.split("::")
+          parts.last
+        end
+      end
+
+      # Register with factory
+      PresenterFactory.register(
+        Lutaml::Uml::TopElementAttribute,
+        AttributePresenter,
+      )
+      # Also register common attribute base class
+      if defined?(Lutaml::Uml::Attribute)
+        PresenterFactory.register(Lutaml::Uml::Attribute, AttributePresenter)
+      end
+    end
+  end
+end

data/lib/lutaml/uml_repository/presenters/class_presenter.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative "element_presenter"
+require_relative "presenter_factory"
+
+module Lutaml
+  module UmlRepository
+    module Presenters
+      # Presenter for UML Class elements.
+      #
+      # Formats class information for different output types:
+      # text, table rows, and structured data.
+      class ClassPresenter < ElementPresenter
+        # Generate detailed text view.
+        #
+        # @return [String] Multi-line formatted text
+        def to_text # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+          lines = []
+          lines << "Class: #{element.name}"
+          lines << ("=" * 50)
+          lines << ""
+          lines << "Name:        #{element.name}"
+          lines << "XMI ID:      #{element.xmi_id}" if
+            element.xmi_id
+          lines << "Stereotype:  #{element.stereotype}" if
+            element.stereotype
+          lines << "Abstract:    #{element.is_abstract}"
+          lines.join("\n")
+        end
+
+        # Generate table row data.
+        #
+        # @return [Hash] Row data with :type, :name, :details keys
+        def to_table_row
+          {
+            type: "Class",
+            name: element.name || "(unnamed)",
+            details: stereotype_display,
+          }
+        end
+
+        # Generate structured hash.
+        #
+        # @return [Hash] Structured representation
+        def to_hash # rubocop:disable Metrics/AbcSize
+          data = {
+            type: "Class",
+            name: element.name,
+            is_abstract: !!element.is_abstract,
+          }
+
+          data[:xmi_id] = element.xmi_id if element.xmi_id
+          if element.stereotype
+            data[:stereotype] = element.stereotype
+          end
+
+          data
+        end
+
+        private
+
+        def stereotype_display
+          if element.respond_to?(:stereotype) && element.stereotype
+            "<<#{element.stereotype}>>"
+          else
+            ""
+          end
+        end
+      end
+
+      # Register with factory
+      PresenterFactory.register(Lutaml::Uml::Class, ClassPresenter)
+    end
+  end
+end

data/lib/lutaml/uml_repository/presenters/datatype_presenter.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require_relative "element_presenter"
+require_relative "presenter_factory"
+
+module Lutaml
+  module UmlRepository
+    module Presenters
+      # Presenter for UML DataType elements.
+      #
+      # Formats data type information including attributes and operations.
+      class DataTypePresenter < ElementPresenter
+        def initialize(element, repository = nil, context = nil)
+          super
+        end
+
+        def to_text # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+          lines = []
+          lines << "DataType: #{element.name}"
+          lines << ("=" * 50)
+          lines << ""
+          lines << "Name:          #{element.name}"
+          if element.respond_to?(:xmi_id) && element.xmi_id
+            lines << "XMI ID:        #{element.xmi_id}"
+          end
+          if element.respond_to?(:type) && element.type
+            lines << "Type:          #{element.type}"
+          end
+          if element.respond_to?(:stereotype) && element.stereotype
+            lines << "Stereotype:    #{element.stereotype}"
+          end
+          if element.respond_to?(:visibility) && element.visibility
+            lines << "Visibility:    #{element.visibility}"
+          end
+          if element.respond_to?(:is_abstract)
+            lines << "Abstract:      #{element.is_abstract}"
+          end
+          lines << ""
+
+          if element.attributes && !element.attributes.empty?
+            lines << "Attributes (#{element.attributes.size}):"
+            element.attributes.each do |attr|
+              type_info = attr.type ? " : #{attr.type}" : ""
+              lines << "  - #{attr.name}#{type_info}"
+            end
+            lines << ""
+          end
+
+          if element.respond_to?(:operations) && element.operations &&
+              !element.operations.empty?
+            lines << "Operations (#{element.operations.size}):"
+            element.operations.each do |op|
+              lines << "  - #{op.name}()"
+            end
+          end
+
+          lines.join("\n")
+        end
+
+        def to_table_row
+          attr_count = element.attributes ? element.attributes.size : 0
+          {
+            type: "DataType",
+            name: element.name || "(unnamed)",
+            details: "#{attr_count} attribute(s)",
+          }
+        end
+
+        def to_hash # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+          data = {
+            type: "DataType",
+            name: element.name,
+          }
+
+          data[:xmi_id] = element.xmi_id if
+            element.respond_to?(:xmi_id) && element.xmi_id
+          data[:data_type] = element.type if
+            element.respond_to?(:type) && element.type
+          data[:stereotype] = element.stereotype if
+            element.respond_to?(:stereotype) && element.stereotype
+          data[:visibility] = element.visibility if
+            element.respond_to?(:visibility) && element.visibility
+          data[:is_abstract] = element.is_abstract if
+            element.respond_to?(:is_abstract)
+
+          if element.attributes && !element.attributes.empty?
+            data[:attributes] = element.attributes.map do |attr|
+              {
+                name: attr.name,
+                type: attr.type,
+              }
+            end
+          end
+
+          if element.respond_to?(:operations) && element.operations &&
+              !element.operations.empty?
+            data[:operations] = element.operations.map(&:name)
+          end
+
+          data
+        end
+      end
+
+      # Register with factory
+      PresenterFactory.register(Lutaml::Uml::DataType, DataTypePresenter)
+    end
+  end
+end