ea 0.1.0 → 0.1.4

data/TODO.next/28-extract-xml-sanitizer.md

@@ -0,0 +1,51 @@
+# 28 - Extract XmlSanitizer (single-pass empty-element strip)
+
+## Status: DONE → SUPERSEDED (2026-07-01)
+
+The XmlSanitizer was extracted into its own class on this branch
+and used as a post-processing pass on the Transformer output. It was
+then deleted when the upstream fix (xmi gem VALUE_MAP) made it
+unnecessary.
+
+## History
+
+### Step 1: extracted into its own class
+Originally `Transformer#strip_empty_elements` was a 12-line
+method on the transformer that worked around the xmi gem's
+round-trip-oriented `VALUE_MAP`. The workaround used a while-loop
+with Nokogiri XPath to remove truly-empty elements.
+
+Extracted to `lib/ea/transformers/qea_to_xmi/xml_sanitizer.rb`
+as a focused class with a single-pass depth-first post-order walk.
+Spec at `spec/ea/transformers/qea_to_xmi/xml_sanitizer_spec.rb`
+(95 LOC, 11 examples).
+
+### Step 2: superseded by upstream VALUE_MAP fix
+The xmi gem refactor (`refactor/owned-end-schema-gap`) changed
+`Xmi::VALUE_MAP` to skip empty elements on serialization:
+
+```ruby
+VALUE_MAP = {
+  from: { nil: :empty, empty: :empty, omitted: :empty },
+  to:   { nil: :omitted, empty: :omitted, omitted: :omitted },
+}
+```
+
+After this change, the ea transformer emits no `<child/>` empty
+elements at all — the post-processing pass was unnecessary.
+
+### Step 3: deleted
+`lib/ea/transformers/qea_to_xmi/xml_sanitizer.rb` and its spec
+were deleted. The transformer's `serialize` method now just calls
+`build_root.to_xml(use_prefix: true)` with no sanitization.
+
+## Verification
+- Full ea suite: 2005 examples, 0 failures, 37 pending
+- Output contains zero truly-empty elements (no `<generalization/>`,
+  no `<ownedEnd/>` without attributes).
+- The transformation pipeline is now: build model graph →
+  `to_xml(use_prefix: true)` → return. One pass, no Nokogiri
+  re-parse, no element-mutation pass.
+
+## Closes
+TODO 21 §1 — "xmi gem empty-element rendering (architectural debt)".

data/TODO.next/29-ocp-registry-for-classifier-builders.md

@@ -0,0 +1,58 @@
+# 29 - OCP registry for QEA classifier builders
+
+## Status: DONE (2026-07-01)
+
+## Problem
+`Transformer#build_classifier` (transformer.rb:179-187) dispatches on
+`obj.transformer_type` via a `case/when` statement:
+
+```ruby
+case kind
+when :class        then build_class(obj)
+when :enumeration  then build_enumeration(obj)
+when :data_type    then build_data_type(obj)
+when :instance     then build_instance(obj)
+end
+```
+
+CLAUDE.md explicitly says "Registry pattern for OCP — new types are
+added by registration, not by modifying `case/when`". With 4
+branches the cost is low, but the project rule is the project rule.
+
+TODO 21 defended the case statement by saying "polymorphism lives in
+the xmi gem's xmi:type discriminator on PackagedElement". That is
+true for *XMI rendering shape* (the xmi gem picks the right element
+name + child set based on `xmi:type`). It is **not** true for the
+decision of *which EA row maps to which builder* — that decision is
+made by `EaObject#transformer_type` and dispatched here. Adding a
+new builder (e.g., `:signal`, `:interface`) still requires modifying
+this method.
+
+## Fix
+Replace the case statement with a frozen hash of lambdas. Builders
+are looked up by `transformer_type` symbol; unknown kinds return nil
+(preserving current "skip" behaviour).
+
+```ruby
+CLASSIFIER_BUILDERS = {
+  class:       ->(t, o) { t.build_class(o) },
+  enumeration: ->(t, o) { t.build_enumeration(o) },
+  data_type:   ->(t, o) { t.build_data_type(o) },
+  instance:    ->(t, o) { t.build_instance(o) },
+}.freeze
+
+def build_classifier(obj)
+  kind = obj.transformer_type || obj.object_type&.downcase&.to_sym
+  CLASSIFIER_BUILDERS[kind]&.call(self, obj)
+end
+```
+
+Adding a new kind now means adding one entry to the constant, no
+method body change.
+
+## Verification
+- Behaviour unchanged: unknown kinds return nil (skipped downstream
+  via `compact`).
+- Spec for `build_classifier` covers all 4 known kinds and the
+  unknown-kind fall-through.
+- Project rule "Registry pattern for OCP" now satisfied.

