ea 0.1.5 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c45bd1d6024b9307f1d67422299289da426b353aa7ab7b9797d8d577b61529a9
-  data.tar.gz: afaf525893ce02307e0fe4f6ab2242b8f0d27d9b3e618db56f1d026b8a0e17ac
+  metadata.gz: 6322d6dfb8ed1b7c957b25ed522ccf6598350a88653e9e44acd0dfb79c2e61b3
+  data.tar.gz: 88be8b7cfc39592348c422bd4277f5d4bd97ec827bef29d0f40bb12c6dc5d9eb
 SHA512:
-  metadata.gz: ae6d56dde262515befe5225a721fa2fca37f50e6162efd48eca52cce324508f18df1f0d916264ba531a57e3cc5a4c6a88818bd03fb33b0639129afce0e3a5aef
-  data.tar.gz: 3ef8943ff38d4ed3c5494f27b29dffc525d1311a47d1452e49f6e34f5147571175d11a26c3931c0d37344b440764584eb184e5e1433b7bbe8d8b90abd40ac8e7
+  metadata.gz: 0a4219aa40e69edc0f5bcf956d01592d203928612345ae35fac33b8fa4bf610c1615fb3bae4a82788d87d3dd4198ed9808abfd080468e79d68c42f869e2f97b2
+  data.tar.gz: 5429e2a0281d4aa1efbe7358e64975a017660f060fcb1ecc76ad07f4eb2f992115ee9b0dc1fa1dcb2b53e114a8741b43040a4cdcb00c95d2cf5a07db6e81ca02

data/CLAUDE.md

@@ -16,14 +16,42 @@ usable standalone — `lutaml-uml` is an optional dependency for the UML bridge.
 
 **Dependency graph**:
 ```
-ea (standalone — sqlite3, rubyzip, nokogiri, xmi, liquid)
-  └── [optional] lutaml-uml (for Ea::Qea.to_uml bridge → Lutaml::Uml::Document)
+ea (standalone — lutaml-model, lutaml-path, sqlite3, rubyzip, xmi, nokogiri, liquid, thor)
+  └── [optional, dev] lutaml-uml (for Ea::Bridge::* → Lutaml::Uml::Document)
 
 lutaml-uml (UML metamodel + UmlRepository + SPA — no dependency on ea)
   └── lutaml-lml
           └── lutaml (meta-bundle)
 ```
 
+**Architecture — pure parse vs bridge**:
+
+The ea gem has TWO entry points:
+
+```ruby
+# PURE — no lutaml-uml dependency. Returns internal EA model.
+Ea.parse("model.qea")   # → Ea::Qea::Database (SQLite tables as Ruby models)
+Ea.parse("model.xmi")   # → Xmi::Sparx::Root   (xmi gem's typed Sparx model)
+
+# BRIDGE — requires optional lutaml-uml. Returns tool-agnostic UML.
+Ea.to_uml("model.qea")  # → Lutaml::Uml::Document (for cross-vendor output)
+Ea.to_uml("model.xmi")  # → Lutaml::Uml::Document
+```
+
+All lutaml-uml-dependent code lives under `Ea::Bridge::*`:
+- `Ea::Bridge::QeaToUml` — transforms Ea::Qea::Database → Lutaml::Uml::Document
+- `Ea::Bridge::XmiToUml` — transforms Xmi::Sparx::Root → Lutaml::Uml::Document
+
+The bridge is lazy-loaded — `require "ea"` does NOT load lutaml-uml. Only calling
+`Ea.to_uml(...)` (or CLI commands that use it: `ea spa`, `ea diagrams extract`)
+triggers the bridge code path.
+
+**Native QEA↔XMI round-trip** (no lutaml-uml):
+```
+Ea::Transformers::QeaToXmi  — Ea::Qea::Database → Sparx XMI string
+Ea::Transformers::UmlToXmi  — Lutaml::Uml::Document → Sparx XMI (bridge)
+```
+
 **XMI parsing**: `Ea::Xmi::Parser` is hard-wired to the Sparx schema
 (`::Xmi::Sparx::Root.parse_xml`). It cannot parse MagicDraw or Papyrus XMI.
 When registering with `UmlRepository`, `ea` registers `.xmi` with content

