ea 0.2.5 → 0.3.1

data/lib/ea/spa/projector.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+module Ea
+  module Spa
+    # One-way transform: Ea::Model::Document → SPA view artifacts.
+    #
+    # The projector walks the model once and emits:
+    # - Skeleton (with package tree + per-classifier entries)
+    # - SearchIndex (flat searchable rows)
+    # - Shards (one per entity, generated lazily via #shard_for)
+    #
+    # Sharding strategy is configurable via the `shard_url_for`
+    # proc — by default it produces "data/<kind>s/<id>.json" paths
+    # matching the sharded output strategy.
+    class Projector
+      attr_reader :document, :shard_url_for, :configuration
+
+      def initialize(document, shard_url_for: nil, configuration: nil)
+        @document = document
+        @shard_url_for = shard_url_for || default_shard_url
+        @configuration = configuration
+      end
+
+      def skeleton
+        Skeleton.new(
+          metadata: metadata_hash,
+          package_tree: build_package_tree,
+          entries: build_entries,
+          view_extras: view_extras
+        )
+      end
+
+      def search_index
+        SearchIndex.new(entries: build_search_entries)
+      end
+
+      def shard_for(model_element)
+        Shard.new(
+          id: model_element.id,
+          kind: kind_of(model_element),
+          payload: payload_for(model_element)
+        )
+      end
+
+      # Enumerate every (id, kind, shard) triple the SPA can address.
+      # Diagrams are skipped when the configuration disables them.
+      def each_shard
+        return enum_for(:each_shard) unless block_given?
+
+        document.classifiers.each { |c| yield shard_for(c) }
+        document.packages.each { |p| yield shard_for(p) }
+        document.diagrams.each { |d| yield shard_for(d) } if render_diagrams?
+      end
+
+      def render_diagrams?
+        configuration ? configuration.render_diagrams? : true
+      end
+
+      private
+
+      def default_shard_url
+        lambda do |element|
+          kind = kind_of(element)
+          "data/#{pluralize(kind)}/#{element.id}.json"
+        end
+      end
+
+      def pluralize(kind)
+        case kind
+        when "class" then "classes"
+        when "property" then "properties"
+        else "#{kind}s"
+        end
+      end
+
+      def metadata_hash
+        base = document.metadata
+        merged = configuration ? configuration.apply_to_metadata(base) : base
+        JSON.parse(merged.to_json)
+      end
+
+      def view_extras
+        configuration&.view_extras || {}
+      end
+
+      def build_package_tree
+        nodes = document.packages.map do |pkg|
+          PackageTreeNode.new(
+            id: pkg.id,
+            name: pkg.name,
+            parent_id: pkg.parent_id,
+            child_ids: pkg.sub_package_ids,
+            classifier_ids: classifiers_in_package_ids(pkg.id),
+            diagram_ids: pkg.diagram_ids
+          )
+        end
+        PackageTree.new(
+          root_ids: document.root_packages.map(&:id),
+          nodes: nodes
+        )
+      end
+
+      def classifiers_in_package_ids(package_id)
+        document.classifiers_in_package(package_id).map(&:id)
+      end
+
+      def build_entries
+        document.classifiers.map do |c|
+          SkeletonEntry.new(
+            id: c.id,
+            name: c.name,
+            kind: c.model_kind,
+            package_id: c.package_id,
+            qualified_name: c.qualified_name,
+            shard_url: shard_url_for.call(c)
+          )
+        end
+      end
+
+      def build_search_entries
+        entries = []
+        document.classifiers.each do |c|
+          entries << search_entry_for_classifier(c)
+          c.properties.each { |p| entries << search_entry_for_property(p, c) }
+        end
+        document.packages.each { |p| entries << search_entry_for_package(p) }
+        entries
+      end
+
+      def search_entry_for_classifier(c)
+        SearchEntry.new(
+          id: c.id,
+          kind: c.model_kind,
+          name: c.name,
+          qualified_name: c.qualified_name,
+          package: package_qualified_name(c.package_id),
+          content: classifier_search_content(c),
+          boost: 1.5
+        )
+      end
+
+      def search_entry_for_property(prop, owner)
+        SearchEntry.new(
+          id: prop.id,
+          kind: "property",
+          name: prop.name,
+          qualified_name: "#{owner.qualified_name}::#{prop.name}",
+          package: package_qualified_name(owner.package_id),
+          content: [prop.name, prop.type_name, prop.annotations.map(&:body)].flatten.compact.join(" "),
+          boost: 1.0
+        )
+      end
+
+      def search_entry_for_package(pkg)
+        SearchEntry.new(
+          id: pkg.id,
+          kind: "package",
+          name: pkg.name,
+          qualified_name: pkg.qualified_name,
+          package: pkg.parent_id ? package_qualified_name(pkg.parent_id) : "",
+          content: [pkg.name, pkg.annotations.map(&:body)].flatten.compact.join(" "),
+          boost: 1.2
+        )
+      end
+
+      def classifier_search_content(c)
+        parts = [c.name, c.qualified_name, c.stereotype_refs].compact
+        parts << c.properties.map(&:name)
+        parts << c.operations.map(&:name)
+        parts << c.annotations.map(&:body)
+        parts.flatten.compact.join(" ").gsub(/\s+/, " ").strip
+      end
+
+      def package_qualified_name(package_id)
+        return "" if package_id.nil?
+
+        pkg = document.index_by_id[package_id]
+        pkg&.qualified_name || ""
+      end
+
+      def kind_of(element)
+        case element
+        when Ea::Model::Klass then "class"
+        when Ea::Model::Enumeration then "enumeration"
+        when Ea::Model::DataType then "data_type"
+        when Ea::Model::PrimitiveType then "primitive_type"
+        when Ea::Model::Interface then "interface"
+        when Ea::Model::Package then "package"
+        when Ea::Model::Diagram then "diagram"
+        else "element"
+        end
+      end
+
+      def payload_for(element)
+        JSON.parse(element.to_json)
+      end
+    end
+  end
+end

