ea 0.1.0 → 0.1.4

data/lib/ea/transformers/qea_to_xmi/guid_format.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Ea
+  module Transformers
+    module QeaToXmi
+      # Pure conversions between Sparx EA GUID strings and XMI identifier
+      # strings. No state, no I/O — same input always yields same output.
+      #
+      # EA stores identifiers as `{ABCD-1234-...}` braced GUID strings. XMI
+      # serializations use unbraced, dash→underscore forms prefixed with
+      # `EAID_` (most elements) or `EAPK_` (packages at the model root).
+      module GuidFormat
+        # Braces and dashes both become underscores; collapse runs of
+        # consecutive underscores so `{AB-CD}` → `AB_CD` (not `_AB_CD_`).
+        SEP = /[-{}]/
+
+        module_function
+
+        # @param ea_guid [String, nil] e.g. "{AB-CD-EF}"
+        # @param prefix [String] "EAID" (default) or "EAPK"
+        # @return [String, nil] e.g. "EAID_AB_CD_EF"
+        def ea_guid_to_xmi_id(ea_guid, prefix: "EAID")
+          return nil if ea_guid.nil? || ea_guid.empty?
+
+          clean = ea_guid.gsub(SEP, "_").gsub(/_+/, "_").gsub(/\A_/, "").gsub(/_\z/, "")
+          "#{prefix}_#{clean}"
+        end
+
+        # @param xmi_id [String, nil] e.g. "EAID_AB_CD_EF"
+        # @return [String, nil] e.g. "{AB-CD-EF}"
+        def xmi_id_to_ea_guid(xmi_id)
+          return nil if xmi_id.nil? || xmi_id.empty?
+
+          body = xmi_id.sub(/\A(?:EAID|EAPK)_/, "")
+          "{#{body.tr('_', '-')}}"
+        end
+
+        # Build a member-end xmi:id for one side of a connector.
+        #
+        # Sparx EA's convention: take the connector's GUID, drop the first two
+        # hex characters of its first segment, and prepend `src` or `dst`.
+        #
+        # @param connector_xmi_id [String] e.g. "EAID_AB12CDEF_..."
+        # @param side [Symbol] :source or :destination
+        # @return [String] e.g. "EAID_src2CDEF_..."
+        def connector_end_xmi_id(connector_xmi_id, side:)
+          tag = side == :source ? "src" : "dst"
+          body = connector_xmi_id.sub(/\A(?:EAID|EAPK)_/, "")
+          first_segment, rest = body.split("_", 2)
+          trimmed = first_segment.length > 2 ? first_segment[2..] : first_segment
+          rest ? "EAID_#{tag}#{trimmed}_#{rest}" : "EAID_#{tag}#{trimmed}"
+        end
+      end
+    end
+  end
+end

data/lib/ea/transformers/qea_to_xmi/id_allocator.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Ea
+  module Transformers
+    module QeaToXmi
+      # Allocates synthetic xmi:id values for elements that don't have a
+      # natural GUID-based one — e.g. literal `<lowerValue>` nodes, or
+      # `<ownedComment>` bodies synthesized from EA's Note objects.
+      #
+      # Sparx's EAID format reserves prefixes like `LI` (LiteralInt),
+      # `SL` (Slot), `NL` (NameLabel), `DB` (DiagramBounds), `OE` (OpaqueExpr),
+      # `RT` (Return parameter) for these synthesized identifiers.
+      #
+      # Output shape: `EAID_<PREFIX><NNNNNN><GUID_TAIL>` where:
+      #
+      # - `EAID_` matches the prefix used by all other Sparx XMI element IDs.
+      # - `<PREFIX>` is a Sparx-reserved literal prefix (LI, SL, OE, ...).
+      # - `<NNNNNN>` is a 6-digit zero-padded counter, scoped to the
+      #   IdAllocator instance (one per `Transformer#serialize` call).
+      # - `<GUID_TAIL>` is the parent element's EA GUID normalised to
+      #   Sparx's wire form. The leading underscore from the opening
+      #   brace of `{GUID-...}` is preserved so the output matches
+      #   real Sparx XMI byte-for-byte (e.g. `EAID_LI000001__EEB1_...`).
+      #   When `parent_guid` is nil, no tail is emitted.
+      #
+      # The allocator is memoised by `seed`: same seed returns the same
+      # allocated ID. Different seeds get different counters.
+      class IdAllocator
+        # Well-known prefixes Sparx uses for synthesized IDs.
+        LITERAL_INTEGER   = "LI"
+        OPAQUE_EXPRESSION = "OE"
+        SLOT              = "SL"
+        NAME_LABEL        = "NL"
+        DIAGRAM_BOUNDS    = "DB"
+        RETURN_PARAMETER  = "RT"
+
+        # Leading-underscore-preserving normalisation: `{AB-CD}` → `_AB_CD`.
+        # Matches the wire form Sparx emits for parent-guid-suffixed IDs.
+        GUID_BRACE_OR_DASH = /[-{}]/
+
+        def initialize
+          @counter = 0
+          @assigned = {}
+        end
+
+        # @param prefix [String] one of LITERAL_INTEGER, OPAQUE_EXPRESSION, ...
+        # @param seed [String, nil] stable seed for memoization (e.g. the
+        #   source record's object_id). Same seed returns same allocated id.
+        # @param parent_guid [String, nil] the owning element's EA GUID
+        #   (e.g. `{EEB1-...}`). When provided, the synthesised ID carries
+        #   the parent GUID tail so it is traceable and round-trip-safe.
+        # @return [String] e.g. "EAID_LI000001__EEB1_4de7_98F5_670D6EE4A52B"
+        def allocate(prefix:, seed: nil, parent_guid: nil)
+          return @assigned[seed] if seed && @assigned.key?(seed)
+
+          @counter += 1
+          id = compose_id(prefix: prefix, n: @counter, parent_guid: parent_guid)
+          @assigned[seed] = id if seed
+          id
+        end
+
+        private
+
+        def compose_id(prefix:, n:, parent_guid:)
+          tail = guid_tail(parent_guid)
+          if tail
+            # The format is `EAID_LI<NN>_<guid_tail>` where guid_tail
+            # preserves its leading underscore. Together with the
+            # separator `_` that yields the double-underscore form
+            # Sparx emits (`EAID_LI000001__EEB1_...`).
+            format("EAID_%<prefix>s%<n>06d_%<tail>s", prefix: prefix, n: n, tail: tail)
+          else
+            format("EAID_%<prefix>s%<n>06d", prefix: prefix, n: n)
+          end
+        end
+
+        # Sparx preserves the leading underscore that comes from the
+        # opening brace of the EA GUID. Strip the closing-brace trailing
+        # underscore only.
+        #
+        # `{EEB1-4de7-98F5-670D6EE4A52B}` → `_EEB1_4de7_98F5_670D6EE4A52B`
+        def guid_tail(parent_guid)
+          return nil if parent_guid.nil? || parent_guid.empty?
+
+          parent_guid
+            .gsub(GUID_BRACE_OR_DASH, "_")
+            .sub(/_\z/, "")
+        end
+      end
+    end
+  end
+end

