ea 0.1.0 → 0.1.4

data/examples/smoke_test_real_qea.rb

@@ -0,0 +1,81 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# End-to-end smoke test: parse a real Sparx EA .qea file end-to-end through
+# both the standalone QEA loader and the UML bridge.
+#
+# Run: bundle exec ruby examples/smoke_test_real_qea.rb
+#
+# Demonstrates:
+#   1. Ea::Qea.database_info  — quick table-count stats (no full load)
+#   2. Ea::Qea.load           — standalone load → Ea::Qea::Database
+#   3. Ea::Qea.to_uml         — bridge → Lutaml::Uml::Document
+#
+# Requires a real .qea file. Defaults to the plateau model fixture; override
+# with the QEA_PATH environment variable.
+
+require "bundler/setup"
+require "lutaml/uml"
+require "ea"
+
+QEA_PATH = ENV.fetch(
+  "QEA_PATH",
+  "/Users/mulgogi/src/mn/plateau-model/20251010_current_plateau_v5.1.qea",
+)
+
+abort "QEA not found: #{QEA_PATH}" unless File.exist?(QEA_PATH)
+
+puts "QEA: #{QEA_PATH}"
+puts "Size: #{(File.size(QEA_PATH) / 1_048_576.0).round(2)} MB"
+puts
+
+# 1. Quick stats — opens the SQLite DB and counts rows per table, no model load
+puts "== database_info (quick stats, top 12 tables) =="
+Ea::Qea.database_info(QEA_PATH)
+  .sort_by { |_, count| -count.to_i }
+  .first(12)
+  .each { |table, count| puts "  #{table}: #{count}" }
+puts
+
+# 2. Standalone load — pure QEA parsing, no lutaml-uml needed
+puts "== Ea::Qea.load (standalone) =="
+database = Ea::Qea.load(QEA_PATH)
+puts "  loaded:        #{database.class}"
+puts "  total_records: #{database.total_records}"
+puts
+
+puts "== EA objects by type =="
+database.objects.group_by(:object_type)
+  .sort_by { |_, objs| -objs.size }
+  .each { |type, objs| puts "  #{type}: #{objs.size}" }
+puts
+
+# 3. UML bridge — compose with lutaml-uml to get a Lutaml::Uml::Document
+puts "== Ea::Qea.to_uml (bridge) =="
+document = Ea::Qea.to_uml(database)
+puts "  document: #{document.class}"
+puts
+
+# 4. Walk the package tree — classes live inside packages, not at document root
+def walk(pkgs, counters)
+  Array(pkgs).each do |pkg|
+    counters[:packages] += 1
+    counters[:classes] += Array(pkg.classes).size
+    counters[:enums] += Array(pkg.enums).size
+    counters[:data_types] += Array(pkg.data_types).size
+    counters[:instances] += Array(pkg.instances).size
+    walk(pkg.packages, counters)
+  end
+end
+
+puts "== UML Document (incl. nested in packages) =="
+counters = { packages: 0, classes: 0, enums: 0, data_types: 0, instances: 0 }
+walk(document.packages, counters)
+counters.each { |k, v| puts "  #{k}: #{v}" }
+puts "  associations (document root): #{document.associations.size}"
+puts "  diagrams (document root):     #{document.diagrams.size}"
+puts "  orphan classes (document root): #{document.classes.size}"
+puts "    ^ classes whose EA package_id has no t_package row"
+puts
+
+puts "SMOKE TEST PASSED"

data/exe/ea

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "ea/cli"
+Ea::Cli::App.start(ARGV)

