ea 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8be6de7047117d3215086c9100d4d12b7a73c724f5e1515246a7372f0c18e030
-  data.tar.gz: 222590d7bdb556931a0cc5ca9a683036f531a8a82ed2bac7a1b5997e26f1b0a3
+  metadata.gz: c45bd1d6024b9307f1d67422299289da426b353aa7ab7b9797d8d577b61529a9
+  data.tar.gz: afaf525893ce02307e0fe4f6ab2242b8f0d27d9b3e618db56f1d026b8a0e17ac
 SHA512:
-  metadata.gz: 4cfb3d52612ad978e92f849325032285b6ff561b9aac749ea0843687f2129d4ac00817ba54c92451a3b26ec5079bb303a131b0d74fa5b8bf71b78fbcd4b8f08e
-  data.tar.gz: 6cd71cab298c8e06bdf5c7b70814f390c19b25b97b10e97ce291930626a7a9bc7f08d37b1d626864a51ff10c29ff15895e690f5d69c1811cff048dce118f3362
+  metadata.gz: ae6d56dde262515befe5225a721fa2fca37f50e6162efd48eca52cce324508f18df1f0d916264ba531a57e3cc5a4c6a88818bd03fb33b0639129afce0e3a5aef
+  data.tar.gz: 3ef8943ff38d4ed3c5494f27b29dffc525d1311a47d1452e49f6e34f5147571175d11a26c3931c0d37344b440764584eb184e5e1433b7bbe8d8b90abd40ac8e7

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/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.parse(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.parse(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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Ea
-  VERSION = "0.1.4"
+  VERSION = "0.1.5"
 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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ea
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.5
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-03 00:00:00.000000000 Z
+date: 2026-07-07 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
@@ -243,6 +246,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