ea 0.2.5 → 0.3.1

data/lib/ea/sources/xmi/relationship_builder.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Ea
+  module Sources
+    module Xmi
+      # Translates XMI relationship elements (uml:Association,
+      # uml:Generalization, uml:Realization, uml:Dependency) into
+      # the appropriate Ea::Model::Relationship subclass.
+      class RelationshipBuilder
+        attr_reader :root
+
+        def initialize(root)
+          @root = root
+        end
+
+        def build_all
+          relationships = []
+          walk(root.model) do |element|
+            next unless RelationshipTypeMap.relationship_type?(element.type)
+
+            rel = build_one(element)
+            relationships << rel if rel
+          end
+          relationships
+        end
+
+        def build_one(element)
+          klass = RelationshipTypeMap.class_for(element.type)
+          args = common_args(element)
+          args.merge!(specific_args_for(klass, element))
+          klass.new(**args)
+        end
+
+        private
+
+        def walk(element, &block)
+          yield element if block
+          element.packaged_element.each { |inner| walk(inner, &block) }
+        end
+
+        def common_args(element)
+          id = IdNormalizer.from_xmi_id(element.id)
+          {
+            id: id,
+            name: element.name || element.type&.split(":")&.last&.downcase,
+            qualified_name: element.name,
+            annotations: AnnotationBuilder.from_element(element, id)
+          }
+        end
+
+        def specific_args_for(klass, element)
+          case klass.name
+          when "Ea::Model::Association" then association_args(element)
+          when "Ea::Model::Generalization" then generalization_args(element)
+          when "Ea::Model::Realization" then realization_args(element)
+          when "Ea::Model::Dependency" then dependency_args(element)
+          else {}
+          end
+        end
+
+        def association_args(element)
+          ends = element.member_ends.to_a
+          source_id = ends.first&.idref
+          target_id = ends.last&.idref
+          owned_ends = element.owned_end.to_a
+          source_end = owned_ends.first
+          target_end = owned_ends.last
+          {
+            source_id: source_id,
+            target_id: target_id,
+            source_role_name: source_end&.name,
+            target_role_name: target_end&.name,
+            source_multiplicity_lower: parse_lower(source_end),
+            source_multiplicity_upper: parse_upper(source_end),
+            target_multiplicity_lower: parse_lower(target_end),
+            target_multiplicity_upper: parse_upper(target_end),
+            source_aggregation: source_end&.aggregation || "none",
+            target_aggregation: target_end&.aggregation || "none",
+            source_navigable: navigable?(source_end),
+            target_navigable: navigable?(target_end)
+          }
+        end
+
+        def generalization_args(element)
+          # PackagedElement#generalization is a collection of
+          # AssociationGeneralization rows. The "specific" (child)
+          # is the owning element; "general" (parent) is the
+          # referenced id on each generalization row.
+          gen = element.generalization.first
+          {
+            specific_id: IdNormalizer.from_xmi_id(element.id),
+            general_id: gen&.general
+          }
+        end
+
+        def realization_args(element)
+          {
+            realizing_id: element.client,
+            contract_id: element.supplier
+          }
+        end
+
+        def dependency_args(element)
+          {
+            client_id: element.client,
+            supplier_id: element.supplier
+          }
+        end
+
+        def parse_lower(end_element)
+          return 1 unless end_element
+
+          value = end_element.lower_value
+          return 1 unless value
+
+          Integer(value.value) rescue 1
+        end
+
+        def parse_upper(end_element)
+          return 1 unless end_element
+
+          value = end_element.upper_value
+          return 1 unless value
+
+          raw = value.value
+          return -1 if raw.to_s == "*"
+
+          Integer(raw) rescue 1
+        end
+
+        def navigable?(end_element)
+          return true unless end_element
+
+          # XMI represents non-navigable ends with aggregation=none
+          # and no role name; treat presence of role name or any
+          # aggregation as navigable. Default: navigable.
+          true
+        end
+      end
+    end
+  end
+end

