ea 0.1.5 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c45bd1d6024b9307f1d67422299289da426b353aa7ab7b9797d8d577b61529a9
-  data.tar.gz: afaf525893ce02307e0fe4f6ab2242b8f0d27d9b3e618db56f1d026b8a0e17ac
+  metadata.gz: af7f7d010d0ca70a7230803dfd39e5037fda7f983e532ee6e4280ee7f472c16d
+  data.tar.gz: badde638cef78b714cc82aa872678b346a6f9ca230784984e5fa3771f040d610
 SHA512:
-  metadata.gz: ae6d56dde262515befe5225a721fa2fca37f50e6162efd48eca52cce324508f18df1f0d916264ba531a57e3cc5a4c6a88818bd03fb33b0639129afce0e3a5aef
-  data.tar.gz: 3ef8943ff38d4ed3c5494f27b29dffc525d1311a47d1452e49f6e34f5147571175d11a26c3931c0d37344b440764584eb184e5e1433b7bbe8d8b90abd40ac8e7
+  metadata.gz: 62d4940b0196c8e603905a05471c1770d904142b35a203a1303e479e4f2e7425afd8fac143641c20cb3d855ffa05c7393735d891897b3a3cae0be3bdcc1e950e
+  data.tar.gz: d0e112129ac798cc9b35f55666d40e594d9fc604bc6768f5de9cc5f9ac2a95a3dcb66b50cffa78145392b9d7c952ce576d9e0373df82e3645c689412f5f10ae3

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/TODO.release/01-release-lutaml-uml-030.md

@@ -0,0 +1,30 @@
+# 01 — Release lutaml-uml 0.3.0
+
+**Status: PENDING**
+
+## Problem
+The local lutaml-uml has 10 unpushed commits (559 files, +354k LOC)
+containing the UmlRepository + StaticSite + Vue frontend infrastructure.
+None of this is on rubygems. The published versions (0.2.12, 1.0.0)
+don't include any of it.
+
+This blocks ea CI — `lutaml/uml_repository` is not installable from
+rubygems.
+
+## Steps
+1. Commit all local changes on `chore/consolidate-todos` branch.
+2. Bump version: `0.2.0` → `0.3.0`.
+3. Verify `bundle exec rspec` passes.
+4. Push branch + open PR.
+5. Merge-rebase.
+6. Trigger GHA release.
+
+## Version rationale
+0.3.0 not 0.2.13 because the UmlRepository + StaticSite is a major
+feature surface. 0.3.0 continues the 0.x API line (Lutaml::Uml::UmlClass
+etc.) that ea targets. Published 1.0.0 has a different API (renamed
+classes) and should be ignored / yanked.
+
+## Verification
+- `gem list -r --exact lutaml-uml` shows 0.3.0.
+- `gem content lutaml-uml --version 0.3.0 | grep uml_repository` succeeds.

data/TODO.release/02-fix-lutaml-meta-gem-requires.md

@@ -0,0 +1,33 @@
+# 02 — Fix lutaml meta-gem broken requires
+
+**Status: PENDING**
+
+## Problem
+`lib/lutaml.rb` requires 6 files that don't exist:
+
+```ruby
+require "lutaml/converter"           # MISSING
+require "lutaml/ea"                  # MISSING (ea uses Ea:: namespace)
+require "lutaml/xmi"                 # MISSING (xmi uses Xmi:: namespace)
+require "lutaml/qea"                 # MISSING
+require "lutaml/model_transformations" # MISSING
+require "lutaml/cli"                 # MISSING
+```
+
+`require "lutaml"` crashes immediately. The meta-gem is unusable.
+
+## Fix
+Remove the 6 broken requires. Keep only the ones that resolve to
+real files in the gem's own `lib/` tree:
+
+```ruby
+require_relative "lutaml/version"
+require "lutaml/lml"
+require "lutaml/uml"
+require "lutaml/uml_repository"
+```
+
+## Note
+The meta-gem should NOT try to remap other gems' namespaces. The ea
+gem uses `Ea::*`, the xmi gem uses `Xmi::*`. Users who want both should
+`require "ea"` and `require "xmi"` explicitly.

data/TODO.release/03-release-lutaml-0110.md

@@ -0,0 +1,20 @@
+# 03 — Release lutaml 0.11.0
+
+**Status: PENDING (depends on 02)**
+
+## Problem
+Published 0.10.19 has phantom runtime deps (htmlentities, liquid,
+listen, nokogiri, paint, lutaml-path) that shouldn't be in the
+meta-gem gemspec. Plus the 6 broken requires from TODO 02.
+
+## Steps
+1. After TODO 02 fix is merged.
+2. Bump version: `0.10.19` → `0.11.0`.
+3. Verify `require "lutaml"` works without LoadError.
+4. Push + merge.
+5. Trigger GHA release.
+
+## Verification
+- `require "lutaml"` succeeds.
+- No LoadError from missing requires.
+- Published gemspec deps are clean.

data/TODO.release/04-update-ea-gemspec-pin.md

@@ -0,0 +1,23 @@
+# 04 — Update ea gemspec pin to ~> 0.3
+
+**Status: PENDING (depends on 01)**
+
+## Problem
+ea.gemspec pins `spec.add_development_dependency "lutaml-uml", "~> 0.2.0"`.
+This resolves to 0.2.12 on rubygems, which doesn't have UmlRepository.
+CI fails on every PR.
+
+## Fix
+```ruby
+# BEFORE:
+spec.add_development_dependency "lutaml-uml", "~> 0.2.0"
+
+# AFTER:
+spec.add_development_dependency "lutaml-uml", "~> 0.3"
+```
+
+`~> 0.3` means `>= 0.3.0, < 1.0.0`, which resolves to 0.3.0 (with
+UmlRepository) and excludes the incompatible 1.0.0.
+
+## Verification
+- `bundle exec rspec` passes in CI (rubygems mode) without admin override.