data/lib/ea/cli/app.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module Ea
+  module Cli
+    class App < Thor
+      class << self
+        def exit_on_failure?
+          true
+        end
+      end
+
+      desc "version", "Show ea gem version"
+      def version
+        puts Ea::VERSION
+      end
+
+      desc "list FILE", "List model elements (auto-detects QEA or XMI)"
+      option :type, type: :string,
+                    desc: "Filter: class | interface | package | diagram | connector | enum"
+      option :format, type: :string, default: "table",
+                      desc: "Output format: table | json | yaml"
+      def list(file)
+        Command::List.new(file: file, **symbolize(options)).call
+      end
+
+      desc "diagrams ACTION FILE [NAME]",
+           "Diagram operations: list FILE | extract NAME FILE"
+      option :format, type: :string, default: "table"
+      option :output, type: :string, desc: "Output path (extract only)"
+      def diagrams(action, file = nil, name = nil)
+        Command::Diagrams
+          .new(action: action, file: file, name: name, **symbolize(options))
+          .call
+      end
+
+      desc "validate FILE", "Validate EA model"
+      option :format, type: :string, default: "table"
+      def validate(file)
+        Command::Validate.new(file: file, **symbolize(options)).call
+      end
+
+      desc "stats FILE", "Show collection counts (standalone — no lutaml-uml)"
+      option :format, type: :string, default: "table"
+      def stats(file)
+        Command::Stats.new(file: file, **symbolize(options)).call
+      end
+
+      desc "parse FILE", "Parse to Lutaml::Uml::Document (requires lutaml-uml)"
+      option :format, type: :string, default: "yaml",
+                      desc: "Output: json | yaml"
+      def parse(file)
+        Command::Parse.new(file: file, **symbolize(options)).call
+      end
+
+      desc "convert FILE", "Convert between EA formats (e.g. QEA → XMI)"
+      option :to, type: :string, required: true, desc: "Target format: xmi"
+      option :output, type: :string, desc: "Output path"
+      option :format, type: :string, default: "table"
+      def convert(file)
+        Command::Convert.new(file: file, **symbolize(options)).call
+      end
+
+      private
+
+      def symbolize(opts)
+        opts.transform_keys(&:to_sym)
+      end
+    end
+  end
+end

data/lib/ea/cli/command/base.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Ea
+  module Cli
+    module Command
+      # Shared base for all CLI commands.
+      #
+      # Provides:
+      # - Options Hash access (read-only)
+      # - Output formatter resolution from `:format` option
+      # - Standalone QEA database loading (no lutaml-uml required)
+      # - UML document parsing (lazy-loads lutaml-uml)
+      # - File existence validation
+      #
+      # Subclasses implement {#call} and may use the protected helpers.
+      class Base
+        def initialize(options = {})
+          @options = options
+        end
+
+        # Template method — subclasses implement.
+        # @raise [NotImplementedError] if not overridden
+        def call
+          raise NotImplementedError, "#{self.class}#call not implemented"
+        end
+
+        protected
+
+        attr_reader :options
+
+        def formatter
+          Ea::Cli::Output.instance_for(options[:format] || :table)
+        end
+
+        def file_path
+          options[:file] or raise Ea::Cli::Error, "missing required --file"
+        end
+
+        # Load a QEA database. Works standalone — no lutaml-uml dependency.
+        # @return [Ea::Qea::Database]
+        def load_database(path = file_path)
+          validate_file!(path)
+          Ea::Qea.load(path)
+        rescue Ea::Cli::Error
+          raise
+        rescue Ea::Error => e
+          raise Ea::Cli::Error, "Failed to load #{path}: #{e.message}"
+        end
+
+        # Parse any EA file to a Lutaml::Uml::Document.
+        # Lazy-loads lutaml-uml via Ea::Qea's require_uml! guard.
+        # @return [Lutaml::Uml::Document]
+        def parse_to_uml(path = file_path, **parse_options)
+          validate_file!(path)
+          Ea::Qea.parse(path, parse_options)
+        rescue Ea::Cli::Error
+          raise
+        rescue Ea::Error => e
+          if e.message.include?("lutaml-uml")
+            raise Ea::Cli::MissingUmlDependency
+          end
+
+          raise Ea::Cli::Error, "Failed to parse #{path}: #{e.message}"
+        end
+
+        def validate_file!(path)
+          raise Ea::Cli::FileNotFound, path unless File.exist?(path)
+        end
+
+        # Write content to a path; honors the `:output` option.
+        # @return [String] the path written to
+        def write_output(content, default_name:)
+          path = options[:output] || default_name
+          File.write(path, content)
+          path
+        end
+      end
+    end
+  end
+end

