ea 0.4.0 → 0.5.1

data/lib/ea/export/json_schema.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ea
+  module Export
+    # JSON Schema (draft 2020-12) export namespace.
+    module JsonSchema
+      autoload :Generator, "ea/export/json_schema/generator"
+    end
+  end
+end

data/lib/ea/export/plantuml/generator.rb

@@ -0,0 +1,140 @@
+# frozen_string: true
+
+module Ea
+  module Export
+    module PlantUml
+      # Generates PlantUML class diagram text from a parsed QEA model.
+      #
+      # Emits:
+      # - Package nesting (`package "X" { ... }`)
+      # - Class declarations with attributes and operations
+      # - Generalizations (`Parent <|-- Child`)
+      # - Associations with multiplicities and role names
+      # - Enumerations as `enum` blocks
+      class Generator
+        def self.call(model, **_opts)
+          new(model).call
+        end
+
+        attr_reader :model
+
+        def initialize(model)
+          @model = model
+        end
+
+        def call
+          lines = ["@startuml", "skinparam classAttributeIconSize 0"]
+          lines.concat(package_lines)
+          lines.concat(connector_lines)
+          lines << "@enduml"
+          lines.join("\n") + "\n"
+        end
+
+        private
+
+        # Wrap classes/enums in their containing packages.
+        def package_lines
+          packages_by_id = packages_index
+          root_objects = (model.collections[:objects] || [])
+
+          # Group classes by their package_id; emit each package.
+          grouped = root_objects.group_by(&:package_id)
+          grouped.flat_map do |pkg_id, objs|
+            next ungrouped_lines(objs) if pkg_id.nil?
+
+            pkg = packages_by_id[pkg_id]
+            pkg_name = pkg&.name || "Package#{pkg_id}"
+            inner = objs.flat_map { |o| class_block(o) }
+            next inner if inner.empty?
+
+            ["package \"#{pkg_name}\" {",
+             *inner.map { |line| "  #{line}" },
+             "}"]
+          end.compact
+        end
+
+        def ungrouped_lines(objs)
+          objs.flat_map { |o| class_block(o) }
+        end
+
+        # Emit `class X { +attr: T ... }` or `enum X { LITERAL1 ... }`.
+        def class_block(obj)
+          case obj.object_type
+          when "Class"
+            attrs = class_attributes(obj)
+            body = attrs.map { |a| "+#{a.name}: #{a.type || 'String'}" }
+            return ["class #{obj.name}"] if body.empty?
+
+            ["class #{obj.name} {", *body.map { |b| "  #{b}" }, "}"]
+          when "Enumeration"
+            literals = enum_literals(obj)
+            return ["enum #{obj.name}"] if literals.empty?
+
+            ["enum #{obj.name} {",
+             *literals.map { |l| "  #{l.name || l}" },
+             "}"]
+          when "Interface"
+            ["interface #{obj.name}"]
+          when "DataType"
+            ["abstract class #{obj.name}"]
+          else
+            ["class #{obj.name}"]
+          end
+        end
+
+        # Generalizations: `<|`-style inheritance.
+        # Associations: multiplicity + role names.
+        def connector_lines
+          (model.collections[:connectors] || []).filter_map do |conn|
+            src = find_object(conn.start_object_id)
+            tgt = find_object(conn.end_object_id)
+            next nil unless src && tgt
+
+            case conn.connector_type
+            when "Generalization"
+              "#{tgt.name} <|-- #{src.name}"
+            when "Association", "Aggregation", "Composition"
+              assoc_arrow(src, tgt, conn)
+            else
+              label = conn.name ? " : #{conn.name}" : ""
+              "#{src.name} --> #{tgt.name}#{label}"
+            end
+          end
+        end
+
+        def assoc_arrow(src, tgt, conn)
+          arrow = case conn.connector_type
+                  when "Composition" then "*--"
+                  when "Aggregation" then "o--"
+                  else "--"
+                  end
+          label = conn.name ? " : #{conn.name}" : ""
+          "#{src.name} #{arrow} #{tgt.name}#{label}"
+        end
+
+        def packages_index
+          (model.collections[:packages] || []).each_with_object({}) do |p, acc|
+            acc[p.package_id] = p
+          end
+        end
+
+        def class_attributes(klass)
+          attrs = model.collections[:attributes] || []
+          attrs.select { |a| a.ea_object_id == klass.ea_object_id }
+        end
+
+        def enum_literals(enum)
+          literals = model.collections[:enumeration_literals] ||
+                     model.collections[:enum_literals] || []
+          # Enumeration literals are linked to the enum via object_id.
+          literals.select { |l| l.respond_to?(:ea_object_id) && l.ea_object_id == enum.ea_object_id }
+        end
+
+        def find_object(object_id)
+          (model.collections[:objects] || [])
+            .find { |o| o.ea_object_id == object_id || o.object_id == object_id }
+        end
+      end
+    end
+  end
+end

