ea 0.4.0 → 0.5.0

data/TODO.diagrams/42-close-all-parity-deltas.md

@@ -0,0 +1,69 @@
+# TODO-D 42: Close all SVG parity deltas to zero
+
+## Goal
+
+Reach shape/text parity 0/0/0/0 against the plateau XMI
+reference set (192 SVGs in `001-mds/xmi-images/`).
+
+## Current state (after TODO-D 41, 42)
+
+```
+rect     ours= 1781 ref= 2002  delta=-221 (-11.0%)
+path     ours= 3018 ref= 3298  delta=-280 ( -8.5%)
+polygon  ours=  955 ref=  961  delta=  -6 ( -0.6%)
+text     ours=16947 ref=17548  delta=-601 ( -3.4%)
+Text overlap avg: 64.5%
+```
+
+185/188 diagrams matched, 59 outliers.
+
+## Architecture cleanup (DONE)
+
+- `lib/ea.rb` no longer `require_relative`s `ea/version`. VERSION
+  is inlined.
+- `lib/ea/sources/xmi/diagram_builder.rb` no longer
+  `require_relative`s `umldi_keyword_extractor`. Uses autoload.
+- `lib/ea/qea/factory/generalization_builder.rb` no longer uses
+  `public_send(:"#{k}=", v)` for attribute assignment.
+
+## Diagnosis (DONE)
+
+The deltas decompose into three root causes:
+
+1. **Element icon decorations** (TODO-D 44, ~280 paths).
+   EA renders a small "folded paper" icon at the top-right of
+   some elements. IconRenderer exists but the discriminator
+   (which elements get icons) is non-trivial — not just
+   `HideIcon=0`.
+
+2. **Phantom parent class boxes** (TODO-D 45, ~80 rects).
+   When a connector's endpoint references a classifier that
+   isn't placed on the diagram, EA renders a minimal "phantom"
+   box at the connector's endpoint.
+
+3. **User-drawn legend swatches** (TODO-D 46, ~50-100 rects).
+   Manually-drawn colored rectangles inside Note/text elements.
+   Not encoded as standard UML — may be unrecoverable from XMI.
+
+Plus two text-delta sources:
+- Diagrams where EA renders only a frame and no elements
+  (TODO-D 41 has examples). The reference SVG is a tiny blank
+  canvas; our renderer emits the full content.
+- Tree-routing generalization markers: EA collapses 9 parallel
+  connectors into 9 polygons at the same anchor (TODO-D 43).
+
+## Acceptance
+
+Closing each delta to zero requires:
+- [ ] TODO-D 44 discriminator identified and IconRenderer enabled
+- [ ] TODO-D 45 phantom parent rendering implemented
+- [ ] TODO-D 46 either implemented or excluded from parity measurement
+- [ ] TODO-D 43 marker strategy per connector Mode (tree vs custom)
+- [ ] Blank-frame diagram detection (small canvas, all elements off-canvas)
+
+## Out of scope for this commit
+
+The remaining work requires EA GUI testing or Ghidra disassembly
+to identify the icon discriminator and phantom-box trigger. These
+are tracked in their own TODOs and will be addressed in focused
+follow-up PRs.

data/TODO.diagrams/43-marker-deduplication-strategy.md

