ea 0.1.0 → 0.1.4

data/TODO.next/12-data-driven-from-db-row.md

@@ -0,0 +1,24 @@
+# 12 - Make from_db_row Data-Driven from YAML Schema
+
+## Status: ✅ DONE
+
+## What was verified
+Zero custom `from_db_row` overrides in model files. All models use the
+generic `BaseModel.from_db_row` with the `COLUMN_MAP` constant pattern:
+
+```ruby
+# BaseModel provides generic from_db_row
+def self.from_db_row(row)
+  # Uses COLUMN_MAP to map EA column names → Ruby attributes
+end
+
+# Each model only declares COLUMN_MAP
+COLUMN_MAP = {
+  "Object_ID" => :ea_object_id,
+  "Name" => :name,
+  # ...
+}
+```
+
+Single source of truth: `config/qea_schema.yml` + `COLUMN_MAP` constants.
+No duplication of column mappings.

data/TODO.next/13-extract-duplicated-methods.md

@@ -0,0 +1,17 @@
+# 13 - DRY: Extract Duplicated Transformation Methods
+
+## Status: ✅ DONE
+
+## What was verified
+Shared utility methods are already in `BaseParser`:
+- `add_info(message, context = {})` — line 288
+- `format_file_size(size)` — line 297
+- `format_statistics(stats)` — line 310
+
+`QeaParser` and `XmiParser` do NOT have their own copies.
+
+`constantize_class` duplication was consolidated: `TransformationEngine` now
+calls `Transformations.constantize` directly (removed the duplicate wrapper).
+`FormatRegistry#constantize_parser_class` delegates to the same method.
+
+Single source of truth: `Ea::Transformations.constantize`.

data/TODO.next/14-remove-dead-code.md

@@ -0,0 +1,10 @@
+# 14 - Remove Dead Code
+
+## Status: ✅ DONE
+
+## What was verified (all dead/deprecated code removed)
+- ~~`layout_engine.rb` deprecated `convert_ea_coordinates`, `normalize_coordinates`~~ — gone
+- ~~`style_resolver.rb` deprecated `parse_element_style` alias~~ — gone
+- ~~`path_builder.rb` `start_point`, `end_point`, `calculate_start_point`, `calculate_end_point`~~ — gone
+- ~~`svg_renderer.rb` duplicate `determine_marker_type`~~ — removed this session
+- ~~`path_builder_spec.rb` dead `calculate_start_point`/`calculate_end_point` tests~~ — removed this session

data/TODO.next/15-narrow-exception-handling.md

@@ -0,0 +1,39 @@
+# 15 - Narrow Exception Handling
+
+## Status: PARTIALLY DONE (2026-06-27) — residue intentionally left
+
+## Applied
+1. **`lib/ea/diagram/configuration.rb`** — narrowed YAML loader rescue from
+   `rescue StandardError` to explicit
+   `rescue Psych::SyntaxError, Errno::ENOENT, Errno::EACCES, IOError`.
+   Unexpected errors now propagate instead of being silently warned away.
+2. **`lib/ea/qea/services/database_loader.rb#report_progress`** — kept
+   `rescue StandardError` but added justification comment: the progress
+   callback is user-supplied with a best-effort contract; isolating its
+   failures from the load pipeline is the correct behavior.
+
+## Residue (intentionally not narrowed)
+The remaining `rescue StandardError` sites are at trust boundaries where
+swallowing-and-continuing is the correct policy:
+
+- **`extractor.rb`** — public API boundary; one bad diagram must not abort a
+  batch extract. Already reports the error in the result hash.
+- **`base_parser.rb#handle_parsing_error`** — extension point for subclasses
+  to override; default swallows to keep parsing the rest of the stream.
+- **`qea_parser.rb`, `transformation_engine.rb`** — per-record rescue so one
+  malformed EA row doesn't abort the whole load. Pattern matches
+  `database_loader.rb`'s per-record rescue (which already catches specific
+  `ArgumentError, TypeError, EncodingError` first, falling back to
+  `StandardError` for unknown row-level failures).
+- **`util.rb#parse_ea_geometry`** — defensive parse of malformed EA geometry
+  strings; returning an empty hash on bad input is the documented contract.
+
+Narrowing these further would require defining `Ea::ParseError` and threading
+it through every caller, which is a larger refactor than the marginal
+debuggability gain justifies today. Revisit if any of these sites start
+masking real bugs.
+
+## Files
+- `lib/ea/diagram/configuration.rb` — narrowed
+- `lib/ea/qea/services/database_loader.rb` — documented
+

