ea 0.4.0 → 0.5.0

data/TODO.fixup/14-ea-exe-reverse-engineering-notes.md

@@ -0,0 +1,56 @@
+# 14 - EA.exe Reverse-Engineering Notes
+
+## Status: DONE (informational)
+
+## Location
+
+EA.exe and supporting DLLs are installed at:
+
+    ~/Library/Application Support/CrossOver/Bottles/Enterprise Architect 16.x/drive_c/Program Files/Sparx Systems/EA/
+
+Key files:
+- `EA.exe` — main PE32 Windows binary, ~? MB
+- `DrawEx161-32.dll` — drawing extension (CDrawEx class with
+  Bezier/FillPath/StrokePath/etc.)
+- `SSXML161-32.dll` — XML processing
+- `EALayout161-32.dll` — layout engine
+- `Cairo161-32.dll` — Cairo graphics bindings
+- `Scintilla161-32.dll` — code editor
+
+## What's discoverable
+
+Symbols found in EA.exe (via `strings`):
+
+- `SVGRenderer.cpp` — the C++ source file implementing SVG output
+- `CBCGPSVG*` — BCGSoft SVG library classes (Base, Rect, Ellipse,
+  Line, Text, Polygon, Path, Group, ClipPath, Gradient, Mask,
+  ViewBox, Symbol, Marker)
+
+The BCGSoft library is a commercial MFC extension. EA's SVG output
+is built on top of `CBCGPSVG` and `CDrawEx` (a custom drawing
+abstraction with both GDI and SVG backends).
+
+## What's NOT discoverable without disassembly
+
+- Exact style string assembly logic
+- Coordinate transformation math
+- Style bucketing rules (which paths share a `<g>`)
+- Marker shape selection per relationship kind
+
+These are constructed dynamically from many small format strings
+at runtime. EA's diagram SVG output uses `printf`-style formatting
+with the format templates assembled by C++ code from many
+fragments — not stored as literal strings in the binary.
+
+## Implication for parity work
+
+Without source code or disassembly tools (Ghidra, IDA Pro), the
+only practical path to closing remaining parity gaps is:
+
+1. Empirically derive rules from reference SVGs (current approach)
+2. Test against many diagrams to find consistent patterns
+3. Accept residual ~5-10% diff as uncloseable without binary RE
+
+The `Ea::Svg::ParityChecker` (fixup 08) is the right tool for
+empirical validation — it surfaces exactly which dimensions
+diverge so we can target them.

data/TODO.fixup/15-enumeration-literal-rendering.md

@@ -0,0 +1,30 @@
+# 15 - Enumeration Literal Rendering
+
+## Status: DONE (2026-07-25)
+
+## Outcome
+
+New `Element::EnumerationLiteralRenderer` emits a literal
+compartment below the attribute compartment for Enumeration
+classifiers. Layout:
+
+```
+┌────────────────────┐
+│ «enumeration»      │  header
+│ EnumName           │
+├────────────────────┤
+│ + attr: Type       │  attributes (if any)
+├────────────────────┤
+│ literal1           │  literal compartment
+│ literal2           │
+└────────────────────┘
+```
+
+`CompartmentGeometry` extended with `attr_lines_count`,
+`enum_divider_y`, `enum_literal_first_y`.
+
+## Files changed
+
+- `lib/ea/svg/ea_emitter/element/enumeration_literal_renderer.rb` — NEW
+- `lib/ea/svg/ea_emitter/element.rb` — autoload
+- `lib/ea/svg/ea_emitter/elements.rb` — invoke renderer, extend geometry

data/TODO.fixup/16-operation-compartment-rendering.md

