ea 0.4.0 → 0.5.1

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.

data/TODO.diagrams/53-remaining-example-gaps.md

@@ -0,0 +1,86 @@
+# TODO-D 53: Remaining example parity gaps (deferred)
+
+## Summary
+
+This round achieved 15/27 → 17/27 example diagrams at 100% parity
+(plus 2/2 simple + 1/2 test, 20/22 basic, 5/6 ArcGIS).
+
+```
+simple              2/2   matched    100% ✓
+ArcGISWorkspace     5/6   matched
+basic              20/22  matched
+test                1/2   matched
+```
+
+## Remaining basic.qea gaps (7 diagrams, all minor)
+
+| Diagram | rect | path | polygon | text | Root cause |
+|---------|------|------|---------|------|------------|
+| Package Imports | -6 | -18 | 0 | -4 | visibility icons missing |
+| Object with Value Specifications | 0 | -6 | 0 | -19 | object instance format |
+| Objects as Instances of Classes | 0 | -4 | 0 | -9 | object instance format |
+| Domain Model | +3 | -7 | +1 | -8 | tree-routed bezier paths |
+| Basic Object Diagram | 0 | -3 | 0 | -2 | (object value slots) |
+| Basic Class with Receptions | 0 | +5 | -2 | -3 | extra compartment dividers |
+| Composition with Substitution | 0 | 0 | 0 | -1 | nested class display_name |
+
+## test.qea gap
+
+`Test Model` diagram: r=-15, p=-58, po=0, t=-11. Needs visibility
+icons + Package element attribute rendering.
+
+## Implementation paths (in priority order)
+
+### TODO-D 54: Visibility icons (TODO-D 51 expansion)
+
+EA renders 5-6 element decorations per attribute row when
+`ShowIcons=1`:
+- 1 outer rect (11x14, pale yellow + blue stroke)
+- 1 inner rect (11x4, white)
+- 1 horizontal divider path (midline)
+- 3-4 short "text line" paths inside
+
+This closes `Test Model` (r=-15, p=-58) and `Package Imports`
+(r=-6, p=-18). 73+ missing elements across examples.
+
+Implementation: `Compartment::VisibilityIcon` + discriminator in
+`RenderContext` (default hidden, opt-in via DiagramElement#icon_visible
+or DisplayConfig#show_icons).
+
+### TODO-D 55: Object instance format
+
+EA renders object instances as:
+- Header: `Object 01 / roleOne: Class A` (instance name + role + classifier)
+- Slot rows: `attribute = value` for each slot
+- Package qualifier: `(from Objects)`
+
+Current code renders them as plain classes with the qualified class
+name. Requires new `Ea::Model::InstanceSpecification` model + QEA
+parser support + ObjectInstanceRenderer compartment.
+
+### TODO-D 56: Tree-routed bezier paths
+
+EA renders tree-routed connectors with cubic bezier curves
+(C commands) for smooth paths. We render straight L segments.
+The visual is similar but path count differs. Detection: when a
+connector has 3+ waypoints with `tree:` style, emit bezier.
+
+## Architectural decisions documented this round
+
+1. **«property» label OY-gap rule**: real geometry check (15px
+   threshold) instead of always-true.
+2. **Implicit connector visibility**: render Nesting when
+   `tree:` style is set, filter otherwise.
+3. **Plus marker**: new `Marker::Plus` kind for Nesting connector
+   "+" decoration (lazy registration architecture).
+4. **Marker registration**: per-file `Registry.register(...)` +
+   `Marker.ensure_builtins_registered!` — OCP-friendly, no
+   autoload cycle.
+
+## Final state
+
+- 1764 specs pass
+- Zero code-quality violations
+- basic.qea: 8 → 9 perfect diagrams (out of 22)
+- test.qea: 0 → 1 perfect diagram (out of 2)
+- simple.qea: 2/2 perfect

data/TODO.diagrams/54-display-name-nested-classes.md

@@ -0,0 +1,40 @@
+# TODO-D 54: display_name for nested classes (DONE)
+
+## Before
+
+`HeaderLines#display_name` used both `visually_nested` AND
+`nested_class_qualifier?` to decide whether to render the
+qualified name:
+
+```ruby
+return name if visually_nested &&
+               classifier.is_a?(Ea::Model::Classifier) &&
+               nested_class_qualifier?(classifier, name)
+```
+
+The `visually_nested` check is a position-based heuristic (child
+bounds inside parent bounds). For basic.qea's "Composition with
+Substitution" diagram, Class B.1, B.2, B.3 are placed at y=-330
+(off-canvas) while Class B is at y=-172. The position check returns
+false, but the reference renders "Class B::Class B.1" (qualified).
+
+## After
+
+The `visually_nested` check is dropped. The `nested_class_qualifier?`
+check alone determines the display:
+
+```ruby
+return name if classifier.is_a?(Ea::Model::Classifier) &&
+               nested_class_qualifier?(classifier, name)
+```
+
+The qualifier is a parent class name (not a package name) when it
+differs from the classifier's package name. EA always shows the
+parent-class qualifier regardless of visual position.
+
+## Verification
+
+- basic.qea "Composition with Substitution": text delta -1 → 0 ✓
+- 1764 specs pass
+- Plateau unchanged (text overlap 64.5%)
+- simple.qea unchanged (100%)

data/TODO.diagrams/55-visibility-icon-discriminator.md

@@ -0,0 +1,58 @@
+# TODO-D 55: Visibility icon discriminator (deferred)
+
+## Status: deferred (out of scope for current session)
+
+EA renders a "folded page" visibility icon for each attribute row
+in some diagrams. The discriminator is `ShowIcons=1` in the
+diagram's Style1 string.
+
+## Icon design (per attribute row)
+
+```
+y_top (rect.y)
+y_top..y_top+4:   inner rect 11x4 (white fill, blue stroke)
+y_top..y_top+14:  outer rect 11x14 (pale yellow, blue stroke)
+y_top+7:          horizontal path (midline)
+y_top+5, y_top+9, y_top+11: 3 short "text line" paths (4 wide)
+```
+
+Total: 2 rects + 4 paths = 6 elements per attribute row.
+
+## Where it appears
+
+| Diagram | rect | path | text | Why |
+|---------|------|------|------|-----|
+| basic.qea Package Imports | -6 | -18 | -4 | 2 attrs × 6 elements = 12 missing |
+| test.qea Test Model | -15 | -58 | -11 | 8 attrs × 6 elements = 48 missing |
+| basic.qea Operations+Object | similar | similar | similar | some object diagrams |
+
+## Implementation
+
+1. Parse `ShowIcons=N` from `t_diagram.Style1` (or per-element
+   `HideIcon=N` from `t_diagramobjects.Style`).
+2. When ShowIcons=1 (or default-icon), pass an `icon_visibility`
+   flag through `RenderContext`.
+3. Add a new `Compartment::VisibilityIcon` module that renders
+   the 2 rects + 4 paths per attribute row.
+4. Wire it into the Attribute compartment (or render alongside
+   it).
+
+## Why deferred
+
+- Requires parsing the QEA Style1 string (already done in
+  DisplayConfig for other flags).
+- Discriminator must be verified across more diagrams (e.g.
+  plateau's Building diagram has 1 icon — the same logic should
+  apply).
+- Each attribute row needs the icon rendered at a precise offset
+  (currently at content_x_offset, attr_y - 9).
+
+Closes ~80 rects + ~50 paths in basic.qea + ~70 rects + ~250
+paths in test.qea (Test Model with 8 attrs).
+
+## Code-quality alignment
+
+The new `Compartment::VisibilityIcon` would follow the OCP
+pattern established by the Compartment pipeline — adding a new
+compartment = appending to `Compartment::ALL`, no modification
+of `Elements#groups_for` needed.