data/lib/ea/cli/command/convert.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Ea
+  module Cli
+    module Command
+      # `ea convert FILE --to xmi [--output PATH]`
+      #
+      # Converts an EA file to another format. Currently supports:
+      #   --to xmi   .qea → Sparx XMI (direct, full Sparx fidelity)
+      #
+      # Routing is by input file extension:
+      #   .qea → Ea::Transformers.qea_to_xmi (direct path, no intermediate
+      #          UML model — preserves all Sparx-specific concepts)
+      #   any other extension → UnsupportedFormat
+      #
+      # Future formats (e.g. parsing a Lutaml::LML .lur file) are added by
+      # extending the case statement in {#convert_to_xmi}.
+      class Convert < Base
+        SUPPORTED_TARGETS = %w[xmi].freeze
+        SUPPORTED_INPUT_FORMATS = %i[qea].freeze
+
+        def call
+          target = options[:to] or raise Ea::Cli::Error, "missing required --to"
+          case target.to_s
+          when "xmi" then convert_to_xmi
+          else
+            raise Ea::Cli::Error,
+                  "Unsupported target '#{target}'. " \
+                  "Valid: #{SUPPORTED_TARGETS.join(', ')}"
+          end
+        end
+
+        private
+
+        def convert_to_xmi
+          xml = case input_format
+                when :qea then qea_to_xmi_xml
+                else
+                  raise Ea::Cli::UnsupportedFormat.new(
+                    file_path,
+                    "supported inputs: " \
+                    "#{SUPPORTED_INPUT_FORMATS.join(', ')}",
+                  )
+                end
+          path = write_output(xml, default_name: "#{file_path}.xmi")
+          formatter.render([[path]], columns: [:written_to])
+        end
+
+        def qea_to_xmi_xml
+          database = load_database(file_path)
+          Ea::Transformers.qea_to_xmi(database)
+        ensure
+          database&.close_connection
+        end
+
+        def input_format
+          File.extname(file_path).downcase[1..].to_sym
+        end
+      end
+    end
+  end
+end

data/lib/ea/cli/command/diagrams.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Ea
+  module Cli
+    module Command
+      # `ea diagrams ACTION FILE [NAME]`
+      #
+      # Actions:
+      #   list FILE           — list diagrams in a QEA/XMI file (standalone)
+      #   extract FILE NAME   — render the named diagram from a LUR file to SVG
+      #
+      # `list` reads the EA database directly (no lutaml-uml required).
+      # `extract` delegates to {Ea::Diagram::Extractor}, which requires a
+      # `.lur` (Lutaml UML Repository) file. To render diagrams from a QEA,
+      # first convert it to `.lur` via the `lutaml` gem.
+      class Diagrams < Base
+        ACTIONS = %w[list extract].freeze
+        LUR_EXT = ".lur"
+
+        def call
+          case action
+          when "list"    then list
+          when "extract" then extract
+          else
+            raise Ea::Cli::UnknownAction.new(action, valid: ACTIONS)
+          end
+        end
+
+        private
+
+        def action
+          options[:action] or raise Ea::Cli::Error, "missing required ACTION"
+        end
+
+        def name
+          options[:name] or raise Ea::Cli::Error, "missing required NAME"
+        end
+
+        def list
+          db = load_database
+          rows = db.diagrams.map { |d| [d.name, diagram_type_label(d), d.ea_guid] }
+          formatter.render(rows, columns: %i[name type guid])
+        end
+
+        def extract
+          validate_lur!(file_path)
+          result = extractor.extract_one(file_path, name, extract_options)
+          raise Ea::Cli::Error, result[:message] unless result[:success]
+
+          path = result[:path] || write_output(result.fetch(:svg_content),
+                                                default_name: "#{name}.svg")
+          formatter.render([[path]], columns: [:written_to])
+        end
+
+        def extractor
+          Ea::Diagram::Extractor.new
+        end
+
+        def extract_options
+          opts = {}
+          opts[:output] = options[:output] if options[:output]
+          opts
+        end
+
+        def validate_lur!(path)
+          return if path.end_with?(LUR_EXT)
+
+          raise Ea::Cli::UnsupportedFormat.new(
+            path,
+            "diagrams extract requires a #{LUR_EXT} file; " \
+            "convert from QEA via the lutaml gem first",
+          )
+        end
+
+        def diagram_type_label(diagram)
+          diagram.diagram_type || "Logical"
+        end
+      end
+    end
+  end
+end