data/lib/ea/export/plantuml.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Ea
+  module Export
+    # PlantUML text-format exporter. Produces a `.puml` file
+    # documenting the model's classes, attributes, and relationships
+    # in PlantUML syntax (rendered by plantuml.com/plantuml).
+    module PlantUml
+      autoload :Generator, "ea/export/plantuml/generator"
+    end
+  end
+end

data/lib/ea/export/xsd/class_mapping.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module Ea
+  module Export
+    module Xsd
+      # Loads EA's GMLClassMapping.xml and exposes per-class mapping
+      # rules: UML class name → GML element/type/propertyType names.
+      #
+      # XML format:
+      #   <ClassMapping>
+      #     <Class name="FeatureType" element="featureMember"
+      #           type="FeaturePropertyType" propertyType="..."
+      #           typeContent="complex"/>
+      #   </ClassMapping>
+      class ClassMapping
+        attr_reader :mappings
+
+        # @param mappings [Hash{String => Mapping}] keyed by UML class name
+        def initialize(mappings = {})
+          @mappings = mappings
+        end
+
+        Mapping = Struct.new(:name, :element, :type, :property_type,
+                             :type_content, keyword_init: true)
+
+        # @param path [String] path to GMLClassMapping.xml
+        # @return [ClassMapping]
+        def self.from_path(path)
+          return new if path.nil? || !File.exist?(path)
+
+          from_nokogiri(Nokogiri::XML(File.read(path)))
+        end
+
+        # @param doc [Nokogiri::XML::Document]
+        # @return [ClassMapping]
+        def self.from_nokogiri(doc)
+          mappings = {}
+          doc.xpath("//Class").each do |node|
+            name = node["name"]
+            next unless name
+
+            mappings[name] = Mapping.new(
+              name: name,
+              element: node["element"],
+              type: node["type"],
+              property_type: node["propertyType"],
+              type_content: node["typeContent"]
+            )
+          end
+          new(mappings)
+        end
+
+        # Look up a mapping by UML class name. Returns nil when no
+        # explicit mapping exists.
+        # @param class_name [String]
+        # @return [Mapping, nil]
+        def for(class_name)
+          mappings[class_name]
+        end
+      end
+    end
+  end
+end