data/lib/ea/spa/search_entry.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Ea
+  module Spa
+    # One searchable row. MiniSearch-compatible shape: id, name,
+    # qualifiedName, type, package, content — all searchable, with
+    # `boost` weighting source-type importance.
+    class SearchEntry < Lutaml::Model::Serializable
+      attribute :id, :string
+      attribute :kind, :string              # class|enumeration|package|...
+      attribute :name, :string
+      attribute :qualified_name, :string
+      attribute :package, :string
+      attribute :content, :string           # flattened searchable text
+      attribute :boost, :float, default: -> { 1.0 }
+
+      json do
+        map "id", to: :id
+        map "kind", to: :kind
+        map "name", to: :name
+        map "qualifiedName", to: :qualified_name
+        map "package", to: :package
+        map "content", to: :content
+        map "boost", to: :boost, render_default: true
+      end
+    end
+  end
+end

data/lib/ea/spa/search_index.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Ea
+  module Spa
+    class SearchIndex < Lutaml::Model::Serializable
+      attribute :version, :string, default: -> { "1.0" }
+      attribute :fields, :string, collection: true,
+                                  default: -> { %w[name qualifiedName kind package content] }
+      attribute :entries, SearchEntry, collection: true, initialize_empty: true
+
+      json do
+        map "version", to: :version, render_default: true
+        map "fields", to: :fields, render_default: true
+        map "entries", to: :entries, render_empty: true
+      end
+    end
+  end
+end

data/lib/ea/spa/shard.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Ea
+  module Spa
+    # Per-entity detail payload. Plain Ruby value object (not a
+    # lutaml-model type) because the payload is an arbitrary JSON
+    # blob whose shape depends on the model element's kind — we
+    # don't want the framework's hash-type cast getting in the way.
+    Shard = Struct.new(:id, :kind, :payload, keyword_init: true) do
+      def to_h
+        { "id" => id, "kind" => kind, "payload" => payload }
+      end
+
+      def to_json(*args)
+        JSON.generate(to_h, *args)
+      end
+    end
+  end
+end

data/lib/ea/spa/skeleton.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Ea
+  module Spa
+    # Top-level SPA skeleton. Plain Struct (not a lutaml-model
+    # type) because it's a thin transport wrapper around typed
+    # sub-objects (PackageTree, SkeletonEntry) plus a raw metadata
+    # hash extracted from the model.
+    Skeleton = Struct.new(:metadata, :package_tree, :entries, :view_extras,
+                          keyword_init: true) do
+      def to_json(*args)
+        payload = {
+          "metadata" => metadata,
+          "packageTree" => package_tree,
+          "entries" => entries
+        }
+        payload["viewExtras"] = view_extras unless view_extras.nil? || view_extras.empty?
+        JSON.generate(payload, *args)
+      end
+    end
+  end
+end