data/lib/ea/cli/command/list.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Ea
+  module Cli
+    module Command
+      # `ea list FILE [--type TYPE]`
+      #
+      # Lists model elements from a QEA file. With `--type`, returns elements
+      # of one kind (class/interface/package/diagram/connector/enum). Without
+      # `--type`, returns a summary of counts per kind.
+      #
+      # Operates standalone — does not require lutaml-uml.
+      class List < Base
+        def call
+          rows =
+            if options[:type]
+              list_by_type(options[:type])
+            else
+              list_summary
+            end
+          formatter.render(rows, columns: columns_for_current_mode)
+        end
+
+        private
+
+        def list_summary
+          db = load_database
+          [
+            [:classes,    db.objects.find_by_type("Class").size],
+            [:interfaces, db.objects.find_by_type("Interface").size],
+            [:packages,   db.packages.size],
+            [:enums,      db.objects.find_by_type("Enumeration").size],
+            [:datatypes,  db.objects.find_by_type("DataType").size],
+            [:diagrams,   db.diagrams.size],
+            [:connectors, db.connectors.size],
+          ]
+        end
+
+        def list_by_type(type)
+          db = load_database
+          case type.to_s
+          when "class"     then db.objects.find_by_type("Class").map { |o| [o.name, o.ea_guid] }
+          when "interface" then db.objects.find_by_type("Interface").map { |o| [o.name, o.ea_guid] }
+          when "enum"      then db.objects.find_by_type("Enumeration").map { |o| [o.name, o.ea_guid] }
+          when "package"   then db.packages.map { |p| [p.name, p.ea_guid] }
+          when "diagram"   then db.diagrams.map { |d| [d.name, d.ea_guid] }
+          when "connector" then db.connectors.map { |c| [c.name, c.ea_guid] }
+          else
+            raise Ea::Cli::Error,
+                  "Unknown type '#{type}'. " \
+                  "Valid: class, interface, package, diagram, connector, enum"
+          end
+        end
+
+        def columns_for_current_mode
+          options[:type] ? %i[name guid] : %i[kind count]
+        end
+      end
+    end
+  end
+end

data/lib/ea/cli/command/parse.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Ea
+  module Cli
+    module Command
+      # `ea parse FILE [--format json|yaml]`
+      #
+      # Parses the EA file (QEA or Sparx XMI) to a Lutaml::Uml::Document and
+      # serializes it. Requires lutaml-uml.
+      class Parse < Base
+        def call
+          document = parse_to_uml(file_path)
+          formatter_output(document)
+        end
+
+        private
+
+        def formatter_output(document)
+          case (options[:format] || :yaml).to_sym
+          when :json then puts document.to_json
+          when :yaml then puts document.to_yaml
+          else
+            raise Ea::Cli::Error, "Unknown format: #{options[:format]}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ea/cli/command/stats.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Ea
+  module Cli
+    module Command
+      # `ea stats FILE`
+      #
+      # Standalone — does not require lutaml-uml. Reads the QEA database
+      # directly and prints per-collection counts.
+      class Stats < Base
+        def call
+          db = load_database
+          stats = db.stats
+          rows = stats.map { |k, v| [k, v] }
+          formatter.render(rows, columns: %i[collection count])
+        end
+      end
+    end
+  end
+end