data/lib/ea/export/xsd/generator.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module Ea
+  module Export
+    module Xsd
+      # Generates an XSD schema string from a parsed QEA model.
+      #
+      # Pure: takes already-loaded ClassMapping and NamespaceRegistry
+      # instances. No file IO, no fixture-path coupling. The CLI
+      # layer is responsible for loading GMLClassMapping.xml and
+      # GMLNamespaces.xml from disk.
+      class Generator
+        XSD_NS = "http://www.w3.org/2001/XMLSchema"
+
+        attr_reader :class_mapping, :namespaces
+
+        # @param class_mapping [ClassMapping] type translation rules
+        # @param namespaces [NamespaceRegistry] namespace declarations
+        def initialize(class_mapping: ClassMapping.new,
+                       namespaces: NamespaceRegistry.new)
+          @class_mapping = class_mapping
+          @namespaces = namespaces
+        end
+
+        # Class-method shortcut. Accepts the same options as #initialize
+        # via keyword args.
+        def self.call(model, target_namespace: "http://example.com/xsd",
+                      prefix: "tns", **opts)
+          new(**opts).call(model, target_namespace: target_namespace, prefix: prefix)
+        end
+
+        # Generate an XSD schema for the given model.
+        # @param model [#collections] anything responding to #collections
+        #   with a :packages and :objects collection (Ea::Qea::Database).
+        # @param target_namespace [String] XSD targetNamespace
+        # @param prefix [String] namespace prefix for the target
+        # @return [String] serialized XSD
+        def call(model, target_namespace:, prefix: "tns")
+          doc = build_schema_doc(target_namespace, prefix)
+          walk_model(model, doc)
+          doc.to_xml(indent: 2)
+        end
+
+        private
+
+        def build_schema_doc(target_namespace, prefix)
+          builder = Nokogiri::XML::Builder.new do |xml|
+            xml.schema("xmlns" => XSD_NS,
+                       "xmlns:#{prefix}" => target_namespace,
+                       "targetNamespace" => target_namespace,
+                       "elementFormDefault" => "qualified")
+          end
+          builder.doc
+        end
+
+        def walk_model(model, doc)
+          classes = model_classes(model)
+          classes.each { |klass| emit_class(doc, doc.root, klass) }
+        end
+
+        # Extract UML-like classes from the model. Ea::Qea::Database
+        # stores them in :objects; we filter to classes (Object_Type
+        # == "Class") and emit a struct for the generator's needs.
+        Classifier = Struct.new(:name, :stereotype, :attributes,
+                                keyword_init: true)
+
+        def model_classes(model)
+          objects = model.collections[:objects] || []
+          objects.select { |o| o.object_type == "Class" }.map do |obj|
+            Classifier.new(
+              name: obj.name,
+              stereotype: stereotype_for(model, obj),
+              attributes: attributes_for(model, obj)
+            )
+          end
+        end
+
+        def stereotype_for(model, obj)
+          # Walk t_xref for the object's GUID; pick first @STEREO.
+          xrefs = model.collections[:xrefs] || []
+          stereo_xref = xrefs.find do |xr|
+            xr.client == obj.ea_guid && xr.description&.include?("@STEREO")
+          end
+          return nil unless stereo_xref
+
+          match = stereo_xref.description.match(/Name=([^;]+)/)
+          match ? match[1] : nil
+        end
+
+        def attributes_for(model, obj)
+          attrs = model.collections[:attributes] || []
+          attrs.select { |a| a.object_id == obj.object_id }
+               .map { |a| { name: a.name, type: a.type || "string" } }
+        end
+
+        def emit_class(doc, schema_root, classifier)
+          mapping = class_mapping.for(classifier.name) ||
+                    class_mapping.for(classifier.stereotype.to_s)
+
+          type_name = mapping&.type || "#{classifier.name}Type"
+          element_name = mapping&.element || classifier.name&.downcase
+
+          schema_root.add_child(element_node(doc, element_name, type_name))
+          schema_root.add_child(complex_type_node(doc, type_name, classifier))
+        end
+
+        def element_node(doc, name, type_name)
+          el = doc.create_element("element", "xmlns" => XSD_NS)
+          el["name"] = name
+          el["type"] = "tns:#{type_name}"
+          el
+        end
+
+        def complex_type_node(doc, type_name, classifier)
+          ct = doc.create_element("complexType", "xmlns" => XSD_NS)
+          ct["name"] = type_name
+          seq = doc.create_element("sequence", "xmlns" => XSD_NS)
+          classifier.attributes.each do |attr|
+            seq.add_child(attribute_element(doc, attr))
+          end
+          ct.add_child(seq)
+          ct
+        end
+
+        def attribute_element(doc, attr)
+          el = doc.create_element("element", "xmlns" => XSD_NS)
+          el["name"] = attr[:name].to_s
+          el["type"] = "xs:string"
+          el["minOccurs"] = "0"
+          el
+        end
+      end
+    end
+  end
+end