data/lib/ea/bridge/qea_to_uml.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Ea
+  module Bridge
+    # Transforms an `Ea::Qea::Database` into a `Lutaml::Uml::Document`.
+    #
+    # This is the bridge between ea's internal EA-native representation
+    # (the SQLite-derived row models) and the tool-agnostic UML
+    # metamodel from `lutaml-uml`.
+    #
+    # The heavy lifting is done by the existing factory classes under
+    # `Ea::Qea::Factory::*`. This module is the clean public entry
+    # point — consumers should call `Ea::Bridge::QeaToUml.transform(db)`
+    # rather than reaching into the factory internals.
+    module QeaToUml
+      module_function
+
+      # @param database [Ea::Qea::Database] loaded QEA database
+      # @param options [Hash] transformation options
+      # @return [Lutaml::Uml::Document]
+      def transform(database, options = {})
+        require_lutaml_uml!
+        factory(database, options).create_document
+      end
+
+      def require_lutaml_uml!
+        require "lutaml/uml"
+      rescue LoadError => e
+        raise Ea::Error,
+              "Ea::Bridge requires the `lutaml-uml` gem. " \
+              "Install it via `gem install lutaml-uml`. (#{e.message})"
+      end
+
+      def factory(database, options)
+        Ea::Qea::Factory::EaToUmlFactory.new(database, options)
+      end
+    end
+  end
+end

data/lib/ea/bridge/xmi_to_uml.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Ea
+  module Bridge
+    # Transforms an `Xmi::Sparx::Root` (the xmi gem's typed Sparx XMI
+    # model) into a `Lutaml::Uml::Document`.
+    #
+    # This is the bridge between ea's internal XMI representation
+    # (the xmi gem's model tree) and the tool-agnostic UML metamodel
+    # from `lutaml-uml`.
+    #
+    # The heavy lifting is done by the existing parser code in
+    # `Ea::Xmi::Parser`. This module is the clean public entry point
+    # — consumers should call `Ea::Bridge::XmiToUml.transform(root)`
+    # rather than reaching into the parser internals.
+    module XmiToUml
+      module_function
+
+      # @param xmi_root [Xmi::Sparx::Root] parsed xmi gem model
+      # @return [Lutaml::Uml::Document]
+      def transform(xmi_root)
+        require_lutaml_uml!
+        Ea::Xmi::Parser.new.parse(xmi_root)
+      end
+
+      def require_lutaml_uml!
+        require "lutaml/uml"
+      rescue LoadError => e
+        raise Ea::Error,
+              "Ea::Bridge requires the `lutaml-uml` gem. " \
+              "Install it via `gem install lutaml-uml`. (#{e.message})"
+      end
+    end
+  end
+end

data/lib/ea/bridge.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Ea
+  # The bridge namespace contains ALL code that depends on the
+  # optional `lutaml-uml` gem. The rest of the ea gem is pure
+  # Sparx EA parsing (QEA SQLite, Sparx XMI) and does NOT require
+  # lutaml-uml.
+  #
+  # The bridge transforms ea's internal model representations:
+  #
+  #   Ea::Qea::Database  ──→  Lutaml::Uml::Document
+  #   Xmi::Sparx::Root   ──→  Lutaml::Uml::Document
+  #
+  # This is the "transformation" layer for cross-vendor UML output.
+  # It is NOT needed for:
+  #   - Parsing QEA/XMI files
+  #   - Converting QEA ↔ XMI (native Sparx round-trip)
+  #   - Listing diagrams, elements, stats
+  #
+  # It IS needed for:
+  #   - Generating a SPA (via lutaml-uml's StaticSite::Generator)
+  #   - Rendering diagrams to SVG (via lutaml-uml's Repository)
+  #   - Producing tool-agnostic UML output for non-Sparx consumers
+  module Bridge
+    autoload :QeaToUml, "ea/bridge/qea_to_uml"
+    autoload :XmiToUml, "ea/bridge/xmi_to_uml"
+  end
+end

data/lib/ea/cli/command/repository_builder.rb

@@ -29,7 +29,7 @@ module Ea
             return Lutaml::UmlRepository::Repository.from_file(path)
           end
 
-          document = Ea::Transformations.parse(path)
+          document = Ea::Transformations.to_uml(path)
           require_lutaml_uml_repository!
           Lutaml::UmlRepository::Repository.from_document(document)
         end

data/lib/ea/cli/command/spa.rb

@@ -10,7 +10,7 @@ module Ea
       # details, diagram list, and member navigation in a browser.
       #
       # Pipeline:
-      #   1. Ea::Transformations.parse(file) → Lutaml::Uml::Document
+      #   1. Ea::Transformations.to_uml(file) → Lutaml::Uml::Document
       #   2. Lutaml::UmlRepository::Repository.from_document(document)
       #   3. Lutaml::UmlRepository::StaticSite::Generator.new(repo, ...).generate
       #

data/lib/ea/diagram/extractor.rb