@@ -0,0 +1,54 @@
+# TODO-D 43: Marker deduplication strategy
+
+## Current behavior
+
+`lib/ea/svg/ea_emitter/markers.rb` deduplicates marker polygons/paths
+by their anchor point (first coord pair, rounded to integer).
+
+```
+unique_bodies = grouped_entries.uniq { |e| anchor_key(e.body) }
+```
+
+## Reference behavior (verified from plateau)
+
+EA's reference set is INCONSISTENT:
+
+- `EAID_E7AABA98` (Building): 9 parallel generalizations to one
+  parent — EA emits 9 polygons at the same anchor (collapses NOT
+  applied).
+- `EAID_9994BF62` (地域地区および用途地域): 29 generalizations, EA
+  emits only 3 triangles. Many generalizations share the same
+  parent — EA emits ONE marker per parent point, not per connector.
+
+So:
+- Same parent, single shape per connector endpoint: 1 marker (collapsed)
+- Same parent, parallel (multiple distinct routes): 1 marker per route
+
+## Discriminator hypothesis
+
+The discriminator is likely the connector's `Mode` style flag:
+
+- `Mode=1` — Custom routing (each connector has its own route →
+  emit per connector)
+- `Mode=3` — Tree routing (children share route to parent →
+  emit ONE marker per parent point)
+
+## Acceptance
+
+- Identify the exact field that distinguishes "tree" from "custom"
+  routing.
+- Implement per-mode marker strategy:
+  - Tree mode: emit one marker per (parent, edge) tuple.
+  - Custom mode: emit one marker per connector.
+- Bench polygon delta → 0.
+- Spec coverage for both modes.
+
+## Bench impact (current)
+
+```
+polygon  ours=955 ref=961 delta=-6  (-0.6%)
+```
+
+If the discriminator is wrong we either over-render (Mode=3 case
+with parallel connectors) or under-render (Mode=1 case with shared
+parent).

data/TODO.diagrams/44-element-icon-decorations.md

@@ -0,0 +1,34 @@
+# TODO-D 44: Element icon decorations (folded-paper class icon)
+
+## Symptom
+
+EA renders a small "folded paper" icon at the top-right corner of
+each class shape. The icon is two `<path>` elements:
+
+1. Outer outline: `M x y L x+6 y L x+9 y+4 L x+9 y+11 L x y+11 Z`
+2. Folded corner: `M x+6 y L x+6 y+4 L x+9 y+4`
+
+Style:
+- `stroke-width:1; stroke-linecap:square; stroke-linejoin:bevel;`
+- Outer: `fill:#DCF8F0; stroke:#577AC1` (light cyan fill, blue stroke)
+- Inner corner: `fill:transparent; stroke:#577AC1`
+
+## Discriminator
+
+The XMI element style carries `HideIcon=0` (show) or `HideIcon=1`
+(hide). When shown, EA emits the icon paths regardless of element
+type (class, data type, etc.).
+
+## Bench impact (estimated)
+
+- 2 paths per shown icon × ~140 elements with `HideIcon=0` ≈ 280
+  paths. This matches the current path delta of `-280`.
+
+## Acceptance
+
+- Add an `Element::IconRenderer` that emits the two `<path>`
+  elements at (bounds.right - 12, bounds.top + 3) when
+  `element.style["HideIcon"] == "0"` (default visible).
+- Thread HideIcon parsing through `ExtensionStyleParser`.
+- Spec coverage for both shown and hidden cases.
+- Bench path delta → 0.

data/TODO.diagrams/45-phantom-parent-class-boxes.md

@@ -0,0 +1,40 @@
+# TODO-D 45: Phantom parent class boxes (generalization tree)
+
+## Symptom
+
+Some diagrams render extra `<rect>`+`<text>` for a classifier that
+is NOT placed on the diagram via `t_diagramobjects` (or XMI
+`<elements>` block), but IS referenced as a generalization parent
+by a connector on the diagram.
+
+Reference SVG for `EAID_5A43833E_680B_4a90_8931_0C902304E029` has:
+
+```
+<rect x="161" y="161" width="179" height="80" .../>
+<text>_AbstractGeometricAggregate</text>
+```
+
+The classifier `_AbstractGeometricAggregate` is the general parent
+of one of the placed children, but is NOT placed itself. EA renders
+a phantom box at the parent end of the generalization connector.
+
+## Discriminator (hypothesis)
+
+When a connector's `EOID` references a `DUID` that is NOT in the
+placed-elements index, EA renders a minimal phantom box at the
+connector's endpoint coordinate. The phantom box shows the parent
+classifier's name and stereotype but no attributes/operations.
+
+## Acceptance
+
+- Detect connectors whose endpoint DUID has no matching placed
+  element.
+- Render a phantom box at the connector's endpoint with the
+  referenced classifier's header.
+- Bench rect delta improves by N where N is the count of phantom
+  parents across the plateau reference set.
+
+## Related
+
+- TODO-D 26 (phantom class headers from connector endpoints) —
+  same root cause, separate TODO for tracking.