data/lib/ea/sources/xmi/relationship_type_map.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Ea
+  module Sources
+    module Xmi
+      # Maps XMI's `xmi:type` discriminator for relationship-shaped
+      # packaged elements (uml:Association, uml:Generalization,
+      # etc.) to the concrete Ea::Model::Relationship subclass.
+      module RelationshipTypeMap
+        module_function
+
+        LOOKUP = {
+          "uml:Association" => "Ea::Model::Association",
+          "uml:Generalization" => "Ea::Model::Generalization",
+          "uml:Realization" => "Ea::Model::Realization",
+          "uml:Dependency" => "Ea::Model::Dependency",
+          "uml:Usage" => "Ea::Model::Dependency",
+          "uml:Abstraction" => "Ea::Model::Dependency",
+        }.freeze
+
+        def class_for(xmi_type)
+          name = LOOKUP[xmi_type]
+          return nil unless name
+
+          Object.const_get(name)
+        end
+
+        def relationship_type?(xmi_type)
+          LOOKUP.key?(xmi_type)
+        end
+      end
+    end
+  end
+end

data/lib/ea/sources/xmi/type_classifier_map.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Ea
+  module Sources
+    module Xmi
+      # Maps XMI's `xmi:type` discriminator on packaged elements to
+      # the concrete Ea::Model::Classifier subclass. New classifier
+      # kinds = one entry here, nothing else changes (OCP).
+      module TypeClassifierMap
+        module_function
+
+        LOOKUP = {
+          "uml:Class" => "Ea::Model::Klass",
+          "uml:DataType" => "Ea::Model::DataType",
+          "uml:PrimitiveType" => "Ea::Model::PrimitiveType",
+          "uml:Enumeration" => "Ea::Model::Enumeration",
+          "uml:Interface" => "Ea::Model::Interface",
+        }.freeze
+
+        def class_for(xmi_type)
+          name = LOOKUP[xmi_type]
+          return nil unless name
+
+          Object.const_get(name)
+        end
+
+        def classifier_type?(xmi_type)
+          LOOKUP.key?(xmi_type)
+        end
+      end
+    end
+  end
+end

data/lib/ea/sources/xmi.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Ea
+  module Sources
+    # XMI source adapter. Mirrors Ea::Sources::Qea: produces an
+    # Ea::Model::Document from a parsed Xmi::Sparx::Root by walking
+    # the UML model tree once and translating each element into the
+    # canonical model.
+    #
+    # Both adapters emit structurally identical Ea::Model instances
+    # — source format becomes irrelevant once you're in the model.
+    # That's the "single way of doing things": one pipeline, two
+    # interchangeable sources.
+    module Xmi
+      autoload :IdNormalizer, "ea/sources/xmi/id_normalizer"
+      autoload :TypeClassifierMap, "ea/sources/xmi/type_classifier_map"
+      autoload :RelationshipTypeMap, "ea/sources/xmi/relationship_type_map"
+      autoload :MetadataBuilder, "ea/sources/xmi/metadata_builder"
+      autoload :PackageBuilder, "ea/sources/xmi/package_builder"
+      autoload :ClassifierBuilder, "ea/sources/xmi/classifier_builder"
+      autoload :PropertyBuilder, "ea/sources/xmi/property_builder"
+      autoload :OperationBuilder, "ea/sources/xmi/operation_builder"
+      autoload :RelationshipBuilder, "ea/sources/xmi/relationship_builder"
+      autoload :AnnotationBuilder, "ea/sources/xmi/annotation_builder"
+      autoload :DiagramBuilder, "ea/sources/xmi/diagram_builder"
+      autoload :Adapter, "ea/sources/xmi/adapter"
+    end
+  end
+end

data/lib/ea/sources.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Ea
+  # Source adapters: translate format-specific parses (QEA SQLite,
+  # Sparx XMI) into the canonical Ea::Model::Document.
+  #
+  # Each adapter is a driving port in the hexagonal sense — its
+  # only job is to take a parsed source and emit model instances.
+  # Adapters do not know about each other or about consumer
+  # adapters (Ea::Spa, etc.).
+  module Sources
+    autoload :Qea, "ea/sources/qea"
+    autoload :Xmi, "ea/sources/xmi"
+  end
+end

