ea 0.1.0 → 0.1.5

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,81 @@
+# 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
+
+      desc "spa FILE", "Generate single-page app (SPA) from QEA/XMI/LUR"
+      option :output, type: :string,
+                      desc: "Output path (default: <basename>.html)"
+      option :mode, type: :string, default: "single_file",
+                    desc: "Output mode: single_file | multi_file"
+      def spa(file)
+        Command::Spa.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,75 @@
+# frozen_string_literal: true
+
+module Ea
+  module Cli
+    module Command
+      # `ea diagrams ACTION FILE [NAME]`
+      #
+      # Actions:
+      #   list FILE           — list diagrams in a QEA/XMI/LUR file (standalone)
+      #   extract FILE NAME   — render the named diagram to SVG
+      #
+      # `list` reads the EA database directly (no lutaml-uml required
+      # for QEA; XMI parsing via xmi gem only).
+      #
+      # `extract` accepts QEA, XMI, or LUR. The Repository is built
+      # from the input file via `RepositoryBuilder` (single source of
+      # truth — QEA/XMI are parsed via `Ea::Transformations`, LUR is
+      # loaded natively via `Repository.from_file`).
+      class Diagrams < Base
+        include RepositoryBuilder
+
+        ACTIONS = %w[list extract].freeze
+
+        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
+          repository = RepositoryBuilder.build_repository(file_path)
+          result = extractor.extract_one(repository, 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 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/repository_builder.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Ea
+  module Cli
+    module Command
+      # Shared helper for building a `Lutaml::UmlRepository::Repository`
+      # from any file format supported by `Ea::Transformations`.
+      #
+      # Single source of truth for "QEA/XMI/LUR → Repository" wiring.
+      # Used by `Ea::Cli::Command::Diagrams` (extract action) and
+      # `Ea::Cli::Command::Spa` (SPA generation).
+      #
+      # `.lur` files take the fast path via `Repository.from_file` (the
+      # native LUR loader). QEA/XMI files are parsed via
+      # `Ea::Transformations.parse` and wrapped via
+      # `Repository.from_document`.
+      module RepositoryBuilder
+        LUR_EXT = ".lur".freeze
+
+        module_function
+
+        # @param path [String] file path (QEA, XMI, or LUR)
+        # @return [Lutaml::UmlRepository::Repository]
+        def build_repository(path)
+          require_lutaml_uml!
+
+          if lur?(path)
+            require_lutaml_uml_repository!
+            return Lutaml::UmlRepository::Repository.from_file(path)
+          end
+
+          document = Ea::Transformations.parse(path)
+          require_lutaml_uml_repository!
+          Lutaml::UmlRepository::Repository.from_document(document)
+        end
+
+        def lur?(path)
+          File.extname(path).downcase == LUR_EXT
+        end
+
+        # Loads the bridge gem. The lutaml-uml gem is an optional
+        # dependency; if missing, raise the CLI's MissingUmlDependency
+        # so the user gets a clear message about installing it.
+        def require_lutaml_uml!
+          require "lutaml/uml"
+        rescue LoadError => e
+          raise Ea::Cli::MissingUmlDependency,
+                "spa and diagrams-extract commands require the " \
+                "`lutaml-uml` gem. Install it via `gem install lutaml-uml` " \
+                "or add it to your Gemfile. (#{e.message})"
+        end
+
+        def require_lutaml_uml_repository!
+          require "lutaml/uml_repository"
+        rescue LoadError => e
+          raise Ea::Cli::MissingUmlDependency,
+                "spa and diagrams-extract commands require the " \
+                "`lutaml-uml` gem. Install it via `gem install lutaml-uml` " \
+                "or add it to your Gemfile. (#{e.message})"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Ea
+  module Cli
+    module Command
+      # `ea spa FILE [--output=PATH] [--mode=MODE]`
+      #
+      # Generates a static single-page application (SPA) from a QEA,
+      # XMI, or LUR file. The SPA shows the package hierarchy, class
+      # details, diagram list, and member navigation in a browser.
+      #
+      # Pipeline:
+      #   1. Ea::Transformations.parse(file) → Lutaml::Uml::Document
+      #   2. Lutaml::UmlRepository::Repository.from_document(document)
+      #   3. Lutaml::UmlRepository::StaticSite::Generator.new(repo, ...).generate
+      #
+      # Output format defaults to single-file Vue IIFE HTML.
+      class Spa < Base
+        DEFAULT_MODE = :single_file
+
+        def call
+          repository = RepositoryBuilder.build_repository(file_path)
+
+          require_lutaml_uml_static_site!
+          strategy = resolve_output_strategy
+
+          output_path = resolve_output_path
+          options = {
+            output: output_path,
+            mode: mode,
+            output_strategy: strategy,
+          }.compact
+
+          Lutaml::UmlRepository::StaticSite::Generator
+            .new(repository, options)
+            .generate
+
+          formatter.render([[output_path]], columns: [:written_to])
+        end
+
+        private
+
+        def mode
+          (options[:mode] || DEFAULT_MODE).to_sym
+        end
+
+        def resolve_output_path
+          options[:output] || default_output_path
+        end
+
+        def default_output_path
+          base = File.basename(file_path, ".*")
+          dir = File.dirname(file_path)
+          File.join(dir, "#{base}.html")
+        end
+
+        def resolve_output_strategy
+          case mode
+          when :single_file, "single_file"
+            Lutaml::UmlRepository::StaticSite::Output::VueInlinedStrategy
+          when :multi_file, "multi_file"
+            Lutaml::UmlRepository::StaticSite::Output::MultiFileStrategy
+          else
+            raise Ea::Cli::UnsupportedFormat,
+                  "Unknown spa mode '#{mode}': use single_file or multi_file"
+          end
+        end
+
+        def require_lutaml_uml_static_site!
+          require "lutaml/uml_repository/static_site"
+        rescue LoadError => e
+          raise Ea::Cli::MissingUmlDependency,
+                "spa command requires the `lutaml-uml` gem. " \
+                "Install it via `gem install lutaml-uml`. (#{e.message})"
+        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