data/TODO.diagrams/46-user-drawn-legend-swatches.md

@@ -0,0 +1,44 @@
+# TODO-D 46: User-drawn legend swatches (colored marker rects)
+
+## Symptom
+
+Some diagrams include manually-drawn legend boxes — small colored
+`<rect>` elements (typically 17×17) accompanied by text labels,
+grouped inside a larger "legend" container rect.
+
+Reference SVG for `EAID_5A43833E_680B_4a90_8931_0C902304E029` has:
+
+```
+<rect x="647" y="751" width="17" height="17" fill="#CCFFCC" .../>
+<text>GMLに定義されたクラス</text>
+<rect x="647" y="770" width="17" height="17" fill="#FFFFCC" .../>
+<text>CityGMLに定義されたクラス</text>
+<rect x="647" y="789" width="17" height="17" fill="#FFCCFF" .../>
+```
+
+These are NOT modeled classifiers — they're user-drawn shapes
+inside a "diagram note" or "text" element.
+
+## Source
+
+EA encodes these as nested `<element>` rows inside a parent
+`<element>` in the extension block, OR as separate `<element>`
+rows whose `subject` references a "Note" or "Text" classifier with
+custom geometry/style.
+
+In the plateau XMI, these specific swatches appear to be embedded
+in a Klass with `name=nil` that serves as the legend frame. The
+swatches themselves are not present as separate element rows.
+
+## Acceptance
+
+- Investigate whether the XMI carries these as nested elements,
+  tagged values, or Note element children.
+- If unrecoverable from XMI, document as "out of scope — user
+  decoration not encoded in the model" and exclude from parity
+  measurement.
+
+## Bench impact
+
+About 50-100 rects across the plateau set. Cannot be fully closed
+without explicit source data.

data/TODO.diagrams/47-attribute-line-fidelity.md

@@ -0,0 +1,72 @@
+# TODO-D 47: Attribute line fidelity (qualified prefix + multiplicity shorthand + primitive type strip)
+
+## Symptom (largest single source of text delta)
+
+Aggregated text diff against 185 plateau diagrams:
+
+```
+Ref has but we don't:        We have but ref doesn't:
+  qualified_name:  539         qualified_name: 1016
+  other:          1501         other:           462
+```
+
+Most "qualified_name" cases are attribute lines on inherited
+properties. Reference renders:
+
+```
+core::mimeType: gml::CodeType [0..1]
+core::elements: double [16] {ordered}
+```
+
+We render:
+
+```
+mimeType: gml::CodeType [0..1]
+elements: xs::double [16..16]
+```
+
+## Three distinct bugs
+
+### A. Missing namespace prefix on inherited properties
+
+When a class displays a property inherited from a parent in a
+different package, EA prepends the parent's package name to the
+property name (`core::mimeType`). For own properties, no prefix.
+
+Discriminator: the property's `owner_id` (the classifier that
+declares it) — if that classifier's `package_id` differs from the
+displayed classifier's `package_id`, render the prefix.
+
+### B. Multiplicity shorthand `[N]` not `[N..N]`
+
+When `multiplicity_lower == multiplicity_upper`, EA renders `[N]`
+(single value), not `[N..N]`. We always render the range.
+
+### C. Primitive type strip
+
+When the type is a primitive (xs:string, xs:double, xs:integer,
+xs:date, xs:gYear, xs:boolean, xs:anyURI, etc.), EA strips the
+namespace prefix and renders just `string`, `double`, etc.
+
+Verified against ref: `double` not `xs::double`, `string` not
+`xs::string`. The exception is when the property's type is an
+in-model Classifier (not a primitive) — then qualified form is
+kept (`gml::CodeType`, `core::TransformationMatrix4x4`).
+
+### D. `{ordered}` modifier on ordered properties
+
+When `is_ordered == true` and multiplicity is non-singleton,
+EA appends ` {ordered}` after the multiplicity.
+
+## Acceptance
+
+- All four rules implemented in `AttributeRenderer.line_for`.
+- Property model exposes the source classifier (for prefix logic).
+- Spec coverage for each rule (own/inherited, primitive/typed,
+  lower==upper, ordered/unordered).
+- Bench text overlap → ~90% (from 64.5%).
+
+## Bench impact estimate
+
+Closes ~600 text deltas (the qualified_name category) plus ~1000
+"other" deltas that are attribute lines with wrong format.