data/lib/ea/spa/skeleton_entry.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Ea
+  module Spa
+    # One row in the SPA skeleton: the minimal info needed to
+    # render the sidebar, do name searches, and route to a shard.
+    # Everything else (properties, operations, etc.) lives in the
+    # per-entity Shard.
+    class SkeletonEntry < Lutaml::Model::Serializable
+      attribute :id, :string
+      attribute :name, :string
+      attribute :kind, :string            # class|enumeration|data_type|...
+      attribute :package_id, :string
+      attribute :qualified_name, :string
+      attribute :shard_url, :string       # where to fetch the full Shard
+
+      json do
+        map "id", to: :id
+        map "name", to: :name
+        map "kind", to: :kind
+        map "packageId", to: :package_id
+        map "qualifiedName", to: :qualified_name
+        map "shardUrl", to: :shard_url
+      end
+    end
+  end
+end

data/lib/ea/spa.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Ea
+  # Ea::Spa is the SPA consumer adapter — a one-way projection of
+  # Ea::Model into view-shaped artifacts (Skeleton, Shard,
+  # SearchIndex, PackageTree) suitable for a browser frontend.
+  #
+  # Projection vs. modeling: the SPA does not redefine what a Class
+  # is. It owns view-shaped types that refer to model elements by
+  # id and add browsing-specific metadata (shard URLs, lazy refs,
+  # search content, navigation tree position).
+  #
+  # Output strategies (single-file vs sharded) live under
+  # Ea::Spa::Output and project the same artifacts to disk.
+  module Spa
+    autoload :SkeletonEntry, "ea/spa/skeleton_entry"
+    autoload :Skeleton, "ea/spa/skeleton"
+    autoload :PackageTreeNode, "ea/spa/package_tree_node"
+    autoload :PackageTree, "ea/spa/package_tree"
+    autoload :SearchEntry, "ea/spa/search_entry"
+    autoload :SearchIndex, "ea/spa/search_index"
+    autoload :Shard, "ea/spa/shard"
+    autoload :LazyRef, "ea/spa/lazy_ref"
+    autoload :Projector, "ea/spa/projector"
+    autoload :Output, "ea/spa/output"
+    autoload :Generator, "ea/spa/generator"
+    autoload :Configuration, "ea/spa/configuration"
+  end
+end

data/lib/ea/svg/bounds_calculator.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Ea
+  module Svg
+    # Computes the actual drawing-area bounding box of an
+    # Ea::Model::Diagram. EA stores bounds in pixel space with two
+    # quirks: element rects can be inverted (rectbottom < recttop,
+    # producing negative height), and elements/connectors can sit
+    # outside the canvas bounds. The drawing area is the union of
+    # all element rects and connector waypoint positions.
+    class BoundsCalculator
+      attr_reader :diagram
+
+      def initialize(diagram)
+        @diagram = diagram
+      end
+
+      def compute
+        points = all_points
+        return fallback_bounds if points.empty?
+
+        xs = points.map(&:first)
+        ys = points.map(&:last)
+        Bounds.new(x: xs.min, y: ys.min, width: xs.max - xs.min,
+                    height: ys.max - ys.min)
+      end
+
+      private
+
+      def all_points
+        points = []
+        diagram.elements.each do |elem|
+          next unless elem.bounds
+
+          b = normalize_bounds(elem.bounds)
+          points << [b.x, b.y]
+          points << [b.x + b.width, b.y + b.height]
+        end
+        diagram.connectors.each do |conn|
+          conn.waypoints.each do |wp|
+            next unless wp.position
+
+            points << [wp.position.x, wp.position.y]
+          end
+        end
+        points
+      end
+
+      # EA occasionally stores inverted rects (rectbottom < recttop).
+      # Normalize so width/height are non-negative.
+      def normalize_bounds(bounds)
+        x = bounds.x
+        y = bounds.y
+        w = bounds.width
+        h = bounds.height
+        x, w = x + w, -w if w.negative?
+        y, h = y + h, -h if h.negative?
+        Bounds.new(x: x, y: y, width: w, height: h)
+      end
+
+      def fallback_bounds
+        return Bounds.new(x: 0, y: 0, width: 1, height: 1) unless diagram.bounds
+
+        Bounds.new(x: diagram.bounds.x, y: diagram.bounds.y,
+                    width: diagram.bounds.width.abs,
+                    height: diagram.bounds.height.abs)
+      end
+
+      # Internal value type — keep private to avoid polluting the
+      # Ea::Svg namespace.
+      Bounds = Struct.new(:x, :y, :width, :height, keyword_init: true)
+    end
+  end
+end