data/TODO.next/30-struct-return-for-association-end.md

@@ -0,0 +1,37 @@
+# 30 - Replace ad-hoc Hash return with Struct in build_association_end
+
+## Status: DONE (2026-07-01)
+
+## Problem
+`Transformer#build_association_end` (transformer.rb:326-344) returns
+a two-key Hash:
+
+```ruby
+{ xmi_id: end_id, model: model }
+```
+
+The caller (`build_association`) destructures it as
+`dest_end[:xmi_id]`, `dest_end[:model]`. Ad-hoc Hash returns are
+fragile — typos in keys (`[:xmii_id]`) fail silently as nil, and
+the contract is invisible at the method signature.
+
+## Fix
+Define a frozen Struct for the return type:
+
+```ruby
+AssociationEnd = Struct.new(:xmi_id, :model)
+```
+
+`build_association_end` returns `AssociationEnd.new(end_id, model)`.
+Caller uses `dest_end.xmi_id`, `dest_end.model` — typos now raise
+NoMethodError at the call site.
+
+The Struct lives in the QeaToXmi namespace
+(`Ea::Transformers::QeaToXmi::AssociationEnd`) so it can be referenced
+in specs and reused by future wire-up code.
+
+## Verification
+- `build_association` reads `dest_end.xmi_id` / `dest_end.model`
+  instead of hash keys.
+- Spec covers `build_association_end` directly, asserting the Struct
+  shape and the synthesised IDs.

data/TODO.next/31-idallocator-specs.md

@@ -0,0 +1,27 @@
+# 31 - Specs for IdAllocator
+
+## Status: DONE (2026-07-01)
+
+## Problem
+`Ea::Transformers::QeaToXmi::IdAllocator` is a public class with two
+public methods (`allocate`, `for_multiplicity` at the time of the
+audit; after TODO 23 it has just `allocate`). It has counter state,
+seed-based memoisation, and prefix-based formatting. None of this
+behaviour is directly tested — it is only exercised transitively via
+the Transformer specs.
+
+## Fix
+New `spec/ea/transformers/qea_to_xmi/id_allocator_spec.rb`:
+
+- `allocate` returns prefixed, zero-padded, monotonic IDs.
+- Same seed → same ID (memoisation).
+- Different seeds → different IDs.
+- `nil` seed → still allocates (no memoisation).
+- After TODO 25: parent GUID incorporation — `parent_guid` arg
+  produces the Sparx `EAID_LI000001_<guid_tail>` format.
+- Multiple parents with the same counter values produce distinct
+  full IDs (GUID suffix disambiguates).
+
+## Verification
+File exists, runs cleanly with `bundle exec rspec`, and covers the
+public `allocate` API exhaustively.

data/TODO.next/32-phase2-gap-sentinel-specs.md