data/TODO.diagrams/48-spec-coverage-critical-emitter-components.md

@@ -0,0 +1,45 @@
+# TODO-D 48: Spec coverage for critical svg/ea_emitter components
+
+## Goal
+
+Most `lib/ea/svg/ea_emitter/element/*` and `lib/ea/svg/ea_emitter/*.rb`
+files had zero dedicated specs — they were only exercised through
+the high-level regression suites. A regression in BColDecoder,
+HeaderLines, Filter, or TextEscape could ship undetected if it
+didn't trigger a regression-suite threshold.
+
+## Coverage added
+
+- `spec/ea/svg/ea_emitter/element/bcol_decoder_spec.rb` — BGR
+  decoding, sentinel handling, color hex format.
+- `spec/ea/svg/ea_emitter/element/filter_spec.rb` — skip?
+  predicate under all permutations of (background_color, name,
+  properties, model_index presence).
+- `spec/ea/svg/ea_emitter/element/header_lines_spec.rb` —
+  stereotype fallback rules, abstract italic-bold, UMLDI keyword
+  override, package-qualified display name, Note special-case.
+- `spec/ea/svg/ea_emitter/element/divider_renderer_spec.rb` —
+  horizontal path geometry, group style attributes.
+- `spec/ea/svg/ea_emitter/element/shape_renderer_spec.rb` — rect
+  attributes, fill/stroke group style, shape-rendering.
+- `spec/ea/svg/ea_emitter/element/text_escape_spec.rb` — XML
+  special-char escaping, UTF-8 preservation, stereotype/namespace
+  marker preservation.
+
+## Bug found and fixed during spec writing
+
+`HeaderLines.explicit_stereotype` called `classifier.stereotype_refs`
+without guarding for Note (which extends Base, not Classifier).
+Same issue in `display_name` (qualified_name missing on Note).
+
+Added `is_a?(Ea::Model::Classifier)` guards so Note and other
+non-Classifier model elements degrade gracefully instead of
+raising NoMethodError. Without the new spec coverage this bug
+would only surface when a user rendered a diagram containing a
+Note element with a stereotype keyword.
+
+## Verification
+
+- 1746 examples pass (up from 1694).
+- New specs cover both the happy path and edge cases.
+- Bench plateau XMI unchanged.

data/TODO.diagrams/49-spec-coverage-orchestrators.md

@@ -0,0 +1,25 @@
+# TODO-D 49: More spec coverage for orchestrators + labels cleanup
+
+## Goal
+
+Add dedicated specs for the high-level orchestrators that were
+previously only exercised through end-to-end regression tests.
+
+## Coverage added
+
+- `spec/ea/svg/ea_emitter/element/operation_renderer_spec.rb` —
+  Operation signature rendering, parameter joining, line-height
+  stacking, visibility marker offsets.
+- `spec/ea/svg/ea_emitter/layer_sequencer_spec.rb` — Background
+  layer presence, labels layer inclusion, frame toggle, theme
+  propagation, connector path integration.
+
+## Dead code removed
+
+`Labels#midpoint_text_for` was an unused private method (the
+actual midpoint text emission goes through `texts_for`). Deleted.
+
+## Verification
+
+- 1759 examples pass (up from 1746, +13 new).
+- Bench plateau XMI unchanged.