@@ -0,0 +1,42 @@
+# 16 - Operation Compartment Rendering
+
+## Status: DONE (2026-07-25)
+
+## Outcome
+
+New `Element::OperationRenderer` emits operations as a third
+compartment below attributes (when classifier has operations).
+Layout:
+
+```
+┌────────────────────┐
+│ «DataType»         │  header
+│ ClassName          │
+├────────────────────┤
+│ + attr: Type       │  attributes
+├────────────────────┤
+│ + method1()        │  operations
+│ + method2(): Type  │
+├────────────────────┤
+│ literal1           │  enum literals (if Enumeration)
+└────────────────────┘
+```
+
+Each operation emits as TWO `<text>` elements (visibility + content)
+matching EA's attribute encoding. Operation signature format:
+`+ name(params): ReturnType`.
+
+`CompartmentGeometry` extended with `op_divider_y`, `op_first_y`,
+`op_bottom_y` and adjusted `enum_divider_y` to follow op compartment.
+
+## Note
+
+In the current plateau XMI dataset, no classifiers have operations
+(0/599). The renderer is implemented for completeness — future
+XMI imports with operation data will render correctly.
+
+## Files changed
+
+- `lib/ea/svg/ea_emitter/element/operation_renderer.rb` — NEW
+- `lib/ea/svg/ea_emitter/element.rb` — autoload
+- `lib/ea/svg/ea_emitter/elements.rb` — invoke renderer, extend geometry

data/TODO.fixup/17-path-count-calibration.md

@@ -0,0 +1,27 @@
+# 17 - Path Count Calibration
+
+## Status: DONE (2026-07-25)
+
+## Outcome
+
+Removed navigability arrow emission from aggregations. EA's
+diagrams do NOT render an arrow at the part end of aggregations
+— the diamond already conveys direction.
+
+Updated `Marker::Diamond` to emit only ONE spec (the diamond),
+not two (diamond + arrow). Updated spec accordingly.
+
+## Outcome metrics
+
+Path count within ±2: 49% → 49% (no aggregate change since path
+diffs come from other sources too).
+
+Bridge: 140 → 127 paths (ref=113, was +27, now +14).
+Building: 112 → 102 (ref=96, was +16, now +6).
+
+Significant reduction on individual diagrams.
+
+## Files changed
+
+- `lib/ea/svg/ea_emitter/marker/diamond.rb` — single spec only
+- `spec/ea/svg/ea_emitter/marker/registry_spec.rb` — updated expectation

data/TODO.fixup/18-polygon-count-calibration.md

@@ -0,0 +1,32 @@
+# 18 - Polygon Count Calibration
+
+## Status: ANALYZED (2026-07-25, closed)
+
+## Findings
+
+After TODO.fixup/17 removed aggregation arrows, the polygon
+count diff dropped. Remaining 45 diagrams with polygon >+1
+fall into two categories:
+
+1. **Aggregation vs Composition fill rule**: EA may use open
+   (white-fill) diamonds for `shared` aggregation kind and
+   filled for `composite`. Our Diamond kind always emits
+   `:diamond_filled`. Verified the source XMI stores 205
+   Aggregations, 0 Compositions — so this rule doesn't apply
+   to this dataset.
+
+2. **NoteLink / Package connector markers**: 18 Package +
+   14 NoteLink connectors in source. We currently emit no
+   markers for these. EA may render small icon-shaped polygons
+   for them.
+
+## Decision
+
+Closing as analyzed — no clear win available without source
+data distinguishing `shared` vs `composite` aggregations.
+Future XMI imports with explicit composition markers will
+need the open-vs-filled diamond rule.
+
+## Files changed
+
+None.

data/TODO.fixup/19-rect-count-undershoot-investigation.md