@@ -0,0 +1,53 @@
+# 32 - Phase 2 sentinel specs (track xmi gem gaps)
+
+## Status: ✅ DONE (2026-07-01) — sentinels flipped as xmi gem schema migrated
+
+## Problem
+TODO 21 documented four attribute gaps the xmi gem didn't model.
+The original spec suite did not assert the absence of these
+attributes. When the xmi gem added support, nothing in the ea test
+suite signaled that we should wire them up.
+
+## Original fix (sentinels)
+Added sentinel specs that explicitly asserted these attributes were
+not emitted, with comments pointing at TODO 21. When the xmi gem
+added support, the first PR to wire the attribute up would need to
+flip the assertion to positive — making the wiring visible in code
+review.
+
+## Update after xmi gem schema migration
+The xmi gem refactor branch `refactor/owned-end-schema-gap` landed
+schema support for:
+- `visibility` on Property / Operation / Parameter / OwnedEnd / Class
+- `isAbstract` on packagedElement
+- `aggregation` on OwnedEnd
+- `classifier` on InstanceSpecification
+- `upperValue`/`lowerValue` child models on OwnedEnd (TODO 26)
+- `Slot`, `OpaqueExpression`, `InterfaceRealization` new models
+
+The ea transformer was extended to wire up visibility, isAbstract,
+aggregation (containment mapping), classifier (pdata1 mapping), and
+the OwnedEnd child elements.
+
+## Current spec state
+The original "Phase 2 gaps" sentinel block has split into two:
+
+### Phase 2 wiring (xmi gem schema migration landed)
+Positive assertions for the four attributes now emitted:
+- visibility on Property
+- visibility on Operation
+- isAbstract on packagedElement
+- upperValue/lowerValue on ownedEnd
+
+### Phase 2 gaps still deferred
+Negative assertions for two attributes the basic.qea fixture does
+not exercise (no data to wire against):
+- aggregation on ownedEnd (no composite/shared containment in fixture)
+- classifier on InstanceSpecification (no pdata1 set in fixture)
+
+When a fixture with relevant data is available, these flip to positive.
+
+## Verification
+All qea_to_xmi specs pass (104 examples). Output now emits visibility
+on all 102 attributes, isAbstract on all 65 classes, upperValue and
+lowerValue on all 102 attributes + 80 association ends.

data/TODO.next/33-normalize-lower-cleanup.md

@@ -0,0 +1,30 @@
+# 33 - normalize_lower was identity — fold into Cardinality module
+
+## Status: DONE (2026-07-01, folded into TODO 27)
+
+## Problem
+`Transformer#normalize_lower` (transformer.rb:474-476) was:
+
+```ruby
+def normalize_lower(raw)
+  raw.to_s
+```
+
+Pure identity — does nothing. Either remove it (callers can `.to_s`
+themselves) or implement actual normalisation matching how
+`normalize_upper` handles the `*` token.
+
+## Fix
+Folded into the Cardinality extraction (TODO 27). The new
+`Cardinality.normalize_lower` returns the default `"0"` for empty
+input, matching how real Sparx XMI represents unspecified lower
+bounds (always emits `<lowerValue value="0"/>`, never empty).
+
+This change also supports TODO 26 (upperValue/lowerValue count gap)
+— always emitting `lowerValue` requires a sane default for the
+"no bound specified" case.
+
+## Verification
+- Old `normalize_lower` identity removed from transformer.
+- `Cardinality.normalize_lower("")` returns `"0"`.
+- `Cardinality.normalize_lower("1")` returns `"1"`.

data/TODO.next/34-document-member-end-order-rt-prefix.md

@@ -0,0 +1,29 @@
+# 34 - Document member-end order + harmonise RT prefix
+
+## Status: DONE (2026-07-01)
+
+## Problem
+Two small clarity issues in `lib/ea/transformers/qea_to_xmi/transformer.rb`:
+
+1. **Implicit member-end order.** `build_association` (line 314-324)
+   emits `dest_end` first, then `src_end`. EA round-trip depends on
+   this ordering but no comment explains why. A future contributor
+   re-ordering for "tidiness" would silently break round-trip
+   fidelity.
+2. **Undocumented "RT" prefix.** `build_return_parameter` (line 400)
+   synthesises IDs with `prefix: "RT"`. The `IdAllocator` documents
+   well-known Sparx prefixes (LI, OE, SL, NL, DB) but not RT.
+
+## Fix
+
+1. Add a one-line comment at the member-end ordering site explaining
+   the Sparx convention. The ordering comes from how Sparx EA
+   serialises its `t_connector` rows: destination role first in
+   `<memberEnd>`, source role second.
+2. Add `RETURN_PARAMETER = "RT"` to IdAllocator's well-known prefix
+   list with a comment explaining what it stands for. Update
+   `build_return_parameter` to reference the constant.
+
+## Verification
+- Diff shows the comment + constant addition; no behaviour change.
+- Existing specs continue to pass.

data/TODO.next/35-walk-runstate-for-instance-slots.md