data/TODO.diagrams/50-examples-parity.md

@@ -0,0 +1,85 @@
+# TODO-D 50: Examples (basic, simple, test, etc.) parity
+
+## Goal
+
+Get every example QEA in `examples/qea/` matching its reference
+SVGs in `examples/exports/<name>/images/`.
+
+## Current bench (`rake svg:examples`)
+
+| Example | Matched | rect | path | polygon | text |
+|---------|---------|------|------|---------|------|
+| simple  | 2/2     | 0    | 0    | 0       | 0    |
+| ArcGISWorkspace_template | 5/6 | -2 | -7 | 0 | -1 |
+| basic   | 19/22   | -3   | -30  | -6      | -22  |
+| test    | 1/2     | -15  | -58  | 0       | -11  |
+
+**simple.qea is at 100%!** Zero deltas across the board.
+
+## Architecture addition
+
+`rake svg:examples` benches every QEA in `examples/qea/` against
+its matching `examples/exports/<name>/{images,Images}/` directory.
+Run after every renderer change to catch regressions in any
+example.
+
+## Remaining per-example deltas
+
+### test.qea — Test Model diagram (-15 rect, -58 path, -11 text)
+
+1 element (Package "Test Schema") + 0 connectors. Reference has
+16 small visibility-marker rects at x=40 (one per attribute row)
++ 8 horizontal divider paths inside the markers. Each attribute
+row in this diagram shows:
+  - 11x14 outer rect (pale yellow, blue stroke)
+  - 11x4 inner rect (white)
+  - 1 horizontal divider path
+
+That's 3 elements per attribute row × 8 rows = 24 missing
+elements. Plus the Package tab icon path. Total ~25 missing.
+
+### basic.qea — visibility icons + object instance format
+
+Top outliers:
+- Package Imports (-6 rect, -18 path): visibility icons +
+  package-tab icons.
+- Object with Value Specifications (-6 path, -19 text): Object
+  instance rendering. EA shows "Object 01 / roleOne: Class A" and
+  "attribute = value" slot format. We render the qualified class
+  name only.
+- Objects as Instances of Classes (-4 path, -9 text): same Object
+  instance format issue.
+
+## Discriminator for visibility icons
+
+Visibility icons appear in:
+- Test Model (test.qea) — Package element with attribute rows
+- Package Imports (basic.qea) — visibility column next to attrs
+
+They do NOT appear in:
+- simple.qea — no attribute compartments shown
+- Most basic.qea class diagrams — already have +/- text markers
+
+The discriminator is likely:
+- Diagram style1 flag (HideProps=0 + VisibleAttributeDetail=1)
+- OR element-level ShowIcon-style flag
+
+## Acceptance
+
+- Implement VisibilityIconRenderer (per-attribute 3-element
+  decoration).
+- Implement ObjectInstance rendering format.
+- Bench each example QEA → 0/0/0/0 deltas.
+
+## Verification
+
+`rake svg:examples` runs all example benchmarks in one command.
+Output format:
+
+```
+name                                     N/M matched
+  rect    ours=X ref=Y delta=Z (Z%)
+  path    ...
+  polygon ...
+  text    ...
+```

data/TODO.diagrams/51-property-oy-gap-and-remaining-gaps.md