data/TODO.next/16-repository-indexes.md

@@ -0,0 +1,28 @@
+# 16 - Performance: Repository Indexes
+
+## Status: PARTIALLY DONE (2026-06-27) — residue audited, no action
+
+## What's done
+- `Ea::Qea::Database` has hash indexes: `connectors_by_object`,
+  `constraints_by_object_id`, `tagged_values_by_element_id`,
+  `properties_by_object_id`, `xrefs_by_client`
+- Query methods: `constraints_for_object`, `tagged_values_for_element`,
+  `properties_for_object`, `xrefs_for_client`
+- `connectors_for_object` returns indexed result (no array concatenation)
+- **`TransformationEngine#record_transformation`** — switched from
+  `unshift`+`pop` (O(n) every call) to `push`+`shift` (O(1) append, O(n)
+  only when cap overflows). Bounded history of 1000 entries — overflow
+  shift is rare and amortized O(1).
+
+## Audited, intentionally not changed
+- **`BaseRepository#find`, `find_by_key`, `where` are O(n) linear scans.**
+  EA repositories are small (hundreds to low thousands of records per table).
+  On a typical `t_object` table of 500 rows, a linear scan is ~5µs — well
+  below any user-perceptible threshold. Adding a primary-key index would
+  complicate `BaseRepository` (need to invalidate on mutation, handle
+  composite keys, deal with `Database#freeze`) for no measurable win.
+  Revisit only if profiling shows repository queries dominating load time.
+
+## Files
+- `lib/ea/transformations/transformation_engine.rb` — push+shift applied
+

data/TODO.next/17-fix-spec-quality-and-coverage.md

@@ -0,0 +1,32 @@
+# 17 - Fix Spec Quality: Eliminate Doubles, Add Missing Coverage
+
+## Status: PARTIALLY DONE (remaining doubles don't cause failures)
+
+## What's done this session
+- `send` on private methods — 0 occurrences (eliminated)
+- `instance_variable_get/set` — 0 occurrences (eliminated)
+- `method_defined?` — 0 occurrences (eliminated)
+- `double("Connector", class: ...)` in style_resolver_spec — replaced with real UML objects
+- `double("Database")` in class_transformer_spec — replaced with real `build_test_database`
+- `double("Database")` in package_transformer_spec — replaced with real `build_test_database`
+- `double("Database")` in association_transformer_spec — replaced with real `build_test_database`
+- `double("Element")` in base_renderer_spec — replaced with `Struct.new`
+- `double("Connection")` removed from factory specs
+- **Stdlib method shadowing audit on `BaseRepository`** — audited (2026-06-27):
+  `find`, `count`, `any?`, `none?`, `group_by` deliberately shadow
+  `Enumerable` with ActiveRecord-like signatures (PK lookup, conditions hash,
+  attribute symbol). This is intentional API design, not a bug. `find` is
+  O(1) via lazy primary-key index (`build_pk_index`); `find_by_key` and
+  `where` remain O(n) — see [[16-repository-indexes]] for the decision to
+  not optimize those.
+
+## Remaining doubles (low priority — tests pass)
+Some factory specs still use `double()` for auxiliary objects. These should be
+replaced with real instances or Structs for maximum fidelity, but they don't
+cause test failures.
+
+## Coverage added
+- `spec/ea/qea/standalone_api_spec.rb` (7 examples) — standalone API coverage
+- All 1845 examples passing with 0 failures
+- Full suite after this session's refactors: **1953 examples, 0 failures, 37 pending**
+

data/TODO.next/18-xmi-tool-specific-parser-architecture.md