@@ -0,0 +1,76 @@
+# 35 - Walk t_object.RunState for instance specification slots
+
+## Status: ✅ DONE (2026-07-03)
+
+## Problem
+`build_instance` originally emitted an empty `slot: []` array, which
+silently dropped the run-state data that real Sparx XMI carries as
+`<slot>` children of `<packagedElement type="uml:InstanceSpecification">`.
+
+EA serialises run-state in `t_object.RunState` as a delimited string:
+
+```
+@VAR;Variable=<name>;Value=<value>;Op=<op>;@ENDVAR;
+```
+
+Multiple `@VAR` blocks concatenate directly. Each block maps to one
+UML Slot.
+
+## Fix
+
+### RunState module
+`lib/ea/transformers/qea_to_xmi/run_state.rb` is a pure-function
+parser. Returns an array of `Binding` structs (`Struct.new(:variable,
+:value, :op)`). The `Binding#body` method renders the Sparx wire form
+(`Op==` + `Value=Alice` → `body="=Alice"`).
+
+### Transformer wiring
+- `slots_for(obj)` walks `RunState.parse(obj.runstate)` and emits one
+  `Xmi::Uml::Slot` per binding.
+- `build_slot(instance, binding)` constructs the Slot with:
+  - `xmi:id` from `IdAllocator.allocate(prefix: SLOT, ...)`
+  - `definingFeature` resolved by looking up the named attribute on
+    the instance's classifier (via `t_object.classifier`)
+  - one `OpaqueExpression` value carrying the body
+- `build_slot_value` builds the OpaqueExpression with `xmi:id` from
+  `IdAllocator.allocate(prefix: OPAQUE_EXPRESSION, ...)`.
+- `defining_feature_for(instance, binding)` looks up the classifier
+  via `obj.classifier.to_i` (NOT `pdata1` as originally documented —
+  the live `t_object.classifier` column holds the ea_object_id of
+  the classifier directly).
+
+### ID prefixes used
+Both `SLOT` (`"SL"`) and `OPAQUE_EXPRESSION` (`"OE"`) are already on
+`IdAllocator`'s well-known-prefix list — no constant additions.
+
+## Discovery: t_object.classifier column
+The original TODO 35 draft assumed `pdata1` held the classifier ID.
+Investigation during implementation showed:
+
+- `pdata1`: always `nil` for `Object`-type rows in basic.qea.
+- `classifier`: an Integer column holding the classifier's
+  `ea_object_id` directly. Zero when no classifier is set.
+
+This matches what real Sparx XMI emits: InstanceSpecification rows
+without a classifier have no `classifier="..."` attribute on the
+`<packagedElement>`; rows with a classifier do.
+
+## Verification
+- Output for basic.qea: 22 slots, 20 with `definingFeature` (the 2
+  without come from InstanceSpecifications that have no classifier).
+  This matches the reference `spec/fixtures/basic.xmi` exactly.
+- Each slot carries one `<value>` child typed as
+  `uml:OpaqueExpression` with `body="=Value..."`.
+- Slot IDs use the Sparx `EAID_SL<NN>__<guid>` format; OpaqueExpression
+  IDs use `EAID_OE<NN>__<guid>`.
+- RunState module specs: 13 examples, 0 failures (pure-function
+  parser, edge cases covered).
+- Slot emission specs in transformer_spec.rb: 4 new examples
+  asserting count, body shape, definingFeature presence, ID prefix.
+
+## Sentinel flipped
+The "Phase 2 gaps still deferred" sentinel block had a negative
+assertion for `classifier on InstanceSpecification`. With this
+wiring landed, the spec flipped to a positive assertion. The
+`aggregation on ownedEnd` sentinel remains negative (basic.qea
+carries no composite/shared containment examples).

data/TODO.next/36-wire-interface-realization.md