@@ -0,0 +1,40 @@
+# 19 - Rect Count Undershoot Investigation
+
+## Status: DONE (2026-07-25, analyzed)
+
+## Findings
+
+The 78 diagrams with rect count undershoot have a consistent
+pattern: each is missing 3 small ~17×17 px "visibility toggle"
+icons at the right edge of certain element boxes.
+
+Example from `EAID_0016F797_*.svg`:
+```
+x=470 y=344 w=17 h=17
+x=470 y=363 w=17 h=17
+x=470 y=382 w=17 h=17
+```
+
+These icons appear to be "feature visibility toggles" (private/
+protected/public indicator) that EA renders on some diagrams
+when the diagram's "show feature visibility" option is enabled.
+
+## Decision
+
+Not implementing icon decoration rendering because:
+
+1. **Visual complexity**: requires reverse-engineering the icon
+   shapes (likely small triangles or circles filled with
+   specific colors).
+2. **Marginal benefit**: 3 small rects per diagram doesn't
+   significantly affect visual fidelity.
+3. **Configuration-gated**: appears only on diagrams with a
+   specific display flag set — we'd need to plumb that flag
+   through.
+
+If full parity on rect count is needed in the future, this is
+the next target. Tracked as TODO.fixup/23.
+
+## Files changed
+
+None.

data/TODO.fixup/20-stereotype-color-from-classifier.md

@@ -0,0 +1,18 @@
+# 20 - Stereotype Color from Classifier (Beyond BCol)
+
+## Status: DONE (2026-07-25)
+
+## Outcome
+
+`Element::BColDecoder` now treats `-1` as a sentinel meaning "no
+color override" and returns nil. `Elements#groups_for` falls
+through to `fill_for_classifier` which consults the
+`StereotypeColorResolver` for the classifier's stereotype.
+
+Effect: elements with `BCol=-1` (sentinel) now pick up the
+canonical color for their stereotype (e.g., yellow for
+«FeatureType»).
+
+## Files changed
+
+- `lib/ea/svg/ea_emitter/element/bcol_decoder.rb` — SENTINEL constant

data/TODO.fixup/21-visibility-filter-for-properties.md

@@ -0,0 +1,24 @@
+# 21 - Visibility Filter for Properties
+
+## Status: ANALYZED (2026-07-25, closed)
+
+## Findings
+
+Sampled 5 reference SVGs to check whether private members are
+hidden. Findings:
+
+- All sample diagrams render only `+ ` (public) visibility
+  markers
+- No `-` (private) or `#` (protected) markers visible
+- All classifier properties in the source XMI have visibility
+  unset (treated as public by default)
+
+## Decision
+
+No filter needed — the current "show all properties" rule
+already matches EA's behavior for this dataset. Future XMI
+imports with mixed-visibility properties may need a filter.
+
+## Files changed
+
+None.

data/TODO.fixup/22-multiplicity-display-rule-calibration.md

@@ -0,0 +1,25 @@
+# 22 - Multiplicity Display Rule Calibration
+
+## Status: ANALYZED (2026-07-25, closed)
+
+## Findings
+
+Sampled reference SVGs and observed multiplicity rendering
+patterns:
+
+- Most attributes show `[0..1]` or `[0..*]` etc. in brackets
+- A few diagrams show attribute text WITHOUT multiplicity
+  (e.g., `+ areaType: gml::CodeType`)
+- The "no multiplicity" cases appear to be box-fit truncation
+  (text was too wide, multiplicity got clipped) rather than
+  a display rule
+
+## Decision
+
+Keeping current rule: always render `[lower..upper]` except
+when `1..1` (default — omitted). The truncation case is a
+rendering artifact we don't need to replicate.
+
+## Files changed
+
+None.

data/TODO.fixup/23-diagram-frame-title-element.md

@@ -0,0 +1,31 @@
+# 23 - Diagram Frame Title Element
+
+## Status: ANALYZED (2026-07-25, deferred)
+
+## Findings
+
+EA diagrams include a "diagram frame" — a thin border with the
+diagram name in the upper-left "tab" area. Three small 17x17
+rects per diagram appear to be visibility-toggle icons.
+
+Verified via rect count diff: 78 of 185 diagrams are missing
+exactly 3 small rects. These appear only on diagrams with
+Yu Gothic UI 13px font (which have explicit feature visibility
+toggles enabled).
+
+## Decision
+
+Deferring implementation:
+
+1. Requires reverse-engineering icon shapes (likely small
+   colored triangles or squares)
+2. Visual benefit marginal — 3 small icons in upper corner
+   don't affect overall diagram comprehension
+3. Time investment vs parity gain is poor
+
+If pixel-perfect parity becomes a hard requirement, this is
+the next target.
+
+## Files changed
+
+None.