data/lib/ea/export/xsd/namespace_registry.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module Ea
+  module Export
+    module Xsd
+      # Loads EA's GMLNamespaces.xml and exposes per-prefix namespace
+      # declarations: prefix → { target_namespace:, xsd_document: }.
+      #
+      # XML format:
+      #   <Namespaces>
+      #     <GMLNS version="3.2.1">
+      #       <Namespace xmlns="gml" targetNamespace="http://..."
+      #                  xsdDocument="http://.../gml.xsd"/>
+      #     </GMLNS>
+      #   </Namespaces>
+      class NamespaceRegistry
+        attr_reader :namespaces
+
+        # @param namespaces [Hash{String => Namespace}]
+        def initialize(namespaces = {})
+          @namespaces = namespaces
+        end
+
+        Namespace = Struct.new(:prefix, :target_namespace, :xsd_document,
+                               :version, keyword_init: true)
+
+        # @param path [String] path to GMLNamespaces.xml
+        # @param version [String, nil] GML version filter (e.g. "3.2.1")
+        # @return [NamespaceRegistry]
+        def self.from_path(path, version: nil)
+          return new if path.nil? || !File.exist?(path)
+
+          from_nokogiri(Nokogiri::XML(File.read(path)), version: version)
+        end
+
+        # @param doc [Nokogiri::XML::Document]
+        # @param version [String, nil] GML version filter
+        # @return [NamespaceRegistry]
+        def self.from_nokogiri(doc, version: nil)
+          namespaces = {}
+          # EA stores the prefix in a `xmlns` attribute, which XML
+          # reserves for namespace declarations. Nokogiri interprets
+          # it as the element's namespace, so we read it back via
+          # `namespace` (the parsed NS) rather than `attribute`.
+          # Use local-name() so the lookup is namespace-agnostic.
+          doc.xpath("//*[local-name()='GMLNS']").each do |gmlns|
+            next if version && gmlns["version"] != version
+
+            gmlns.element_children.each do |node|
+              next unless node.name == "Namespace"
+
+              prefix = node.namespace&.href
+              next unless prefix
+
+              namespaces[prefix] = Namespace.new(
+                prefix: prefix,
+                target_namespace: node["targetNamespace"],
+                xsd_document: node["xsdDocument"],
+                version: gmlns["version"]
+              )
+            end
+          end
+          new(namespaces)
+        end
+
+        # @param prefix [String]
+        # @return [Namespace, nil]
+        def for(prefix)
+          namespaces[prefix]
+        end
+
+        # All distinct versions present (e.g. ["3.2.1", "3.3"]).
+        # @return [Array<String>]
+        def versions
+          namespaces.values.map(&:version).compact.uniq
+        end
+      end
+    end
+  end
+end

data/lib/ea/export/xsd.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Ea
+  module Export
+    # XSD (XML Schema Definition) export namespace.
+    #
+    # Translates a parsed QEA/UML model into an XSD schema by:
+    # 1. Reading GMLClassMapping.xml to learn how UML classes map to
+    #    GML types (element/type/propertyType names).
+    # 2. Reading GMLNamespaces.xml to learn target namespaces.
+    # 3. Walking the model's classes and emitting `<xs:element>` +
+    #    `<xs:complexType>` declarations for each.
+    module Xsd
+      autoload :ClassMapping, "ea/export/xsd/class_mapping"
+      autoload :NamespaceRegistry, "ea/export/xsd/namespace_registry"
+      autoload :Generator, "ea/export/xsd/generator"
+    end
+  end
+end

data/lib/ea/export.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Ea
+  # Export namespace — format-specific exporters (XSD, PlantUML, etc.).
+  # One sub-namespace per output format; each is independent and
+  # autoloadable.
+  module Export
+    autoload :Json, "ea/export/json"
+    autoload :JsonSchema, "ea/export/json_schema"
+    autoload :PlantUml, "ea/export/plantuml"
+    autoload :Xsd, "ea/export/xsd"
+  end
+end

data/lib/ea/image/emf_renderer.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Ea
+  module Image
+    # Converts EA's t_image EMF blobs to SVG strings by delegating to
+    # the pure-Ruby `emfsvg` gem. Lazy-loads the gem on first call.
+    #
+    # When emfsvg is unavailable, returns nil — callers should fall
+    # back to skipping image rendering. This keeps the gem optional
+    # rather than a hard runtime requirement.
+    module EmfRenderer
+      module_function
+
+      # Convert an EMF blob (raw bytes) to an SVG string.
+      #
+      # @param bytes [String, nil] EMF binary blob from t_image.Image
+      # @param options [Hash] forwarded to Emfsvg.from_bytes
+      # @return [String, nil] SVG markup, or nil if emfsvg unavailable
+      def render(bytes, **options)
+        return nil if bytes.nil? || bytes.empty?
+        return nil unless available?
+
+        Emfsvg.from_bytes(bytes, **options)
+      rescue StandardError => e
+        warn "[ea] emfsvg render failed: #{e.message}" if ENV["EA_DEBUG"]
+        nil
+      end
+
+      # @return [Boolean] true if the emfsvg gem can be loaded
+      def available?
+        return @available if defined?(@available)
+
+        begin
+          require "emfsvg"
+          @available = !!Emfsvg
+        rescue LoadError
+          @available = false
+        end
+      end
+    end
+  end
+end