@@ -497,24 +497,30 @@ module Ea
           }
         end
 
-        # Determine element type from UML element
+        # Determine element type from UML element. Lazy-resolves
+        # Lutaml::Uml::* classes so the file loads cleanly without
+        # lutaml-uml installed.
         def element_type(uml_element)
+          return "unknown" unless defined?(::Lutaml::Uml)
+
           case uml_element
-          when Lutaml::Uml::UmlClass then "class"
-          when Lutaml::Uml::Package then "package"
-          when Lutaml::Uml::DataType then "datatype"
-          when Lutaml::Uml::Enum then "enumeration"
-          when Lutaml::Uml::Instance then "instance"
+          when ::Lutaml::Uml::UmlClass then "class"
+          when ::Lutaml::Uml::Package then "package"
+          when ::Lutaml::Uml::DataType then "datatype"
+          when ::Lutaml::Uml::Enum then "enumeration"
+          when ::Lutaml::Uml::Instance then "instance"
           else "unknown"
           end
         end
 
         # Determine connector type
         def connector_type(connector)
+          return "connector" unless defined?(::Lutaml::Uml)
+
           case connector
-          when Lutaml::Uml::Association then "association"
-          when Lutaml::Uml::Generalization then "generalization"
-          when Lutaml::Uml::Dependency then "dependency"
+          when ::Lutaml::Uml::Association then "association"
+          when ::Lutaml::Uml::Generalization then "generalization"
+          when ::Lutaml::Uml::Dependency then "dependency"
           else "connector"
           end
         end

data/lib/ea/diagram/style_resolver.rb

@@ -231,13 +231,7 @@ module Ea
         end
 
         # Maps UML connector classes to their style type names.