data/lib/ea/svg/connector_path.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module Ea
+  module Svg
+    # Renders one DiagramConnector as an SVG <path> through its
+    # waypoints, with an arrowhead at the target end. Matches EA's
+    # convention: filled triangle for navigable associations, filled
+    # diamond for aggregations, open diamond for shared aggregations.
+    class ConnectorPath
+      ARROW_SIZE = 8
+
+      attr_reader :connector, :relationship
+
+      def initialize(connector, relationship: nil)
+        @connector = connector
+        @relationship = relationship
+      end
+
+      def render
+        points = waypoints
+        return "" if points.size < 2
+
+        path_d = build_path_d(points)
+        style = StyleResolver.new(connector.style)
+
+        parts = []
+        parts << %(<g class="connector" data-connector-id="#{escape(connector.id)}">)
+        parts << %(  <path d="#{path_d}" stroke="#{style.stroke_color}" stroke-width="#{style.stroke_width}" fill="none"/>)
+        parts << render_source_marker(points) if source_marker?
+        parts << render_target_marker(points)
+        parts << %(</g>)
+        parts.join("\n            ")
+      end
+
+      private
+
+      def waypoints
+        connector.waypoints.filter_map do |wp|
+          next unless wp.position
+
+          [wp.position.x, wp.position.y]
+        end
+      end
+
+      def build_path_d(points)
+        moves = points.each_with_index.map do |p, idx|
+          prefix = idx.zero? ? "M" : "L"
+          "#{prefix} #{p[0]} #{p[1]}"
+        end
+        moves.join(" ")
+      end
+
+      def source_marker?
+        return false unless relationship
+
+        relationship.is_a?(Ea::Model::Association) &&
+          relationship.source_aggregation != "none"
+      end
+
+      def render_source_marker(points)
+        case relationship.source_aggregation
+        when "composite" then filled_diamond(points.first, points[1])
+        when "shared" then open_diamond(points.first, points[1])
+        else ""
+        end
+      end
+
+      def render_target_marker(points)
+        filled_arrow(points.last, points[-2])
+      end
+
+      def filled_arrow(tip, base)
+        return "" unless tip && base
+
+        # Build a triangle pointing from base toward tip
+        bx, by = base
+        tx, ty = tip
+        # Perpendicular vector for the wings
+        dx = tx - bx
+        dy = ty - by
+        len = Math.sqrt(dx * dx + dy * dy)
+        return "" if len.zero?
+
+        ux = dx / len
+        uy = dy / len
+        # Wing points are ARROW_SIZE back from tip, perpendicular
+        back_x = tx - ux * ARROW_SIZE
+        back_y = ty - uy * ARROW_SIZE
+        perp_x = -uy * (ARROW_SIZE / 2.0)
+        perp_y = ux * (ARROW_SIZE / 2.0)
+        w1_x = back_x + perp_x
+        w1_y = back_y + perp_y
+        w2_x = back_x - perp_x
+        w2_y = back_y - perp_y
+        points_str = "#{tx} #{ty} #{w1_x.round(1)} #{w1_y.round(1)} #{w2_x.round(1)} #{w2_y.round(1)}"
+        %(  <polygon points="#{points_str}" fill="black" stroke="black" stroke-width="1"/>)
+      end
+
+      def filled_diamond(tip, base)
+        diamond_polygon(tip, base, fill: "black")
+      end
+
+      def open_diamond(tip, base)
+        diamond_polygon(tip, base, fill: "white")
+      end
+
+      def diamond_polygon(tip, base, fill:)
+        bx, by = base
+        tx, ty = tip
+        dx = tx - bx
+        dy = ty - by
+        len = Math.sqrt(dx * dx + dy * dy)
+        return "" if len.zero?
+
+        ux = dx / len
+        uy = dy / len
+        back_x = tx - ux * ARROW_SIZE
+        back_y = ty - uy * ARROW_SIZE
+        perp_x = -uy * (ARROW_SIZE / 2.0)
+        perp_y = ux * (ARROW_SIZE / 2.0)
+        far_x = tx - ux * (2 * ARROW_SIZE)
+        far_y = ty - uy * (2 * ARROW_SIZE)
+        w1_x = back_x + perp_x
+        w1_y = back_y + perp_y
+        w2_x = back_x - perp_x
+        w2_y = back_y - perp_y
+        points_str = "#{far_x.round(1)} #{far_y.round(1)} #{w1_x.round(1)} #{w1_y.round(1)} #{tx} #{ty} #{w2_x.round(1)} #{w2_y.round(1)}"
+        %(  <polygon points="#{points_str}" fill="#{fill}" stroke="black" stroke-width="1"/>)
+      end
+
+      def escape(text)
+        return "" if text.nil?
+
+        text.to_s.gsub("\"", "&quot;")
+      end
+    end
+  end
+end