data/lib/ea/image.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Ea
+  # Image rendering namespace. Converts EA's t_image EMF blobs to SVG.
+  #
+  # The emfsvg gem is an OPTIONAL runtime dependency. If it isn't
+  # loadable, callers degrade gracefully (image is skipped). This
+  # keeps the ea gem usable without forcing emfsvg on every install.
+  module Image
+    autoload :EmfRenderer, "ea/image/emf_renderer"
+  end
+end

data/lib/ea/lint/engine.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Ea
+  module Lint
+    # Runs all registered rules against a model and collects offenses.
+    # Adding a rule = adding it to DEFAULT_RULES (OCP).
+    class Engine
+      attr_reader :rules
+
+      DEFAULT_RULES = [
+        Rules::NamingConventionRule,
+        Rules::OrphanElementRule,
+        Rules::DuplicateNameRule,
+        Rules::CyclicGeneralizationRule,
+        Rules::MissingStereotypeRule
+      ].freeze
+
+      # @param rules [Array<Class>] LintRule subclasses
+      def initialize(rules: DEFAULT_RULES)
+        @rules = rules
+      end
+
+      # @param model [#collections]
+      # @return [Array<Offense>]
+      def run(model)
+        @rules.flat_map { |rule_class| rule_class.new.check(model) }
+      end
+    end
+  end
+end

data/lib/ea/lint/lint_rule.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Ea
+  module Lint
+    # Base class for lint rules. Subclasses implement #check(model)
+    # and return an Array<Offense>. Default severity is :warning;
+    # subclasses can override via `self.severity`.
+    class LintRule
+      class << self
+        attr_accessor :severity
+      end
+
+      def self.name
+        to_s.split("::").last.gsub(/Rule\z/, "").gsub(/([a-z])([A-Z])/, '\1_\2').downcase
+      end
+
+      def self.severity
+        @severity || :warning
+      end
+
+      def check(_model)
+        raise NotImplementedError, "#{self.class}#check not implemented"
+      end
+
+      protected
+
+      def offense(entity_id:, entity_name:, message:, severity: nil)
+        Offense.new(
+          rule: self.class.name,
+          severity: severity || self.class.severity,
+          entity_id: entity_id,
+          entity_name: entity_name,
+          message: message
+        )
+      end
+    end
+  end
+end

data/lib/ea/lint/offense.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Ea
+  module Lint
+    # One lint offense. Carries rule name, severity, entity id/name,
+    # and a human-readable message.
+    Offense = Struct.new(:rule, :severity, :entity_id, :entity_name,
+                         :message, keyword_init: true) do
+      def error?
+        severity == :error
+      end
+
+      def warning?
+        severity == :warning
+      end
+    end
+  end
+end

data/lib/ea/lint/rules/cyclic_generalization.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Ea
+  module Lint
+    module Rules
+      # Detects cyclic generalization chains (A → B → A).
+      class CyclicGeneralizationRule < LintRule
+        self.severity = :error
+
+        def check(model)
+          graph = build_graph(model)
+          cycles = find_cycles(graph)
+          cycles.map do |cycle|
+            offense(entity_id: cycle.first,
+                    entity_name: cycle.join(" → "),
+                    message: "Cyclic generalization: #{cycle.join(' → ')} → #{cycle.first}")
+          end
+        end
+
+        private
+
+        def build_graph(model)
+          graph = {}
+          (model.collections[:connectors] || []).each do |conn|
+            next unless conn.connector_type == "Generalization"
+
+            from = conn.start_object_id
+            to = conn.end_object_id
+            graph[from] ||= []
+            graph[from] << to
+          end
+          graph
+        end
+
+        def find_cycles(graph)
+          cycles = []
+          visited = Set.new
+
+          graph.each_key do |start|
+            next if visited.include?(start)
+
+            dfs(graph, start, [start], Set.new([start]), cycles, visited)
+          end
+          cycles
+        end
+
+        def dfs(graph, node, path, on_path, cycles, visited)
+          (graph[node] || []).each do |neighbor|
+            if on_path.include?(neighbor)
+              idx = path.index(neighbor)
+              cycles << path[idx..] + [neighbor] if idx
+            elsif !visited.include?(neighbor)
+              dfs(graph, neighbor, path + [neighbor],
+                  on_path + [neighbor], cycles, visited)
+            end
+          end
+          visited.add(node)
+        end
+      end
+    end
+  end
+end