data/lib/ea/spa/configuration.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Ea
+  module Spa
+    # SPA-side configuration. A YAML file with the shape:
+    #
+    #   metadata:
+    #     title: ...
+    #     description: ...
+    #     version: ...
+    #     author: ...
+    #     license: ...
+    #     homepage: ...
+    #     repository: ...
+    #   ui:
+    #     title: ...
+    #     description: ...
+    #
+    # Values under `metadata` override fields on the model's
+    # Ea::Model::Metadata. Values under `ui` (and other sections
+    # like `appearance`) are surfaced to the SPA view via the
+    # skeleton's metadata hash so the frontend can use them.
+    class Configuration
+      attr_reader :path, :data
+
+      def self.load(path)
+        return nil if path.nil? || path.empty?
+        unless File.exist?(path)
+          raise ArgumentError, "SPA config not found: #{path}"
+        end
+
+        new(path, YAML.safe_load(File.read(path)) || {})
+      end
+
+      def initialize(path, data)
+        @path = path
+        @data = data.is_a?(Hash) ? data : {}
+      end
+
+      def metadata_override
+        (@data["metadata"] || {}).transform_keys(&:to_sym)
+      end
+
+      def ui
+        @data["ui"] || {}
+      end
+
+      def appearance
+        @data["appearance"] || {}
+      end
+
+      # Diagram rendering control. Default: true (preserve historical
+      # behavior). Set `diagrams.enabled: false` in the YAML to skip
+      # diagram shards entirely — useful when the renderer output is
+      # not yet production-quality and you'd rather hide diagrams
+      # than ship broken visuals.
+      def render_diagrams?
+        diagrams_cfg = @data["diagrams"].is_a?(Hash) ? @data["diagrams"] : {}
+        enabled = diagrams_cfg.key?("enabled") ? diagrams_cfg["enabled"] : true
+        enabled != false
+      end
+
+      # Apply overrides to a model Metadata instance, returning a new
+      # one. The original is left untouched.
+      def apply_to_metadata(model_metadata)
+        return model_metadata unless model_metadata
+
+        merged = model_metadata_to_hash(model_metadata)
+                                     .merge(stringify_keys(metadata_override))
+        hash_to_metadata(merged)
+      end
+
+      # Surface the relevant config (ui, appearance, diagrams) into
+      # a hash the SPA skeleton embeds in its metadata payload so
+      # the frontend can hide its diagram UI when disabled.
+      def view_extras
+        extras = { "ui" => ui, "appearance" => appearance }
+        extras["diagrams"] = { "enabled" => render_diagrams? }
+        extras.reject { |_, v| v.nil? || v.empty? }
+      end
+
+      private
+
+      def model_metadata_to_hash(meta)
+        JSON.parse(meta.to_json)
+      end
+
+      def hash_to_metadata(hash)
+        Ea::Model::Metadata.new(
+          id: hash["id"] || "metadata",
+          title: hash["title"],
+          version: hash["version"],
+          author: hash["author"],
+          company: hash["company"],
+          created_date: hash["createdDate"],
+          modified_date: hash["modifiedDate"],
+          source_format: hash["sourceFormat"],
+          source_tool: hash["sourceTool"],
+          source_path: hash["sourcePath"]
+        )
+      end
+
+      def stringify_keys(hash)
+        hash.transform_keys(&:to_s)
+      end
+    end
+  end
+end

