ea 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: af7f7d010d0ca70a7230803dfd39e5037fda7f983e532ee6e4280ee7f472c16d
-  data.tar.gz: badde638cef78b714cc82aa872678b346a6f9ca230784984e5fa3771f040d610
+  metadata.gz: e5f5e58db4cb228d4e35c2d250b57d4b8874c9545d90aacc6792755d6637c121
+  data.tar.gz: 4ba8ca434a0ec8c6e3f09f27a828e05b035df520f1a104de7e0b38d2b2de6d24
 SHA512:
-  metadata.gz: 62d4940b0196c8e603905a05471c1770d904142b35a203a1303e479e4f2e7425afd8fac143641c20cb3d855ffa05c7393735d891897b3a3cae0be3bdcc1e950e
-  data.tar.gz: d0e112129ac798cc9b35f55666d40e594d9fc604bc6768f5de9cc5f9ac2a95a3dcb66b50cffa78145392b9d7c952ce576d9e0373df82e3645c689412f5f10ae3
+  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/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.2.0"
+  VERSION = "0.2.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ea
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Ribose Inc.
@@ -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