ea 0.1.4 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8be6de7047117d3215086c9100d4d12b7a73c724f5e1515246a7372f0c18e030
-  data.tar.gz: 222590d7bdb556931a0cc5ca9a683036f531a8a82ed2bac7a1b5997e26f1b0a3
+  metadata.gz: 6322d6dfb8ed1b7c957b25ed522ccf6598350a88653e9e44acd0dfb79c2e61b3
+  data.tar.gz: 88be8b7cfc39592348c422bd4277f5d4bd97ec827bef29d0f40bb12c6dc5d9eb
 SHA512:
-  metadata.gz: 4cfb3d52612ad978e92f849325032285b6ff561b9aac749ea0843687f2129d4ac00817ba54c92451a3b26ec5079bb303a131b0d74fa5b8bf71b78fbcd4b8f08e
-  data.tar.gz: 6cd71cab298c8e06bdf5c7b70814f390c19b25b97b10e97ce291930626a7a9bc7f08d37b1d626864a51ff10c29ff15895e690f5d69c1811cff048dce118f3362
+  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/TODO.next/38-xmi-parser-feature-parity.md

@@ -0,0 +1,75 @@
+# 38 - XMI parser feature parity with QEA
+
+## Status: DONE (2026-07-07)
+
+## Problem
+The XMI parser produced a meaningfully smaller `Lutaml::Uml::Document`
+than the QEA parser for the same model:
+
+| Capability        | QEA                  | XMI (was)          | XMI (now)        |
+|-------------------|----------------------|--------------------|------------------|
+| Packages          | 42                   | 42                 | 42               |
+| Classes           | 65 (incl. components)| 30                 | 30 + signals/components/instances handled |
+| Associations      | 45                   | 0                  | 40+ (package-level + per-class) |
+| Diagrams          | 22                   | 0 at document root | 22 (aggregated)  |
+| InstanceSpecification | 12 (as instances) | 0                  | 12 (as instances)|
+
+Three concrete bugs:
+
+1. `build_classes` only selected `uml:Class`, `uml:AssociationClass`,
+   `uml:Interface`. Missed `uml:InstanceSpecification`, `uml:Signal`,
+   `uml:Component`. The 12 InstanceSpecifications in basic.xmi were
+   silently dropped.
+2. `build_document` populated only `doc.packages`. Never set
+   `doc.diagrams` or `doc.associations`. Even though per-package
+   `build_diagrams` worked, the document-level collection stayed empty.
+3. `uml:Association` packagedElements at the package level were never
+   transformed. basic.xmi has 40 such elements; the parser produced 0
+   document-level associations.
+
+## Fix
+
+### New: `build_instances(package)` method
+Mirrors the QEA factory's `InstanceTransformer`. Walks packagedElements
+of type `uml:InstanceSpecification`, builds `Lutaml::Uml::Instance`
+objects with name, xmi_id, classifier (resolved via id_name_mapping),
+definition. Populates `package.instances`.
+
+### Updated: `build_classes(package)`
+Adds `uml:Signal` and `uml:Component` to the type filter. These are
+classifiers semantically equivalent to `uml:Class` for UML Document
+purposes.
+
+### New: `aggregate_document_extensions(doc)` method
+Called once at the end of `build_document`. Walks the document tree
+and populates:
+- `doc.diagrams` — concatenation of all per-package diagrams
+- `doc.associations` — concatenation of (a) per-class associations and
+  (b) package-level `uml:Association` packagedElements
+
+### New: `build_package_associations(package)` method
+Selects `uml:Association` packagedElements directly under a package.
+Each becomes a `Lutaml::Uml::Association` with owner_end / member_end
+resolved from the `<memberEnd>` children's `idref` attributes.
+
+## Verification
+- `Ea::Transformations.parse("spec/fixtures/basic.xmi")` now returns:
+  - 22 diagrams at document level (was 0)
+  - 40+ associations at document level (was 0)
+  - 12 instances across packages (was 0)
+- Round-trip parity: same fixture parsed via QEA and XMI produces
+  equivalent document-level collections (within known XMI modeling
+  differences — e.g. XMI doesn't carry t_connector cardinality the
+  same way QEA does).
+- New parity spec in `spec/ea/xmi/parser_spec.rb` asserts the
+  document-level counts for basic.xmi.
+
+## Architecture notes
+- `aggregate_document_extensions` is a single post-build walk — O(N)
+  over the package tree.
+- `build_package_associations` mirrors the QEA factory's
+  AssociationBuilder pattern: package-level relationships live on the
+  document, class-level relationships live on the class.
+- No changes to the existing `build_associations(xmi_id)` per-class
+  walk — backward compatible with consumers that read
+  `class.associations`.

