ea 0.1.0 → 0.1.4

data/docs/ea_to_uml_type_mapping.md

@@ -0,0 +1,89 @@
+# EA Object Type → UML Mapping
+
+This document describes how `ea` maps Sparx EA object types (from the QEA
+`t_object` table's `Object_Type` column) to UML model elements during the
+`Ea::Qea.to_uml` transformation.
+
+The mapping is implemented in
+`Ea::Qea::Models::EaObject#transformer_type`, which returns a
+`TransformerRegistry` key or `nil`.
+
+## Principles
+
+1. **Hub-and-spoke, not format-to-format.** Both QEA and XMI parse *into* a
+   common `Lutaml::Uml::Document`. There is no direct QEA↔XMI translator.
+2. **Model elements only.** Only EA object types that correspond to genuine
+   UML model elements are transformed. Rendering hints and tool-internal
+   plumbing are dropped.
+3. **Stereotype can override type.** A Class with stereotype `enumeration`
+   transforms as an Enum, not a Class.
+
+## Mapping table
+
+| EA `Object_Type`   | UML element         | Transformer key | Notes                                     |
+|--------------------|---------------------|-----------------|-------------------------------------------|
+| `Class`            | `UmlClass`          | `:class`        |                                           |
+| `Interface`        | `UmlClass`          | `:class`        |                                           |
+| `Enumeration`      | `Enum`              | `:enumeration`  | Also: Class with `<<enumeration>>`        |
+| `DataType`         | `DataType`          | `:data_type`    |                                           |
+| `Instance`/`Object`| `Instance`          | `:instance`     |                                           |
+| `Package`          | `Package`           | `:package`      | From `t_package`, not `t_object`          |
+| `Text`             | _(dropped)_         | `nil`           | See below                                 |
+| `Note`             | _(dropped)_         | `nil`           | See below                                 |
+| `ProxyConnector`   | _(dropped)_         | `nil`           | See below                                 |
+
+Connectors (`t_connector`) are handled separately from objects and map to
+`Association`, `Generalization`, or `Dependency` depending on their type.
+
+## Dropped types — rationale
+
+### `Text`
+
+A free-form text box placed on a diagram for labeling or annotation. It is a
+**rendering hint**, not a model element — it has no semantic relationship to
+the classes and packages in the model.
+
+- **Current behavior:** dropped. Content is not preserved in the UML document.
+- **Why not `UmlClass`:** Text has no attributes, operations, or type
+  semantics. Treating it as a class (the previous behavior) polluted the class
+  collection with non-classes and broke class counts.
+- **Future:** map to `Lutaml::Uml::Comment`. This requires adding a `comments`
+  collection to `Lutaml::Uml::Package` (currently only `Document` has one, and
+  it is a flat string list). Until then, Text content is lost.
+
+### `Note`
+
+A note element on a diagram. Same category as `Text` — a rendering/annotation
+hint, not a model element.
+
+- **Current behavior:** dropped.
+- **Future:** same as `Text` — map to `Comment` when the metamodel supports it.
+
+### `ProxyConnector`
+
+EA's internal stub representing a connector that crosses a package boundary.
+When a connector in package A points at an element in package B, EA may insert
+a `ProxyConnector` in one package as a stand-in for the foreign element.
+
+- **Current behavior:** dropped.
+- **Why:** it is structural plumbing. The actual relationship is already
+  captured by the real connector (in `t_connector`) and resolved by
+  `ReferenceResolver`. A `ProxyConnector` in `t_object` is a rendering/UX
+  artifact, not a second model element.
+- **Future:** no plan to preserve. If diagram rendering needs the proxy
+  geometry, it should come from `t_diagram_objects`, not from treating the
+  proxy as a class.
+
+## Verifying counts
+
+After transformation:
+
+```
+EA t_object (Class)        =  UML UmlClass count (in packages + orphan root)
+EA t_object (Enumeration)  =  UML Enum count
+EA t_object (DataType)     =  UML DataType count
+```
+
+If counts don't match, check for orphaned classes (objects whose `package_id`
+has no row in `t_package`) — these surface at the document root via
+`EaToUmlFactory#transform_orphan_classes`, not inside any package.

