ea 0.1.6 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6322d6dfb8ed1b7c957b25ed522ccf6598350a88653e9e44acd0dfb79c2e61b3
-  data.tar.gz: 88be8b7cfc39592348c422bd4277f5d4bd97ec827bef29d0f40bb12c6dc5d9eb
+  metadata.gz: e5f5e58db4cb228d4e35c2d250b57d4b8874c9545d90aacc6792755d6637c121
+  data.tar.gz: 4ba8ca434a0ec8c6e3f09f27a828e05b035df520f1a104de7e0b38d2b2de6d24
 SHA512:
-  metadata.gz: 0a4219aa40e69edc0f5bcf956d01592d203928612345ae35fac33b8fa4bf610c1615fb3bae4a82788d87d3dd4198ed9808abfd080468e79d68c42f869e2f97b2
-  data.tar.gz: 5429e2a0281d4aa1efbe7358e64975a017660f060fcb1ecc76ad07f4eb2f992115ee9b0dc1fa1dcb2b53e114a8741b43040a4cdcb00c95d2cf5a07db6e81ca02
+  metadata.gz: f680d715948b18cca3848bcf436a05e9d30ce9dd9a49303f83038ad760e9a9c09eeb71301b63fb04343ad269e2b4b30467c258cdb392c3e252db171bd454223f
+  data.tar.gz: a147e69b20c373722320d2d78b796c6c2550c350017a8ff1398be6d25c1a2906d95e048314211785db8781f9bebeb0e193965965fef4e2fd0a2fa1fba5233a98

data/README.adoc

@@ -0,0 +1,131 @@
+= ea
+Ronald Tse <open.source@ribose.com>
+:doctype: article
+:toc: left
+:toclevels: 3
+:source-highlighter: highlightjs
+
+Standalone Ruby gem for parsing Sparx Enterprise Architect data files
+(QEA SQLite database and Sparx XMI). Pure parse, optional bridge to
+`lutaml-uml` for cross-vendor UML output and SPA generation.
+
+== Installation
+
+ gem install ea
+
+For SPA generation (optional):
+
+ gem install ea lutaml-uml
+
+Or in your Gemfile:
+
+ source "https://rubygems.org"
+ gem "ea", "~> 0.2"
+ gem "lutaml-uml", "~> 0.5"   # optional: SPA + SVG diagram rendering
+
+== Quick start
+
+=== Parse a QEA file (pure — no lutaml-uml needed)
+
+[source,ruby]
+----
+require "ea"
+
+db = Ea.parse("model.qea")   #=> Ea::Qea::Database
+puts "#{db.packages.size} packages, #{db.objects.size} objects"
+----
+
+=== Generate a SPA from QEA (requires lutaml-uml)
+
+[source,bash]
+----
+ea spa model.qea --output browser.html
+----
+
+Produces a single-file Vue IIFE HTML (~300KB for a typical model)
+with package hierarchy, class details, and diagram navigation.
+
+=== Generate Sparx XMI from QEA (pure — no lutaml-uml)
+
+[source,bash]
+----
+ea convert model.qea --to xmi --output model.xmi
+----
+
+=== Extract a diagram as SVG (requires lutaml-uml)
+
+[source,bash]
+----
+ea diagrams extract model.qea "Diagram Name" --output diagram.svg
+----
+
+== Architecture
+
+The ea gem has two layers:
+
+=== Pure layer (no lutaml-uml dependency)
+
+[cols="1,2"]
+|===
+| `Ea.parse(path)` | Returns `Ea::Qea::Database` (.qea) or `Xmi::Sparx::Root` (.xmi)
+| `Ea::Transformers::QeaToXmi` | Converts `Ea::Qea::Database` → Sparx XMI string
+| `Ea::Qea.load(path)` | Low-level QEA loader → `Ea::Qea::Database`
+| `Ea::Xmi.load(path)` | Low-level XMI loader → `Xmi::Sparx::Root`
+|===
+
+=== Bridge layer (optional — lazy-requires lutaml-uml)
+
+[cols="1,2"]
+|===
+| `Ea.to_uml(path_or_model)` | Returns `Lutaml::Uml::Document` (tool-agnostic)
+| `Ea::Bridge::QeaToUml` | `Ea::Qea::Database` → `Lutaml::Uml::Document`
+| `Ea::Bridge::XmiToUml` | `Xmi::Sparx::Root` → `Lutaml::Uml::Document`
+|===
+
+=== Data flow
+
+----
+QEA file ──→ Ea::Qea::Database  ──┐
+                                   ├──→ Ea::Bridge ──→ Lutaml::Uml::Document
+XMI file ──→ Xmi::Sparx::Root    ──┘                        │
+                                                           ├──→ SPA (HTML)
+                                                           ├──→ SVG diagram
+                                                           └──→ cross-vendor output
+
+QEA file ──→ Ea::Qea::Database  ──→ Ea::Transformers::QeaToXmi ──→ Sparx XMI
+                                    (pure, no lutaml-uml)
+----
+
+== CLI commands
+
+[cols="1,3"]
+|===
+| `ea spa FILE` | Generate single-page app from QEA/XMI/LUR
+| `ea list FILE` | List model elements (auto-detects QEA or XMI)
+| `ea diagrams list FILE` | List diagrams in a QEA/XMI file
+| `ea diagrams extract FILE NAME` | Render a diagram to SVG
+| `ea validate FILE` | Validate EA model
+| `ea stats FILE` | Show collection counts
+| `ea parse FILE` | Parse to internal model representation
+| `ea convert FILE --to xmi` | Convert QEA → Sparx XMI
+| `ea version` | Show gem version
+|===
+
+== Limitations
+
+- **Sparx only**: QEA format and Sparx-flavored XMI only. Does not parse
+  MagicDraw or Papyrus XMI.
+- **XMI parser**: Parses `<xmi:Extension>` blocks for Sparx-specific
+  diagram metadata. Generic OMG XMI is handled by the `xmi` gem.
+
+== Development
+
+ git clone https://github.com/lutaml/ea
+ cd ea
+ bundle install
+ bundle exec rspec        # run specs (2036 examples)
+ bundle exec ea help      # see CLI commands
+
+== License
+
+MIT — see `LICENSE` file.

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/exe/ea

@@ -3,5 +3,6 @@
 
 $LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
 
+require "ea"
 require "ea/cli"
 Ea::Cli::App.start(ARGV)

data/lib/ea/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ea
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.2.1
 platform: ruby
 authors:
 - Ribose Inc.
@@ -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
@@ -170,6 +170,7 @@ files:
 - CHANGELOG.md
 - CLAUDE.md
 - CODE_OF_CONDUCT.md
+- README.adoc
 - README.md
 - Rakefile
 - TODO.next/00-publish-blocking-bugs.md
@@ -213,6 +214,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