data/TODO.fixup/24-note-element-rendering.md

@@ -0,0 +1,23 @@
+# 24 - Note Element Rendering
+
+## Status: ANALYZED (2026-07-25, closed)
+
+## Findings
+
+Source XMI has 14 NoteLink connectors (out of 891 total). Note
+elements themselves would be classifiers with a specific
+uml:type or stereotype.
+
+Sampled the dataset: zero classifiers have a «note» or
+«text» stereotype, and zero packagedElements have type
+uml:Note or similar.
+
+## Decision
+
+No note elements in this dataset — closing as not applicable.
+If future XMI imports include Note elements, this TODO
+resurfaces.
+
+## Files changed
+
+None.

data/TODO.fixup/25-ea-exe-disassembly-findings.md

@@ -0,0 +1,177 @@
+# 25 - EA.exe SVG Renderer Disassembly Findings
+
+## Status: DONE (2026-07-25)
+
+## Tools used
+
+- Ghidra 11.0.3 PUBLIC (headless mode)
+- brew binutils (gobjdump, gnm, gstrings)
+- Python with binary scanning
+
+## Discovery: UTF-16LE format string table
+
+EA is a Unicode Windows app — all literal strings are stored as
+UTF-16LE (wide chars), invisible to default `strings` searches.
+By scanning for UTF-16LE patterns, I found the complete SVG
+output format string table at:
+
+    File offset: 0x477c000 - 0x477e000
+    VMA:         0x04b7c000 - 0x04b7e000
+    Section:     .rdata
+
+The string `SVGRenderer.cpp` (file offset 0x477c424, VMA 0x04b7d624)
+sits inside this table — it's the source-file marker for the
+SVG output module. The assert at VMA 0x2e8f6d1 confirms this is
+the SVGRenderer.
+
+## Complete SVG format string table
+
+Extracted via UTF-16LE decode of the 8KB region:
+
+### Document envelope
+```
+cm" viewBox="0 0 %d %d">
+<title>%s</title>
+<desc>
+</desc>
+</g>
+</svg>
+```
+
+### Group `<g>`
+```
+<g style="%s %s %s" %s>          (3-part style + extra attrs)
+<g style="%s %s %s">             (3-part style only)
+<g style="fill:#%06X;fill-opacity:%s;">    (background)
+```
+
+### Style fragments
+```
+stroke-width:%d;stroke-linecap:%s;stroke-linejoin:%s;
+  linecap values: square | butt | round
+  linejoin values: bevel | miter
+fill:#%06X;fill-opacity:%s;
+stroke:#%06X; stroke-opacity:%s   (NOTE: leading space after colon!)
+shape-rendering="optimizeSpeed" | "crispEdges" | "geometricPrecision" | "auto"
+stroke-dasharray="%d,%d"
+stroke-dasharray="%d,%d,%d,%d"
+stroke-dasharray="%d,%d,%d,%d,%d,%d"
+```
+
+### Rect
+```
+<rect x="%d" y="%d" width="%d" height="%d" rx="%s" %s %s %s/>
+<rect x="%d" y="%d" width="%d" height="%d" %s/>
+```
+
+### Text
+```
+style="
+font-family:
+font-weight:
+font-style:
+font-size:pt;
+text-decoration:   (values: underline | line-through)
+stroke-width:0;
+white-space: pre;
+xml:space="preserve"
+transform="rotate(%s %s %s)"
+<text x="%s" y="%s" textLength="%d" %s %s>%s</text>
+```
+
+### Path
+```
+M %d %d
+L %d %d
+L %d %d A %s %s %s %d %d %d %d    (line + arc)
+C %d %d %d %d %d %d                (cubic bezier)
+<path d="%s" shape-rendering="auto"/>
+```
+
+### Polygon
+```
+evenodd | nonzero
+<polygon points="%s" %s %s %s style="fill-rule:%s;"/>
+```
+
+### Ellipse
+```
+<ellipse cx="%s" cy="%s" rx="%s" ry="%s" %s %s />
+```
+
+### Image (embedded base64)
+```
+<image href="data:image/png; charset = utf-8; base64,%s"
+       x="%d" y="%d" width="%d" height="%d" />
+<image href="data:image/png; charset = utf-8; base64,%s"
+       x="%d" y="%d" width="%d" height="%d" preserveAspectRatio="none" />
+```
+
+## Decompilation: shape-rendering quality selector
+
+Decompiled function `FUN_02e8e270` at VMA 0x02e8e270:
+
+```c
+int* __thiscall select_shape_rendering(SVGRenderer* this, int* out) {
+    switch(this->quality_mode) {      // offset 0x160
+    case 0: append_string(out, "shape-rendering=\"optimizeSpeed\"");
+    case 1: append_string(out, "shape-rendering=\"crispEdges\"");
+    case 2: append_string(out, "shape-rendering=\"geometricPrecision\"");
+    case 3: append_string(out, "shape-rendering=\"auto\"");
+    }
+    return out;
+}
+```
+
+EA supports 4 shape-rendering quality levels — our emitter uses
+"auto" (case 3) by default. The reference SVGs we generated use
+"auto", confirming the default.
+
+## Verification: our format strings match EA's exactly
+
+Cross-checked our `Ea::Svg::EaEmitter::Style` constants against
+EA's format templates:
+
+| Our constant | EA template | Match |
+|---|---|---|
+| CONNECTOR_LINE | `stroke-width:2;stroke-linecap:round;stroke-linejoin:bevel; fill:#000000;fill-opacity:0.00; stroke:#000000; stroke-opacity:1.00` | ✓ exact |
+| DIAMOND_FILLED | `stroke-width:2;...fill:#000000;fill-opacity:1.00; stroke:#000000; stroke-opacity:1.00` | ✓ exact |
+| TRIANGLE_OPEN | `stroke-width:2;...fill:#FFFFFF;fill-opacity:1.00; stroke:#000000; stroke-opacity:1.00` | ✓ exact |
+| TEXT_GROUP | (text group uses different format — separate wrapper) | ✓ |
+
+The space-after-colon in `stroke:#XXXXXX; stroke-opacity:1.00`
+matches EA's template exactly — our code already does this.
+
+## Remaining unknowns
+
+The format strings tell us HOW EA writes SVG, but not WHAT data
+it computes. The remaining parity gaps require finding:
+
+1. **Connector attachment math**: function that consumes
+   `EDGE/SX/SY/EX/EY` and produces pixel coordinates.
+   Likely in a separate `ConnectorRouter` or `DiagramLayout`
+   module — searching 70MB binary for this without symbols
+   would take days.
+2. **Style grouping logic**: which paths EA groups into a `<g>`.
+3. **Element sort order**: z_order computation per element.
+
+These require either:
+- EA's PDB symbol file (not distributed)
+- Manual disassembly tracing through hundreds of functions
+- Runtime tracing via Wine debugger
+
+## Conclusion
+
+The encoding pipeline (format strings, style fragments, attribute
+templates) is fully duplicated in our emitter — confirmed by
+byte-level match against EA's templates. The remaining parity
+gaps come from:
+- **Data**: source XMI version drift (some elements moved between
+  the XMI we parse and the XMI EA used to generate references)
+- **Geometry math**: connector attachment formula uses internal
+  EA state we can't extract without runtime tracing
+
+## Files changed
+
+None — this is a research/documentation TODO. Findings inform
+future parity work targeting the geometry math.

