ea 0.2.5 → 0.3.0

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,96 @@
+# 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
+
+      # 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) into a hash the
+      # SPA skeleton embeds in its metadata payload.
+      def view_extras
+        { "ui" => ui, "appearance" => appearance }.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

data/lib/ea/spa/projector.rb

@@ -0,0 +1,194 @@
+# 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.
+      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) }
+      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