data/docs/xmi_qea_conversion_capabilities.md

@@ -0,0 +1,99 @@
+# Format Conversion Capabilities: QEA, XMI, and UML
+
+## Short answer
+
+**No.** The `ea` gem cannot convert XMI→QEA or QEA→XMI. Neither direction
+exists. Both formats are parsed *into* a common `Lutaml::Uml::Document`
+(hub-and-spoke), but there is no write-back path to either native format.
+
+## Current capability matrix
+
+| From              | To                   | Status       | API                           |
+|-------------------|----------------------|--------------|-------------------------------|
+| `.qea` (SQLite)   | `Ea::Qea::Database`  | ✅ Full      | `Ea::Qea.load(path)`          |
+| `.qea`            | `Lutaml::Uml::Document` | ✅ Full   | `Ea::Qea.parse(path)` / `to_uml(db)` |
+| Sparx `.xmi`      | `::Xmi::Sparx::Root` model | ✅ Full | `Ea::Xmi::Parser.parse(path)` |
+| Sparx `.xmi`      | Liquid drops (display) | ✅ Full    | `Parser.serialize_to_liquid`  |
+| Sparx `.xmi`      | `Lutaml::Uml::Document` | ❌ None   | —                             |
+| `Lutaml::Uml::Document` | Sparx `.xmi`    | ❌ None      | —                             |
+| `Lutaml::Uml::Document` | `.qea` (SQLite) | ❌ None      | —                             |
+
+## Why neither direction exists
+
+### QEA is read-only
+
+`Ea::Qea::Infrastructure::DatabaseConnection` opens SQLite with
+`readonly: true`. There is no `INSERT`/`UPDATE` path, no writer class, no
+`to_qea`. Building one requires reverse-mapping a UML Document into EA's
+~30 interrelated tables (`t_object`, `t_package`, `t_connector`, `t_attribute`,
+`t_diagram`, `t_objectproperties`, `t_xref`, `t_taggedvalue`, …), generating
+valid EA GUIDs and object_ids, and populating tool-specific columns
+(style strings, diagram geometry, visibility flags) that have no UML source.
+
+### XMI is parse-only
+
+`Ea::Xmi::Parser` consumes Sparx XMI via `::Xmi::Sparx::Root.parse_xml` and
+exposes the result through Liquid drops for *display* rendering (HTML/JSON
+templates). The drops wrap XMI-derived data — they do not serialize a
+`Lutaml::Uml::Document` back to XMI. There is no `UmlDocument → XMI`
+serializer.
+
+### The drops are display, not generation
+
+`Ea::Xmi::LiquidDrops::*` are Liquid `Drop` wrappers around the parsed XMI
+model. They exist to render XMI content in templates (for browsing,
+documentation, HTML export). A Liquid drop reads from a model; it does not
+write one. To generate XMI, you'd need XMI-schema-aware serialization
+(`xmi:Documentation`, `xmi:Extension`, `EAStub`, profile application, etc.),
+which is a separate, substantial piece of work.
+
+## What "conversion" would actually require
+
+### QEA → XMI (export)
+
+1. Build a `Lutaml::Uml::Document → Sparx XMI` serializer.
+2. Lossy: the UML Document does not carry EA-specific data (diagram layout,
+   style strings, tagged value geometry, t_xref cross-references). The
+   exported XMI would be semantically faithful but visually bare.
+3. The Sparx XMI schema is documented but large; `::Xmi::Sparx::Root`
+   parses it but cannot (currently) serialize it.
+
+### XMI → QEA (import)
+
+1. Build `XMI → Lutaml::Uml::Document` (does not exist — `Ea::Xmi::Parser`
+   produces display drops, not a UML Document).
+2. Build `Lutaml::Uml::Document → QEA SQLite` writer (does not exist —
+   see "QEA is read-only" above).
+3. Highly lossy: EA's QEA schema has ~30 tables with tool-specific columns.
+   Sparx's own XMI import into QEA is lossy; reimplementing it faithfully
+   is a major project with marginal value (you'd produce a QEA that opens
+   in EA but has no diagrams, no layout, no EA-specific metadata).
+
+## Recommendation
+
+Do **not** position the gem as offering XMI↔QEA conversion. Instead:
+
+- **Read both formats into UML** — this is the gem's core value.
+- **Query and analyze** the resulting UML Document (directly or via
+  `Lutaml::UmlRepository::Repository.from_document`).
+- **Export to neutral formats** — JSON, CSV, HTML (via Liquid drops),
+  `.lur` package (via Repository). These are one-way, lossy, and honest
+  about what they are.
+
+If true XMI↔QEA round-trip is needed, the pragmatic path is to use Sparx EA
+itself (which does both natively) and treat this gem as the
+extract/query/analyze layer that sits alongside EA, not as a replacement
+for its file-format converters.
+
+## If we ever build write paths
+
+The clean order would be:
+
+1. **`Lutaml::Uml::Document → Sparx XMI`** — most useful, least schema
+   complexity. Reuses `::Xmi::Sparx::Root`'s type system if serialization
+   support is added upstream.
+2. **`Lutaml::Uml::Document → .lur`** — already exists via
+   `Repository.export_to_package`. Neutral, lossless for the UML subset.
+3. **`Lutaml::Uml::Document → .qea`** — last resort. Only if EA-native
+   interchange is a hard requirement and `.lur` + XMI export are
+   insufficient.