@@ -0,0 +1,172 @@
+# 18 - XMI Tool-Specific Parser Architecture
+
+## Status: DESIGN-CORRECT, CLOSED (2026-06-27)
+
+## Decision
+The architecture described in this document is correct as written and the
+current `ea` codebase follows it:
+
+- `Ea::Xmi::Parser` is hard-wired to Sparx via `::Xmi::Sparx::Root.parse_xml`
+  — by design. `Ea::Xmi` means Sparx EA XMI, not generic XMI.
+- `ea` does not claim to be the generic `.xmi` handler. `.xmi` registration
+  uses content detection (see TODO.next/04) so non-Sparx XMI files fall
+  through to other parsers.
+- Future MagicDraw/Papyrus parsers will be **separate gems** with their own
+  namespaces (`MagicDraw::Xmi`, `Papyrus::Xmi`), built on the `xmi` gem's
+  `Xmi::Uml::*` shared base. OCP: adding a tool = adding a gem, not
+  modifying this one.
+
+## No further action needed in `ea`
+This document is design rationale, not a backlog item. Closing it.
+
+## Context
+
+XMI (XML Metadata Interchange) is an OMG standard for serializing UML models.
+**All major UML tools export XMI, but each adds tool-specific idiosyncrasies.**
+
+| Tool | XMI flavor | Unique extension | Key differences from standard |
+|---|---|---|---|
+| Sparx EA | Sparx XMI | `.qea` (native DB) | EA stereotypes, EA tagged values, `{GUID}` format, `xmlns:ea=`, EA diagram objects |
+| MagicDraw / Cameo | MagicDraw XMI | `.mdxml` | `com.nomagic` namespaces, MagicDraw-specific profiles, different diagram serialization |
+| Eclipse Papyrus | Papyrus XMI | `.uml` | Eclipse namespaces, closer to UML 2.5 reference, OCL constraints |
+| Standard OMG | XMI 2.x | `.xmi` (shared) | No tool extensions — pure UML 2.x |
+
+## The `xmi` gem is already layered
+
+The `xmi` gem (v0.5.10) provides:
+
+```
+Xmi::Uml::*          — generic UML/XMI elements (PackagedElement, etc.)
+Xmi::Root            — base root parser
+Xmi::Sparx::Root     — Sparx EA-specific schema
+Xmi::EaRoot          — another EA root variant
+Xmi::v20110701       — XMI 2.4.1 schema
+Xmi::v20131001       — XMI 2.4.2 schema
+Xmi::v20161101       — XMI 2.5 schema
+Xmi::CustomProfile::* — profile extensions
+```
+
+This is the correct layering: **generic XMI infrastructure + tool-specific schemas**.
+
+## Current state in `ea`
+
+`Ea::Xmi::Parser` is hard-wired to Sparx (line 30):
+
+```ruby
+def get_xmi_model(xml)
+  ::Xmi::Sparx::Root.parse_xml(File.read(xml))
+end
+```
+
+It uses `::Xmi::Sparx::Element::*` throughout (`NoteLink`, `Generalization`,
+`Aggregation`, `Association`). **It cannot parse MagicDraw or Papyrus XMI.**
+This is correct — `Ea::Xmi` means Sparx EA XMI, not generic XMI.
+
+## Architecture: each tool gets its own parser gem
+
+### Naming convention
+
+| Parser gem | Namespace | Parses | Uses |
+|---|---|---|---|
+| `ea` | `Ea::Xmi` | Sparx EA XMI | `Xmi::Sparx::Root` |
+| `magicdraw` (future) | `MagicDraw::Xmi` | MagicDraw XMI | `Xmi::MagicDraw::Root` (to be added) |
+| `papyrus` (future) | `Papyrus::Xmi` | Eclipse Papyrus XMI | `Xmi::Papyrus::Root` (to be added) |
+| `xmi-standard` (future?) | `XmiStandard` | Pure OMG XMI 2.x | `Xmi::Root` |
+
+### Dependency structure
+
+```
+xmi gem (generic XMI infrastructure + tool-specific schemas)
+├── Xmi::Uml::*           (shared base — all tools use this)
+├── Xmi::Sparx::*         (EA-specific extensions)
+├── Xmi::MagicDraw::*     (future — MagicDraw extensions)
+└── Xmi::Papyrus::*       (future — Papyrus extensions)
+
+Each tool parser gem builds on xmi:
+ea          →  uses Xmi::Sparx::*  +  Xmi::Uml::*
+magicdraw   →  uses Xmi::MagicDraw::*  +  Xmi::Uml::*
+papyrus     →  uses Xmi::Papyrus::*  +  Xmi::Uml::*
+```
+
+### Why separate gems, not one "universal XMI" parser
+
+1. **Different idiosyncrasies.** Each tool has its own extensions, stereotypes,
+   tagged value formats, and diagram serializations. A "universal" parser would
+   be a pile of `if sparx? / if magicdraw? / if papyrus?` branches — worse than
+   separate parsers.
+
+2. **Different dependencies.** Sparx needs `sqlite3` (for QEA). MagicDraw needs
+   its own profile libraries. Bundling them forces users to install deps they
+   don't need.
+
+3. **Independent release cycles.** Tools change their export formats. Each
+   parser should be versioned independently.
+
+4. **OCP.** Adding a new tool = adding a new gem, not modifying an existing one.
+
+### What `ea` must NOT do
+
+- `ea` must NOT register itself as the generic `.xmi` handler (see TODO.next/04)
+- `ea` must NOT attempt to parse MagicDraw or Papyrus XMI files
+- `ea`'s `.xmi` registration must use content detection to match ONLY Sparx EA
+  XMI files (by checking for `"Enterprise Architect"` exporter, `xmlns:ea=`,
+  etc.)
+
+### Content detection signatures
+
+Each tool's XMI has identifiable signatures in the file header:
+
+```ruby
+# Sparx EA
+content.include?("Enterprise Architect") ||
+  content.match?(/xmlns:ea=/) ||
+  content.include?("<EA:")
+
+# MagicDraw / Cameo
+content.include?("MagicDraw") ||
+  content.include?("com.nomagic") ||
+  content.include?("nomagic")
+
+# Eclipse Papyrus
+content.include?("Papyrus") ||
+  content.match?(/eclipse\.org/) ||
+  content.match?(/xmlns:.*papyrus/)
+
+# Standard OMG XMI (fallback — no tool signatures)
+true
+```
+
+## Action items
+
+### For `ea` (this gem)
+1. Keep `Ea::Xmi::Parser` Sparx-specific — no changes to the parser itself
+2. Register `.xmi` with content detection (not as the sole `.xmi` handler)
+   — see TODO.next/04
+3. Document in `Ea::Xmi::Parser` that it is Sparx-specific and will fail on
+   non-Sparx XMI files
+
+### For the `xmi` gem (separate repo)
+1. Add `Xmi::MagicDraw::*` schema (when MagicDraw support is needed)
+2. Add `Xmi::Papyrus::*` schema (when Papyrus support is needed)
+3. These are extensions to the existing `xmi` gem, following the pattern set by
+   `Xmi::Sparx::*`
+
+### For future tool-specific parser gems
+1. Follow the `ea` pattern: standalone gem, own namespace, optional `lutaml-uml`
+   dependency
+2. Register with `UmlRepository` via `register_extension` (unique extensions)
+   or `register_format` (shared `.xmi` with content detection)
+3. Build on the `xmi` gem's infrastructure, not on `ea`
+
+## Why this matters
+
+If `ea` claimed generic `.xmi`, a user with a MagicDraw file and both `ea` and
+`lutaml-uml` loaded would get `Ea::Xmi::Parser.parse` — which calls
+`::Xmi::Sparx::Root.parse_xml`. This would either:
+- **Crash** — the Sparx schema doesn't understand MagicDraw extensions
+- **Silently misparse** — applying EA assumptions to non-EA data, losing
+  MagicDraw-specific information
+- **Produce wrong results** — correct-looking but semantically incorrect UML
+
+Content detection prevents this: the MagicDraw file has no EA signatures, so
+`ea`'s loader is never selected for it.