data/TODO.release/05-remove-ea-conditional-requires.md

@@ -0,0 +1,48 @@
+# 05 — Remove ea conditional require workarounds
+
+**Status: PENDING (depends on 01)**
+
+## Problem
+Multiple spec files use `begin/rescue LoadError` around
+`require "lutaml/uml_repository"` because the published gem didn't
+ship the file. After lutaml-uml 0.3.0 is released, these workarounds
+are unnecessary noise.
+
+## Files to simplify
+
+### spec/spec_helper.rb
+```ruby
+# BEFORE:
+begin
+  require "lutaml/uml"
+rescue LoadError
+end
+begin
+  require "lutaml/uml_repository"
+rescue LoadError
+end
+
+# AFTER:
+require "lutaml/uml"
+require "lutaml/uml_repository"
+```
+
+### spec/ea/diagram/extractor_spec.rb
+```ruby
+# BEFORE:
+begin
+  require "lutaml/uml_repository/repository"
+rescue LoadError
+end
+RSpec.configure do ... skip ... end
+
+# AFTER:
+require "lutaml/uml_repository/repository"
+```
+
+### spec/ea/qea/verification/comprehensive_equivalence_spec.rb
+Same pattern — remove begin/rescue + skip guard.
+
+## Verification
+- Full suite passes without any conditional requires.
+- No `skip "lutaml/uml_repository not available"` messages.

data/TODO.release/06-release-ea-020.md

@@ -0,0 +1,20 @@
+# 06 — Release ea 0.2.0
+
+**Status: PENDING (depends on 04, 05)**
+
+## Problem
+ea is at 0.1.6. The gemspec pin change (`~> 0.2.0` → `~> 0.3`) is a
+breaking change for anyone using ea's dev dependency — they need to
+install lutaml-uml 0.3.0. This warrants a minor version bump.
+
+## Steps
+1. After TODO 04 and 05 are merged.
+2. Bump version: `0.1.6` → `0.2.0`.
+3. Verify `bundle exec rspec` passes in rubygems mode (CI mode).
+4. Push + merge.
+5. Trigger GHA release.
+
+## Verification
+- ea 0.2.0 on rubygems.
+- `gem install ea && ea spa model.qea` works with published lutaml-uml 0.3.0.
+- CI passes WITHOUT admin override (first time ever).

data/TODO.release/07-migrate-plateau-model.md

@@ -0,0 +1,35 @@
+# 07 — Migrate plateau-model to ea gem
+
+**Status: PENDING (depends on 06)**
+
+## Problem
+The plateau-model project (`/Users/mulgogi/src/mn/plateau-model`)
+currently depends on the broken `lutaml` meta-gem via a local path:
+
+```ruby
+# Gemfile
+gem "lutaml", path: "/Users/mulgogi/src/lutaml/lutaml"
+```
+
+And generates SPA via:
+```bash
+bundle exec lutaml uml build-spa model.qea -o index.html
+```
+
+## Fix
+Switch to the standalone `ea` gem:
+
+```ruby
+# Gemfile
+source "https://rubygems.org"
+gem "ea", "~> 0.2"
+```
+
+```bash
+bundle exec ea spa model.qea -o index.html
+```
+
+## Verification
+- Generated index.html is structurally equivalent to the existing one
+  (same packages=58, diagrams=188, classes≈600).
+- No dependency on the lutaml meta-gem.

data/TODO.release/README.md

@@ -0,0 +1,15 @@
+# TODO.release — Streamlined dependency tree
+
+Execute each item in order. Each step depends on the previous.
+
+## Index
+
+| # | Title | Gem | Priority |
+|---|---|---|---|
+| 01 | [Release lutaml-uml 0.3.0](01-release-lutaml-uml-030.md) | lutaml-uml | BLOCKING — critical path |
+| 02 | [Fix lutaml meta-gem broken requires](02-fix-lutaml-meta-gem-requires.md) | lutaml | high — independent of 01 |
+| 03 | [Release lutaml 0.11.0](03-release-lutaml-0110.md) | lutaml | high — depends on 02 |
+| 04 | [Update ea gemspec pin to ~> 0.3](04-update-ea-gemspec-pin.md) | ea | high — depends on 01 |
+| 05 | [Remove ea conditional require workarounds](05-remove-ea-conditional-requires.md) | ea | high — depends on 01 |
+| 06 | [Release ea 0.2.0](06-release-ea-020.md) | ea | high — depends on 04, 05 |
+| 07 | [Migrate plateau-model to ea gem](07-migrate-plateau-model.md) | plateau-model | medium — depends on 06 |

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.2.0"
 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.2.0
 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
@@ -134,14 +134,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: '0.5'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: '0.5'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
@@ -213,6 +213,14 @@ files:
 - TODO.next/38-xmi-parser-feature-parity.md
 - TODO.next/39-ea-spa-cli-command.md
 - TODO.next/40-drop-lur-only-check-in-diagrams-extract.md
+- TODO.release/01-release-lutaml-uml-030.md
+- TODO.release/02-fix-lutaml-meta-gem-requires.md
+- TODO.release/03-release-lutaml-0110.md
+- TODO.release/04-update-ea-gemspec-pin.md
+- TODO.release/05-remove-ea-conditional-requires.md
+- TODO.release/06-release-ea-020.md
+- TODO.release/07-migrate-plateau-model.md
+- TODO.release/README.md
 - config/diagram_styles.yml
 - config/model_transformations.yml
 - config/qea_schema.yml
@@ -238,6 +246,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