data/lib/ea/transformers/qea_to_xmi/run_state.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "strscan"
+
+module Ea
+  module Transformers
+    module QeaToXmi
+      # Pure-function parser for EA's RunState column on `t_object`.
+      #
+      # EA serialises instance-specification run-state as a delimited
+      # string of the form:
+      #
+      #   @VAR;Variable=<name>;Value=<value>;Op=<op>;@ENDVAR;
+      #
+      # Multiple variables concatenate directly:
+      #
+      #   @VAR;Variable=a;Value=1;Op==;@ENDVAR;@VAR;Variable=b;Value=2;Op==;@ENDVAR;
+      #
+      # Each `@VAR ... @ENDVAR;` block maps to one UML Slot. The
+      # `Variable` is the attribute name on the classifier (used to
+      # resolve the definingFeature EAID at transformation time).
+      # The `Value` plus `Op` form the OpaqueExpression body — Sparx
+      # prepends the operator character to the value (`Op==` →
+      # `body="=Value"`).
+      #
+      # The parser is pure: no I/O, no state. Same input always yields
+      # the same output array of {Variable, Value, Op} structs.
+      module RunState
+        # A single parsed RunState variable binding.
+        #
+        # @!attribute variable [String] the attribute name on the classifier
+        # @!attribute value [String] the literal value text
+        # @!attribute op [String] the operator character(s) EA stored
+        Binding = Struct.new(:variable, :value, :op) do
+          # Sparx serialises the value with the operator character
+          # prepended (`Op==` → `body="=Value"`). For other operators
+          # (`!=`, `<`, `>`) the full operator string is prepended.
+          #
+          # @return [String] the body to set on the OpaqueExpression
+          def body
+            return value if op.nil? || op.empty?
+
+            "#{op[0]}#{value}"
+          end
+        end
+
+        module_function
+
+        # @param raw [String, nil] the EA RunState column content
+        # @return [Array<Binding>] one Binding per @VAR block; empty
+        #   array for nil/empty/blank input.
+        def parse(raw)
+          return [] if raw.nil? || raw.to_s.strip.empty?
+
+          stripped = raw.to_s
+          each_var_block(stripped).map do |block|
+            parse_binding(block)
+          end
+        end
+
+        # ---- Internal helpers ----
+
+        # Yields each `@VAR;...;@ENDVAR;` block body (without the
+        # delimiters). Tolerant of multiple blocks concatenated
+        # without separation.
+        def each_var_block(raw)
+          return enum_for(:each_var_block, raw) unless block_given?
+
+          scanner = StringScanner.new(raw)
+          until scanner.eos?
+            scanner.scan_until(/@VAR;/) || break
+            body = scanner.scan_until(/@ENDVAR;/)
+            break if body.nil?
+
+            yield body.sub(/@ENDVAR;\z/, "")
+          end
+        end
+
+        # @param block [String] the inside of one @VAR;...;@ENDVAR;
+        #   block, e.g. `Variable=a;Value=1;Op==;`
+        # @return [Binding]
+        def parse_binding(block)
+          fields = parse_fields(block)
+          Binding.new(
+            fields["Variable"] || "",
+            fields["Value"] || "",
+            fields["Op"] || "",
+          )
+        end
+
+        # Parse `Key=value;` pairs into a Hash. Values may contain
+        # `;` literally — only split on `;` immediately followed by a
+        # known key boundary. In practice EA's values rarely contain
+        # semicolons, so a simple split is sufficient.
+        #
+        # @param block [String]
+        # @return [Hash{String=>String}]
+        def parse_fields(block)
+          block.split(";").each_with_object({}) do |pair, hash|
+            key, value = pair.split("=", 2)
+            hash[key] = value.to_s if key && !key.empty?
+          end
+        end
+      end
+    end
+  end
+end