data/lib/ea/cli/command/validate.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Ea
+  module Cli
+    module Command
+      # `ea validate FILE`
+      #
+      # Runs Ea::Qea::Validation::ValidationEngine and reports messages.
+      # Exits non-zero if any errors were found.
+      #
+      # Requires lutaml-uml (validation runs against Lutaml::Uml::Document).
+      class Validate < Base
+        COLUMNS = %i[severity entity_type entity_name message].freeze
+
+        def call
+          result = parse_with_validation(file_path)
+          rows = result.messages.map do |m|
+            [m.severity, m.entity_type, m.entity_name, m.message]
+          end
+          formatter.render(rows, columns: COLUMNS)
+          exit(1) if result.errors.any?
+        end
+
+        private
+
+        def parse_with_validation(path)
+          validate_file!(path)
+          Ea::Qea.parse(path, validate: true)[:validation_result]
+        rescue Ea::Cli::Error
+          raise
+        rescue Ea::Error => e
+          if e.message.include?("lutaml-uml")
+            raise Ea::Cli::MissingUmlDependency
+          end
+
+          raise Ea::Cli::Error, "Failed to validate #{path}: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/ea/cli/command.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Ea
+  module Cli
+    module Command
+      autoload :Base, "ea/cli/command/base"
+      autoload :List, "ea/cli/command/list"
+      autoload :Diagrams, "ea/cli/command/diagrams"
+      autoload :Validate, "ea/cli/command/validate"
+      autoload :Stats, "ea/cli/command/stats"
+      autoload :Parse, "ea/cli/command/parse"
+      autoload :Convert, "ea/cli/command/convert"
+    end
+  end
+end

data/lib/ea/cli/error.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Ea
+  module Cli
+    class Error < Ea::Error; end
+
+    class FileNotFound < Error
+      def initialize(path)
+        super("File not found: #{path}")
+      end
+    end
+
+    class UnsupportedFormat < Error
+      def initialize(path, detail = nil)
+        msg = "Unsupported format for file: #{path}"
+        msg = "#{msg} (#{detail})" if detail
+        super(msg)
+      end
+    end
+
+    class MissingUmlDependency < Error
+      def initialize
+        super("lutaml-uml is required for this command. " \
+              "Add gem 'lutaml-uml' to your Gemfile.")
+      end
+    end
+
+    class UnknownAction < Error
+      def initialize(action, valid:)
+        super("Unknown action '#{action}'. Valid: #{valid.join(', ')}")
+      end
+    end
+  end
+end

data/lib/ea/cli/output/formatter.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Ea
+  module Cli
+    module Output
+      class Formatter
+        def render(rows, columns: [])
+          raise NotImplementedError
+        end
+
+        protected
+
+        def normalize_row(row, columns)
+          return row if row.is_a?(Hash)
+
+          columns.each_with_index.to_h { |k, i| [k, row[i]] }
+        end
+
+        def infer_columns(rows)
+          first = rows.first
+          return columns_of(first) if first
+
+          []
+        end
+
+        private
+
+        def columns_of(obj)
+          obj.is_a?(Hash) ? obj.keys.map(&:to_sym) : []
+        end
+      end
+    end
+  end
+end

data/lib/ea/cli/output/json_formatter.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ea
+  module Cli
+    module Output
+      class JsonFormatter < Formatter
+        def render(rows, columns: [])
+          data = rows.map do |row|
+            normalize_row(row, columns)
+          end
+          puts JSON.pretty_generate(data)
+        end
+      end
+    end
+  end
+end
+
+Ea::Cli::Output.register(:json, Ea::Cli::Output::JsonFormatter)

data/lib/ea/cli/output/table_formatter.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Ea
+  module Cli
+    module Output
+      class TableFormatter < Formatter
+        COLUMN_WIDTH = 24
+        SEPARATOR = "  "
+
+        def render(rows, columns: [])
+          return puts("(no rows)") if rows.empty?
+
+          cols = columns.empty? ? Array(infer_columns(rows)) : columns
+          puts render_header(cols)
+          rows.each { |row| puts render_row(row, cols) }
+        end
+
+        private
+
+        def render_header(cols)
+          cols.map { |c| pad(c.to_s) }.join(SEPARATOR)
+        end
+
+        def render_row(row, cols)
+          values =
+            if row.is_a?(Hash)
+              cols.map { |c| row[c] || row[c.to_s] }
+            else
+              row
+            end
+          values.map { |v| pad(v.to_s) }.join(SEPARATOR)
+        end
+
+        def pad(s)
+          s.length >= COLUMN_WIDTH ? s : s.ljust(COLUMN_WIDTH)
+        end
+      end
+    end
+  end
+end
+
+Ea::Cli::Output.register(:table, Ea::Cli::Output::TableFormatter)