data/lib/ea/spa/generator.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Ea
+  module Spa
+    # Orchestrator: takes an Ea::Model::Document and an output mode,
+    # dispatches to the matching Output::Strategy. Single source of
+    # truth for which modes exist; new modes = one entry in
+    # OUTPUT_STRATEGIES.
+    class Generator
+      OUTPUT_STRATEGIES = {
+        single_file: Output::SingleFileStrategy,
+        sharded: Output::ShardedMultiFileStrategy
+      }.freeze
+
+      DEFAULT_MODE = :single_file
+
+      attr_reader :document, :mode, :output_path, :shard_url_for, :configuration
+
+      def initialize(document, output:, mode: nil, shard_url_for: nil,
+                     configuration: nil)
+        @document = document
+        @output_path = output
+        @mode = (mode || DEFAULT_MODE).to_sym
+        @shard_url_for = shard_url_for
+        @configuration = configuration
+      end
+
+      def generate
+        strategy_class.new(output_path).render(projector)
+      end
+
+      def projector
+        @projector ||= Projector.new(document,
+                                      shard_url_for: shard_url_for,
+                                      configuration: configuration)
+      end
+
+      def strategy_class
+        OUTPUT_STRATEGIES[mode] ||
+          raise(ArgumentError, "Unknown SPA mode: #{mode.inspect}. " \
+                                "Use :single_file or :sharded.")
+      end
+    end
+  end
+end

data/lib/ea/spa/lazy_ref.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Ea
+  module Spa
+    # A lazy reference: id + URL to where the full shard lives. Used
+    # in the skeleton so the frontend can fetch detail on demand
+    # rather than upfront.
+    class LazyRef < Lutaml::Model::Serializable
+      attribute :id, :string
+      attribute :url, :string
+
+      json do
+        map "id", to: :id
+        map "url", to: :url
+      end
+    end
+  end
+end

data/lib/ea/spa/output/sharded_multi_file_strategy.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Ea
+  module Spa
+    module Output
+      # Sharded layout: directory with skeleton.json, search.json,
+      # and one JSON file per entity under data/. The frontend
+      # loads skeleton + search upfront and fetches shards on
+      # demand. This is the layout for large models.
+      class ShardedMultiFileStrategy < Strategy
+        def render(projector)
+          FileUtils.mkdir_p(output_path)
+          FileUtils.mkdir_p(File.join(output_path, "data"))
+
+          skeleton = projector.skeleton
+          write_json(File.join(output_path, "skeleton.json"), skeleton)
+          write_json(File.join(output_path, "search.json"),
+                     projector.search_index)
+          write_shards(projector)
+          write_index_html(skeleton)
+
+          output_path
+        end
+
+        private
+
+        def write_shards(projector)
+          projector.each_shard.each do |shard|
+            path = File.join(output_path, "data", pluralize(shard.kind),
+                             "#{shard.id}.json")
+            write_json(path, shard)
+          end
+        end
+
+        def pluralize(kind)
+          case kind
+          when "class" then "classes"
+          when "property" then "properties"
+          else "#{kind}s"
+          end
+        end
+
+        def write_index_html(skeleton)
+          title = skeleton.view_extras&.dig("ui", "title") ||
+                  skeleton.metadata&.fetch("title", nil) ||
+                  "Ea::Spa"
+          File.write(File.join(output_path, "index.html"), <<~HTML)
+            <!DOCTYPE html>
+            <html lang="en">
+            <head>
+              <meta charset="UTF-8">
+              <meta name="viewport" content="width=device-width, initial-scale=1.0">
+              <title>#{title}</title>
+            </head>
+            <body>
+              <div id="app"></div>
+              <script>
+              window.__SPA_SKELETON_URL__ = 'skeleton.json';
+              window.__SPA_SEARCH_URL__ = 'search.json';
+              window.__SPA_SHARD_BASE__ = 'data/';
+              </script>
+            </body>
+            </html>
+          HTML
+        end
+      end
+    end
+  end
+end