data/examples/lur_basic_usage.rb

@@ -0,0 +1,221 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example: Basic LUR Repository Operations
+#
+# This example demonstrates basic repository operations including:
+# - Loading from XMI or LUR files
+# - Finding packages and classes
+# - Navigating inheritance hierarchies
+# - Querying associations
+
+# Load local development version
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "lutaml"
+require "lutaml/uml_repository"
+require "ea"
+
+# Example 1: Load from XMI file
+puts "=" * 80
+puts "Example 1: Load from XMI"
+puts "=" * 80
+
+# Build repository from XMI (slow, 5-8 seconds for large models)
+# repo = Lutaml::UmlRepository::Repository.from_xmi("model.xmi")
+
+# Or use smart file detection (auto-detects .xmi or .lur)
+# repo = Lutaml::UmlRepository::Repository.from_file("model.xmi")
+
+# For this example, we'll show the API without actual file
+puts "repo = Lutaml::UmlRepository::Repository.from_xmi('model.xmi')"
+puts "# Builds indexes from XMI (5-8s for large models)"
+puts
+
+# Example 2: Load from LUR package (fast loading)
+puts "=" * 80
+puts "Example 2: Load from LUR package (< 100ms)"
+puts "=" * 80
+
+puts "repo = Lutaml::UmlRepository::Repository.from_package('model.lur')"
+puts "# Fast loading from pre-indexed package"
+puts
+
+# Example 3: Smart caching
+puts "=" * 80
+puts "Example 3: Smart caching"
+puts "=" * 80
+
+puts "repo = Lutaml::UmlRepository::Repository.from_file_cached('model.xmi')"
+puts "# Uses cached .lur if newer than .xmi, otherwise rebuilds"
+puts
+
+# For demonstration, let's use a QEA file if available
+qea_file = Dir.glob("examples/qea/*.qea").first
+puts "=" * 80
+if qea_file
+  puts "Example 4: Loading from QEA file (10-20x faster than XMI)"
+  puts "=" * 80
+  puts "QEA file found: #{qea_file}"
+
+  # Parse QEA directly
+  document = Ea::Qea.parse(qea_file)
+  repo = Lutaml::UmlRepository::Repository.new(document: document)
+
+  puts "Loaded successfully!"
+  puts
+
+  # Example 5: Finding packages
+  puts "=" * 80
+  puts "Example 5: Finding packages"
+  puts "=" * 80
+
+  # Find root package
+  root = repo.find_package("ModelRoot")
+  if root
+    puts "Root package: #{root.name}"
+    puts "Root type: #{root.class}"
+  end
+  puts
+
+  # List top-level packages
+  packages = repo.list_packages("ModelRoot", recursive: false)
+  puts "Top-level packages (#{packages.size}):"
+  packages.first(5).each do |pkg|
+    puts "  - #{pkg.name}"
+  end
+  puts "  ..." if packages.size > 5
+  puts
+
+  # Example 6: Finding classes
+  puts "=" * 80
+  puts "Example 6: Finding classes"
+  puts "=" * 80
+
+  # Get all classes
+  all_classes = repo.classes_index
+  puts "Total classes: #{all_classes.size}"
+  puts
+
+  # Find by stereotype
+  if all_classes.any?
+    first_class = all_classes.first
+    puts "First class: #{first_class.name}"
+    if first_class.respond_to?(:stereotype) && first_class.stereotype
+      puts "  Stereotype: #{first_class.stereotype}"
+    end
+  end
+  puts
+
+  # Example 7: Working with associations
+  puts "=" * 80
+  puts "Example 7: Associations"
+  puts "=" * 80
+
+  associations = repo.associations_index
+  puts "Total associations: #{associations.size}"
+
+  if associations.any?
+    assoc = associations.first
+    puts "\nFirst association:"
+    member_end = assoc.member_end
+    if member_end.is_a?(Array) && member_end.any?
+      puts "  Name: #{member_end.first&.name || 'unnamed'}"
+    elsif member_end.respond_to?(:name)
+      puts "  Name: #{member_end.name}"
+    else
+      puts "  Name: unnamed"
+    end
+
+    member_end_type = assoc.member_end_type
+    if member_end_type.is_a?(Array) && member_end_type.any?
+      puts "  Type: #{member_end_type.first}"
+    elsif member_end_type
+      puts "  Type: #{member_end_type}"
+    end
+  end
+  puts
+
+  # Example 8: Statistics
+  puts "=" * 80
+  puts "Example 8: Repository statistics"
+  puts "=" * 80
+
+  stats = repo.statistics
+  puts "Packages: #{stats[:total_packages]}"
+  puts "Classes: #{stats[:total_classes]}"
+  puts "Associations: #{stats[:total_associations]}"
+  puts "Diagrams: #{stats[:total_diagrams]}"
+
+  if stats[:classes_by_stereotype]
+    puts "\nClasses by stereotype:"
+    stats[:classes_by_stereotype].first(5).each do |stereotype, count|
+      puts "  #{stereotype}: #{count}"
+    end
+  end
+  puts
+
+  # Example 9: Search
+  puts "=" * 80
+  puts "Example 9: Search"
+  puts "=" * 80
+
+  # Search for elements
+  results = repo.search("Object", types: [:class])
+  puts "Search for 'Object' in class names:"
+  puts "  Found #{results[:total]} matches"
+  if results[:classes]
+    puts "  Classes (#{results[:classes].size}):"
+    results[:classes].first(3).each do |result|
+      puts "    - #{result.element.name}"
+    end
+  end
+  puts
+
+else
+  puts "No QEA files found in examples/qea/"
+  puts "=" * 80
+  puts
+  puts "To use this example:"
+  puts "1. Place a .qea or .xmi file in examples/qea/"
+  puts "2. Or modify the script to point to your model file"
+  puts
+  puts "Example API usage (without actual file):"
+  puts <<~RUBY
+
+    # Load repository
+    repo = Lutaml::UmlRepository::Repository.from_xmi("model.xmi")
+
+    # Find package
+    package = repo.find_package("ModelRoot::MyPackage")
+
+    # Find class
+    klass = repo.find_class("ModelRoot::MyPackage::MyClass")
+
+    # Get class attributes
+    klass.attributes.each do |attr|
+      puts "\#{attr.name}: \#{attr.type}"
+    end
+
+    # Find by stereotype
+    feature_types = repo.find_classes_by_stereotype("featureType")
+
+    # Get inheritance
+    parent = repo.supertype_of(klass)
+    children = repo.subtypes_of(klass)
+
+    # Get associations
+    assocs = repo.associations_of(klass)
+
+    # Search
+    results = repo.search("Building")
+
+    # Get statistics
+    stats = repo.statistics
+    puts "Total classes: \#{stats[:total_classes]}"
+  RUBY
+end
+
+puts "=" * 80
+puts "Example complete!"
+puts "=" * 80

