ea 0.3.1 → 0.5.0

data/TODO.diagrams/08-qea-direct-pipeline.md

@@ -0,0 +1,46 @@
+# TODO-D 08-11 - QEA-direct pipeline
+
+## Status: COMPLETE (2026-07-27)
+
+## What was wired
+
+1. **TODO-D 08**: QEA DiagramBuilder propagates StyleEx to
+   Diagram.style_ex. Theme=:119 is now correctly detected from QEA.
+
+2. **TODO-D 09**: IdNormalizer.to_eaid converts `{GUID}` to
+   `EAID_<guid-with-underscores>` for matching reference SVG
+   filenames. The QEA stores diagram GUIDs in braces-dashes form;
+   the reference SVGs use the EAID_ underscore form.
+
+3. **TODO-D 10**: New QEA NoteBuilder parses t_object rows with
+   object_type="Note" or "Text". These render as Package-shaped
+   diagram boxes (not dog-eared Notes — QEA's "Note" type is a
+   diagrammatic Package-shape box for free text, distinct from
+   XMI's uml:Note).
+
+   Also: connector_type from t_connector.Type is now propagated
+   to DiagramConnector so Marker::Diamond matches Aggregation
+   and Composition (was being dropped, all connectors fell back
+   to Association).
+
+4. **TODO-D 11**: spec/ea/svg/qea_regression_spec.rb renders all
+   188 diagrams directly from the QEA against reference SVGs.
+   Passes at the 60 percent within-tolerance threshold.
+
+## Parity delta from QEA-direct fixes
+
+| Metric | Before | After |
+|---|---|---|
+| Polygon delta | n/a (was reading XMI) | -166 (was -842 at start) |
+| Path delta | n/a | -181 |
+| Text overlap avg | 10% (initial QEA-direct) | 56% |
+| Within tolerance | 60.6% | 65.4% |
+
+## Bonus fixes shipped alongside
+
+- ClassifierBuilder no longer prepends package name to
+  qualified_name (QEA t_object.Name already includes the prefix).
+- HeaderLines no longer renders fallback stereotype labels.
+- AttributeRenderer no longer double-colons type names.
+- bounds_from_rect uses min/max of rect values (QEA stores rect
+  with recttop > rectbottom).

data/TODO.diagrams/08-visual-regression-harness.md

@@ -0,0 +1,34 @@
+# 08 - Visual Regression Harness
+
+## Status: DONE (2026-07-21)
+
+## Problem
+
+"Matches EA's SVG" is a fuzzy target. We need an automated way to
+detect regressions and measure fidelity.
+
+## Approach
+
+A spec that:
+
+1. Loads `plateau_all_packages_export.xmi`.
+2. For each diagram in the XMI's extension block, locates the
+   matching EA reference SVG in
+   `mn-samples-plateau/sources/001-mds/xmi-images/`.
+3. Renders our SVG for the same diagram.
+4. Compares structurally (canonicalized XML diff ignoring
+   whitespace and attribute order).
+5. Reports: which diagrams match exactly, which have structural
+   differences, which have only attribute differences.
+
+Not a hard-fail spec; produces a report we can track over time.
+Once fidelity is high enough, tighten to a hard threshold.
+
+## Files
+
+- `spec/ea/svg/visual_regression_spec.rb`
+- `spec/support/svg_canonicalizer.rb`
+
+## Verification
+
+- Run produces a report; not asserting 100% match initially.

data/TODO.diagrams/09-cli-render-all-diagrams.md

@@ -0,0 +1,25 @@
+# 09 - CLI: Render All Diagrams from a Source
+
+## Status: DONE (2026-07-21)
+
+## Problem
+
+`ea svg NAME FILE` renders one named diagram. For batch
+regeneration of all diagrams (e.g. plateau-model deploy), we need
+a way to render every diagram in a source file.
+
+## Approach
+
+Add `ea svg --all FILE [--output-dir=PATH]` mode. Iterates every
+diagram in the model, names the output file by diagram id (e.g.
+`EAID_0016F797_....svg`).
+
+## Files
+
+- `lib/ea/cli/command/svg.rb` (extend)
+- `spec/ea/cli/svg_command_spec.rb`
+
+## Verification
+
+- `ea svg --all plateau.xmi --output-dir=/tmp/svgs` produces one
+  SVG per diagram.

data/TODO.diagrams/10-stereotype-color-config.md

@@ -0,0 +1,29 @@
+# 10 - Stereotype Color Configuration (QEA fallback)
+
+## Status: DONE (2026-07-21)
+
+## Problem
+
+When the source is QEA, the element's BCol is often the default
+white. EA picks stereotype-based colors at render time when BCol
+is not set. Our renderer currently hard-codes a stereotype →
+color map, which is fragile.
+
+## Approach
+
+Externalize the stereotype → color map to a YAML configuration
+file (`config/stereotype_colors.yml`). Users can override per
+project.
+
+The XMI source carries BCol directly from EA, so the config only
+applies when BCol is missing (QEA sources without style data).
+
+## Files
+
+- `config/stereotype_colors.yml`
+- `lib/ea/svg/stereotype_color_resolver.rb`
+- `spec/ea/svg/stereotype_color_resolver_spec.rb`
+
+## Verification
+
+- Custom YAML overrides default map.

data/TODO.diagrams/11-elkrb-auto-layout-integration.md

@@ -0,0 +1,53 @@
+# 11 - ElkRb Auto-Layout Integration
+
+## Status: TODO (post-PR #24)
+
+## Problem
+
+The current Ea::Svg::EaEmitter renders diagrams from the placement
+data captured by the source adapter (QEA's t_diagramobjects /
+t_diagramlinks, XMI's <xmi:Extension>/<elements>). When the source
+doesn't carry placement data — or when the user wants to re-layout
+an existing diagram — there's no fallback.
+
+Eclipse Layout Kernel (ELK) is the standard auto-layout library for
+node-link diagrams (UML class diagrams, flowcharts, etc.). `elkrb`
+is a pure-Ruby implementation in `/Users/mulgogi/src/claricle/elkrb/`.
+
+## Approach
+
+Build an `Ea::Layout::ElkAdapter` that:
+
+1. Translates an `Ea::Model::Document` (or a subset — packages,
+   classifiers, relationships) into elkrb's `Graph` / `Node` /
+   `Edge` model.
+2. Runs the chosen elkrb algorithm (`Layered` for class diagrams
+   is the Sugiyama-style default; `Force` for organic; `Stress`
+   for high-quality).
+3. Reads back the computed positions and writes them into an
+   `Ea::Model::Diagram` (with DiagramElement bounds and
+   DiagramConnector waypoints computed by elkrb's edge router).
+
+Then the standard `Ea::Svg::EaEmitter` renders the layout-posed
+diagram just like an EA-authored one. No renderer changes needed.
+
+CLI surface:
+- `ea layout FILE [--algorithm=layered|force|stress]` — runs
+  auto-layout, emits a JSON of computed positions
+- `ea svg NAME FILE --layout=auto` — runs layout then renders
+
+## Files
+
+- `lib/ea/layout.rb` (namespace)
+- `lib/ea/layout/elk_adapter.rb`
+- `lib/ea/layout/document_to_graph.rb`
+- `lib/ea/layout/graph_to_diagram.rb`
+- `lib/ea/cli/command/layout.rb`
+- `spec/ea/layout/*_spec.rb`
+
+## Verification
+
+- Spec: known small document → elk graph → known layout output.
+- Spec: QEA fixture with no placement data → auto-layout produces
+  non-overlapping positions.
+- Spec: round-trip — auto-layout, render to SVG, no errors.

data/TODO.diagrams/12-connector-labels.md

@@ -0,0 +1,40 @@
+# TODO-D 12 - Connector role/multiplicity labels
+
+## Status: COMPLETE (2026-07-27)
+
+## What changed
+
+Labels renderer refactored to support both XMI and QEA paths:
+
+1. **Property lookup (XMI path)**: When the Association's
+   source_id/target_id reference Property IDs, look them up and
+   render the role name + multiplicity from the Property fields.
+
+2. **Association fields (QEA path)**: Fall back to the
+   Association's own source_role_name, target_role_name,
+   source_multiplicity_lower/upper, target_multiplicity_lower/upper
+   fields. These are populated by QEA's t_connector.sourcerole/
+   destrole/sourcecard/destcard columns.
+
+3. **Default label offset**: When label_boxes aren't populated
+   (QEA path — the geometry parser doesn't yet extract them),
+   use a default offset (anchor + 5, -10) so labels render near
+   the connector endpoints rather than being silently dropped.
+
+## Acceptance
+
+QEA-direct parity measurement:
+
+| Metric | Before | After |
+|---|---|---|
+| Text delta vs ref | -2728 (14% under) | -883 (5% under) |
+| Text overlap avg | 56.0% | 62.8% |
+
+## Remaining
+
+- QEA t_diagramlinks.Geometry parser doesn't extract LLB/LRB
+  boxes. Adding that would let labels render at EA's recorded
+  pixel positions rather than the default offset.
+- The XMI-encoded `<text>` ordering within Labels is still
+  suboptimal — EA emits role name and multiplicity in a single
+  `<g>` block, we emit each as a separate text element.

data/TODO.diagrams/12-per-entity-svg-layer-ordering.md

@@ -0,0 +1,24 @@
+# 12 - Per-Entity SVG Layer Ordering
+
+## Status: DONE (2026-07-23)
+
+## Outcome
+
+Restructured `Ea::Svg::EaEmitter::Document` to emit a flat sequence
+of top-level `<g>` elements matching EA's per-entity layering:
+
+- `Elements#groups` returns Array of per-element `<g>` blocks
+  (shape → header → divider → attrs)
+- `Connectors#groups` returns Array of one `<g>` per connector line
+- `Markers#groups` returns Array of one `<g>` per connector marker
+- `Document#connector_layers` interleaves line + marker per connector
+
+Verified on Waterway: 50 top-level `<g>` (ours) vs 47 (ref) — the
+3-group delta is due to the spurious frame element (TODO 14).
+
+## Files changed
+
+- `lib/ea/svg/ea_emitter/document.rb` — interleaves line/marker per connector
+- `lib/ea/svg/ea_emitter/elements.rb` — `groups` method, per-element arrays
+- `lib/ea/svg/ea_emitter/connectors.rb` — `groups` method, one `<g>` per connector
+- `lib/ea/svg/ea_emitter/markers.rb` — `groups` method, one `<g>` per marker

data/TODO.diagrams/13-marker-polygon-vs-path-dispatch.md

@@ -0,0 +1,20 @@
+# 13 - Marker Encoding: Polygon vs Path by Shape
+
+## Status: DONE (2026-07-23)
+
+## Outcome
+
+Refactored `Ea::Svg::EaEmitter::Markers` to dispatch marker shape
+via a `Spec` value object. Each marker emits the correct element type:
+
+- Diamond (Aggregation/Composition) → `<polygon>` 4 points
+- Open triangle (Generalization/Realization/Dependency) → `<polygon>` 3 points, white fill
+- Filled arrow (Association navigability) → `<path d="M .. L .. L .."/>` 3 points
+
+Marker placement is direction-aware: "Destination -> Source" flips
+which end holds the marker.
+
+## Files changed
+
+- `lib/ea/svg/ea_emitter/markers.rb` — Spec struct + dispatch
+- `spec/ea/svg/ea_emitter/markers_spec.rb` — updated to reflect arrow emission

data/TODO.diagrams/13-per-text-type-font-sizes.md

@@ -0,0 +1,33 @@
+# TODO-D 13 - Per-text-type font sizes
+
+## Status: COMPLETE (2026-07-27)
+
+## Context
+
+Reference SVGs use different font sizes for different text types:
+- 9pt for classifier compartments (header, attributes, operations,
+  enumeration literals, tagged values)
+- 7pt for diagram-level text (frame label, swimlane names)
+- 12pt for some classifier names (rare)
+
+Theme :119 specifies font_size=7pt — that's the DIAGRAM-LEVEL font
+size, not the element-level default. Element compartment text uses
+9pt regardless of theme.
+
+## What changed
+
+- `FontResolver::DEFAULT_ELEMENT_FONT_SIZE = 9` — replaces the
+  previous default of 13 (which was the Yu Gothic UI locale default)
+- `FontResolver#size_for` no longer falls back to `theme.font_size`
+  for elements — only diagram-level text uses theme font size
+- `HeaderRenderer` and `AttributeRenderer` gain `size_unit:`
+  parameter (defaults to `"pt"`) and propagate it to TextRenderer
+- `Elements#groups_for` reads `size_unit` from FontResolver and
+  passes through to all renderers
+
+## Acceptance
+
+- Reference text uses `font-size:9pt` for classifier compartments
+- Our text now emits `font-size:9pt` (was `font-size:7px`)
+- Text overlap metric unchanged (counts content, not formatting)
+- 1612 specs pass

data/TODO.diagrams/14-center-header-text.md

@@ -0,0 +1,33 @@
+# TODO-D 14 - Center classifier header text
+
+## Status: COMPLETE (2026-07-27)
+
+## Context
+
+EA centers stereotype and classifier-name text horizontally within
+the element bounds. SVG `<text x=>` is the LEFT edge of the text,
+not the center, so we need to compute:
+
+  left_edge = bounds.center_x - text_width / 2
+
+Our previous code emitted `x = bounds.center_x` directly, which
+placed the LEFT EDGE at the center — making all text appear
+right-of-center.
+
+## What changed
+
+`HeaderRenderer.center_x_for(text, bounds, size)` computes the
+left edge from a text-width approximation:
+
+  text_width = text.length * size * 0.55
+
+The factor 0.55 approximates average Carlito character width as a
+fraction of point size. Not pixel-perfect (EA uses GDI text
+metrics) but visually centered.
+
+## Acceptance
+
+- Stereotype label now visually centered in element box
+- Classifier name now visually centered
+- Close to reference x positions (within ~5px due to text-width
+  approximation)

data/TODO.diagrams/14-filter-diagram-frame-elements.md

@@ -0,0 +1,18 @@
+# 14 - Filter Diagram-Frame / Note Elements
+
+## Status: DONE (2026-07-23)
+
+## Outcome
+
+Added `Elements#frame_element?` predicate that skips elements
+matching the diagram-frame pattern:
+- `background_color == -1` (sentinel for "no fill / default"), AND
+- Classifier name is nil/empty, AND
+- Classifier has no properties
+
+Verified: Waterway top-level `<g>` count drops 50→47, rect count
+drops 10→9 — both now match EA reference exactly.
+
+## Files changed
+
+- `lib/ea/svg/ea_emitter/elements.rb` — `frame_element?` predicate

data/TODO.diagrams/15-deep-dead-code-audit.md

@@ -0,0 +1,47 @@
+# TODO-D 15 - Deep dead code audit
+
+## Status: COMPLETE (2026-07-27)
+
+## Audit findings
+
+All production subsystems in `lib/ea/` are actively used:
+
+| Subsystem | Used by | Status |
+|---|---|---|
+| `Ea::Model` | All adapters and renderers | KEEP |
+| `Ea::Sources::Qea` | `Ea.parse`, `Ea::Sources::Qea::Adapter.from_path` | KEEP |
+| `Ea::Sources::Xmi` | `Ea::Sources::Xmi::Adapter.from_path` | KEEP |
+| `Ea::Svg::EaEmitter` | `ea svg` CLI command | KEEP |
+| `Ea::Theme` | Diagram.theme resolution | KEEP |
+| `Ea::Diagram::DisplayConfig` | `Diagram#display_config` | KEEP |
+| `Ea::Qea` (SQLite layer) | `Ea::Sources::Qea::*` adapters | KEEP |
+| `Ea::Xmi` | `Ea::Sources::Xmi::*` adapters | KEEP |
+| `Ea::Spa` | `ea spa` CLI command | KEEP |
+| `Ea::Transformers` | `ea convert` CLI command | KEEP |
+| `Ea::Bridge` | `Ea::Transformations.to_uml` | KEEP |
+| `Ea::Transformations` | `RepositoryBuilder` for bridge CLI | KEEP |
+
+## Code quality audit
+
+| Rule | Status |
+|---|---|
+| No `send` to call private methods | CLEAN |
+| No `instance_variable_set`/`get` | CLEAN (only mentioned in a comment) |
+| No `respond_to?` for type checks | CLEAN (replaced with `is_a?` earlier) |
+| No `require_relative` for library code | CLEAN (one in `lib/ea.rb` for VERSION — standard gemspec pattern) |
+| autoload for all internal loading | CLEAN |
+
+## Architecture observations
+
+The codebase follows OCP well:
+- `Marker::Kind` subclasses registered via `Marker::Registry.register`
+- `Theme::Definition` immutable value object with `#with` for variants
+- `Theme::Registry` auto-loads from `config/themes/*.yml`
+- `Element::*Renderer` classes are independent — adding a new
+  compartment type doesn't modify existing renderers
+
+## DRY
+
+Found one minor duplication: `Labels` and `AttributeRenderer` both
+have text-emission logic. Consolidated into shared `TextRenderer`
+calls. No further DRY violations observed.

data/TODO.diagrams/15-per-element-font-from-style.md

@@ -0,0 +1,24 @@
+# 15 - Per-Element Font from Style
+
+## Status: DONE (2026-07-23)
+
+## Outcome
+
+Added `Ea::Svg::EaEmitter::FontResolver` that resolves font family +
+size + weight + style per element, using EA's fallback chain:
+
+1. Element-level `font_family` / `font_size` (set from EA's
+   `font=NAME;fontsz=PCT` style fields via ExtensionStyleParser)
+2. Diagram-level default (most common non-nil value across elements)
+3. Module default (`Yu Gothic UI`, `13`)
+
+`Elements` emitter delegates font resolution to FontResolver so the
+fallback rule lives in one place (MECE).
+
+## Files changed
+
+- `lib/ea/svg/ea_emitter/font_resolver.rb` — new resolver
+- `lib/ea/svg/ea_emitter.rb` — autoload registration
+- `lib/ea/svg/ea_emitter/elements.rb` — uses FontResolver
+- `spec/ea/svg/ea_emitter/font_resolver_spec.rb` — 9 specs covering
+  explicit, fallback, and empty-diagram cases

data/TODO.diagrams/16-canvas-marker-extent.md

@@ -0,0 +1,30 @@
+# 16 - Canvas Bounds Include Marker Extent
+
+## Status: DONE (2026-07-23)
+
+## Outcome
+
+`Canvas.from` now extends the points list with `MARKER_EXTENT=15`
+padding around each connector's source and target waypoints. This
+prevents markers (diamonds, triangles, arrows) from being clipped
+when they project beyond element bounds.
+
+For Waterway this didn't change the canvas size (markers fit within
+existing element bounds), but for diagrams where arrows extend below
+or beside elements, the canvas now grows accordingly.
+
+## Remaining diff
+
+Waterway height: ours 869 vs ref 892 (23 px short). Root cause:
+EA's renderer uses `image_bounds` (with 12 px image padding) for
+certain elements while we use logical `bounds`. The 23 px diff
+matches the difference between logical and image_bounds for the
+lowest element (FacilityIdAttribute: logical bottom=895, image
+bottom=918). To close this fully we'd need to compute canvas from
+image_bounds union (matching EA's behavior), but this would also
+require translating elements by image_bounds rather than logical
+bounds — a larger change deferred to TODO 18.
+
+## Files changed
+
+- `lib/ea/svg/ea_emitter/canvas.rb` — `marker_extents` + concat into points

data/TODO.diagrams/16-document-remaining-parity-gaps.md

@@ -0,0 +1,91 @@
+# TODO-D 16 - Document all remaining parity gaps
+
+## Status: LIVING DOCUMENT (2026-07-27)
+
+## Current parity (QEA-direct, 188 diagrams)
+
+| Metric | Value |
+|---|---|
+| Within shape-count tolerance | 123/188 (65.4%) |
+| Text overlap avg | 62.8% |
+| Polygon delta | -166 |
+| Path delta | -181 |
+| Text delta | -883 |
+| Rect delta | -460 |
+
+## Byte-level diff status (maintenance diagram)
+
+The simplest diagram (`maintenance`, 1 classifier) now matches
+reference byte-for-byte on:
+
+- Canvas dimensions (254x177) ✓
+- Element position (35, 40) ✓
+- Background rect dimensions ✓
+- Frame border path coordinates ✓
+
+Remaining byte-level differences on maintenance:
+
+### 1. Build ID
+- Ours: `Build: 1628`
+- Ref: `Build: 1624`
+
+The QEA was authored with build 1628 (newer). The reference SVGs
+were exported with build 1624. Either change the BUILD_ID constant
+or accept the difference.
+
+### 2. Frame tab width
+- Ours: `points="6 26 135 26 148 13 148 6 6 6 6 26"` (width=129)
+- Ref:  `points="6 26 86 26 99 12 99 6 6 6 6 26"` (width=80)
+
+EA calculates the tab width from GDI text metrics on the label
+"class maintenance". Our calculation uses `label.length * 7 + 10`
+which overshoots. Need a better text-width approximation, OR
+match EA's hardcoded minimum (80px).
+
+### 3. textLength attribute
+- Ours: `textLength="65"`
+- Ref:  `textLength="73"`
+
+Same root cause as #2 — text-width approximation differs from
+GDI metrics.
+
+### 4. Whitespace formatting
+- Ours: extra blank lines between `<g>` blocks
+- Ref:  no blank lines, tabs for indentation
+
+Cosmetic only — doesn't affect rendering.
+
+## Aggregate parity gaps (across 188 diagrams)
+
+### Polygon under-rendering (-166)
+Source-side diamond markers on Aggregation connectors. The diamond
+anchor positions drift from EA because connector SX/SY/EX/EY
+interpretation isn't exact. Markers render but at slightly wrong
+positions, breaking the per-anchor dedup match.
+
+### Path under-rendering (-181)
+EA combines connector line + arrow head into one `<path>` with
+multiple `M` sub-paths. We emit them as separate paths. Restructure
+`Connectors` renderer to emit combined paths per connector.
+
+### Text under-rendering (-883)
+Three categories:
+1. Connector label positions (we use default offset; EA records
+   exact LLB/LRB boxes in t_diagramlinks.Geometry)
+2. Attribute defaults (e.g. `lod: integerBetween0and4 = 1` — we
+   drop the `= default_value` part)
+3. Stereotype-tagged-value text (we render the «property»
+   stereotype label on some diagrams where ref doesn't)
+
+### Rect under-rendering (-460)
+Mostly classifier-box compartment rects that EA emits as inner
+rects (not paths) for some diagram configurations. Also legend
+swatches inside Note elements. Not yet investigated thoroughly.
+
+## Priority order for closing remaining gaps
+
+1. **Combined connector paths** — fixes path -181, no architectural change
+2. **QEA geometry parser for LLB/LRB** — fixes most of text -883
+3. **Attribute default value rendering** — fixes some text delta
+4. **Frame tab width calculation** — fixes byte-diff on simple diagrams
+5. **Rect inner-compartment rendering** — fixes rect -460

data/TODO.diagrams/17-italic-abstract-classes.md

@@ -0,0 +1,28 @@
+# 17 - Italic Rendering for Abstract Classes
+
+## Status: DONE (2026-07-23)
+
+## Outcome
+
+Updated `Elements#header_lines` to handle the abstract + stereotype
+combination: when a class is abstract AND has a stereotype, emit
+both lines (stereotype normal, name italic with `_` prefix).
+
+```ruby
+if classifier.is_abstract
+  lines << ["«abstract»", :normal] if classifier.stereotype_refs&.any?
+  lines << ["_#{classifier.name}", :italic]
+elsif classifier.stereotype_refs&.any?
+  lines << ["«#{stereotype}»", :normal]
+  lines << [name, :bold]
+else
+  lines << [name, :bold]
+end
+```
+
+Abstract classes now render matching EA's encoding:
+`<text style="font-style:italic;...">_TransportationObject</text>`.
+
+## Files changed
+
+- `lib/ea/svg/ea_emitter/elements.rb` — `header_lines` abstract+stereotype branch