data/lib/ea/spa/output/single_file_strategy.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Ea
+  module Spa
+    module Output
+      # Embeds skeleton + search + every shard in one HTML file
+      # (data inlined as a JSON blob). Suitable for small models
+      # only; not appropriate when shard count or total payload is
+      # large.
+      class SingleFileStrategy < Strategy
+        def render(projector)
+          FileUtils.mkdir_p(File.dirname(output_path))
+
+          skeleton = projector.skeleton
+          payload = {
+            metadata: skeleton.metadata,
+            packageTree: skeleton.package_tree,
+            skeletonEntries: skeleton.entries,
+            searchIndex: projector.search_index,
+            shards: projector.each_shard.to_a
+          }
+          payload[:viewExtras] = skeleton.view_extras unless skeleton.view_extras.nil? || skeleton.view_extras.empty?
+
+          File.write(output_path, build_html(payload))
+          output_path
+        end
+
+        private
+
+        def build_html(payload)
+          title = payload.dig(:viewExtras, "ui", "title") ||
+                  payload[:metadata]&.fetch("title", nil) ||
+                  "Ea::Spa"
+          <<~HTML
+            <!DOCTYPE html>
+            <html lang="en">
+            <head>
+              <meta charset="UTF-8">
+              <meta name="viewport" content="width=device-width, initial-scale=1.0">
+              <title>#{title}</title>
+            </head>
+            <body>
+              <div id="app"></div>
+              <script>
+              window.__SPA_DATA__ = #{payload.to_json};
+              </script>
+            </body>
+            </html>
+          HTML
+        end
+      end
+    end
+  end
+end

data/lib/ea/spa/output/strategy.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Ea
+  module Spa
+    module Output
+      # Abstract output strategy. Concrete subclasses project the
+      # same SPA artifacts (skeleton, search index, shards) to disk
+      # in different layouts.
+      #
+      # Adding a new layout = new subclass + registration in
+      # Generator::OUTPUT_STRATEGIES. No edit to Projector or
+      # existing strategies.
+      class Strategy
+        SIZE_THRESHOLD_BYTES = 2 * 1024 * 1024 # 2 MB
+
+        attr_reader :output_path
+
+        def initialize(output_path)
+          @output_path = output_path
+        end
+
+        def render(_projector)
+          raise NotImplementedError,
+                "#{self.class} must implement #render"
+        end
+
+        private
+
+        def write_json(path, data)
+          FileUtils.mkdir_p(File.dirname(path))
+          File.write(path, data.to_json)
+        end
+      end
+    end
+  end
+end

data/lib/ea/spa/output.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Ea
+  module Spa
+    module Output
+      autoload :Strategy, "ea/spa/output/strategy"
+      autoload :SingleFileStrategy, "ea/spa/output/single_file_strategy"
+      autoload :ShardedMultiFileStrategy, "ea/spa/output/sharded_multi_file_strategy"
+    end
+  end
+end

data/lib/ea/spa/package_tree.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Ea
+  module Spa
+    class PackageTree < Lutaml::Model::Serializable
+      attribute :root_ids, :string, collection: true, initialize_empty: true
+      attribute :nodes, PackageTreeNode, collection: true, initialize_empty: true
+
+      json do
+        map "rootIds", to: :root_ids, render_empty: true
+        map "nodes", to: :nodes, render_empty: true
+      end
+    end
+  end
+end

data/lib/ea/spa/package_tree_node.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Ea
+  module Spa
+    # One node in the SPA's package navigation tree. References
+    # sub-packages and classifiers by id — the frontend resolves
+    # them via the skeleton index.
+    class PackageTreeNode < Lutaml::Model::Serializable
+      attribute :id, :string
+      attribute :name, :string
+      attribute :parent_id, :string
+      attribute :child_ids, :string, collection: true, initialize_empty: true
+      attribute :classifier_ids, :string, collection: true, initialize_empty: true
+      attribute :diagram_ids, :string, collection: true, initialize_empty: true
+
+      json do
+        map "id", to: :id
+        map "name", to: :name
+        map "parentId", to: :parent_id
+        map "childIds", to: :child_ids, render_empty: true
+        map "classifierIds", to: :classifier_ids, render_empty: true
+        map "diagramIds", to: :diagram_ids, render_empty: true
+      end
+    end
+  end
+end