data/examples/lur_cli_workflow.rb

@@ -0,0 +1,263 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example: CLI Workflow Patterns
+#
+# This example demonstrates common command-line workflow patterns for
+# working with LUR packages, including building, validation, and export.
+
+# Load local development version
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "lutaml"
+require "lutaml/uml_repository"
+require "ea"
+require "fileutils"
+
+puts "=" * 80
+puts "LUR CLI Workflow Examples"
+puts "=" * 80
+puts
+
+# Setup: Find a test file
+qea_file = Dir.glob("examples/qea/*.qea").first
+xmi_file = Dir.glob("examples/qea/*.xmi").first
+test_file = qea_file || xmi_file
+
+unless test_file
+  puts "No test files found in examples/qea/"
+  puts
+  puts "This example demonstrates CLI workflows. To run:"
+  puts "  1. Place a .qea or .xmi file in examples/qea/"
+  puts "  2. Or use the CLI commands directly:"
+  puts
+  puts "CLI command examples:"
+  puts <<~TEXT
+    # Build LUR package from XMI
+    $ lutaml uml build model.xmi -o model.lur
+
+    # Build from QEA (10-20x faster)
+    $ lutaml uml build model.qea -o model.lur
+
+    # Show package info
+    $ lutaml uml info model.lur
+
+    # List packages
+    $ lutaml uml ls model.lur
+
+    # Show package tree
+    $ lutaml uml tree model.lur --depth 3
+
+    # Search
+    $ lutaml uml search model.lur "Building"
+
+    # Find by stereotype
+    $ lutaml uml find model.lur --stereotype featureType
+
+    # Get statistics
+    $ lutaml uml stats model.lur
+
+    # Validate
+    $ lutaml uml validate model.lur
+
+    # Export to CSV
+    $ lutaml uml export model.lur --format csv -o classes.csv
+
+    # Generate documentation site
+    $ lutaml uml docs model.lur -o docs/
+
+    # Start interactive shell
+    $ lutaml uml repl model.lur
+
+    # Watch mode (auto-rebuild on changes)
+    $ lutaml uml watch model.xmi -o model.lur
+  TEXT
+  exit 0
+end
+
+puts "Test file found: #{test_file}"
+puts "File size: #{File.size(test_file) / 1024}KB"
+puts
+
+# Workflow 1: Build LUR package
+puts "=" * 80
+puts "Workflow 1: Building LUR package"
+puts "=" * 80
+
+lur_output = "examples/workflow_test.lur"
+FileUtils.rm_f(lur_output)
+
+puts "Loading from: #{test_file}"
+start_time = Time.now
+
+# Parse the source file
+if test_file.end_with?(".qea")
+  puts "Parsing QEA file (fast)..."
+  document = Ea::Qea.parse(test_file)
+elsif test_file.end_with?(".xmi")
+  puts "Parsing XMI file..."
+  document = Lutaml::Parser.parse([File.new(test_file)]).first
+else
+  puts "Unknown file type"
+  exit 1
+end
+
+parse_time = Time.now - start_time
+puts "Parsed in #{parse_time.round(2)}s"
+
+# Build repository
+puts "Building repository..."
+repo = Lutaml::UmlRepository::Repository.new(document: document)
+build_time = Time.now - start_time - parse_time
+puts "Built in #{build_time.round(2)}s"
+
+# Export to LUR package
+puts "Exporting to LUR package..."
+export_start = Time.now
+repo.export_to_package(lur_output,
+                       name: "Test Model",
+                       version: "1.0",
+                       serialization_format: :marshal)
+export_time = Time.now - export_start
+puts "Exported in #{export_time.round(2)}s"
+puts "Package created: #{lur_output} (#{File.size(lur_output) / 1024}KB)"
+puts
+
+# Workflow 2: Load from LUR (fast)
+puts "=" * 80
+puts "Workflow 2: Fast loading from LUR"
+puts "=" * 80
+
+load_start = Time.now
+loaded_repo = Lutaml::UmlRepository::Repository.from_package(lur_output)
+load_time = Time.now - load_start
+puts "Loaded in #{load_time.round(2)}s (vs #{parse_time.round(2)}s for parsing)"
+puts "Speedup: #{(parse_time / load_time).round(1)}x faster"
+puts
+
+# Workflow 3: Validation
+puts "=" * 80
+puts "Workflow 3: Model validation"
+puts "=" * 80
+
+result = loaded_repo.validate
+puts "Validation result: #{result.valid? ? 'VALID ✓' : 'INVALID ✗'}"
+puts "Errors: #{result.errors.size}"
+puts "Warnings: #{result.warnings.size}"
+
+if result.errors.any?
+  puts "\nFirst 3 errors:"
+  result.errors.first(3).each do |error|
+    puts "  - #{error}"
+  end
+end
+
+if result.warnings.any?
+  puts "\nFirst 3 warnings:"
+  result.warnings.first(3).each do |warning|
+    puts "  - #{warning}"
+  end
+end
+puts
+
+# Workflow 4: Statistics
+puts "=" * 80
+puts "Workflow 4: Model statistics"
+puts "=" * 80
+
+stats = loaded_repo.statistics
+puts "Model overview:"
+puts "  Packages: #{stats[:total_packages]}"
+puts "  Classes: #{stats[:total_classes]}"
+puts "  Data types: #{stats[:total_data_types]}"
+puts "  Enumerations: #{stats[:total_enums]}"
+puts "  Associations: #{stats[:total_associations]}"
+puts "  Diagrams: #{stats[:total_diagrams]}"
+
+if stats[:max_package_depth]
+  puts "\nPackage structure:"
+  puts "  Max depth: #{stats[:max_package_depth]}"
+end
+
+if stats[:classes_by_stereotype]
+  puts "\nTop stereotypes:"
+  stats[:classes_by_stereotype].first(5).each do |stereotype, count|
+    puts "  #{stereotype}: #{count}"
+  end
+end
+puts
+
+# Workflow 5: Query and export
+puts "=" * 80
+puts "Workflow 5: Query and export"
+puts "=" * 80
+
+# Find all classes
+all_classes = loaded_repo.classes_index
+puts "Found #{all_classes.size} classes"
+
+if all_classes.any?
+  # Sample some classes
+  sample_classes = all_classes.first(5)
+  puts "\nSample classes:"
+  sample_classes.each do |klass|
+    puts "  - #{klass.name}"
+    if klass.respond_to?(:stereotype) && klass.stereotype
+      puts "    Stereotype: #{klass.stereotype}"
+    end
+    if klass.respond_to?(:attributes) && klass.attributes
+      puts "    Attributes: #{klass.attributes.size}"
+    end
+  end
+
+  # Search example
+  puts "\nSearch for 'Object':"
+  results = loaded_repo.search("Object", types: [:class])
+  puts "  Found #{results[:total]} matches in class names"
+end
+puts
+
+# Workflow 6: Smart caching demonstration
+puts "=" * 80
+puts "Workflow 6: Smart caching"
+puts "=" * 80
+
+puts "Smart caching automatically uses LUR if newer than source:"
+puts
+puts "# First run - builds from source"
+puts "repo = Repository.from_file_cached('#{test_file}')"
+puts "# Creates #{test_file.sub(/\.(xmi|qea)$/, '.lur')}"
+puts
+puts "# Subsequent runs - loads from cache"
+puts "repo = Repository.from_file_cached('#{test_file}')"
+puts "# Uses cached .lur (< 100ms)"
+puts
+
+# Cleanup
+puts "=" * 80
+puts "Cleanup"
+puts "=" * 80
+FileUtils.rm_f(lur_output)
+puts "Removed test file: #{lur_output}"
+puts
+
+puts "=" * 80
+puts "Workflow examples complete!"
+puts "=" * 80
+puts
+puts "Summary of CLI commands:"
+puts "  build      - Build LUR package from XMI/QEA"
+puts "  info       - Show package metadata"
+puts "  validate   - Validate model integrity"
+puts "  ls         - List elements"
+puts "  tree       - Show package hierarchy"
+puts "  inspect    - Show element details"
+puts "  search     - Full-text search"
+puts "  find       - Find by criteria"
+puts "  stats      - Model statistics"
+puts "  export     - Export to various formats"
+puts "  docs       - Generate documentation site"
+puts "  serve      - Start web UI"
+puts "  repl       - Interactive shell"
+puts
+puts "Run 'lutaml uml --help' for full command reference"