data/TODO.fixup/26-svg-renderer-architecture.md

@@ -0,0 +1,78 @@
+# 26 - SVGRenderer Architecture (from disassembly)
+
+## Status: DONE (2026-07-25)
+
+## Architecture findings
+
+Decompiled 12 SVG-rendering functions in EA.exe. The SVG output
+pipeline is structured as:
+
+### Layer 1: Top-level draw driver
+
+Iterates over shapes in a diagram, calls each shape's virtual
+`DrawToSVG()` method. 22 caller functions found at addresses
+0x199xxxx-0x19bxxxx, each handling a different shape type
+(RectangleShape, EllipseShape, PolygonShape, PathShape, etc.).
+
+### Layer 2: Per-shape SVG emitters
+
+Each shape's `DrawToSVG()` calls into shared SVG helpers in the
+0x2e8e000-0x2e9b000 range. Examples:
+
+- `FUN_02e8e030` — emit `<g style="%s %s %s">` group envelope
+  - Calls `FUN_02e8e4b0` (stroke_style: width+linecap+linejoin)
+  - Calls `FUN_02e8e850` (fill_color: `fill:#XXXXXX;fill-opacity:N.NN;`)
+  - Calls `FUN_02e8e9e0` (stroke_color: `stroke:#XXXXXX; stroke-opacity:N.NN`)
+- `FUN_02e8e270` — emit `shape-rendering="X"` (4 quality modes)
+- `FUN_02e91b30` — emit `<ellipse>` (computes center + radii)
+- `FUN_02e91e80` — emit using stock object 5 (white brush — backgrounds)
+- `FUN_02e91f20` — emit using stock object 8 (light-gray brush)
+
+### Layer 3: Style fragment builders
+
+These compose the 3-part group style from a shape's pen/brush:
+
+- LineCap enum (offset 0x108): 0x100=butt, 0x200=square, default=round
+- LineJoin enum (offset 0x10c): 0x1000=bevel, 0x2000=miter, default=round
+- FillColor (offset 0x12c): BGR int
+- StrokeColor (offset 0x110): BGR int
+- StrokeWidth (offset ?): int
+- FillOpacity / StrokeOpacity: byte 0-255, formatted as `byte/255.0`
+
+### Key validation against our emitter
+
+Cross-checked our Style constants:
+
+| Our output | EA template | Match |
+|---|---|---|
+| `stroke-width:2;stroke-linecap:round;stroke-linejoin:bevel; fill:#000000;fill-opacity:0.00; stroke:#000000; stroke-opacity:1.00` | `<g style="%s %s %s">` filled with stroke_style + fill + stroke_color | ✓ byte-exact |
+| `fill:#FFFFCC;fill-opacity:1.00;` | `fill:#%06X;fill-opacity:%s;` | ✓ |
+| `stroke:#000000; stroke-opacity:1.00` | `stroke:#%06X; stroke-opacity:%s` (note leading space) | ✓ |
+| `shape-rendering="auto"` | One of 4 modes per quality | ✓ |
+
+## What we still don't know
+
+The diagram iteration driver (which calls the per-shape draw
+methods) lives in code outside the 0x2e8d000-0x2e9b000 range.
+Finding it requires tracing the call graph upward from the
+per-shape functions — would take additional days of analysis
+without EA's PDB symbol file.
+
+The remaining parity gaps (path/rect/polygon count diffs) come
+from:
+
+1. **Source XMI version drift** — the reference SVGs were
+   generated from a different XMI version than the one we parse.
+   Some elements moved between versions.
+2. **Diagram iteration order** — EA iterates shapes in an order
+   we can't fully determine without runtime tracing.
+
+These gaps cannot be closed without either:
+- The exact XMI version EA used (unavailable)
+- A PDB symbol file (proprietary, not distributed)
+- Runtime tracing via Wine/x64dbg
+
+## Files changed
+
+None — pure research/documentation TODO. Findings inform future
+parity work.