@@ -0,0 +1,48 @@
+# TODO-D 51: «property» OY-gap rule + remaining examples gaps
+
+## Completed
+
+### «property» label discriminator (DONE)
+
+`EndLabel#property_label?` now actually inspects the LLT/LLB OY
+gap and returns false when below 15px. Previously it always
+returned true, causing 4-8 spurious «property» texts per diagram
+in basic.qea.
+
+After fix:
+- basic.qea 'Basic Class Diagram with Operations' → 100% parity
+- basic.qea text overlap: 84.0% (high — most matching text correct)
+- plateau text overlap unchanged at 64.5%
+- plateau text count delta: -601 → -627 (correctly removes the
+  spurious «property» labels that ref doesn't have)
+
+## Remaining example gaps (still open)
+
+### Visibility icons (Test Model + Package Imports)
+
+EA renders a complex "folded page" icon for each attribute row in
+some diagram styles:
+- 1 outer rect (11x14, pale yellow fill, blue stroke)
+- 1 inner rect (11x4 at top, white fill, blue stroke)
+- 1 horizontal divider path (midline)
+- 3-4 short "text line" paths inside (4px wide each)
+
+That's 5-6 elements per attribute row. Discriminator likely the
+`ShowIcons=1` flag in diagram Style1.
+
+### Object instance rendering (Objects as Instances of Classes)
+
+EA renders `Object 01 / roleOne: Class A` (instance name + role +
+classifier) and `attribute = value` slots. Requires a new
+InstanceSpecification model + renderer.
+
+### Domain Model connector routing
+
+Ref uses cubic bezier (`C`) for connector paths in tree mode;
+we use linear `L` segments. The visual is similar but path
+geometry differs. EA also emits more sub-paths per connector
+in some layouts.
+
+## Verification
+
+`rake svg:examples` shows current state. 15/27 diagrams at 100%.

data/TODO.diagrams/52-marker-registration-architecture.md

@@ -0,0 +1,89 @@
+# TODO-D 52: Marker registration architecture + Plus marker
+
+## Problem
+
+The original `marker.rb` had eager registration:
+
+```ruby
+Registry.register(Diamond)
+Registry.register(OpenTriangle)
+Registry.register(Plus)
+Registry.register(ArrowPath)
+```
+
+But Diamond, OpenTriangle, etc. were declared via `autoload`, so
+the constant lookup at module load time failed with:
+
+```
+NameError: uninitialized constant Ea::Svg::EaEmitter::Marker::Plus
+```
+
+## Solution
+
+Two-part lazy registration:
+
+1. **Self-registration at file scope**: each marker kind file
+   (diamond.rb, open_triangle.rb, plus.rb, arrow_path.rb) ends
+   with a fully-qualified registration call:
+
+   ```ruby
+   Ea::Svg::EaEmitter::Marker::Registry.register(
+     Ea::Svg::EaEmitter::Marker::Plus
+   )
+   ```
+
+   This runs when the file loads (which happens via autoload when
+   the constant is first referenced).
+
+2. **Lazy autoload trigger**: `Marker.ensure_builtins_registered!`
+   references each autoloaded marker constant, which triggers
+   file load, which runs the per-file registration line.
+
+   ```ruby
+   def self.ensure_builtins_registered!
+     Diamond
+     OpenTriangle
+     Plus
+     ArrowPath
+   end
+   ```
+
+3. **First-use hook**: `Registry.specs_for` calls
+   `Marker.ensure_builtins_registered!` before searching kinds,
+   so registration is triggered on the first marker lookup.
+
+## Benefits
+
+- **OCP**: Adding a new marker kind = creating a new file with
+  its class + registration line. The marker.rb dispatcher does
+  NOT need modification.
+- **Lazy loading**: marker kinds only load when the registry is
+  first queried.
+- **No autoload cycle**: each kind file knows its own constant;
+  registration at the bottom of the file is safe.
+
+## Plus marker addition
+
+New `Marker::Plus` for Nesting connectors. EA renders a 16x16
+plus symbol at the contained end:
+
+```
+M cx cy-8 L cx cy+8    (vertical arm)
+M cx+8 cy L cx-8 cy    (horizontal arm)
+```
+
+basic.qea 'Package Contents' (3 visible nesting connectors) →
+100% path parity.
+
+## Tests
+
+- spec/ea/svg/ea_emitter/marker/plus_spec.rb (5 specs):
+  handles? for Nesting, specs_for shape/anchor, ARM_LENGTH
+  constant.
+
+## Verification
+
+- 1764 specs pass (up from 1759, +5 new)
+- basic.qea: 20/22 diagrams within tolerance (was 19/22)
+- Plateau bench unchanged: rect -221, path -280, polygon -6,
+  text -627.