-        # New connector types are added here — no method changes needed.
-        CONNECTOR_TYPE_MAP = {
-          Lutaml::Uml::Generalization => "generalization",
-          Lutaml::Uml::Association => "association",
-          Lutaml::Uml::Dependency => "dependency",
-          Lutaml::Uml::Realization => "realization",
-        }.freeze
+        # Built lazily — see {#connector_type_map}.
 
         # Association sub-type precedence for style resolution
         ASSOCIATION_SUBTYPE_MAP = {
@@ -251,18 +245,39 @@ module Ea
         def determine_connector_type(connector)
           return "association" unless connector
 
-          type_name = CONNECTOR_TYPE_MAP[connector.class]
+          type_name = connector_type_map[connector.class]
           return type_name if type_name && type_name != "association"
           return determine_association_type(connector) if type_name == "association"
 
           "association"
         end
 
+        # Maps UML connector classes to their style type names.
+        # Built lazily on first call so the resolver can be loaded
+        # without `lutaml/uml` installed (the ea gem is standalone;
+        # lutaml-uml is an optional bridge dependency). Adding a new
+        # connector type = adding one entry here.
+        def connector_type_map
+          @connector_type_map ||= build_connector_type_map
+        end
+
+        def build_connector_type_map
+          map = {}
+          return map unless defined?(::Lutaml::Uml)
+
+          map[::Lutaml::Uml::Generalization] = "generalization"
+          map[::Lutaml::Uml::Association] = "association"
+          map[::Lutaml::Uml::Dependency] = "dependency"
+          map[::Lutaml::Uml::Realization] = "realization"
+          map
+        end
+
         # Determine specific association type
         # @param connector [Object] Association connector
         # @return [String] Specific association type
         def determine_association_type(connector)
-          return "association" unless connector.is_a?(Lutaml::Uml::Association)
+          return "association" unless defined?(::Lutaml::Uml::Association)
+          return "association" unless connector.is_a?(::Lutaml::Uml::Association)
 
           [connector.owner_end_type, connector.member_end_type].each do |type|
             resolved = ASSOCIATION_SUBTYPE_MAP[type&.downcase]

data/lib/ea/transformations.rb

@@ -33,8 +33,57 @@ module Ea
         @engine = engine
       end
 
+      # Parse an EA file into its native representation.
+      #
+      # Pure entry point — does NOT require `lutaml-uml`. Returns:
+      #   .qea → Ea::Qea::Database
+      #   .xmi → Xmi::Sparx::Root
+      #
+      # To get a Lutaml::Uml::Document instead, use {to_uml}.
+      #
+      # @param file_path [String] path to a .qea or .xmi file
+      # @param options [Hash] parser options (e.g. config: for QEA)
+      # @return [Ea::Qea::Database, Xmi::Sparx::Root]
       def parse(file_path, options = {})
-        engine.parse(file_path, options)
+        ext = File.extname(file_path).downcase
+        case ext
+        when ".qea"
+          Ea::Qea.load(file_path, options[:config])
+        when ".xmi", ".xml"
+          Ea::Xmi.load(file_path)
+        else
+          raise Ea::Error,
+                "Unsupported file extension #{ext.inspect}. " \
+                "Supported: .qea, .xmi"
+        end
+      end
+
+      # Transform an EA file (or pre-parsed model) into a
+      # `Lutaml::Uml::Document`.
+      #
+      # Bridge entry point — requires the optional `lutaml-uml` gem.
+      # Lazy-loads the bridge code on first call.
+      #
+      # @param path_or_model [String, Ea::Qea::Database, Xmi::Sparx::Root]
+      # @param options [Hash] transformation options
+      # @return [Lutaml::Uml::Document]
+      def to_uml(path_or_model, options = {})
+        model = if path_or_model.is_a?(String)
+                  parse(path_or_model, options)
+                else
+                  path_or_model
+                end
+
+        case model
+        when Ea::Qea::Database
+          Ea::Bridge::QeaToUml.transform(model, options)
+        when ::Xmi::Sparx::Root
+          Ea::Bridge::XmiToUml.transform(model)
+        else
+          raise Ea::Error,
+                "Cannot transform #{model.class} to Lutaml::Uml::Document. " \
+                "Expected Ea::Qea::Database or Xmi::Sparx::Root."
+        end
       end
 
       def detect_parser(file_path)

data/lib/ea/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Ea
-  VERSION = "0.1.5"
+  VERSION = "0.1.6"
 end

data/lib/ea/xmi.rb

@@ -31,5 +31,22 @@ module Ea
       autoload :ConnectorDrop, "ea/xmi/liquid_drops/connector_drop"
       autoload :SourceTargetDrop, "ea/xmi/liquid_drops/source_target_drop"
     end
+
+    module_function
+
+    # Parse an XMI file into the xmi gem's typed Sparx model.
+    #
+    # Pure entry point — does NOT require `lutaml-uml`. Returns the
+    # `Xmi::Sparx::Root` model tree from the `xmi` gem. This is the
+    # internal EA-native representation for XMI files.
+    #
+    # To get a `Lutaml::Uml::Document` instead (requires the optional
+    # `lutaml-uml` gem), use `Ea::Bridge::XmiToUml.transform(root)`.
+    #
+    # @param path [String] path to a .xmi file
+    # @return [Xmi::Sparx::Root]
+    def load(path)
+      ::Xmi::Sparx::Root.parse_xml(File.read(path))
+    end
   end
 end

data/lib/ea.rb

@@ -13,5 +13,36 @@ module Ea
   autoload :Transformations, "ea/transformations"
   autoload :Xmi, "ea/xmi"
   autoload :Transformers, "ea/transformers"
+  autoload :Bridge, "ea/bridge"
   autoload :Cli, "ea/cli"
+
+  class << self
+    # Parse an EA file into its native representation.
+    #
+    # Pure entry point — does NOT require the optional `lutaml-uml`
+    # gem. The return type depends on the input format:
+    #
+    #   .qea → Ea::Qea::Database (Sparx SQLite tables as Ruby models)
+    #   .xmi → Xmi::Sparx::Root   (typed Sparx XMI model from the xmi gem)
+    #
+    # @param path [String] path to a .qea or .xmi file
+    # @return [Ea::Qea::Database, Xmi::Sparx::Root]
+    def parse(path)
+      Transformations.parse(path)
+    end
+
+    # Transform an EA file (or pre-parsed model) into a
+    # `Lutaml::Uml::Document`.
+    #
+    # Bridge entry point — requires the optional `lutaml-uml` gem.
+    # Used for cross-vendor UML output (e.g. EA → PlantUML via the
+    # tool-agnostic UML metamodel). The lutaml-uml dependency is
+    # lazy-required on first call.
+    #
+    # @param path_or_model [String, Ea::Qea::Database, Xmi::Sparx::Root]
+    # @return [Lutaml::Uml::Document]
+    def to_uml(path_or_model)
+      Transformations.to_uml(path_or_model)
+    end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ea
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.6
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-07 00:00:00.000000000 Z
+date: 2026-07-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: lutaml-model
@@ -238,6 +238,9 @@ files:
 - examples/smoke_test_real_qea.rb
 - exe/ea
 - lib/ea.rb
+- lib/ea/bridge.rb
+- lib/ea/bridge/qea_to_uml.rb
+- lib/ea/bridge/xmi_to_uml.rb
 - lib/ea/cli.rb
 - lib/ea/cli/app.rb
 - lib/ea/cli/command.rb