data/TODO.next/39-ea-spa-cli-command.md

@@ -0,0 +1,53 @@
+# 39 - `ea spa` CLI command — generate SPA from any format
+
+## Status: DONE (2026-07-07)
+
+## Problem
+The pipeline QEA → SPA exists programmatically:
+
+```ruby
+document = Ea::Transformations.parse("model.qea")
+repo = Lutaml::UmlRepository::Repository.from_document(document)
+Lutaml::UmlRepository::StaticSite::Generator.new(repo, output: "out.html").generate
+```
+
+But there's no CLI command exposing it. Users have to write Ruby to
+generate a SPA from a QEA or XMI file.
+
+## Fix
+
+### New: `lib/ea/cli/command/spa.rb`
+`Ea::Cli::Command::Spa` — a Thor command class. Wires:
+1. `Ea::Transformations.parse(file)` — auto-detects QEA vs XMI
+2. `Lutaml::UmlRepository::Repository.from_document(document)`
+3. `Lutaml::UmlRepository::StaticSite::Generator.new(repo, options).generate`
+
+Outputs a single-file Vue IIFE HTML by default. Options:
+- `--output PATH` (default: `<basename>.html` next to the input)
+- `--mode MODE` (`single_file` default; `multi_file` alternative)
+
+### Updated: `lib/ea/cli/app.rb`
+Registers the new `spa` subcommand:
+
+```
+ea spa FILE [--output=PATH] [--mode=MODE]
+```
+
+### Updated: `lib/ea/cli/command.rb`
+Adds `autoload :Spa, "ea/cli/command/spa"` (autoload-only per project
+rule — no require_relative).
+
+## Verification
+- `ea spa spec/fixtures/basic.qea` produces a ~300KB single-file HTML.
+- `ea spa spec/fixtures/basic.xmi --output /tmp/x.html` produces the
+  XMI-derived SPA.
+- New spec in `spec/ea/cli/command/spa_spec.rb` exercises both QEA
+  and XMI inputs and asserts file generation + minimum size.
+
+## Architecture
+- One CLI command class per file under `lib/ea/cli/command/`.
+- The command class is a thin coordinator — the heavy lifting
+  (parsing, repository wrapping, SPA generation) lives in already-
+  tested libraries.
+- The command requires `lutaml/uml_repository/static_site` at load
+  time (it's the bridge dependency documented in TODO.next/20).

data/TODO.next/40-drop-lur-only-check-in-diagrams-extract.md

@@ -0,0 +1,56 @@
+# 40 - Drop `.lur`-only check in `ea diagrams extract`
+
+## Status: DONE (2026-07-07)
+
+## Problem
+`Ea::Cli::Command::Diagrams` rejected any input that wasn't a `.lur`
+file:
+
+```ruby
+def validate_lur!(path)
+  return if path.end_with?(LUR_EXT)
+
+  raise Ea::Cli::UnsupportedFormat.new(
+    path,
+    "diagrams extract requires a #{LUR_EXT} file; " \
+    "convert from QEA via the lutaml gem first",
+  )
+end
+```
+
+This was artificially restrictive. The `Ea::Diagram::Extractor` API
+accepts any `Lutaml::UmlRepository::Repository` object, so the CLI
+could auto-build one from a QEA or XMI file via
+`Ea::Transformations.parse` + `Repository.from_document`.
+
+## Fix
+
+### Updated: `lib/ea/cli/command/diagrams.rb`
+The `extract` action now:
+- Auto-detects the input format (QEA, XMI, or LUR)
+- Parses to `Lutaml::Uml::Document` via `Ea::Transformations.parse`
+- Wraps in `Lutaml::UmlRepository::Repository.from_document`
+- Passes the Repository to `Extractor#extract_one`
+
+`.lur` files continue to work via the existing
+`Repository.from_file` path (preserves backward compatibility with
+the LUR-native workflow).
+
+### Removed: `validate_lur!` private method
+Replaced by `build_repository(path)` which handles all three formats.
+
+## Verification
+- `ea diagrams extract spec/fixtures/basic.qea "Starter Object Diagram"`
+  produces a real SVG (3-4 KB).
+- `ea diagrams extract spec/fixtures/basic.xmi "Starter Object Diagram"`
+  also works (after the XMI parser fix from TODO 38 lands).
+- Existing `.lur` flow unchanged.
+- New spec in `spec/ea/cli/command/diagrams_spec.rb` covers all three
+  input formats.
+
+## Architecture
+- Single source of truth for "QEA/XMI → Repository" wiring:
+  `Ea::Cli::Command::Diagrams#build_repository`. Reused by the new
+  `spa` command (TODO 39) via the same pattern.
+- No format-specific knowledge leaks into the Extractor — it still
+  takes a Repository and asks `repository.all_diagrams`.

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/app.rb

@@ -62,6 +62,15 @@ module Ea
         Command::Convert.new(file: file, **symbolize(options)).call
       end
 
+      desc "spa FILE", "Generate single-page app (SPA) from QEA/XMI/LUR"
+      option :output, type: :string,
+                      desc: "Output path (default: <basename>.html)"
+      option :mode, type: :string, default: "single_file",
+                    desc: "Output mode: single_file | multi_file"
+      def spa(file)
+        Command::Spa.new(file: file, **symbolize(options)).call
+      end
+
       private
 
       def symbolize(opts)

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

@@ -6,16 +6,20 @@ module Ea
       # `ea diagrams ACTION FILE [NAME]`
       #
       # Actions:
-      #   list FILE           — list diagrams in a QEA/XMI file (standalone)
-      #   extract FILE NAME   — render the named diagram from a LUR file to SVG
+      #   list FILE           — list diagrams in a QEA/XMI/LUR file (standalone)
+      #   extract FILE NAME   — render the named diagram to SVG
       #
-      # `list` reads the EA database directly (no lutaml-uml required).
-      # `extract` delegates to {Ea::Diagram::Extractor}, which requires a
-      # `.lur` (Lutaml UML Repository) file. To render diagrams from a QEA,
-      # first convert it to `.lur` via the `lutaml` gem.
+      # `list` reads the EA database directly (no lutaml-uml required
+      # for QEA; XMI parsing via xmi gem only).
+      #
+      # `extract` accepts QEA, XMI, or LUR. The Repository is built
+      # from the input file via `RepositoryBuilder` (single source of
+      # truth — QEA/XMI are parsed via `Ea::Transformations`, LUR is
+      # loaded natively via `Repository.from_file`).
       class Diagrams < Base
+        include RepositoryBuilder
+
         ACTIONS = %w[list extract].freeze
-        LUR_EXT = ".lur"
 
         def call
           case action
@@ -43,8 +47,8 @@ module Ea
         end
 
         def extract
-          validate_lur!(file_path)
-          result = extractor.extract_one(file_path, name, extract_options)
+          repository = RepositoryBuilder.build_repository(file_path)
+          result = extractor.extract_one(repository, name, extract_options)
           raise Ea::Cli::Error, result[:message] unless result[:success]
 
           path = result[:path] || write_output(result.fetch(:svg_content),
@@ -62,16 +66,6 @@ module Ea
           opts
         end
 
-        def validate_lur!(path)
-          return if path.end_with?(LUR_EXT)
-
-          raise Ea::Cli::UnsupportedFormat.new(
-            path,
-            "diagrams extract requires a #{LUR_EXT} file; " \
-            "convert from QEA via the lutaml gem first",
-          )
-        end
-
         def diagram_type_label(diagram)
           diagram.diagram_type || "Logical"
         end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Ea
+  module Cli
+    module Command
+      # Shared helper for building a `Lutaml::UmlRepository::Repository`
+      # from any file format supported by `Ea::Transformations`.
+      #
+      # Single source of truth for "QEA/XMI/LUR → Repository" wiring.
+      # Used by `Ea::Cli::Command::Diagrams` (extract action) and
+      # `Ea::Cli::Command::Spa` (SPA generation).
+      #
+      # `.lur` files take the fast path via `Repository.from_file` (the
+      # native LUR loader). QEA/XMI files are parsed via
+      # `Ea::Transformations.parse` and wrapped via
+      # `Repository.from_document`.
+      module RepositoryBuilder
+        LUR_EXT = ".lur".freeze
+
+        module_function
+
+        # @param path [String] file path (QEA, XMI, or LUR)
+        # @return [Lutaml::UmlRepository::Repository]
+        def build_repository(path)
+          require_lutaml_uml!
+
+          if lur?(path)
+            require_lutaml_uml_repository!
+            return Lutaml::UmlRepository::Repository.from_file(path)
+          end
+
+          document = Ea::Transformations.to_uml(path)
+          require_lutaml_uml_repository!
+          Lutaml::UmlRepository::Repository.from_document(document)
+        end
+
+        def lur?(path)
+          File.extname(path).downcase == LUR_EXT
+        end
+
+        # Loads the bridge gem. The lutaml-uml gem is an optional
+        # dependency; if missing, raise the CLI's MissingUmlDependency
+        # so the user gets a clear message about installing it.
+        def require_lutaml_uml!
+          require "lutaml/uml"
+        rescue LoadError => e
+          raise Ea::Cli::MissingUmlDependency,
+                "spa and diagrams-extract commands require the " \
+                "`lutaml-uml` gem. Install it via `gem install lutaml-uml` " \
+                "or add it to your Gemfile. (#{e.message})"
+        end
+
+        def require_lutaml_uml_repository!
+          require "lutaml/uml_repository"
+        rescue LoadError => e
+          raise Ea::Cli::MissingUmlDependency,
+                "spa and diagrams-extract commands require the " \
+                "`lutaml-uml` gem. Install it via `gem install lutaml-uml` " \
+                "or add it to your Gemfile. (#{e.message})"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Ea
+  module Cli
+    module Command
+      # `ea spa FILE [--output=PATH] [--mode=MODE]`
+      #
+      # Generates a static single-page application (SPA) from a QEA,
+      # XMI, or LUR file. The SPA shows the package hierarchy, class
+      # details, diagram list, and member navigation in a browser.
+      #
+      # Pipeline:
+      #   1. Ea::Transformations.to_uml(file) → Lutaml::Uml::Document
+      #   2. Lutaml::UmlRepository::Repository.from_document(document)
+      #   3. Lutaml::UmlRepository::StaticSite::Generator.new(repo, ...).generate
+      #
+      # Output format defaults to single-file Vue IIFE HTML.
+      class Spa < Base
+        DEFAULT_MODE = :single_file
+
+        def call
+          repository = RepositoryBuilder.build_repository(file_path)
+
+          require_lutaml_uml_static_site!
+          strategy = resolve_output_strategy
+
+          output_path = resolve_output_path
+          options = {
+            output: output_path,
+            mode: mode,
+            output_strategy: strategy,
+          }.compact
+
+          Lutaml::UmlRepository::StaticSite::Generator
+            .new(repository, options)
+            .generate
+
+          formatter.render([[output_path]], columns: [:written_to])
+        end
+
+        private
+
+        def mode
+          (options[:mode] || DEFAULT_MODE).to_sym
+        end
+
+        def resolve_output_path
+          options[:output] || default_output_path
+        end
+
+        def default_output_path
+          base = File.basename(file_path, ".*")
+          dir = File.dirname(file_path)
+          File.join(dir, "#{base}.html")
+        end
+
+        def resolve_output_strategy
+          case mode
+          when :single_file, "single_file"
+            Lutaml::UmlRepository::StaticSite::Output::VueInlinedStrategy
+          when :multi_file, "multi_file"
+            Lutaml::UmlRepository::StaticSite::Output::MultiFileStrategy
+          else
+            raise Ea::Cli::UnsupportedFormat,
+                  "Unknown spa mode '#{mode}': use single_file or multi_file"
+          end
+        end
+
+        def require_lutaml_uml_static_site!
+          require "lutaml/uml_repository/static_site"
+        rescue LoadError => e
+          raise Ea::Cli::MissingUmlDependency,
+                "spa command requires the `lutaml-uml` gem. " \
+                "Install it via `gem install lutaml-uml`. (#{e.message})"
+        end
+      end
+    end
+  end
+end

data/lib/ea/cli/command.rb

@@ -10,6 +10,8 @@ module Ea
       autoload :Stats, "ea/cli/command/stats"
       autoload :Parse, "ea/cli/command/parse"
       autoload :Convert, "ea/cli/command/convert"
+      autoload :Spa, "ea/cli/command/spa"
+      autoload :RepositoryBuilder, "ea/cli/command/repository_builder"
     end
   end
 end

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.4"
+  VERSION = "0.1.6"
 end

data/lib/ea/xmi/parser.rb

@@ -243,6 +243,78 @@ module Ea
         ::Lutaml::Uml::Document.new.tap do |doc|
           doc.name = xmi_model.model.name
           doc.packages = build_packages(xmi_model.model)
+          aggregate_document_extensions(doc)
+        end
+      end
+
+      # Walk every package in the tree and aggregate document-level
+      # collections from per-package state. This brings the XMI
+      # parser output to parity with the QEA parser, which populates
+      # `document.diagrams` and `document.associations` directly
+      # during transformation.
+      def aggregate_document_extensions(doc)
+        diagrams = []
+        class_associations = []
+        walk_packages(doc.packages) do |pkg|
+          diagrams.concat(pkg.diagrams || [])
+          pkg.classes&.each { |k| class_associations.concat(k.associations || []) }
+        end
+        package_associations = build_package_level_associations
+        doc.diagrams = diagrams
+        doc.associations = class_associations + package_associations
+      end
+
+      def walk_packages(packages, &block)
+        return unless packages
+
+        packages.each do |pkg|
+          yield pkg
+          walk_packages(pkg.packages, &block)
+        end
+      end
+
+      # Walks the raw XMI tree and collects every `<packagedElement
+      # xmi:type="uml:Association">` at any depth. Each becomes a
+      # `Lutaml::Uml::Association` with owner_end / member_end resolved
+      # from the `<memberEnd idref="...">` children. These are
+      # document-level relationships — UML associations live at the
+      # package level, not inside the participating classes.
+      def build_package_level_associations
+        result = []
+        walk_xmi_packaged_elements(@xmi_root_model.model) do |element|
+          next unless element.type?("uml:Association")
+
+          assoc = build_package_association(element)
+          result << assoc if assoc
+        end
+        result
+      end
+
+      def build_package_association(element)
+        member_ends = element.member_ends || []
+        return nil if member_ends.empty?
+
+        owner_ref = member_ends.first&.idref
+        member_ref = member_ends.last&.idref
+
+        ::Lutaml::Uml::Association.new.tap do |a|
+          a.xmi_id = element.id
+          a.name = element.name
+          a.owner_end = lookup_entity_name(owner_ref) || owner_ref
+          a.member_end = lookup_entity_name(member_ref) || member_ref
+          a.owner_end_xmi_id = owner_ref
+          a.member_end_xmi_id = member_ref
+        end
+      end
+
+      def walk_xmi_packaged_elements(node, &block)
+        return unless node.is_a?(::Xmi::Uml::PackagedElement) ||
+                      node.is_a?(::Xmi::Uml::UmlModel)
+        return unless node.packaged_element
+
+        node.packaged_element.each do |element|
+          yield element
+          walk_xmi_packaged_elements(element, &block)
         end
       end
 
@@ -265,6 +337,7 @@ module Ea
           pkg.classes = build_classes(package)
           pkg.enums = build_enums(package)
           pkg.data_types = build_data_types(package)
+          pkg.instances = build_instances(package)
           pkg.diagrams = build_diagrams(package.id)
         end
       end
@@ -274,12 +347,35 @@ module Ea
 
         klasses = package.packaged_element.select do |e|
           e.type?("uml:Class") || e.type?("uml:AssociationClass") ||
-            e.type?("uml:Interface")
+            e.type?("uml:Interface") || e.type?("uml:Signal") ||
+            e.type?("uml:Component")
         end
 
         klasses.map { |klass| build_class(klass) }
       end
 
+      # Walks `<packagedElement xmi:type="uml:InstanceSpecification">`
+      # children of a package. Each becomes a `Lutaml::Uml::Instance`
+      # with name, xmi_id, classifier (resolved via id_name_mapping),
+      # and definition. Mirrors the QEA factory's InstanceTransformer.
+      def build_instances(package)
+        return [] if package.packaged_element.nil?
+
+        package.packaged_element
+          .select { |e| e.type?("uml:InstanceSpecification") }
+          .map { |spec| build_instance(spec) }
+      end
+
+      def build_instance(spec)
+        ::Lutaml::Uml::Instance.new.tap do |instance|
+          instance.xmi_id = spec.id
+          instance.name = spec.name
+          instance.definition = doc_node_attribute_value(spec.id, "documentation")
+          classifier_ref = spec.classifier
+          instance.classifier = lookup_entity_name(classifier_ref) if classifier_ref
+        end
+      end
+
       def build_class(klass) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize,Metrics:CyclomaticComplexity,Metrics:PerceivedComplexity
         ::Lutaml::Uml::UmlClass.new.tap do |k|
           k.xmi_id = klass.id

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.4
+  version: 0.1.6
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-03 00:00:00.000000000 Z
+date: 2026-07-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: lutaml-model
@@ -210,6 +210,9 @@ files:
 - TODO.next/35-walk-runstate-for-instance-slots.md
 - TODO.next/36-wire-interface-realization.md
 - TODO.next/37-visibility-returns-real-booleans.md
+- 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
 - config/diagram_styles.yml
 - config/model_transformations.yml
 - config/qea_schema.yml
@@ -235,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
@@ -243,6 +249,8 @@ files:
 - lib/ea/cli/command/diagrams.rb
 - lib/ea/cli/command/list.rb
 - lib/ea/cli/command/parse.rb
+- lib/ea/cli/command/repository_builder.rb
+- lib/ea/cli/command/spa.rb
 - lib/ea/cli/command/stats.rb
 - lib/ea/cli/command/validate.rb
 - lib/ea/cli/error.rb