@@ -0,0 +1,50 @@
+# 36 - Wire interfaceRealization for Interface-implementing classes
+
+## Status: DONE (2026-07-02)
+
+## Problem
+Sparx XMI emits `<interfaceRealization>` as a child of the
+implementing `<packagedElement type="uml:Class">`, not as a
+package-level relationship. The ea transformer was not emitting
+these at all — Realization connectors were silently dropped by
+`package_level_relationships` (Realization is not in
+`RELATIONSHIP_AT_PACKAGE_LEVEL`).
+
+## Fix
+
+### xmi gem
+`Xmi::Uml::InterfaceRealization` model added in the xmi gem refactor
+branch `refactor/owned-end-schema-gap`. `Xmi::Uml::PackagedElement`
+declares `interface_realization` as a child-element collection.
+
+### ea transformer
+- New `interface_realizations_for(obj)` method on
+  `Ea::Transformers::QeaToXmi::Transformer`. Walks the realization
+  connectors where this class is the source (client) and emits one
+  `InterfaceRealization` model per connector.
+- New `build_interface_realization(conn)` builder. Wires
+  `client` (this class), `supplier` and `contract` (the target
+  Interface — supplier and contract are the same when the target is
+  an Interface; if EA's data model ever distinguishes, this is the
+  single place to change).
+- `build_class` now passes `interface_realization:
+  interface_realizations_for(obj)`.
+- New `realization_connectors(obj)` helper — a specialization of
+  `inheritance_connectors(obj, "Realization")` for readability.
+
+## Verification
+- All 113 qea_to_xmi specs pass.
+- `basic.qea` has 0 Realization connectors, so the output has 0
+  `<interfaceRealization>` elements. The path is exercised by the
+  xmi gem's `sparx-instance-specification.xmi` fixture (parser side)
+  and by structural round-trip — when the ea transformer is given an
+  EA database with Realization connectors, it will produce the
+  correct child elements.
+
+## Sentinel
+The Phase 2 sentinel spec block in
+`spec/ea/transformers/qea_to_xmi/transformer_spec.rb` keeps two
+negative sentinels for cases `basic.qea` doesn't exercise
+(aggregation on ownedEnd, classifier on InstanceSpecification).
+Realization does not need a sentinel because the wiring path is
+already type-checked end-to-end.

data/TODO.next/37-visibility-returns-real-booleans.md

@@ -0,0 +1,36 @@
+# 37 - Visibility.boolean_from_flag returns real Ruby booleans
+
+## Status: DONE (2026-07-02)
+
+## Problem
+`Ea::Transformers::QeaToXmi::Visibility.boolean_from_flag` returned
+the strings `"true"` / `"false"` for EA's `"1"` / `"0"` flags. The
+xmi gem's `is_*` attributes (`is_abstract`, `is_static`,
+`is_ordered`, `is_derived`, `is_unique`, `is_id`, `is_read_only`,
+`is_query`) were initially typed as `:string` so this worked — but
+the xmi gem refactor migrated them to `:boolean` per UML 2.5 type
+semantics.
+
+After the migration, the ea-side `boolean_from_flag` returning
+strings caused silent type coercion (Ruby `"true" == true` is
+false; lutaml-model was lenient but the type contract was wrong).
+
+## Fix
+Return actual Ruby `true` / `false` (or `nil` when EA's field is
+blank). Drop the ternary string coercion. Update the spec to assert
+`be(true)` / `be(false)` instead of `eq("true")` / `eq("false")`.
+
+```ruby
+def boolean_from_flag(raw)
+  return nil if raw.nil? || raw.to_s.strip.empty?
+
+  raw.to_s == "1"
+end
+```
+
+## Verification
+- visibility_spec.rb: 6 examples pass with the new boolean contract.
+- Output `isAbstract="false"` count for basic.qea: 80 (one per
+  Class). All emit as lowercase XSD booleans per the xmi gem's
+  lutaml-model :boolean type.
+- Full qea_to_xmi suite passes (113 examples).

data/config/diagram_styles.yml