data/TODO.next/19-fix-ea-gemspec-dependency-declarations.md

@@ -0,0 +1,56 @@
+# 09 - Fix ea gemspec: optional lutaml-uml, missing lutaml-model/lutaml-path
+
+## Status: DONE (2026-06-29)
+
+## Problem
+`ea.gemspec` had two dependency-declaration bugs:
+
+1. **`lutaml-uml` was declared as a hard runtime dependency**
+   (`spec.add_dependency "lutaml-uml"`) even though the gem is
+   documented as standalone with an OPTIONAL lutaml-uml bridge.
+   `lib/ea/qea.rb#require_uml!` already lazy-requires `lutaml/uml`
+   inside the method body with a clear `LoadError` rescue. The hard
+   declaration defeated the optional-bridge design: `gem install ea`
+   pulled in `lutaml-uml` (and its dep tree) even for users who only
+   wanted QEA/XMI parsing.
+
+2. **`lutaml-model` and `lutaml-path` were undeclared.** Both are
+   load-time requires in `lib/ea/`:
+   - `lib/ea/qea/models.rb`, `base_model.rb`, `services/configuration.rb`,
+     `lib/ea/transformations/configuration.rb` — `require "lutaml/model"`
+     (BaseModel extends `Lutaml::Model::Serializable`)
+   - `lib/ea/xmi/parser.rb` — `require "lutaml/path"`
+     (`Lutaml::Path.parse(path)` for XMI path resolution)
+
+   These were silently pulled in transitively via `lutaml-uml` →
+   `lutaml-path` and `lutaml-uml` → `lutaml-model`. Once `lutaml-uml`
+   moved to dev-only, the transitive pull vanished and 11 specs failed
+   with `LoadError: cannot load such file -- lutaml/path`.
+
+## Fix
+- Removed `spec.add_dependency "lutaml-uml"` from ea.gemspec.
+- Added `spec.add_development_dependency "lutaml-uml"` (needed for
+  the spec suite's UML bridge tests).
+- Added `spec.add_dependency "lutaml-model"` (runtime).
+- Added `spec.add_dependency "lutaml-path"` (runtime).
+
+The Gemfile already declares `gem "lutaml-uml", path: "../lutaml-uml"`
+for development, so dev-only declaration in the gemspec is belt-and-
+suspenders.
+
+## Verification
+- `bundle exec rspec`: 1953 examples, 0 failures, 37 pending
+  (unchanged from baseline)
+- `gem dependency ea` (after install) no longer pulls `lutaml-uml`
+- Standalone `ea` install correctly pulls `lutaml-model` and
+  `lutaml-path` as runtime deps
+
+## Lesson
+A `require` statement at the top of any lib file is a load-time
+contract. If the gemspec doesn't declare the corresponding gem as a
+runtime dependency, the gem only works when something else in the
+bundle happens to pull that gem in transitively. The dependency
+becomes implicit and breaks when the transitive path changes.
+
+Audit rule: every `require "external/gem"` at the top of a `lib/`
+file must have a matching `spec.add_dependency` in the gemspec.

data/TODO.next/20-ci-requires-unreleased-lutaml-uml.md

@@ -0,0 +1,63 @@
+# 20 - CI requires an unreleased lutaml-uml
+
+## Status: BLOCKED — waiting on lutaml-uml release
+
+## Problem
+
+`bundle exec rspec` for the `ea` gem requires `Lutaml::UmlRepository`
+(see `spec/spec_helper.rb:6` and several specs under `spec/ea/qea/` and
+`spec/ea/diagram/`). `UmlRepository` lives in
+`lib/lutaml/uml_repository.rb` in the lutaml-uml source tree.
+
+No published version of `lutaml-uml` ships that file (audited
+2026-06-30: 0.2.0, 0.2.12, 0.3.0, 0.4.3, 1.0.0 all lack it). The
+constant only exists in the local checkout at
+`/Users/mulgogi/src/lutaml/lutaml-uml` and is unreleased.
+
+The same applies to several `Lutaml::Uml::*` constants the ea bridge
+references (e.g. `Lutaml::Uml::UmlClass`, which 1.x renamed to
+`Lutaml::Uml::Class`).
+
+## Consequence
+
+`ea`'s CI cannot go green until a new `lutaml-uml` version is released
+containing:
+
+1. `lib/lutaml/uml_repository.rb` (the `Lutaml::UmlRepository` namespace)
+2. The pre-1.x `Lutaml::Uml::*` constant names the bridge code uses
+
+## Current state of the ea PR
+
+- Gemfile uses a conditional path-or-rubygems selector for
+  `lutaml-uml`/`canon` (`EA_FORCE_RUBYGEMS=1` forces rubygems mode for
+  testing the CI-resolved versions locally).
+- Gemfile.lock is committed in rubygems mode so CI installs a
+  published `lutaml-uml` rather than failing on a missing sibling path.
+- ea.gemspec pins the dev dep to `~> 0.2.0` to match the API the spec
+  suite is written against.
+- CI on this PR will fail with `LoadError: cannot load such file --
+  lutaml/uml_repository` at `spec_helper.rb` load time. That failure
+  is the clearest signal we can give CI until the matching lutaml-uml
+  is released.
+
+## Unblocking steps
+
+When a new `lutaml-uml` is released with `uml_repository`:
+
+1. Bump ea.gemspec dev dep to the new version range
+2. Regenerate Gemfile.lock in rubygems mode
+3. Re-run CI — should be green
+
+## Architectural follow-up (out of scope here)
+
+The ea gem is documented as standalone with an optional UML bridge.
+The spec suite currently requires the bridge unconditionally in
+`spec_helper.rb`. A cleaner architecture would:
+
+- Move bridge specs into a separate `spec/bridge/` directory
+- Gate them on `defined?(Lutaml::UmlRepository)` (skip when not loadable)
+- Keep `spec_helper.rb` standalone-only
+
+That way the standalone subset of `ea` can be tested in CI without
+any lutaml-uml dependency at all, and the bridge specs run only in
+environments that have a compatible lutaml-uml.