@@ -0,0 +1,200 @@
+# diagram_styles.yml - Configurable EA Diagram Styling
+# This file defines the default styling for LutaML diagram generation
+
+# Global defaults - applied when no other configuration matches
+defaults:
+  colors:
+    background: "#FFFFFF"
+    default_fill: "#E0E0E0"
+    default_stroke: "#000000"
+    text: "#000000"
+
+  fonts:
+    default:
+      family: "Carlito, Arial, sans-serif"
+      size: 9
+      weight: 400
+      style: normal
+
+    class_name:
+      family: "Carlito, Arial, sans-serif"
+      size: 9
+      weight: 700  # bold
+      style: normal
+
+    stereotype:
+      family: "Carlito, Arial, sans-serif"
+      size: 9
+      weight: 400
+      style: normal
+
+    attribute:
+      family: "Carlito, Arial, sans-serif"
+      size: 9
+      weight: 400
+      style: normal
+
+    operation:
+      family: "Carlito, Arial, sans-serif"
+      size: 9
+      weight: 400
+      style: normal
+
+  box:
+    stroke_width: 2
+    stroke_linecap: round
+    stroke_linejoin: bevel
+    corner_radius: 0
+    padding: 5
+    fill_opacity: 1.0
+    stroke_opacity: 1.0
+
+  text:
+    visibility_public: "+"
+    visibility_private: "-"
+    visibility_protected: "#"
+    visibility_package: "~"
+    cardinality_format: "[%s]"
+    stereotype_format: "«%s»"
+
+# Stereotype-based styling
+# These apply when elements have specific stereotypes
+stereotypes:
+  DataType:
+    colors:
+      fill: "#FFCCFF"  # Pink for i-UR DataTypes
+      stroke: "#000000"
+    fonts:
+      class_name:
+        weight: 700
+        style: italic
+
+  FeatureType:
+    colors:
+      fill: "#FFFFCC"  # Yellow for CityGML FeatureTypes
+      stroke: "#000000"
+
+  GMLType:
+    colors:
+      fill: "#CCFFCC"  # Green for GML Types
+      stroke: "#000000"
+
+  Interface:
+    colors:
+      fill: "#FFFFEE"
+      stroke: "#000000"
+    fonts:
+      class_name:
+        style: italic
+
+  Enumeration:
+    colors:
+      fill: "#FFE6CC"
+      stroke: "#000000"
+
+  Abstract:
+    fonts:
+      class_name:
+        style: italic
+
+# Package-based styling (optional)
+# Supports wildcards: "CityGML::*" matches any package starting with "CityGML::"
+packages:
+  "CityGML::*":
+    colors:
+      fill: "#FFFFCC"
+
+  "i-UR::*":
+    colors:
+      fill: "#FFCCFF"
+
+  "gml::*":
+    colors:
+      fill: "#CCFFCC"
+
+# Class-specific overrides (highest priority after EA data)
+# These take precedence over package and stereotype styling
+classes: {}
+
+# Connector styling
+connectors:
+  generalization:
+    arrow:
+      type: hollow_triangle
+      size: 10
+    line:
+      stroke_width: 1
+      stroke: "#000000"
+      fill: none
+
+  association:
+    arrow:
+      type: open_arrow
+      size: 8
+    line:
+      stroke_width: 1
+      stroke: "#000000"
+    labels:
+      show_role_names: true
+      show_cardinality: true
+      font:
+        family: "Carlito, Arial, sans-serif"
+        size: 8
+
+  dependency:
+    arrow:
+      type: open_arrow
+      size: 8
+    line:
+      stroke_width: 1
+      stroke: "#000000"
+      stroke_dasharray: "5,5"
+
+  aggregation:
+    arrow:
+      type: diamond
+      size: 10
+      fill: white
+    line:
+      stroke_width: 1
+      stroke: "#000000"
+
+  composition:
+    arrow:
+      type: filled_diamond
+      size: 10
+      fill: black
+    line:
+      stroke_width: 1
+      stroke: "#000000"
+
+  realization:
+    arrow:
+      type: hollow_triangle
+      size: 10
+    line:
+      stroke_width: 1
+      stroke: "#000000"
+      stroke_dasharray: "5,5"
+
+# Legend configuration
+legend:
+  enabled: true
+  position: bottom_right
+  title: "Legend"
+  box:
+    fill: "#FFFFFF"
+    stroke: "#000000"
+    stroke_width: 1
+    padding: 10
+  font:
+    family: "Carlito, Arial, sans-serif"
+    size: 9
+    weight: 400
+  entries:
+    - label: "i-UR DataTypes"
+      color: "#FFCCFF"
+    - label: "CityGML FeatureTypes"
+      color: "#FFFFCC"
+    - label: "GML Types"
+      color: "#CCFFCC"